[Net] MultiplayerReplicator with initial state.

Move the former "spawnables" functions to a dedicated
MultiplayerReplicator class.
Support custom overrides in replicator.
Spawn/despawn messages can now contain a state.
The state can be automatically encoded/decoded by passing the desired
object properties to `spawnable_config`.
You can use script properties to optimize the state representation.
2 Callables can be also specified to completely override the default
implementation for sending and receiving the spawn/despawn event.
(9 bytes overhead, and there's room for improvement here).
When using a custom implementation `spawn` and `despawn` can be called
with any Object, `send_spawn`/`send_despawn` can receive any Variant as
a state, and the path is not required.

Two new functions, `spawn` and `despawn`, convey the implementation
independent method for requesting a spawn/despawn of an Object, while
`send_spawn` and `send_despawn` represent the more low-level send event
for a Variant to be used by the custom implementations.

2 files changed, 141 insertions, 89 deletions

diff --git a/doc/classes/MultiplayerAPI.xml b/doc/classes/MultiplayerAPI.xml
index b9f50ad02a..610b00efe9 100644
--- a/doc/classes/MultiplayerAPI.xml
+++ b/doc/classes/MultiplayerAPI.xml
@@ -66,34 +66,6 @@
 				Sends the given raw [code]bytes[/code] to a specific peer identified by [code]id[/code] (see [method MultiplayerPeer.set_target_peer]). Default ID is [code]0[/code], i.e. broadcast to all peers.
 			</description>
 		</method>
-		<method name="send_despawn">
-			<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="path" type="NodePath" />
-			<argument index="3" name="data" type="PackedByteArray" default="PackedByteArray()" />
-			<description>
-				Sends a despawn 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 SPAWN_MODE_SERVER] (see [method spawnable_config]) and the request is sent by the server (see [method is_network_server]), the receiving peer(s) will automatically queue for deletion the node at [code]path[/code] and emit the signal [signal network_despawn]. In all other cases no deletion happens, and the signal [signal network_despawn_request] is emitted instead.
-			</description>
-		</method>
-		<method name="send_spawn">
-			<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="path" type="NodePath" />
-			<argument index="3" name="data" type="PackedByteArray" default="PackedByteArray()" />
-			<description>
-				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 SPAWN_MODE_SERVER] (see [method spawnable_config]) and the request is sent by the server (see [method 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 network_spawn]. In all other cases no instantiation happens, and the signal [signal network_spawn_request] is emitted instead.
-			</description>
-		</method>
-		<method name="spawnable_config">
-			<return type="int" enum="Error" />
-			<argument index="0" name="scene_id" type="int" />
-			<argument index="1" name="spawn_mode" type="int" enum="MultiplayerAPI.SpawnMode" />
-			<description>
-				Configures the MultiplayerAPI to track instances of the [PackedScene] idenfied by [code]scene_id[/code] (see [method ResourceLoader.get_resource_uid]) for the purpose of network replication. See [enum SpawnMode] for the possible configurations.
-			</description>
-		</method>
 	</methods>
 	<members>
 		<member name="allow_object_decoding" type="bool" setter="set_allow_object_decoding" getter="is_object_decoding_allowed" default="false">
@@ -106,6 +78,8 @@
 		<member name="refuse_new_network_connections" type="bool" setter="set_refuse_new_network_connections" getter="is_refusing_new_network_connections" default="false">
 			If [code]true[/code], the MultiplayerAPI's [member network_peer] refuses new incoming connections.
 		</member>
+		<member name="replicator" type="MultiplayerReplicator" setter="" getter="get_replicator">
+		</member>
 		<member name="root_node" type="Node" setter="set_root_node" getter="get_root_node">
 			The root node to use for RPCs. Instead of an absolute path, a relative path will be used to find the node upon which the RPC should be executed.
 			This effectively allows to have different branches of the scene tree to be managed by different MultiplayerAPI, allowing for example to run both client and server in the same scene.
@@ -122,25 +96,6 @@
 				Emitted when this MultiplayerAPI's [member network_peer] fails to establish a connection to a server. Only emitted on clients.
 			</description>
 		</signal>
-		<signal name="network_despawn">
-			<argument index="0" name="id" type="int" />
-			<argument index="1" name="scene_id" type="int" />
-			<argument index="2" name="node" type="Node" />
-			<argument index="3" name="data" type="PackedByteArray" />
-			<description>
-				Emitted on a client before deleting a local Node upon receiving a despawn request from the server.
-			</description>
-		</signal>
-		<signal name="network_despawn_request">
-			<argument index="0" name="id" type="int" />
-			<argument index="1" name="scene_id" type="int" />
-			<argument index="2" name="parent" type="Node" />
-			<argument index="3" name="name" type="String" />
-			<argument index="4" name="data" type="PackedByteArray" />
-			<description>
-				Emitted when a network despawn request has been received from a client, or for a [PackedScene] that has been configured as [constant SPAWN_MODE_CUSTOM].
-			</description>
-		</signal>
 		<signal name="network_peer_connected">
 			<argument index="0" name="id" type="int" />
 			<description>
@@ -160,39 +115,6 @@
 				Emitted when this MultiplayerAPI's [member network_peer] receive a [code]packet[/code] with custom data (see [method send_bytes]). ID is the peer ID of the peer that sent the packet.
 			</description>
 		</signal>
-		<signal name="network_spawn">
-			<argument index="0" name="id" type="int" />
-			<argument index="1" name="scene_id" type="int" />
-			<argument index="2" name="node" type="Node" />
-			<argument index="3" name="data" type="PackedByteArray" />
-			<description>
-				Emitted on a client after a new Node is instantiated locally and added to the SceneTree upon receiving a spawn request from the server.
-			</description>
-		</signal>
-		<signal name="network_spawn_request">
-			<argument index="0" name="id" type="int" />
-			<argument index="1" name="scene_id" type="int" />
-			<argument index="2" name="parent" type="Node" />
-			<argument index="3" name="name" type="String" />
-			<argument index="4" name="data" type="PackedByteArray" />
-			<description>
-				Emitted when a network spawn request has been received from a client, or for a [PackedScene] that has been configured as [constant SPAWN_MODE_CUSTOM].
-			</description>
-		</signal>
-		<signal name="network_spawnable_added">
-			<argument index="0" name="scene_id" type="int" />
-			<argument index="1" name="node" type="Node" />
-			<description>
-				Emitted when an instance of a [PackedScene] that has been configured for networking enters the [SceneTree]. See [method spawnable_config].
-			</description>
-		</signal>
-		<signal name="network_spawnable_removed">
-			<argument index="0" name="scene_id" type="int" />
-			<argument index="1" name="node" type="Node" />
-			<description>
-				Emitted when an instance of a [PackedScene] that has been configured for networking leaves the [SceneTree]. See [method spawnable_config].
-			</description>
-		</signal>
 		<signal name="server_disconnected">
 			<description>
 				Emitted when this MultiplayerAPI's [member network_peer] disconnects from server. Only emitted on clients.
@@ -212,14 +134,5 @@
 		<constant name="RPC_MODE_PUPPET" value="3" enum="RPCMode">
 			Used with [method Node.rpc_config] to set a method to be called or a property to be changed only on puppets for this node. Analogous to the [code]puppet[/code] keyword. Only accepts calls or property changes from the node's network master, see [method Node.set_network_master].
 		</constant>
-		<constant name="SPAWN_MODE_NONE" value="0" enum="SpawnMode">
-			Used with [method spawnable_config] to identify a [PackedScene] that should not be replicated.
-		</constant>
-		<constant name="SPAWN_MODE_SERVER" value="1" enum="SpawnMode">
-			Used with [method spawnable_config] to identify a [PackedScene] that should be automatically replicated from server to clients.
-		</constant>
-		<constant name="SPAWN_MODE_CUSTOM" value="2" enum="SpawnMode">
-			Used with [method spawnable_config] to identify a [PackedScene] that can be manually replicated among peers.
-		</constant>
 	</constants>
 </class>
diff --git a/doc/classes/MultiplayerReplicator.xml b/doc/classes/MultiplayerReplicator.xml
new file mode 100644
index 0000000000..15029e181f
--- /dev/null
+++ b/doc/classes/MultiplayerReplicator.xml
@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="MultiplayerReplicator" inherits="Object" version="4.0">
+	<brief_description>
+	</brief_description>
+	<description>
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="decode_state">
+			<return type="int" enum="Error" />
+			<argument index="0" name="scene_id" type="int" />
+			<argument index="1" name="object" type="Object" />
+			<argument index="2" name="data" type="PackedByteArray" />
+			<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].
+			</description>
+		</method>
+		<method name="despawn">
+			<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>
+			</description>
+		</method>
+		<method name="encode_state">
+			<return type="PackedByteArray" />
+			<argument index="0" name="scene_id" type="int" />
+			<argument index="1" name="object" type="Object" />
+			<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].
+			</description>
+		</method>
+		<method name="send_despawn">
+			<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="Variant" default="null" />
+			<argument index="3" name="path" type="NodePath" default="NodePath(&quot;&quot;)" />
+			<description>
+				Sends a despawn 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 queue for deletion the node at [code]path[/code] and emit the signal [signal despawned]. In all other cases no deletion happens, and the signal [signal despawn_requested] is emitted instead.
+			</description>
+		</method>
+		<method name="send_spawn">
+			<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="Variant" default="null" />
+			<argument index="3" name="path" type="NodePath" default="NodePath(&quot;&quot;)" />
+			<description>
+				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="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>
+			</description>
+		</method>
+		<method name="spawn_config">
+			<return type="int" enum="Error" />
+			<argument index="0" name="scene_id" type="int" />
+			<argument index="1" name="spawn_mode" type="int" enum="MultiplayerReplicator.ReplicationMode" />
+			<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 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.
+				Tip: You can use a custom property in the scene main script to return a customly optimized state representation.
+			</description>
+		</method>
+	</methods>
+	<signals>
+		<signal name="despawn_requested">
+			<argument index="0" name="id" type="int" />
+			<argument index="1" name="scene_id" type="int" />
+			<argument index="2" name="parent" type="Node" />
+			<argument index="3" name="name" type="String" />
+			<argument index="4" name="data" type="PackedByteArray" />
+			<description>
+				Emitted when a network despawn request has been received from a client, or for a [PackedScene] that has been configured as [constant REPLICATION_MODE_CUSTOM].
+			</description>
+		</signal>
+		<signal name="despawned">
+			<argument index="0" name="scene_id" type="int" />
+			<argument index="1" name="node" type="Node" />
+			<description>
+				Emitted on a client before deleting a local Node upon receiving a despawn request from the server.
+			</description>
+		</signal>
+		<signal name="replicated_instance_added">
+			<argument index="0" name="scene_id" type="int" />
+			<argument index="1" name="node" type="Node" />
+			<description>
+				Emitted when an instance of a [PackedScene] that has been configured for networking enters the [SceneTree]. See [method spawn_config].
+			</description>
+		</signal>
+		<signal name="replicated_instance_removed">
+			<argument index="0" name="scene_id" type="int" />
+			<argument index="1" name="node" type="Node" />
+			<description>
+				Emitted when an instance of a [PackedScene] that has been configured for networking leaves the [SceneTree]. See [method spawn_config].
+			</description>
+		</signal>
+		<signal name="spawn_requested">
+			<argument index="0" name="id" type="int" />
+			<argument index="1" name="scene_id" type="int" />
+			<argument index="2" name="parent" type="Node" />
+			<argument index="3" name="name" type="String" />
+			<argument index="4" name="data" type="PackedByteArray" />
+			<description>
+				Emitted when a network spawn request has been received from a client, or for a [PackedScene] that has been configured as [constant REPLICATION_MODE_CUSTOM].
+			</description>
+		</signal>
+		<signal name="spawned">
+			<argument index="0" name="scene_id" type="int" />
+			<argument index="1" name="node" type="Node" />
+			<description>
+				Emitted on a client after a new Node is instantiated locally and added to the SceneTree upon receiving a spawn request from the server.
+			</description>
+		</signal>
+	</signals>
+	<constants>
+		<constant name="REPLICATION_MODE_NONE" value="0" enum="ReplicationMode">
+			Used with [method spawn_config] to identify a [PackedScene] that should not be replicated.
+		</constant>
+		<constant name="REPLICATION_MODE_SERVER" value="1" enum="ReplicationMode">
+			Used with [method spawn_config] to identify a [PackedScene] that should be automatically replicated from server to clients.
+		</constant>
+		<constant name="REPLICATION_MODE_CUSTOM" value="2" enum="ReplicationMode">
+			Used with [method spawn_config] to identify a [PackedScene] that can be manually replicated among peers.
+		</constant>
+	</constants>
+</class>