Merge pull request #51788 from Faless/mp/4.x_replicator_sync

[Net] MultiplayerReplicator state sync.

1 files changed, 53 insertions, 1 deletions

diff --git a/doc/classes/MultiplayerReplicator.xml b/doc/classes/MultiplayerReplicator.xml
index 15029e181f..0778a7335f 100644
--- a/doc/classes/MultiplayerReplicator.xml
+++ b/doc/classes/MultiplayerReplicator.xml
@@ -12,6 +12,7 @@
 			<argument index="0" name="scene_id" type="int" />
 			<argument index="1" name="object" type="Object" />
 			<argument index="2" name="data" type="PackedByteArray" />
+			<argument index="3" name="initial" type="bool" default="true" />
 			<description>
 				Decode the given [code]data[/code] representing a spawnable state into [code]object[/code] using the configuration associated with the provided [code]scene_id[/code]. This function is called automatically when a client receives a server spawn for a scene with [constant REPLICATION_MODE_SERVER]. See [method spawn_config].
 				Tip: You may find this function useful in servers when parsing spawn requests from clients, or when implementing your own logic with [constant REPLICATION_MODE_CUSTOM].
@@ -23,12 +24,14 @@
 			<argument index="1" name="object" type="Object" />
 			<argument index="2" name="peer_id" type="int" default="0" />
 			<description>
+				Request a despawn for the scene identified by [code]scene_id[/code] to the given [code]peer_id[/code]. This will either trigger the default behaviour, or invoke the custom spawn/despawn callables specified in [method spawn_config]. See [method send_despawn] for the default behavior.
 			</description>
 		</method>
 		<method name="encode_state">
 			<return type="PackedByteArray" />
 			<argument index="0" name="scene_id" type="int" />
 			<argument index="1" name="object" type="Object" />
+			<argument index="2" name="initial" type="bool" default="true" />
 			<description>
 				Encode the given [code]object[/code] using the configuration associated with the provided [code]scene_id[/code]. This function is called automatically when the server spawns scenes with [constant REPLICATION_MODE_SERVER]. See [method spawn_config].
 				Tip: You may find this function useful when requesting spawns from clients to server, or when implementing your own logic with [constant REPLICATION_MODE_CUSTOM].
@@ -54,12 +57,24 @@
 				Sends a spawn request for the scene identified by [code]scene_id[/code] to the given [code]peer_id[/code] (see [method MultiplayerPeer.set_target_peer]). If the scene is configured as [constant REPLICATION_MODE_SERVER] (see [method spawn_config]) and the request is sent by the server (see [method MultiplayerAPI.is_network_server]), the receiving peer(s) will automatically instantiate that scene, add it to the [SceneTree] at the given [code]path[/code] and emit the signal [signal spawned]. In all other cases no instantiation happens, and the signal [signal spawn_requested] is emitted instead.
 			</description>
 		</method>
+		<method name="send_sync">
+			<return type="int" enum="Error" />
+			<argument index="0" name="peer_id" type="int" />
+			<argument index="1" name="scene_id" type="int" />
+			<argument index="2" name="data" type="PackedByteArray" />
+			<argument index="3" name="transfer_mode" type="int" enum="MultiplayerPeer.TransferMode" default="2" />
+			<argument index="4" name="channel" type="int" default="0" />
+			<description>
+				Sends a sync request for the instances of the scene identified by [code]scene_id[/code] to the given [code]peer_id[/code] (see [method MultiplayerPeer.set_target_peer]). This function can only be called manually when overriding the send and receive sync functions (see [method sync_config]).
+			</description>
+		</method>
 		<method name="spawn">
 			<return type="int" enum="Error" />
 			<argument index="0" name="scene_id" type="int" />
 			<argument index="1" name="object" type="Object" />
 			<argument index="2" name="peer_id" type="int" default="0" />
 			<description>
+				Request a spawn for the scene identified by [code]scene_id[/code] to the given [code]peer_id[/code]. This will either trigger the default behaviour, or invoke the custom spawn/despawn callables specified in [method spawn_config]. See [method send_spawn] for the default behavior.
 			</description>
 		</method>
 		<method name="spawn_config">
@@ -70,10 +85,47 @@
 			<argument index="3" name="custom_send" type="Callable" />
 			<argument index="4" name="custom_receive" type="Callable" />
 			<description>
-				Configures the MultiplayerAPI to track instances of the [PackedScene] identified by [code]scene_id[/code] (see [method ResourceLoader.get_resource_uid]) for the purpose of network replication. When [code]mode[/code] is [constant REPLICATION_MODE_SERVER], the specified [code]properties[/code] will also be replicated to clients during the initial spawn.
+				Configures the MultiplayerReplicator to track instances of the [PackedScene] identified by [code]scene_id[/code] (see [method ResourceLoader.get_resource_uid]) for the purpose of network replication. When [code]mode[/code] is [constant REPLICATION_MODE_SERVER], the specified [code]properties[/code] will also be replicated to clients during the initial spawn. You can optionally specify a [code]custom_send[/code] and a [code]custom_receive[/code] to override the default behaviour and customize the spawn/despawn proecess.
 				Tip: You can use a custom property in the scene main script to return a customly optimized state representation.
 			</description>
 		</method>
+		<method name="sync_all">
+			<return type="int" enum="Error" />
+			<argument index="0" name="scene_id" type="int" />
+			<argument index="1" name="peer_id" type="int" default="0" />
+			<description>
+				Manually request a sync for all the instances of the scene identified by [code]scene_id[/code]. This function will trigger the default sync behaviour, or call your send custom send callable if specified in [method sync_config].
+				Note: The default implementation only allow syncing from server to clients.
+			</description>
+		</method>
+		<method name="sync_config">
+			<return type="int" enum="Error" />
+			<argument index="0" name="scene_id" type="int" />
+			<argument index="1" name="interval" type="int" />
+			<argument index="2" name="properties" type="StringName[]" default="[]" />
+			<argument index="3" name="custom_send" type="Callable" />
+			<argument index="4" name="custom_receive" type="Callable" />
+			<description>
+				Configures the MultiplayerReplicator to sync instances of the [PackedScene] identified by [code]scene_id[/code] (see [method ResourceLoader.get_resource_uid]) for the purpose of network replication at the desired [code]interval[/code] (in milliseconds). The specified [code]properties[/code] will be part of the state sync. You can optionally specify a [code]custom_send[/code] and a [code]custom_receive[/code] to override the default behaviour and customize the syncronization proecess.
+				Tip: You can use a custom property in the scene main script to return a customly optimized state representation (having a single property that returns a PackedByteArray is higly recommended when dealing with many instances).
+			</description>
+		</method>
+		<method name="track">
+			<return type="void" />
+			<argument index="0" name="scene_id" type="int" />
+			<argument index="1" name="object" type="Object" />
+			<description>
+				Track the given [code]object[/code] as an instance of the scene identified by [code]scene_id[/code]. This object will be passed to your custom sync callables (see [method sync_config]). Tracking and untracking is automatic in [constant REPLICATION_MODE_SERVER].
+			</description>
+		</method>
+		<method name="untrack">
+			<return type="void" />
+			<argument index="0" name="scene_id" type="int" />
+			<argument index="1" name="object" type="Object" />
+			<description>
+				Untrack the given [code]object[/code]. This object will no longer be passed to your custom sync callables (see [method sync_config]). Tracking and untracking is automatic in [constant REPLICATION_MODE_SERVER].
+			</description>
+		</method>
 	</methods>
 	<signals>
 		<signal name="despawn_requested">