AGENT SKILL

godot-data-driven-config

Create or extend data-driven config tables (WeaponData, EnemyData, LevelData, etc.) in a Godot 4 project so that designers can tweak numbers in .tres files via natural language. Use this skill whenever the user says something like "give weapons a config table", "extract hardcoded numbers into data", "add a new enemy type", "designer wants to tune damage/hp/speed", "add WeaponData/PlayerData/EnemyData", or asks to make Godot values editable without touching code.

License 许可
MIT
最近更新
2026-11-12
Stars
★ 3
Forks
1

01 前言 Front Matter

name
godot-data-driven-config
description
Create or extend data-driven config tables (WeaponData, EnemyData, LevelData, etc.) in a Godot 4 project so that designers can tweak numbers in .tres files via natural language. Use this skill whenever the user says something like "give weapons a config table", "extract hardcoded numbers into data", "add a new enemy type", "designer wants to tune damage/hp/speed", "add WeaponData/PlayerData/EnemyData", or asks to make Godot values editable without touching code.

02 资源文件 11

03 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:

{
  "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

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:
    @export var <name>_data: <Name>Data
    
  2. In _ready():
    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.

Step 5 — Validate

bash tools/validate_data.sh
# exit 0 = OK
# exit 1 = validation failed (stdout/stderr has reasons)
# exit 2 = environment issue

On cold clone (no .godot/ dir), the wrapper auto-refreshes the class cache once via godot --headless --editor --quit — designers/CI need no special knowledge.

Step 6 — Document

Append to PROJECT_OVERVIEW.md or README.md:

  • The mapping table from Step 1
  • Designer workflow: "edit .tres → run bash tools/validate_data.sh → F5".
  • Validator command.

Hard rules

  • One Resource class per category, never a god-class.
  • Numeric fields MUST have @export_range.
  • Every <Name>Data MUST have an id: StringName field; filename stem is used as fallback id.
  • DataManager is ALWAYS an Autoload named DataManager.
  • data_manager.gd returns Resource (not <Name>Data) from getters; callers cast with as WeaponData if they want static typing. This keeps cold-start safe.
  • DO NOT mutate a Resource at runtime (shared reference). To modify: var copy = data.duplicate(); copy.x = ....
  • DO NOT try to MultiplayerSynchronizer-sync a Resource. Instead, guarantee the same .tres exists on all peers (git-managed).
  • Validator never uses exit_code because Godot bug #88055 drops it under --script. Use the VALIDATION_RESULT=OK|FAIL:n stdout marker (the generated validate_data.sh does this).
  • DO NOT hand-edit the # region *_AUTOGEN blocks; scaffold.py rewrites them on every run.

Cold-start / CI notes

  • Godot's global_script_class_cache.cfg is created by the editor. For headless/CI, the first run needs godot --headless --editor --quit to populate it (the generated wrapper does this automatically when .godot/ is missing).
  • Validator is intentionally written to NOT depend on class_name resolution (uses Resource base + res.get("field") duck-typing), so even if the cache is stale it still works.

Anti-patterns to avoid

  • ❌ Using CSV/JSON/YAML loaders at runtime — Godot's native .tres is already text, git-friendly, type-safe, and Inspector-editable.
  • ❌ Putting everything in one god-resource — harder to diff, no grouping, single-file merge conflicts.
  • ❌ Hardcoding defaults in the Resource script AND in the .tres at different values — keep .tres authoritative; script defaults only act as fallback when a consumer never binds a resource.
  • ❌ Reading .tres with FileAccess / JSON.parse — always use load() / preload().

Smoke-test before declaring done

Run scripts/selftest.sh (in this skill) which:

  1. Creates a fresh temp Godot project.
  2. Runs scaffold.py with every example spec.
  3. Refreshes class cache + runs the validator.
  4. Injects a bad value and confirms the validator now exits 1.
  5. Cleans up.
bash ~/.codebuddy/skills/godot-data-driven-config/scripts/selftest.sh

Deliverables checklist

When you finish, confirm ALL of:

  • [ ] res://data/specs/<name>.spec.json exists and is committed
  • [ ] res://data/resources/<name>_data.gd with class_name + typed @export fields
  • [ ] res://data/<name>s/default_<name>.tres with sensible defaults
  • [ ] res://data/resources/data_manager.gd exists and references the new category
  • [ ] project.godot has DataManager in [autoload]
  • [ ] Consumer .gd reference <name>_data.xxx (no more magic numbers)
  • [ ] bash tools/validate_data.sh → exit 0
  • [ ] PROJECT_OVERVIEW.md / README.md updated

Files in this skill

SKILL.md                                  this file
QUICKREF.md                               one-page cheat sheet for the AI
schemas/field_spec.schema.json            JSON schema for designer-facing spec
templates/
  data_class.gd.tmpl                      Resource class template
  data_resource.tres.tmpl                 .tres template
  data_manager.gd.tmpl                    Autoload template (uses Resource base)
  validate_data.gd.tmpl                   CLI validator template (duck-typed)
  validate_data.sh.tmpl                   bash wrapper (exit-code fix-up)
scripts/
  scaffold.py                             end-to-end generator
  selftest.sh                             self-test / regression check
examples/
  weapon_spec.json
  enemy_spec.json

04 同仓库更多 Skills

welflau
welflau/ai-dev-system

webapp-testing

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

测试与质量前端开发
★ 3
welflau
welflau/ai-dev-system

internal-comms

A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).

邮件与沟通
★ 3
welflau
welflau/ai-dev-system

web-artifacts-builder

Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.

前端开发
★ 3
welflau
welflau/ai-dev-system

frontend-design

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.

设计师前端开发视觉设计
★ 3
welflau
welflau/ai-dev-system

algorithmic-art

Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.

视觉设计
★ 3
welflau
welflau/ai-dev-system

theme-factory

Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.

视觉设计
★ 3