gdscript-debugging

name	gdscript-debugging
description	Diagnose Godot/GDScript failures by reproducing the scene lifecycle, reading engine/runtime evidence, tracing signals and references, isolating timing/state assumptions, and validating the fix in the real project.

GDScript Debugging

Use for GDScript errors, wrong scene behavior, missing signals, invalid references, lifecycle/timing bugs, state corruption, or intermittent engine-side behavior.

Procedure

1. Record the Godot version, project/scene, reproduction steps, editor versus exported/runtime context, exact error/warning, and whether the failure depends on reload, scene transition, input, frame/physics timing, or platform.
2. Reproduce from a known scene/project state before editing and inspect the full debugger/output/stack evidence instead of only the last message.
3. Trace node/resource ownership and lifecycle around the failure: when the object is instantiated, enters/exits tree, becomes ready, processes, emits/receives signals, is queued/freed, or survives a scene change.
4. Verify node/resource references and exported dependencies against the actual scene tree/instances. Check for stale references, duplicated instances, missing initialization, and assumptions about editor-only nodes/resources.
5. Trace signal connections and callbacks, including who connects, how many times, argument shape, object lifetime, and whether deferred/awaited work runs after the owning node changes or is freed.
6. Check state/timing boundaries: _process versus physics/update timing, deferred calls, async/await continuation, timers, animation events, input ordering, and scene changes as relevant to the actual Godot version/project.
7. Form one hypothesis and add the smallest logging/breakpoint/assertion or isolated reproduction needed to test it. Avoid rewriting scene architecture before locating the first bad state transition.
8. Apply the fix at the owning lifecycle/state boundary and clean up temporary diagnostics that would create noise.
9. Re-run the original flow plus scene reload/transition/restart or export path implicated by the bug, and check the editor/runtime for new warnings/errors.