Merge pull request #66938 from Faless/mp/4.x_debugger_split

[Editor] Better expose editor debugger plugins, use it in the multiplayer module.

3 files changed, 146 insertions, 60 deletions

diff --git a/doc/classes/EditorDebuggerPlugin.xml b/doc/classes/EditorDebuggerPlugin.xml
index c3e0a995c6..10da1edd56 100644
--- a/doc/classes/EditorDebuggerPlugin.xml
+++ b/doc/classes/EditorDebuggerPlugin.xml
@@ -1,88 +1,88 @@
 <?xml version="1.0" encoding="UTF-8" ?>
-<class name="EditorDebuggerPlugin" inherits="Control" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+<class name="EditorDebuggerPlugin" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
 		A base class to implement debugger plugins.
 	</brief_description>
 	<description>
 		[EditorDebuggerPlugin] provides functions related to the editor side of the debugger.
-		You don't need to instantiate this class; that is automatically handled by the debugger. [Control] nodes can be added as child nodes to provide a GUI for the plugin.
-		Do not free or reparent this node, otherwise it becomes unusable.
-		To use [EditorDebuggerPlugin], register it using the [method EditorPlugin.add_debugger_plugin] method first.
+		To interact with the debugger, an instance of this class must be added to the editor via [method EditorPlugin.add_debugger_plugin].
+		Once added, the [method _setup_session] callback will be called for every [EditorDebuggerSession] available to the plugin, and when new ones are created (the sessions may be inactive during this stage).
+		You can retrieve the available [EditorDebuggerSession]s via [method get_sessions] or get a specific one via [method get_session].
+		[codeblocks]
+		[gdscript]
+		@tool
+		extends EditorPlugin
+
+		class ExampleEditorDebugger extends EditorDebuggerPlugin:
+
+		    func _has_capture(prefix):
+		        # Return true if you wish to handle message with this prefix.
+		        return prefix == "my_plugin"
+
+		    func _capture(message, data, session_id):
+		        if message == "my_plugin:ping":
+		            get_session(session_id).send_message("my_plugin:echo", data)
+
+		    func _setup_session(session_id):
+		        # Add a new tab in the debugger session UI containing a label.
+		        var label = Label.new()
+		        label.name = "Example plugin"
+		        label.text = "Example plugin"
+		        var session = get_session(session_id)
+		        # Listens to the session started and stopped signals.
+		        session.started.connect(func (): print("Session started"))
+		        session.stopped.connect(func (): print("Session stopped"))
+		        session.add_session_tab(label)
+
+		var debugger = ExampleEditorDebugger.new()
+
+		func _enter_tree():
+		    add_debugger_plugin(debugger)
+
+		func _exit_tree():
+		    remove_debugger_plugin(debugger)
+		[/gdscript]
+		[/codeblocks]
 	</description>
 	<tutorials>
 	</tutorials>
 	<methods>
-		<method name="has_capture">
-			<return type="bool" />
-			<param index="0" name="name" type="StringName" />
-			<description>
-				Returns [code]true[/code] if a message capture with given name is present otherwise [code]false[/code].
-			</description>
-		</method>
-		<method name="is_breaked">
-			<return type="bool" />
-			<description>
-				Returns [code]true[/code] if the game is in break state otherwise [code]false[/code].
-			</description>
-		</method>
-		<method name="is_debuggable">
+		<method name="_capture" qualifiers="virtual">
 			<return type="bool" />
+			<param index="0" name="message" type="String" />
+			<param index="1" name="data" type="Array" />
+			<param index="2" name="session_id" type="int" />
 			<description>
-				Returns [code]true[/code] if the game can be debugged otherwise [code]false[/code].
+				Override this method to process incoming messages. The [param session_id] is the ID of the [EditorDebuggerSession] that received the message (which you can retrieve via [method get_session]).
 			</description>
 		</method>
-		<method name="is_session_active">
+		<method name="_has_capture" qualifiers="virtual const">
 			<return type="bool" />
+			<param index="0" name="capture" type="String" />
 			<description>
-				Returns [code]true[/code] if there is an instance of the game running with the attached debugger otherwise [code]false[/code].
+				Override this method to enable receiving messages from the debugger. If [param capture] is "my_message" then messages starting with "my_message:" will be passes to the [method _capture] method.
 			</description>
 		</method>
-		<method name="register_message_capture">
+		<method name="_setup_session" qualifiers="virtual">
 			<return type="void" />
-			<param index="0" name="name" type="StringName" />
-			<param index="1" name="callable" type="Callable" />
+			<param index="0" name="session_id" type="int" />
 			<description>
-				Registers a message capture with given [param name]. If [param name] is "my_message" then messages starting with "my_message:" will be called with the given callable.
-				Callable must accept a message string and a data array as argument. If the message and data are valid then callable must return [code]true[/code] otherwise [code]false[/code].
+				Override this method to be notified whenever a new [EditorDebuggerSession] is created (the session may be inactive during this stage).
 			</description>
 		</method>
-		<method name="send_message">
-			<return type="void" />
-			<param index="0" name="message" type="String" />
-			<param index="1" name="data" type="Array" />
+		<method name="get_session">
+			<return type="EditorDebuggerSession" />
+			<param index="0" name="id" type="int" />
 			<description>
