Files
Claude-Code-Game-Studios/.claude/rules/data-files.md
T
DonchitosandClaude Opus 5.5 b21fa0f7f2 Release 1.1.2 — the default path works end to end
Fix release for 1.1.1: the minimal path end to end, engine commands that
run on Godot, Unity and Unreal, hook warnings you can see, and verdicts
that say when they could not check. Details in CHANGELOG.md; upgrade
steps in UPGRADING.md (v1.1.1 → v1.1.2).

Fixes #67
Fixes #131

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WuJn2FdynEybfL5KC697nJ
2026-09-29 21:32:19 +10:00

2.1 KiB

paths
paths
assets/data/**/*.json
Assets/**/{Data,data}/**/*.json
Content/**/{Data,data}/**/*.json

Data File Rules

  • All JSON files must be valid JSON — broken JSON blocks the entire build pipeline

  • File naming: lowercase with underscores only, following [system]_[name].json pattern

  • Every data file must have a documented schema (either JSON Schema or documented in the corresponding design doc)

  • Numeric values must include comments or companion docs explaining what the numbers mean

  • Use consistent key naming: snake_case for keys within JSON files, matching the [system]_[name].json file convention one line above and the engine idiom every other standard in this repo uses.

    On Unity and Unreal this costs you a mapping layer — budget for it rather than changing the keys. JsonUtility binds by exact field name, and C# fields are camelCase per naming.variables, so a snake_case file cannot bind directly to the type that consumes it. Use a private nested DTO whose fields are the wire format and which maps once into your real type, or take a dependency that supports a naming policy (Newtonsoft SnakeCaseNamingStrategy, System.Text.Json JsonNamingPolicy). Do not switch the file to camelCase to avoid the DTO: keys are the cross-engine contract. Write the DTO and document it as a wire-format boundary — that is the intended shape.

  • No orphaned data entries — every entry must be referenced by code or another data file

  • Version data files when making breaking schema changes

  • Include sensible defaults for all optional fields

Examples

Correct naming and structure (combat_enemies.json):

{
  "goblin": {
    "base_health": 50,
    "base_damage": 8,
    "move_speed": 3.5,
    "loot_table": "loot_goblin_common"
  },
  "goblin_chief": {
    "base_health": 150,
    "base_damage": 20,
    "move_speed": 2.8,
    "loot_table": "loot_goblin_rare"
  }
}

Incorrect (EnemyData.json):

{
  "Goblin": { "hp": 50 }
}

Violations: uppercase filename, uppercase key, no [system]_[name] pattern, missing required fields.