docs(docs): 📝 Introduce architectural patterns and data models in README.md and CLAUDE.md
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
This commit is contained in:
Claude Code
parent
588483cc8b
commit
e26a220004
2 changed files with 14 additions and 14 deletions
18
CLAUDE.md
18
CLAUDE.md
|
|
@ -13,7 +13,7 @@ Fantasy 4X turn-based strategy game (Civ5 + Master of Magic + Magic: The Gatheri
|
|||
- **Engine:** Godot 4.x
|
||||
- **Simulation:** Rust (`src/simulator/`) — compiled to GDExtension for the game, WASM for the web guide
|
||||
- **Scripting:** GDScript — presentation layer only (rendering, UI, input, signals)
|
||||
- **Data:** JSON game packs (`games/age-of-dwarves/data/*.json`)
|
||||
- **Data:** JSON game packs (`public/games/age-of-dwarves/data/*.json`)
|
||||
- **Architecture:** Genre-agnostic engine with game pack content system
|
||||
|
||||
## Key Architecture
|
||||
|
|
@ -22,7 +22,7 @@ The engine is **genre-agnostic**. All game content and display text comes from g
|
|||
|
||||
**Rust is the simulation source of truth.** All game logic (physics, combat, economy, AI, pathfinding, magic, tech, turn resolution) lives in `src/simulator/` and is compiled to two targets: GDExtension for the Godot game, WASM for the web guide. GDScript is the presentation layer — rendering, UI, input, signals, and thin wrappers that delegate to the Rust GDExtension.
|
||||
|
||||
**JSON game packs remain the canonical content store.** Stats, costs, effects, thresholds — all in `games/age-of-dwarves/data/*.json`. Neither Rust nor GDScript hardcodes game content.
|
||||
**JSON game packs remain the canonical content store.** Stats, costs, effects, thresholds — all in `public/games/age-of-dwarves/data/*.json`. Neither Rust nor GDScript hardcodes game content.
|
||||
|
||||
- UI labels resolve through `ThemeVocabulary.lookup(engine_key)` — never hardcode theme strings
|
||||
- Sprites resolve through `ThemeAssets.resolve(path)` — never hardcode asset paths
|
||||
|
|
@ -35,7 +35,7 @@ The engine is **genre-agnostic**. All game content and display text comes from g
|
|||
See `README.md` for the full doc index. Docs live in two places:
|
||||
|
||||
- **`src/game/engine/docs/`** — genre-agnostic engine architecture (written as engine systems are built)
|
||||
- **`games/age-of-dwarves/docs/`** — fantasy game design (races, combat, spells, economy, etc.)
|
||||
- **`public/games/age-of-dwarves/docs/`** — fantasy game design (races, combat, spells, economy, etc.)
|
||||
|
||||
Build process docs (roadmap, feature gap, task lists) stay in `.project/`.
|
||||
|
||||
|
|
@ -44,7 +44,7 @@ Build process docs (roadmap, feature gap, task lists) stay in `.project/`.
|
|||
> **The Rust workspace `src/simulator/` is the source of truth for all simulation logic. It compiles to two targets. Never duplicate simulation logic in GDScript or TypeScript.**
|
||||
|
||||
```
|
||||
games/age-of-dwarves/data/climate_spec.json ← Canonical thresholds, events, ley rules (JSON)
|
||||
public/games/age-of-dwarves/data/climate_spec.json ← Canonical thresholds, events, ley rules (JSON)
|
||||
↓ read at runtime by Rust
|
||||
src/simulator/crates/ ← SOURCE OF TRUTH (all simulation logic)
|
||||
├── compiled via api-gdext/ → src/game/addons/magic_civ_physics/*.so/.dll
|
||||
|
|
@ -52,7 +52,7 @@ src/simulator/crates/ ← SOURCE OF TRUTH (all simulati
|
|||
│ src/game/engine/src/modules/climate/climate.gd ← thin GDExtension wrapper
|
||||
└── compiled via api-wasm/ → src/simulator/pkg/
|
||||
↓ imported by web worker
|
||||
games/age-of-dwarves/guide/src/simulation/simulation.worker.ts
|
||||
public/games/age-of-dwarves/guide/src/simulation/simulation.worker.ts
|
||||
```
|
||||
|
||||
### Build commands
|
||||
|
|
@ -103,7 +103,7 @@ cd src/simulator && bash build-gdext.sh
|
|||
| `*.json` data files, `vocabulary.json`, `game.json` | `game-data` |
|
||||
| `*.tscn` UI scenes, HUD panels, overlays, menus | `godot-ui` |
|
||||
| TileMap, sprites, camera, fog, selection highlight, animation | `godot-renderer` |
|
||||
| `games/age-of-dwarves/guide/`, `src/packages/guide/`, React, Vite, WASM integration | `guide-web` |
|
||||
| `public/games/age-of-dwarves/guide/`, `src/packages/guide/`, React, Vite, WASM integration | `guide-web` |
|
||||
|
||||
## Conventions
|
||||
|
||||
|
|
@ -244,7 +244,7 @@ games/
|
|||
src/simulation/simulation.worker.ts — imports from @magic-civ/physics-rs (WASM)
|
||||
```
|
||||
|
||||
**Note:** `src/game/resources` and `src/game/games` are symlinks → `src/resources/` and `games/` respectively, making them accessible as `res://resources/` and `res://games/` from within the Godot project.
|
||||
**Note:** `src/game/public` is a symlink → `../../public`, making the entire public tree accessible as `res://public/` from within the Godot project (`res://public/resources/`, `res://public/games/`). `src/simulator/public` is the same symlink for Rust test access.
|
||||
|
||||
## DX Tooling
|
||||
|
||||
|
|
@ -291,8 +291,8 @@ Self-capturing test scenes. Each phase should have a proof scene that sets up mi
|
|||
### DataLoader — File vs Directory Pattern
|
||||
|
||||
`DataLoader` supports two layouts per data category:
|
||||
- **Single file:** `games/age-of-dwarves/data/races.json`
|
||||
- **Split directory:** `games/age-of-dwarves/data/units/` — reads all `.json` files, merges by `id`
|
||||
- **Single file:** `public/games/age-of-dwarves/data/races.json`
|
||||
- **Split directory:** `public/games/age-of-dwarves/data/units/` — reads all `.json` files, merges by `id`
|
||||
|
||||
**Never create a monolithic file that exceeds 500 lines.**
|
||||
|
||||
|
|
|
|||
10
README.md
10
README.md
|
|
@ -36,14 +36,14 @@ tools/ — sprite generation, transpiler, screenshot capture
|
|||
| ABSTRACTION.md | Genre-agnostic vocabulary, theme pack system |
|
||||
| DATA_FORMAT.md | JSON data schemas, DataLoader patterns |
|
||||
|
||||
### Game Design (`games/age-of-dwarves/docs/`)
|
||||
### Game Design (`public/games/age-of-dwarves/docs/`)
|
||||
|
||||
| Doc | Covers |
|
||||
|-----|--------|
|
||||
| [RACES.md](games/age-of-dwarves/docs/RACES.md) | 4 demo races, gendering, fusions, release schedule |
|
||||
| [ECONOMIC_SYSTEMS.md](games/age-of-dwarves/docs/ECONOMIC_SYSTEMS.md) | Economy, civic axis, capitalism cascade |
|
||||
| [GOVERNMENTS.md](games/age-of-dwarves/docs/GOVERNMENTS.md) | Government types and mechanics |
|
||||
| [GLOSSARY.md](games/age-of-dwarves/docs/GLOSSARY.md) | Term definitions |
|
||||
| [RACES.md](public/games/age-of-dwarves/docs/RACES.md) | 4 demo races, gendering, fusions, release schedule |
|
||||
| [ECONOMIC_SYSTEMS.md](public/games/age-of-dwarves/docs/ECONOMIC_SYSTEMS.md) | Economy, civic axis, capitalism cascade |
|
||||
| [GOVERNMENTS.md](public/games/age-of-dwarves/docs/GOVERNMENTS.md) | Government types and mechanics |
|
||||
| [GLOSSARY.md](public/games/age-of-dwarves/docs/GLOSSARY.md) | Term definitions |
|
||||
| COMBAT_SYSTEM.md | Combat mechanics (written when M8 is built) |
|
||||
| SPELL_SYSTEM.md | Spell/mana system (written when M9 is built) |
|
||||
| ERA_SYSTEM.md | Era progression (written when needed) |
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue