godot-debugging_skill

Overview

This skill provides expert Godot debugging guidance to diagnose and fix errors, crashes, and unexpected behavior. It focuses on interpreting error messages, common root causes, and step-by-step fixes across parsing, runtime, scene tree, signals, resources, performance, and memory issues. Use it when you need concrete troubleshooting steps or code-level corrections.

How this skill works

I inspect the error message, identify the most likely cause, and propose minimal, practical fixes you can apply immediately. I cover syntax and parser errors, null-reference and index issues, node path and signal mistakes, resource loading problems, performance hotspots, and memory leaks. I also recommend debugging techniques like print traces, breakpoints, the remote debugger, asserts, and debug drawing to validate fixes.

When to use it

• When you see a Godot error or crash message
• When code behaves unexpectedly or returns null references
• When nodes are not found or signals fail to connect
• When performance drops or memory usage keeps growing
• When migrating projects between Godot 3 and 4
• When you want concrete, testable fixes for common bugs

Best practices

• Read the full error and stack trace before editing code
• Use @onready and get_node_or_null to avoid null references
• Protect operations with null checks or is_instance_valid
• Defer scene changes with call_deferred when modifying the tree during callbacks
• Cache expensive lookups and reduce per-frame work with timers
• Use asserts and debug-only checks; remove heavy debug code in release builds

Example use cases

• Fixing a parser error caused by a missing colon or bad indentation
• Resolving 'Attempt to call function on null instance' by validating node paths or onready setup
• Stopping index out of range crashes by checking array sizes before access
• Preventing 'Can't change state while flushing queries' by using call_deferred for queue_free or add_child
• Tracking memory leaks with object pooling and clearing circular references
• Updating Godot 3 code to Godot 4 node and API changes