Merge pull request #39440 from simpuid/custom-profilers

Debugger Plugins in Godot

4 files changed, 256 insertions, 0 deletions

diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml
index 7f7df33471..570bf191c7 100644
--- a/doc/classes/@GlobalScope.xml
+++ b/doc/classes/@GlobalScope.xml
@@ -27,6 +27,9 @@
 		<member name="Engine" type="Engine" setter="" getter="">
 			The [Engine] singleton.
 		</member>
+		<member name="EngineDebugger" type="EngineDebugger" setter="" getter="">
+			The [EngineDebugger] singleton.
+		</member>
 		<member name="Geometry2D" type="Geometry2D" setter="" getter="">
 			The [Geometry2D] singleton.
 		</member>
diff --git a/doc/classes/EditorDebuggerPlugin.xml b/doc/classes/EditorDebuggerPlugin.xml
new file mode 100644
index 0000000000..b97933e582
--- /dev/null
+++ b/doc/classes/EditorDebuggerPlugin.xml
@@ -0,0 +1,103 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="EditorDebuggerPlugin" inherits="Control" version="4.0">
+	<brief_description>
+		A base class to implement debugger plugins.
+	</brief_description>
+	<description>
+		All debugger plugin scripts must extend [EditorDebuggerPlugin]. It provides functions related to editor side of debugger.
+		You don't need to instantiate this class. That is handled by the debugger itself. [Control] nodes can be added as child nodes to provide a GUI front-end for the plugin.
+		Do not queue_free/reparent it's instance otherwise the instance becomes unusable.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="has_capture">
+			<return type="bool">
+			</return>
+			<argument index="0" name="name" type="StringName">
+			</argument>
+			<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">
+			</return>
+			<description>
+				Returns [code]true[/code] if the game is in break state otherwise [code]false[/code].
+			</description>
+		</method>
+		<method name="is_debuggable">
+			<return type="bool">
+			</return>
+			<description>
+				Returns [code]true[/code] if the game can be debugged otherwise [code]false[/code].
+			</description>
+		</method>
+		<method name="is_session_active">
+			<return type="bool">
+			</return>
+			<description>
+				Returns [code]true[/code] if there is an instance of  the game running with the attached debugger otherwise [code]false[/code].
+			</description>
+		</method>
+		<method name="register_message_capture">
+			<return type="void">
+			</return>
+			<argument index="0" name="name" type="StringName">
+			</argument>
+			<argument index="1" name="callable" type="Callable">
+			</argument>
+			<description>
+				Registers a message capture with given [code]name[/code]. If [code]name[/code] 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].
+			</description>
+		</method>
+		<method name="send_message">
+			<return type="void">
+			</return>
+			<argument index="0" name="message" type="String">
+			</argument>
+			<argument index="1" name="data" type="Array">
+			</argument>
+			<description>
+				Sends a message with given [code]message[/code] and [code]data[/code] array.
+			</description>
+		</method>
+		<method name="unregister_message_capture">
+			<return type="void">
+			</return>
+			<argument index="0" name="name" type="StringName">
+			</argument>
+			<description>
+				Unregisters the message capture with given name.
+			</description>
+		</method>
+	</methods>
+	<signals>
+		<signal name="breaked">
+			<argument index="0" name="can_debug" type="bool">
+			</argument>
+			<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>
+	<constants>
+	</constants>
+</class>
diff --git a/doc/classes/EditorPlugin.xml b/doc/classes/EditorPlugin.xml
index 99fe9b4bb5..36076d8909 100644
--- a/doc/classes/EditorPlugin.xml
+++ b/doc/classes/EditorPlugin.xml
@@ -76,6 +76,15 @@
 				During run-time, this will be a simple object with a script so this function does not need to be called then.
 			</description>
 		</method>
+		<method name="add_debugger_plugin">
+			<return type="void">
+			</return>
+			<argument index="0" name="script" type="Script">
+			</argument>
+			<description>
+				Adds a [Script] as debugger plugin to the Debugger. The script must extend [EditorDebuggerPlugin].
+			</description>
+		</method>
 		<method name="add_export_plugin">
 			<return type="void">
 			</return>
@@ -424,6 +433,15 @@
 				Removes a custom type added by [method add_custom_type].
 			</description>
 		</method>
+		<method name="remove_debugger_plugin">
+			<return type="void">
+			</return>
+			<argument index="0" name="script" type="Script">
+			</argument>
+			<description>
+				Removes the debugger plugin with given script fromm the Debugger.
+			</description>
+		</method>
 		<method name="remove_export_plugin">
 			<return type="void">
 			</return>
