godot-data-driven-config

SKILL.md 节选

# Godot Data-Driven Config Skill

## What this skill does

Turns hardcoded `const` / magic numbers inside `.gd` files into a clean **Resource-based config layer** that designers can edit via `.tres` or the Godot Inspector. Also generates a CLI validator (`bash tools/validate_data.sh`) so a human or CI can check "did I break the config table?" in one command.

## When to invoke

Trigger on intents like:
- "Create a WeaponData / EnemyData / LevelData / SkillData for this project"
- "Move these hardcoded numbers into a config table"
- "I want designers to tune damage/hp/speed without touching code"
- "Add a new weapon/enemy type through data"
- "Build an AI-native Godot config workflow"

## Canonical file layout (ALWAYS use this)

```
res://data/
├── specs/                       # JSON specs, source of truth (git-tracked)
│   ├── weapon.spec.json
│   └── ...
├── resources/
│   ├── <name>_data.gd           # class_name <Name>Data extends Resource
│   └── data_manager.gd          # Autoload (AUTOGENERATED — do not hand-edit AUTOGEN regions)
├── <name>s/                     # plural dir, one .tres per entry
│   └── default_<name>.tres
tools/
├── validate_data.gd             # Godot-side CLI validator (autogen)
└── validate_data.sh             # bash wrapper (exit code fix-up)
project.godot                    # [autoload] DataManager="*res://data/resources/data_manager.gd"
```

Rationale: plural-dir + `id` field makes `DirAccess` scanning trivial. Specs under `data/specs/*.spec.json` are the **source of truth**; regenerating `data_manager.gd` / `validate_data.gd` is always a pure function of that directory, so nothing can drift.

## Required workflow

### Step 1 — Discover & propose

1. Read target `.gd` files; collect hardcoded constants and literals.
2. Ask the user which category (weapon/player/enemy/level/skill/item/…). Each category becomes one `<Name>Data` class.
3. Produce a **field mapping table** (source constant → new field → range). Present it, wait for OK (max 1 round of confirmation).

### Step 2 — Write spec JSON under `data/specs/`

Every category is described by exactly one JSON file matching `schemas/field_spec.schema.json`. Commit these to git — they are the source of truth and diff well.

Minimal valid spec:
```json
{
  "name": "weapon",
  "default_id": "default_pistol",
  "fields": [
    { "key": "id", "type": "StringName", "default": "&\"\"", "group": "Identity" },
    { "key": "damage", "type": "int", "default": 10, "range": [0, 9999, 1] }
  ],
  "validators": ["damage >= 0"]
}
```

### Step 3 — Run `scaffold.py` once per new/updated category

```bash
python3 ~/.codebuddy/skills/godot-data-driven-config/scripts/scaffold.py \
    --project-root <abs Godot project path> \
    --spec <abs path to spec>.spec.json
```

The script:
- copies the spec into `res://data/specs/` (creates source-of-truth file)
- writes `res://data/resources/<name>_data.gd` (first time only; re-run with `--force-class` to overwrite)
- writes `res://data/<name>s/default_<name>.tres` (first time only; `--force-tres` to overwrite)
- **rebuilds** `res://data/resources/data_manager.gd` from **all** `data/specs/*.spec.json` — you never lose a previously-added category
- **rebuilds** `res://tools/validate_data.gd` (duck-typed against `Resource`, so cold-start without `.godot/` cache still works)
- writes `res://tools/validate_data.sh` wrapper
- patches `[autoload]` in `project.godot` idempotently

### Step 4 — Migrate consumer `.gd` files

For each file with hardcoded values:
1. Add at top of class:
   ```gdscript
   @export var <name>_data: <Name>Data
   ```
2. In `_ready()`:
   ```gdscript
   if <name>_data == null:
       <name>_data = DataManager.get_<name>()
   ```
3. Replace literal(s): `JUMP_SPEED` → `<name>_data.jump_speed` etc.
4. **Keep purely-technical consts** unchanged (collision masks, shader paths, blend-tree parameter strings).
5. **DO NOT** edit `.tscn` unless necessary — the `DataManager` fallback covers unbound cases.

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

技能包内容

共 12 个文件，合计 41.3 KiB