[Net] Allow branch-specific MultiplayerAPIs.

Removes custom_multiplayer from Node.
MultiplayerAPI overrides are now set at SceneTree level, and apply to
whole branches.
Impact on performance when using only the default multiplayer or
overriding it is minimal, the use of branches can likely be further
optimized by caching nodes and relevant MultiplayerAPI IDs.

3 files changed, 18 insertions, 9 deletions

diff --git a/doc/classes/MultiplayerAPI.xml b/doc/classes/MultiplayerAPI.xml
index ac17886183..059d147979 100644
--- a/doc/classes/MultiplayerAPI.xml
+++ b/doc/classes/MultiplayerAPI.xml
@@ -6,7 +6,7 @@
 	<description>
 		This class implements the high-level multiplayer API. See also [MultiplayerPeer].
 		By default, [SceneTree] has a reference to this class that is used to provide multiplayer capabilities (i.e. RPCs) across the whole scene.
-		It is possible to override the MultiplayerAPI instance used by specific Nodes by setting the [member Node.custom_multiplayer] property, effectively allowing to run both client and server in the same scene.
+		It is possible to override the MultiplayerAPI instance used by specific tree branches by calling the [method SceneTree.set_multiplayer] method, effectively allowing to run both client and server in the same scene.
 		[b]Note:[/b] The high-level multiplayer API protocol is an implementation detail and isn't meant to be used by non-Godot servers. It may change without notice.
 		[b]Note:[/b] When exporting to Android, make sure to enable the [code]INTERNET[/code] permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android.
 	</description>
@@ -53,7 +53,7 @@
 		<method name="poll">
 			<return type="void" />
 			<description>
-				Method used for polling the MultiplayerAPI. You only need to worry about this if you are using [member Node.custom_multiplayer] override or you set [member SceneTree.multiplayer_poll] to [code]false[/code]. By default, [SceneTree] will poll its MultiplayerAPI for you.
+				Method used for polling the MultiplayerAPI. You only need to worry about this if you set [member SceneTree.multiplayer_poll] to [code]false[/code]. By default, [SceneTree] will poll its MultiplayerAPI(s) for you.
 				[b]Note:[/b] This method results in RPCs being called, so they will be executed in the same context of this function (e.g. [code]_process[/code], [code]physics[/code], [Thread]).
 			</description>
 		</method>
diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml
index 56c80078b3..c9795856d5 100644
--- a/doc/classes/Node.xml
+++ b/doc/classes/Node.xml
@@ -745,14 +745,11 @@
 		</method>
 	</methods>
 	<members>
-		<member name="custom_multiplayer" type="MultiplayerAPI" setter="set_custom_multiplayer" getter="get_custom_multiplayer">
-			The override to the default [MultiplayerAPI]. Set to [code]null[/code] to use the default [SceneTree] one.
-		</member>
 		<member name="editor_description" type="String" setter="set_editor_description" getter="get_editor_description" default="&quot;&quot;">
 			Add a custom description to a node. It will be displayed in a tooltip when hovered in editor's scene tree.
 		</member>
 		<member name="multiplayer" type="MultiplayerAPI" setter="" getter="get_multiplayer">
-			The [MultiplayerAPI] instance associated with this node. Either the [member custom_multiplayer], or the default SceneTree one (if inside tree).
+			The [MultiplayerAPI] instance associated with this node. See [method SceneTree.get_multiplayer].
 		</member>
 		<member name="name" type="StringName" setter="set_name" getter="get_name">
 			The name of the node. This name is unique among the siblings (other child nodes from the same parent). When set to an existing name, the node will be automatically renamed.
diff --git a/doc/classes/SceneTree.xml b/doc/classes/SceneTree.xml
index 77023d2126..ddff766b17 100644
--- a/doc/classes/SceneTree.xml
+++ b/doc/classes/SceneTree.xml
@@ -99,6 +99,13 @@
 				Returns the current frame number, i.e. the total frame count since the application started.
 			</description>
 		</method>
+		<method name="get_multiplayer" qualifiers="const">
+			<return type="MultiplayerAPI" />
+			<argument index="0" name="for_path" type="NodePath" default="NodePath(&quot;&quot;)" />
+			<description>
+				Return the [MultiplayerAPI] configured for the given path, or the default one if [code]for_path[/code] is empty.
+			</description>
+		</method>
 		<method name="get_node_count" qualifiers="const">
 			<return type="int" />
 			<description>
@@ -193,6 +200,14 @@
 				Sets the given [code]property[/code] to [code]value[/code] on all members of the given group, respecting the given [enum GroupCallFlags].
 			</description>
 		</method>
+		<method name="set_multiplayer">
+			<return type="void" />
+			<argument index="0" name="multiplayer" type="MultiplayerAPI" />
+			<argument index="1" name="root_path" type="NodePath" default="NodePath(&quot;&quot;)" />
+			<description>
+				Sets a custom [MultiplayerAPI] with the given [code]root_path[/code] (controlling also the relative subpaths), or override the default one if [code]root_path[/code] is empty.
+			</description>
+		</method>
 		<method name="set_quit_on_go_back">
 			<return type="void" />
 			<argument index="0" name="enabled" type="bool" />
@@ -215,9 +230,6 @@
 		<member name="edited_scene_root" type="Node" setter="set_edited_scene_root" getter="get_edited_scene_root">
 			The root of the edited scene.
 		</member>
-		<member name="multiplayer" type="MultiplayerAPI" setter="set_multiplayer" getter="get_multiplayer">
-			The default [MultiplayerAPI] instance for this [SceneTree].
-		</member>
 		<member name="multiplayer_poll" type="bool" setter="set_multiplayer_poll_enabled" getter="is_multiplayer_poll_enabled" default="true">
 			If [code]true[/code] (default value), enables automatic polling of the [MultiplayerAPI] for this SceneTree during [signal process_frame].
 			If [code]false[/code], you need to manually call [method MultiplayerAPI.poll] to process network packets and deliver RPCs. This allows running RPCs in a different loop (e.g. physics, thread, specific time step) and for manual [Mutex] protection when accessing the [MultiplayerAPI] from threads.