diff --git a/doc/classes/EngineDebugger.xml b/doc/classes/EngineDebugger.xml
new file mode 100644
index 0000000000..7db36b89d0
--- /dev/null
+++ b/doc/classes/EngineDebugger.xml
@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="EngineDebugger" inherits="Object" version="4.0">
+	<brief_description>
+		Exposes the internal debugger.
+	</brief_description>
+	<description>
+		[EngineDebugger] handles the communication between the editor and the running game. It is active in the running game. Messages can be sent/received through it. It also manages the profilers.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="has_capture">
+			<return type="bool">
+			</return>
+			<argument index="0" name="name" type="StringName">
+			</argument>
+			<description>
+				Returns [code]true[/code] if a capture with the given name is present otherwise [code]false[/code].
+			</description>
+		</method>
+		<method name="has_profiler">
+			<return type="bool">
+			</return>
+			<argument index="0" name="name" type="StringName">
+			</argument>
+			<description>
+				Returns [code]true[/code] if a profiler with the given name is present otherwise [code]false[/code].
+			</description>
+		</method>
+		<method name="is_active">
+			<return type="bool">
+			</return>
+			<description>
+				Returns [code]true[/code] if the debugger is active otherwise [code]false[/code].
+			</description>
+		</method>
+		<method name="is_profiling">
+			<return type="bool">
+			</return>
+			<argument index="0" name="name" type="StringName">
+			</argument>
+			<description>
+				Returns [code]true[/code] if a profiler with the given name is present and active otherwise [code]false[/code].
+			</description>
+		</method>
+		<method name="profiler_add_frame_data">
+			<return type="void">
+			</return>
+			<argument index="0" name="name" type="StringName">
+			</argument>
+			<argument index="1" name="data" type="Array">
+			</argument>
+			<description>
+				Calls the [code]add[/code] callable of the profiler with given [code]name[/code] and [code]data[/code].
+			</description>
+		</method>
+		<method name="profiler_enable">
+			<return type="void">
+			</return>
+			<argument index="0" name="name" type="StringName">
+			</argument>
+			<argument index="1" name="enable" type="bool">
+			</argument>
+			<argument index="2" name="arguments" type="Array" default="[  ]">
+			</argument>
+			<description>
+				Calls the [code]toggle[/code] callable of the profiler with given [code]name[/code] and [code]arguments[/code]. Enables/Disables the same profiler depending on [code]enable[/code] argument.
+			</description>
+		</method>
+		<method name="register_message_capture">
+			<return type="void">
+			</return>
+			<argument index="0" name="name" type="StringName">
+			</argument>
+			<argument index="1" name="callable" type="Callable">
+			</argument>
+			<description>
+				Registers a message capture with given [code]name[/code]. If [code]name[/code] 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].
+			</description>
+		</method>
+		<method name="register_profiler">
+			<return type="void">
+			</return>
+			<argument index="0" name="name" type="StringName">
+			</argument>
+			<argument index="1" name="toggle" type="Callable">
+			</argument>
+			<argument index="2" name="add" type="Callable">
+			</argument>
+			<argument index="3" name="tick" type="Callable">
+			</argument>
+			<description>
+				Registers a profiler with the given [code]name[/code].
+				[code]toggle[/code] callable is called when the profiler is enabled/disabled. It must take an argument array as an argument.
+				[code]add[/code] callable is called when data is added to profiler using [method EngineDebugger.profiler_add_frame_data]. It must take a data array as argument.
+				[code]tick[/code] callable is called at every active profiler iteration. It must take frame time, idle time, physics time, and physics idle time as arguments.
+			</description>
+		</method>
+		<method name="send_message">
+			<return type="void">
+			</return>
+			<argument index="0" name="message" type="String">
+			</argument>
+			<argument index="1" name="data" type="Array">
+			</argument>
+			<description>
+				Sends a message with given [code]message[/code] and [code]data[/code] array.
+			</description>
+		</method>
+		<method name="unregister_message_capture">
+			<return type="void">
+			</return>
+			<argument index="0" name="name" type="StringName">
+			</argument>
+			<description>
+				Unregisters the message capture with given [code]name[/code].
+			</description>
+		</method>
+		<method name="unregister_profiler">
+			<return type="void">
+			</return>
+			<argument index="0" name="name" type="StringName">
+			</argument>
+			<description>
+				Unregisters a profiler with given [code]name[/code].
+			</description>
+		</method>
+	</methods>
+	<constants>
+	</constants>
+</class>