{"id":101315,"plugin_id":"plugin_asdk_app_6ae4dce05e848191869076c72aec15cc","kind":"skill","collection_source":"plugin_package","comparison_source":null,"observed_at":"2026-11-17T12:11:07.807Z","digest":"d025bcd859f632a174d675eba045f45405469c86129501f55a3885732d6805b3","against":null,"payload":{"description":"For Exekite-hosted Godot games only. Instrumenting a headless Godot run — print/push_error, reading the gate's quoted engine output, and the silent-failure classes (signal with no listener, layer/mask 0, node never added to the tree, _ready order, dangling await). Use when code parses and boots but behaves wrongly.","included_files":[],"name":"debugging-godot","skill_md_contents":"---\nname: debugging-godot\ndescription: \"For Exekite-hosted Godot games only. Instrumenting a headless Godot run — print/push_error, reading the gate's quoted engine output, and the silent-failure classes (signal with no listener, layer/mask 0, node never added to the tree, _ready order, dangling await). Use when code parses and boots but behaves wrongly.\"\n---\n\n# Debugging Godot 4\n\nMost Godot bugs aren't compile errors — they're silent ones. A signal that isn't connected. A collision mask of 0. A scene that loaded but wasn't added to the tree. The code looks right; nothing happens.\n\n## Print and inspect\n\n```gdscript\nprint(\"Player jumped, velocity = \", velocity)\nprint_debug(\"inventory state:\", inventory)        # adds an \"At:\" line after it\npush_warning(\"falling back to defaults\")\npush_error(\"save file corrupt — resetting\")       # also flagged in editor\n```\n\n`print_debug` is the most useful: it's the same as `print` but APPENDS the\nsource location on its own indented line. Measured on 4.6.1,\n`print_debug(\"x\")` prints\n\n```\nx\n   At: res://probe.gd:3:_init()\n```\n\n— after the message, not before it, and with the function name. So a grep for\nyour marker shows the message and not the location; grep with `-A 1`. It is\ndebug-build only (`OS.is_debug_build()`), which every gate and rig run is. Use\nit liberally during a hunt; remove afterward.\n\n## Where output actually goes\n\nThere is no editor here, so there are no docks, no breakpoints and no live\nscene tree. The game runs headless and everything you learn comes from two\nplaces:\n\n- **stdout/stderr from the run.** `print()` and `push_error()` land there, and\n  the gate's boot and playtest tiers capture them. An engine error looks like\n  `SCRIPT ERROR: Invalid call. Nonexistent function 'x' in base 'Nil'.`\n- **The gate's own verdict**, which names the tier that failed and quotes the\n  engine text. That is the same output, already read for you.\n\nSo instrument, run, and read — there is nothing to step through.\n\n## Common silent failures and how to catch them\n\n### Signal not connected\n\n```gdscript\nsignal coin_collected(amount: int)\n\nfunc collect() -> void:\n    coin_collected.emit(1)   # fires into the void if no listener\n```\n\nCatch at runtime:\n```gdscript\nprint(\"connections: \", coin_collected.get_connections())\n```\n\nAn empty array at the moment of emit is the bug — connect before the first emit, or emit deferred.\n\n### Layer/mask = 0 (or wrong)\n\nA body in layer 1 with mask 0 doesn't detect any collisions. An Area2D with no mask doesn't see any bodies.\n\nQuick sanity check:\n```gdscript\nprint(name, \" layer=\", collision_layer, \" mask=\", collision_mask)\n```\n\n### Node never added to tree\n\nA scene `instantiate()`-ed but never `add_child`-ed never `_ready`s. Symptoms: signals you connected don't fire, `_process` never runs, nothing visible. Always pair `instantiate` with `add_child`.\n\n```gdscript\nvar inst := scene.instantiate()\nadd_child(inst)               # ← THIS\ninst.global_position = pos\n```\n\n### `_ready` order\n\n`_ready` runs from leaves up. A parent's `_ready` runs after all its children's `_ready`s. If a parent connects to a child's signal in `_ready`, the child has already `_ready`-ed; if the child emits in `_ready`, the parent missed it.\n\nSolution: have the parent connect from `_enter_tree` (which runs top-down, before any child's `_ready`), or have the child `call_deferred` its emit so the parent has wired up first.\n\n### `await` consumed by the wrong thing\n\n```gdscript\n# BUG: waiting for the WRONG node's signal\nawait get_node(\"OtherTimer\").timeout      # never fires; we wanted OUR timer\n\n# FIX: store the timer reference\nvar t := Timer.new()\nadd_child(t)\nt.start(1.0)\nawait t.timeout\n```\n\nPrint the signal source before `await` if confused: `print(\"awaiting \", t, \" timeout\")`.\n\n### Scene structure mismatch\n\n`@onready var sprite: Sprite2D = $Sprite2D` fails silently (returns null) if the child node was renamed. Symptoms: null reference errors on the next line that uses `sprite`.\n\nA renamed child makes `$Sprite2D` log `Node not found: \"Sprite2D\"` at runtime and leaves the var null — the boot tier's stderr shows it. When an @onready var is null, diff the node names in the `.tscn` against the paths in the script.\n\n### Visible but no input\n\nA plain `Control`'s default `mouse_filter` is `MOUSE_FILTER_STOP` — a full-rect panel left at the default silently consumes every click over it. `MOUSE_FILTER_PASS` lets clicks through; `MOUSE_FILTER_IGNORE` makes it transparent to input entirely. A button that \"doesn't respond to clicks\" usually has a sibling Control at the STOP default covering it.\n\nPrint `get_global_rect()` on the button and each sibling Control to find the one covering it.\n\n### Pause behavior\n\nFor pause `process_mode` rules, read [startability-and-input-gates](../startability-and-input-gates/SKILL.md). One extra mode: `PROCESS_MODE_WHEN_PAUSED` runs a node ONLY while paused (pause-screen-only animations).\n\n## Debug visualizations\n\nThere is no editor toggle here — when a shape seems misaligned or zero-area (\"I set up the collision but it doesn't trigger\"), print the CollisionShape2D's `shape.size`/`global_position`, or draw its outline with the `_draw()` overlay below.\n\nFor shipping debug overlays, draw to a `_draw()` callback on a CanvasItem:\n\n```gdscript\nextends Node2D\n\nfunc _ready() -> void:\n    set_process(true)\n\nfunc _process(_delta: float) -> void:\n    queue_redraw()\n\nfunc _draw() -> void:\n    var player := get_tree().get_first_node_in_group(\"player\")\n    if not player: return\n    draw_circle(player.global_position - global_position, 4, Color.RED)\n    draw_string(ThemeDB.fallback_font, player.global_position - global_position + Vector2(8, -8),\n        \"v=%s\" % player.velocity, HORIZONTAL_ALIGNMENT_LEFT, -1, 12)\n```\n\nDisable in production via a feature tag or a simple `const DEBUG := false`.\n\n## When something is slow\n\nNo profiler either. Measure in code, over a window rather than a frame:\n\n```gdscript\nvar _t := 0.0\nvar _frames := 0\n\nfunc _process(delta: float) -> void:\n    _t += delta\n    _frames += 1\n    if _t >= 1.0:\n        print(\"fps ~\", _frames, \"  nodes: \", get_tree().get_node_count())\n        _t = 0.0\n        _frames = 0\n```\n\nThe usual culprits, in the order they are usually true: work done per-frame\nthat could be done once (building a texture, allocating an array), a `for` loop\nover every node each frame, and `sin()`/`cos()` tables recomputed instead of\ncached. `get_node()` in `_process` is cheap but not free — bind it with\n`@onready` once.\n\n## When the game will not boot at all\n\nThe recovery procedure that used to be here began \"open `project.godot` in a\ntext editor and delete the `[autoload]` line\". You may not write that file —\nthe operation refuses forbidden writes. Read the returned turn state rather\nthan assuming a refusal rolled back the draft. The version that works here:\n\n1. Read the gate's error. It names the tier and quotes the engine.\n2. Run the parse check over the files you touched. A cascade usually has ONE\n   real cause: the file that declares the `class_name` everything else refers to.\n3. If a scene will not load, read the `.tscn` as text — an `[ext_resource]`\n   pointing at a path you renamed is visible on inspection.\n4. Comment out the suspect node's script line in the `.tscn` and re-run, rather\n   than deleting the node. A missing node breaks every `@onready` that referred\n   to it and buries the original error under new ones.\n\n## Anti-patterns in debugging\n\n- `print` scattered without reading the result. The gate already quotes engine output — instrument the one suspect narrowly, run, and read what came back before adding more prints.\n- Removing all `print_debug`s before testing the next case. Leave the diagnostic ones until the bug's confirmed dead.\n- \"It works in editor\". Web export and headless Godot have different behavior — the shipped game runs single-threaded WebGL2 (`gl_compatibility`) in a browser tab; test assumptions against that target.\n- Adding an \"if debug:\" branch that's `true` by default and ships to production. Use `OS.is_debug_build()` or a `const DEBUG`.\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}