From d568b25e366cd99fa7479e054ad4f7fcb5079501 Mon Sep 17 00:00:00 2001 From: Fabio Alessandrelli Date: Mon, 3 Oct 2022 15:21:25 +0200 Subject: [Editor] Better expose EditorDebuggerPlugin. Now splitted into two classes: - EditorDebuggerPlugin (RefCounted). - EditorDebuggerSession (abstract). This allows the EditorPlugin to be in control of the debugger plugin lifecycle, be notified when sessions are created, and customize each of them independently. We should slowly transition the various profilers and captures in ScriptEditorDebugger to their own plugins, and decouple ScriptEditorDebugger from it's UI part (making it the "real" EditorDebuggerSession potentially dropping the wrappers). --- doc/classes/EditorDebuggerPlugin.xml | 116 +++++++++++++++++----------------- doc/classes/EditorDebuggerSession.xml | 86 +++++++++++++++++++++++++ doc/classes/EditorPlugin.xml | 4 +- 3 files changed, 146 insertions(+), 60 deletions(-) create mode 100644 doc/classes/EditorDebuggerSession.xml (limited to 'doc') 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 @@ - + A base class to implement debugger plugins. [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] - - - - - Returns [code]true[/code] if a message capture with given name is present otherwise [code]false[/code]. - - - - - - Returns [code]true[/code] if the game is in break state otherwise [code]false[/code]. - - - + + + + - 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]). - + + - 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. - + - - + - 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). - - - - + + + - Sends a message with given [param message] and [param data] array. + Returns the [EditorDebuggerSession] with the given [param id]. - - - + + - 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] - - - - - Emitted when the game enters a break state. - - - - - Emitted when the game exists a break state. - - - - - Emitted when the debugging starts. - - - - - Emitted when the debugging stops. - - - 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 @@ + + + + A class to interact with the editor debugger. + + + 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]. + + + + + + + + + Adds the given [param control] to the debug session UI in the debugger bottom panel. + + + + + + Returns [code]true[/code] if the debug session is currently attached to a remote instance. + + + + + + Returns [code]true[/code] if the attached remote instance is currently in the debug loop. + + + + + + Returns [code]true[/code] if the attached remote instance can be debugged. + + + + + + + Removes the given [param control] from the debug session UI in the debugger bottom panel. + + + + + + + + Sends the given [param message] to the attached remote instance, optionally passing additionally [param data]. See [EngineDebugger] for how to retrieve those messages. + + + + + + + + + Toggle the given [param profiler] on the attached remote instance, optionally passing additionally [param data]. See [EngineProfiler] for more details. + + + + + + + + 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. + + + + + Emitted when the attached remote instance exits a break state. + + + + + Emitted when a remote instance is attached to this session (i.e. the session becomes active). + + + + + Emitted when a remote instance is detached from this session (i.e. the session becomes inactive). + + + + 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 @@ - + Adds a [Script] as debugger plugin to the Debugger. The script must extend [EditorDebuggerPlugin]. @@ -599,7 +599,7 @@ - + Removes the debugger plugin with given script from the Debugger. -- cgit v1.2.3