-				Sends a message with given [param message] and [param data] array.
+				Returns the [EditorDebuggerSession] with the given [param id].
 			</description>
 		</method>
-		<method name="unregister_message_capture">
-			<return type="void" />
-			<param index="0" name="name" type="StringName" />
+		<method name="get_sessions">
+			<return type="Array" />
 			<description>
-				Unregisters the message capture with given name.
+				Returns an array of [EditorDebuggerSession] currently available to this debugger plugin.
+				Note: Not sessions in the array may be inactive, check their state via [method EditorDebuggerSession.is_active]
 			</description>
 		</method>
 	</methods>
-	<signals>
-		<signal name="breaked">
-			<param index="0" name="can_debug" type="bool" />
-			<description>
-				Emitted when the game enters a break state.
-			</description>
-		</signal>
-		<signal name="continued">
-			<description>
-				Emitted when the game exists a break state.
-			</description>
-		</signal>
-		<signal name="started">
-			<description>
-				Emitted when the debugging starts.
-			</description>
-		</signal>
-		<signal name="stopped">
-			<description>
-				Emitted when the debugging stops.
-			</description>
-		</signal>
-	</signals>
 </class>
diff --git a/doc/classes/EditorDebuggerSession.xml b/doc/classes/EditorDebuggerSession.xml
new file mode 100644
index 0000000000..faf528c143
--- /dev/null
+++ b/doc/classes/EditorDebuggerSession.xml
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="EditorDebuggerSession" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		A class to interact with the editor debugger.
+	</brief_description>
+	<description>
+		This class cannot be directly instantiated and must be retrieved via a [EditorDebuggerPlugin].
+		You can add tabs to the session UI via [method add_session_tab], send messages via [method send_message], and toggle [EngineProfiler]s via [method toggle_profiler].
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="add_session_tab">
+			<return type="void" />
+			<param index="0" name="control" type="Control" />
+			<description>
+				Adds the given [param control] to the debug session UI in the debugger bottom panel.
+			</description>
+		</method>
+		<method name="is_active">
+			<return type="bool" />
+			<description>
+				Returns [code]true[/code] if the debug session is currently attached to a remote instance.
+			</description>
+		</method>
+		<method name="is_breaked">
+			<return type="bool" />
+			<description>
+				Returns [code]true[/code] if the attached remote instance is currently in the debug loop.
+			</description>
+		</method>
+		<method name="is_debuggable">
+			<return type="bool" />
+			<description>
+				Returns [code]true[/code] if the attached remote instance can be debugged.
+			</description>
+		</method>
+		<method name="remove_session_tab">
+			<return type="void" />
+			<param index="0" name="control" type="Control" />
+			<description>
+				Removes the given [param control] from the debug session UI in the debugger bottom panel.
+			</description>
+		</method>
+		<method name="send_message">
+			<return type="void" />
+			<param index="0" name="message" type="String" />
+			<param index="1" name="data" type="Array" default="[]" />
+			<description>
+				Sends the given [param message] to the attached remote instance, optionally passing additionally [param data]. See [EngineDebugger] for how to retrieve those messages.
+			</description>
+		</method>
+		<method name="toggle_profiler">
+			<return type="void" />
+			<param index="0" name="profiler" type="String" />
+			<param index="1" name="enable" type="bool" />
+			<param index="2" name="data" type="Array" default="[]" />
+			<description>
+				Toggle the given [param profiler] on the attached remote instance, optionally passing additionally [param data]. See [EngineProfiler] for more details.
+			</description>
+		</method>
+	</methods>
+	<signals>
+		<signal name="breaked">
+			<param index="0" name="can_debug" type="bool" />
+			<description>
+				Emitted when the attached remote instance enters a break state. If [param can_debug] is [code]true[/code], the remote instance will enter the debug loop.
+			</description>
+		</signal>
+		<signal name="continued">
+			<description>
+				Emitted when the attached remote instance exits a break state.
+			</description>
+		</signal>
+		<signal name="started">
+			<description>
+				Emitted when a remote instance is attached to this session (i.e. the session becomes active).
+			</description>
+		</signal>
+		<signal name="stopped">
+			<description>
+				Emitted when a remote instance is detached from this session (i.e. the session becomes inactive).
+			</description>
+		</signal>
+	</signals>
+</class>
diff --git a/doc/classes/EditorPlugin.xml b/doc/classes/EditorPlugin.xml
index 2289a373bf..806588d100 100644
--- a/doc/classes/EditorPlugin.xml
+++ b/doc/classes/EditorPlugin.xml
@@ -415,7 +415,7 @@
 		</method>
 		<method name="add_debugger_plugin">
 			<return type="void" />
-			<param index="0" name="script" type="Script" />
+			<param index="0" name="script" type="EditorDebuggerPlugin" />
 			<description>
 				Adds a [Script] as debugger plugin to the Debugger. The script must extend [EditorDebuggerPlugin].
 			</description>
@@ -599,7 +599,7 @@
 		</method>
 		<method name="remove_debugger_plugin">
 			<return type="void" />
-			<param index="0" name="script" type="Script" />
+			<param index="0" name="script" type="EditorDebuggerPlugin" />
 			<description>
 				Removes the debugger plugin with given script from the Debugger.
 			</description>