godot-headless-verify

SKILL.md 节选

# Godot Headless Verify & Repair

> A pocket toolkit of **reproducible CLI recipes** for Godot 4 projects.
> Every recipe here is a copy-paste-ready one-liner (or short script) that
> exercises the engine without opening the editor. Use these instead of
> asking the user "can you open the editor and…" — that's slower and
> lossy.

---

## 0. The one-binary convention

Every recipe assumes you can reach Godot via either `$GODOT` env var or
its standard macOS location. Prefix every command with:

```bash
GODOT="${GODOT:-/Applications/Godot.app/Contents/MacOS/Godot}"
```

On Linux / Windows, set `$GODOT` to your binary. **Never** hard-code
`godot4` or `/opt/godot/...` in scripts — it breaks across machines.

---

## 1. Recipe: cache clean (safe)

**When**: editor shows `Cannot open file 'res://…'` or
`referenced non-existent resource` *even though the file exists*, typically
after a refactor / folder rename / branch swap.

**Why**: `.godot/imported/` and `.godot/uid_cache.bin` remember pre-move
paths. Godot doesn't self-heal until you force a rebuild.

```bash
# Requires: editor closed.
cd <project-root>

# Safe cache reset — preserves window layout + per-file folding state.
rm -rf .godot/imported \
       .godot/uid_cache.bin \
       .godot/global_script_class_cache.cfg \
       .godot/scene_groups_cache.cfg \
       .godot/editor/filesystem_cache* \
       .godot/editor/filesystem_update_* \
       .godot/editor/filesystem_update[0-9]*
# (zsh note: use `setopt NULL_GLOB` or run in bash if the * patterns
#  don't match anything and zsh complains)

# Rebuild cache headlessly (takes 30s-2min depending on project size).
"$GODOT" --headless --import --path .
```

**Keep these** (do NOT rm):
- `.godot/shader_cache/` — compiled shaders, expensive to rebuild
- `.godot/editor/*-folding-*.cfg` — per-file UI state
- `.godot/editor/editor_layout.cfg` — window layout

---

## 2. Recipe: scene-load smoke test

**When**: you just refactored something and want a 5-second "does it still
load?" answer before bothering with the full editor.

```bash
cat > /tmp/smoke.gd <<'EOF'
extends SceneTree

# Edit the paths you want to smoke-test:
const SCENES := [
    "res://scenes/boot/main.tscn",
    "res://scenes/levels/arena/arena.tscn",
    "res://scenes/levels/forest/forest.tscn",
]

func _initialize() -> void:
    var failed := 0
    for s in SCENES:
        var ps := load(s) as PackedScene
        if ps == null:
            push_error("FAIL load: %s" % s); failed += 1; continue
        var inst := ps.instantiate()
        if inst == null:
            push_error("FAIL instantiate: %s" % s); failed += 1; continue
        print("OK %s (children=%d)" % [s, inst.get_child_count()])
        inst.queue_free()
    quit(0 if failed == 0 else 1)
EOF

GODOT="${GODOT:-/Applications/Godot.app/Contents/MacOS/Godot}"
"$GODOT" --headless --path . --script /tmp/smoke.gd \
    2>&1 | grep -E 'ERROR|OK '

rm -f /tmp/smoke.gd
```

**Exit code** is 0 iff every scene loaded. Good for CI.

**Important**: `/tmp/smoke.gd` is outside the project, so Godot can't
resolve `res://` in its own script path. Always pass the full `/tmp/...`
filesystem path via `--script`. Don't put it inside `tools/` without the
matching `.uid` sidecar (pre-commit hook will otherwise complain).

---

## 3. Recipe: script-only parse check

**When**: you edited a bunch of `.gd` files and want to confirm they all
parse without opening the editor.

```bash
# --check-only runs the GDScript parser over all scripts the project
# touches; no scene is instantiated.
"$GODOT" --headless --quit --path . 2>&1 \
    | grep -iE 'SCRIPT ERROR|Parse Error' || echo "all scripts parse OK"
```

Note: `--quit` without a script exits after the engine's first idle frame,
which is enough to trigger script preloading.

---

## 4. Recipe: forced reimport of one folder

**When**: one specific asset got stuck with stale `.import` data but you
don't want a full project reimport.

```bash
# Delete just the .import files under the folder you care about.

SKILL.md 不止这些内容，安装后可阅读全文。

技能包内容

共 1 个文件，合计 8.9 KiB