game-data
Use when a Godot game keeps items, enemies, levels, dialogue or balance numbers as data (Resources, JSON or CSV tables, spreadsheets), or when that data loads wrong, changes by itself or is missing from an export.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-13
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- game-data
- description
- Use when a Godot game keeps items, enemies, levels, dialogue or balance numbers as data (Resources, JSON or CSV tables, spreadsheets), or when that data loads wrong, changes by itself or is missing from an export.
03 SKILL.md 正文
Data-driven design in Godot 4 (C#)
Keep what designers tune (numbers, lists, ids, references between them) out of code, check it in CI like code, and load
it the same way in the editor, in tests and in the exported game. Every behaviour below was measured on Godot 4.7.2
mono; sources: ${CLAUDE_PLUGIN_ROOT}/docs/data.md.
1. Resources or tables
[GlobalClass] Resources (.tres) |
JSON or CSV tables | |
|---|---|---|
| Best for | A few hand-tuned items tied to art and scenes | Many rows of numbers, tuned in a spreadsheet |
| Editing | The inspector | A spreadsheet, exported to the repository |
| Reviewing a change | Readable diffs | Readable diffs; one row per item |
| Checked by the kit | Section 3 | The data runner (section 4) |
| Mods and downloads | Never: a .tres runs scripts embedded in it |
Yes, validated (modding) |
Either way: every definition has a stable string Id (not a file name, not an index); references name ids; one loader,
used by the game, tests and CI, reports every problem at once instead of stopping at the first.
Content edited often (maps, waves, dialogue) deserves its own editor, a @tool script or a small plugin, so people
other than the programmer can make it: Toru Hidaka's graphics, map and sound utilities let others make games at Enix
(Untold History).
2. The traps of custom Resources
- A loaded Resource is one shared object. Two enemies with
[Export] Weaponset toaxe.treshold the same object;a.Weapon.Damage += 5changesband every laterGD.Load("res://axe.tres"). Definitions are read-only at run time; per-instance state goes in a plain C# object built from the definition (new WeaponState(def)). ResourceLocalToScenecopies only when a scene is instantiated; twoGD.Loadcalls still share.Duplicate(true)keeps external sub-resources (another.tres) shared and drops fields that are not[Export]ed;Duplicate()shares arrays.DuplicateDeep(Resource.DeepDuplicateMode.All)copies external ones too. Cost: 45 µs for a small resource, 1.5 ms for a large one, against 5 µs fornew; never duplicate per bullet.- Renaming or removing an
[Export]property loses data silently. The old.tresloads with no warning (not even with--verbose), the property gets its C# default, and the next save erases the old value. When renaming, edit every.tresin the same commit (the keys are plain text) and check with the test below. - Renaming a class or its file: move the
.cs.uidwith the.cs(git mvboth); a.treswithout auid=(any written byResourceSaver.Savein a running game) then fails to load and returns null. - Values equal to the default are not written. Changing a C# default silently changes every file that had it. Give balance numbers no meaningful default (0, then validate).
- Inspector hints are not validation. A hand-edited
.tresloadedHp = 999pastPropertyHint.Range "0,100", an enum value 7 that does not exist, andSpeed = "fast"on a float as 0, all without an error. - Hot reload:
GD.Loadreturns the cached object after the file changes;ResourceLoader.Load(path, "", ResourceLoader.CacheMode.Replace)reloads into the same object, so every holder sees the new values. A debug "reload data" key can do this for changed files.
3. Tests for Resources (in the game's test project)
- every
.tresunder the data folders loads, non-null, of the expected class - every key in each
.tresis a stored property of its class: parse the keys from the text and compare withGetPropertyList()entries whose usage hasPropertyUsageFlags.Storage(this alone catches renamed properties); the kit'svalidaterunner now does this for every.tres(keeps spead, which EnemyStats no longer has) - ids unique and matching
^[a-z0-9_]+$; references resolve; no cycles where none belong (upgrade chains) - ranges from the
PropertyHint.Rangehint strings; enums withEnum.IsDefined - the game's balance rules from the GDD: damage rises with tier, drop weights sum above 0, every enemy beatable at the level's expected player power
- a cost curve: one formula, kept in one place, gives each item's benefits minus its costs; the test fails on any item outside a stated band (the method of a game balance course's GDC talk)
- chance tables: no negative weight, every probability within 0 and 1, the exclusive outcomes summing to exactly 1 (most
probability mistakes fail one of these); where the exact chance of an outcome is known, the seeded rate of
procgen's "Chances come out right" test must agree with it
4. Tables: JSON and CSV
- A
.csvis imported as a translation by default, even a table of enemies, and then the file itself is not in the exported game. In the Import dock choose Import As > Keep File and commit its.import(importer="keep"); read it withFileAccess.GetCsvLine(), which handles quoted commas. .jsonis exported as is..txtand.yamlare exported only if the export preset's include filter names them.- A
.tresis converted to binary in an export and appears asname.tres.remap, so aDirAccessscan for*.tresfinds nothing there. List withResourceLoader.ListDirectory("res://data")and load by path. - Godot's
Jsonreturns every number as a double (10is10.0; ids above 2^53 are corrupted), accepts trailing commas and keeps the last of duplicate keys. Parse tables in C# withSystem.Text.Jsoninto records; setUnmappedMemberHandling = JsonUnmappedMemberHandling.Disallowso a misspelt field fails. - Parse numbers with
CultureInfo.InvariantCulture:float.Parse("0.5")gives 5 on a German system, inside Godot too, and CI machines never show it; thearchitecturerunner warns (culture-parse).
The data runner
data.json in the project describes each table; the data runner (picked automatically when the file exists) checks
every row without Godot and writes one JUnit case per table:
{ "tables": {
"items": { "file": "data/items.json", "id": "id",
"fields": { "price": { "type": "int", "min": 0 }, "rarity": { "enum": ["common", "rare"] } } },
"enemies": { "file": "data/enemies.csv", "id": "id",
"fields": { "hp": { "type": "int", "min": 1 }, "drops": { "ref": "items", "list": true },
"boss": { "type": "bool", "optional": true } } } } }
- It catches: duplicate or missing ids, wrong types, values out of range or not in the enum, references to ids that do not exist, unknown columns (typos in a header), and a CSV still imported as a translation; a mistyped id, enum value, column or table comes with the near name ("did you mean 'mining'?").
- Field rules:
type(string, int, number, bool),min,max,enum,pattern,ref,list(;between values in a CSV cell),optional,acyclic(on arefto its own table: prerequisites that loop, as in a tech tree,algorithms);"extra": "allow"on a table permits unlisted columns. - Across rows:
"totals"on a table (what a zone's quests give must reach its next level:progression) and"names"at the top level (misspelt proper nouns in dialogue, translations and scenes:narrative);"economy": { "currency": ..., "rate": ... }on a table of flows per hour fails a currency with no sink (progression). - Dialogue rules: a table of
"kind": "responses"(narrativesection 4), with"locales"for lines missing a translation;"type": "criteria"checks the same criteria grammar (health<25;!seen_tank) in any table, such as quest or unlock conditions. - Soft-locks: a table of
"kind": "softlock", levels as areas, passages, pickups, supplies and goals, searched likeSoftLockCheckin C# (game-playtestsection 6), so GDScript games get it too. - Run it alone:
pwsh ${CLAUDE_PLUGIN_ROOT}/ci/godot/hyperdot.ps1 test -Json -Quiet -Runners data. - Puzzle levels:
game-designsection 6 has alevelstable that requires a one-sentence solution and a purpose for every level.
5. Spreadsheets
- One direction only: the sheet, then an export (a script or a downloaded CSV) committed to the repository, then the game. Never hand-edit the export; commit it so a review shows every balance change.
- Keep derived columns (damage per second, time to kill) in the sheet; export only the inputs.
- Feature switches are data too, so a feature can be turned off for a test (DayZ). Values tuned around a bug break when it is fixed: retune after fixes, and keep whole-system regression runs (IL-2).
- Print a digest of all data tables in the game's log and in bug reports, so a report says which balance it ran.
- Balance downloaded from a server (rebalancing without a patch; a Sony online consultant's GDC advice) is data only:
JSON or CSV parsed into the same records and checked by the same rules, never a
.tres, a script or an expression, which would be a way in for an attacker. The shipped tables stay the fallback, so the game plays offline with whatever version it has; apply a download between missions or runs, never mid-mission; write its version into saves.
6. Placed objects: every one, every run
Anyone breaks placed content, often far from where they worked: a prop's collision fix moves AI points off the navmesh
in every level that uses the prop, a navmesh change drops the slopes, a code change lowers a limit. Check every placed
node of every level in each test run instead of by hand (Assassin's Creed Origins: 228 zip lines at two minutes each is
a tester's full day; ${CLAUDE_PLUGIN_ROOT}/docs/gdc/assassins-creed-origins-world-data.md).
Write a placement.json and the placement runner checks every level in each test run, no test to write:
{ "levels": ["res://levels"], "limits": { "reach": "res://player.gd:REACH" } }, each limit read from the GDScript
constant it names, in GDScript or C# ("res://Tuning.cs:Reach": a const or static readonly set to a literal or arithmetic on other such fields). Or copy
${CLAUDE_PLUGIN_ROOT}/ci/godot/templates/placement_check.gd into the game's test folder and call it from a GUT test
(its header has the code). It loads each level, waits for navigation, checks nodes by group and reports one line per
finding: scene, node path, position, rule, measured value and limit.
| Group | Rule | Passes when |
|---|---|---|
ai_point |
navmesh_below |
navmesh is at most 0.5 m straight below |
path_to_link |
a path reaches each node in its links metadata |
|
interactable |
ground_in_reach |
a ray down hits ground within the player's reach |
zipline |
zipline_clear |
a capsule swept under the rope to its End child hits nothing |
zipline_angle |
the rope is no steeper than the movement code allows | |
landmark |
landmark_still |
it is no moving body and did not move in 30 physics frames |
landmark_seen |
it is in view ahead from at least two separate stretches of the route paths |
|
route (a Path3D) |
landmark_ahead |
walked each way (metadata one_way skips the way back), a landmark is in view ahead on a quarter of it |
- The wayfinding rules and why they matter:
game-designsection 7. They aim at a landmark'sMarker3Dchildren (the top of a tower), fromeye_heightwithinview_fov; only what has collision hides a landmark. - Limits come from gameplay code:
check.reach = Player.REACHwithconst Player := preload("res://player.gd"). A copied number keeps passing after the code changes; yesterday's valid zip line must fail the day the limit drops. - A bug found once becomes a rule for its whole type: one torch out of reach means a check of every torch.
- Prove each rule on a broken fixture before trusting it. A false positive sends someone looking for nothing, and
they stop reading the report. Two traps the kit's fixture caught: before the map syncs,
map_get_closest_pointreturns (0, 0, 0), so a probe at the origin looks ready early (wait formap_get_closest_point_ownerto be valid);map_get_pathto another navmesh island returns a path to the nearest reachable point, so compare where it ends. - Exemptions are visible: node metadata
placement_skip = {"zipline_clear": "the crate breaks"}; the summary lists each with its reason, and one without a reason is a finding. - One summary with the change per type since the last run (
counts_file; keep the file between runs). The talk's most useful line was "ladders +500", seen before anyone complained. - On 4.7.2 headless, navigation answered after 9 to 11 physics frames for the first level of a GUT run and 3 or 4 for the next; the helper polls, capped. The checks take about 10 ms per 1,000 nodes.
- A check at commit time does not replace the full run: data fine on day one breaks on day ten through another change.
- Run it:
pwsh ${CLAUDE_PLUGIN_ROOT}/ci/godot/hyperdot.ps1 test -Json -Quiet -Runners gut -Filter test_every_level.
04 同仓库更多 Skills
over-budget
Use when a fixture exceeds the size budget.
bad-yaml
暂无简介
bad-workflow-description
Use when testing; runs the kit and then reads the JSON.
bad-version
Use when a fixture quotes a stale package version.
bad-value
Use when a fixture passes a value outside a parameter's set.
bad-trigger
Helps with Godot tests.