Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify EngineDebugger and EditorDebugger* documentation #98378

Merged
merged 1 commit into from
Oct 25, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 26 additions & 6 deletions doc/classes/EditorDebuggerPlugin.xml
Original file line number Diff line number Diff line change
Expand Up @@ -15,18 +15,20 @@

class ExampleEditorDebugger extends EditorDebuggerPlugin:

func _has_capture(prefix):
# Return true if you wish to handle message with this prefix.
return prefix == "my_plugin"
func _has_capture(capture):
# Return true if you wish to handle messages with the prefix "my_plugin:".
return capture == "my_plugin"

func _capture(message, data, session_id):
if message == "my_plugin:ping":
get_session(session_id).send_message("my_plugin:echo", data)
return true
return false

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.name = "Example plugin" # Will be used as the tab title.
label.text = "Example plugin"
var session = get_session(session_id)
# Listens to the session started and stopped signals.
Expand All @@ -43,6 +45,24 @@
remove_debugger_plugin(debugger)
[/gdscript]
[/codeblocks]
To connect on the running game side, use the [EngineDebugger] singleton:
[codeblocks]
[gdscript]
extends Node

func _ready():
EngineDebugger.register_message_capture("my_plugin", _capture)
EngineDebugger.send_message("my_plugin:ping", ["test"])

func _capture(message, data):
# Note that the "my_plugin:" prefix is not used here.
if message == "echo":
prints("Echo received:", data)
return true
return false
[/gdscript]
[/codeblocks]
[b]Note:[/b] While the game is running, [method @GlobalScope.print] and similar functions [i]called in the editor[/i] do not print anything, the Output Log prints only game messages.
</description>
<tutorials>
</tutorials>
Expand All @@ -68,7 +88,7 @@
<param index="1" name="data" type="Array" />
<param index="2" name="session_id" type="int" />
<description>
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]).
Override this method to process incoming messages. The [param session_id] is the ID of the [EditorDebuggerSession] that received the [param message]. Use [method get_session] to retrieve the session. This method should return [code]true[/code] if the message is recognized.
</description>
</method>
<method name="_goto_script_line" qualifiers="virtual">
Expand All @@ -90,7 +110,7 @@
<return type="void" />
<param index="0" name="session_id" type="int" />
<description>
Override this method to be notified whenever a new [EditorDebuggerSession] is created (the session may be inactive during this stage).
Override this method to be notified whenever a new [EditorDebuggerSession] is created. Note that the session may be inactive during this stage.
</description>
</method>
<method name="get_session">
Expand Down
2 changes: 1 addition & 1 deletion doc/classes/EditorDebuggerSession.xml
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
<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.
Adds the given [param control] to the debug session UI in the debugger bottom panel. The [param control]'s node name will be used as the tab title.
</description>
</method>
<method name="is_active">
Expand Down
3 changes: 2 additions & 1 deletion doc/classes/EngineDebugger.xml
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,8 @@
<param index="1" name="callable" type="Callable" />
<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].
The callable must accept a message string and a data array as argument. The callable should return [code]true[/code] if the message is recognized.
[b]Note:[/b] The callable will receive the message with the prefix stripped, unlike [method EditorDebuggerPlugin._capture]. See the [EditorDebuggerPlugin] description for an example.
</description>
</method>
<method name="register_profiler">
Expand Down
2 changes: 1 addition & 1 deletion editor/debugger/script_editor_debugger.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -827,7 +827,7 @@ void ScriptEditorDebugger::_parse_message(const String &p_msg, uint64_t p_thread

bool parsed = EditorDebuggerNode::get_singleton()->plugins_capture(this, p_msg, p_data);
if (!parsed) {
WARN_PRINT("unknown message " + p_msg);
WARN_PRINT("Unknown message: " + p_msg);
}
}
}
Expand Down
Loading