godot-debugging
Debugging workflow for Godot 4.x: print vs push_error, editor output window, debugger panel, profiling with built-in profiler, network debugging, export/build troubleshooting. Use when debugging Godot games or resolving Godot-specific errors.
How do I install this agent skill?
npx skills add https://github.com/vl4dt/godot-skills --skill godot-debuggingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a comprehensive debugging guide and utility functions for the Godot Game Engine (4.x), focusing on error handling, profiling, and network diagnostics.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Godot Debugging Guide
Comprehensive debugging workflow and common issue resolution for Godot 4.x.
Output Methods
print() vs push_error() vs push_warning()
# print() — General output, filtered in editor output
print("Debug: position = ", position)
print("Debug: player health = ", player_health)
# printf-style formatting
printf("Player %s has %d health", player_name, health)
# push_error() — Shows in red, includes file and line number
push_error("Failed to load resource: ", resource_path)
# push_warning() — Shows in yellow, non-fatal issues
push_warning("Missing animation for state: ", state)
# load() returns null on failure — check before use
var data = load(risky_path)
if data == null:
push_error("Could not load resource at: %s" % risky_path)
# Or with ResourceLoader for error codes
var err, data = ResourceLoader.load_interactive(risky_path)
if err != OK:
push_error("Failed to load: %s (error code %d)" % [risky_path, err])
Editor Output Window
Access via Window > Debugger or Debug > Start Debugging. The output panel shows:
- Standard print output (gray)
- Warnings (yellow)
- Errors (red) with file/line info
- Custom logger messages
Debugger Panel
Built-in Debugger Features
- Scene Tree — Visual tree of current scene with property inspection
- Resources — List of loaded resources, check for leaks
- Profiler — CPU and GPU usage breakdown
- Remote Transform — Edit node properties in running scenes
- Network Profiler — Monitor multiplayer traffic
Remote Debugging
# Connect to remote scene tree from editor
# When running in debug mode (F6), the editor connects automatically
# Access remote nodes
func get_remote_node(path: String):
var node = get_node(path) # Works on local and remote
return node
Profiling Workflow
CPU Profiler
Profile > Start Profiling in the editor
Then view: Profile > CPU Usage or Profile > Frame Time Graph
Key metrics:
- Frame time — Should be under 16.67ms for 60fps
- Physics FPS — Should match target (usually 60)
- Script time — Time spent in GDScript/C# code
- Draw calls — Number of GPU draw calls per frame
Memory Profiler
Profile > Memory Usage
Check for:
- Growing resource count over time
- Unfreed scene instances
- Large textures not being unloaded
GPU Profiler
Project Settings > Rendering > Debug > GPU Profiling = On
Then: Profile > GPU Usage
Common Error Patterns & Fixes
"Script class 'XXX' does not exist in current project"
- Cause: Autoload script reference broken after rename/move
- Fix: Re-add the autoload in Project Settings > Autoload
"Cannot instantiate non-imported scene: res://..."
- Cause: Scene file not saved or path is incorrect
- Fix: Open the scene in editor and save it, verify path
"Invalid get index 'XXX' (on base: 'Node2D')"
- Cause: Accessing a property that doesn't exist on the node
- Fix: Check node type and available properties, use
has_method()oris()checks
"Failed to connect signal"
- Cause: Method name mismatch or signal doesn't exist
- Fix: Verify signal exists on source node, check method signature matches
Export/Build Errors
| Error | Cause | Fix |
|---|---|---|
| "Export failed with code -1" | Missing export preset config | Re-create export preset |
| "Android build failed" | SDK/NDK path wrong | Check Project Settings > Android |
| "HTML5 export failed" | Emscripten not installed | Install Godot HTML5 export template |
| "Windows export failed" | MSVC not installed | Install Visual Studio Build Tools |
Network Debugging
Multiplayer API Inspection
# Check connection status
print("Connected: ", Network.multiplayer.is_connected_to_server())
print("Peer count: ", Network.multiplayer.get_peers().size())
# Log RPC calls for debugging
func _rpc_debug_message(msg):
print("[RPC] ", msg)
# Monitor network traffic
# Use Profile > Network Profiler in the editor
Lag Compensation Debugging
# Log timing information
print("Server time: ", get_tree().get_network_unique_id())
print("Local latency: ", Network.multiplayer.get_connection_status())
Godot 4.7 Debugging Notes
- Perfetto tracing — New built-in Android profiler for detailed performance analysis
- New editor log improvements — Better error messages with more context
- tween_await() debugging — Use
awaitbreakpoints in C# debugger for animation sequences
Debug Utility Functions
class_name DebugUtils extends Node
static func draw_rect_debug(rect: Rect2, color: Color, lifetime: float = 0.0):
# Draw debug rectangle (use with CanvasItem.draw_rect)
pass
static func log_tree(node: Node, indent: int = 0):
# Print scene tree for debugging
var prefix = " ".repeat(indent)
print(prefix + node.name, " (", node.get_class(), ")")
for child in node.get_children():
log_tree(child, indent + 1)
static func check_node_ready(node: Node):
# Verify node is ready before accessing children
if not node.is_inside_tree():
push_error("Node not in tree: ", node.name)
return node.is_inside_tree()
MCP Bridge Tools (Optional — Live Editor Integration)
When the MCP bridge is running (Phase 2), these tools provide live debugging capabilities:
debugger_output— Read real-time debugger output from the running sceneoutput_log— Read Godot's output log with level filtering (error/warning/info)scene_run/scene_stop— Start and stop scenes for testing fixespause_resume— Pause execution to inspect state at breakpointsscript_validate— Validate scripts without leaving the agent workflowscene_tree— Inspect runtime scene hierarchy for missing nodes
Note: MCP tools require the Godot editor to be running with the MCP plugin enabled. Skills work independently without the bridge.
References
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/vl4dt/godot-skills/godot-debugging">View godot-debugging on skillZs</a>