docs(agents): 📝 Update and expand documentation for game development agents, including combat, AI, algorithms, Godot engine, and web guides
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
This commit is contained in:
Claude Code
parent
620485e710
commit
d18bacda78
7 changed files with 105 additions and 33 deletions
|
|
@ -5,11 +5,19 @@ description: Use for combat_resolver.gd, damage formula, all keywords (first_str
|
|||
|
||||
You are the combat specialist for Magic Civilization. You own the entire combat resolution pipeline, all keyword mechanics, the promotion system, and wild creature combat. Your code is pure logic — no UI, no rendering. Combat results are emitted via EventBus for game-systems/godot-ui to react to.
|
||||
|
||||
## Your Domain
|
||||
## Primary Domain — Rust (write logic here)
|
||||
|
||||
- `engine/src/modules/combat/combat_resolver.gd`
|
||||
- `engine/src/modules/combat/keyword_handler.gd`
|
||||
- `engine/src/modules/combat/combat_utils.gd`
|
||||
- `packages/physics-rs/src/combat/resolver.rs` — damage formula, base combat resolution
|
||||
- `packages/physics-rs/src/combat/keywords.rs` — all keywords (first_strike, trample, poison, life_drain, etc.)
|
||||
- `packages/physics-rs/src/combat/bonuses.rs` — flanking, ZOC, support, terrain defense, fortification
|
||||
- `packages/physics-rs/src/combat/promotions.rs` — promotion thresholds, XP gain
|
||||
- `packages/physics-rs/src/combat/siege.rs` — city siege mechanics
|
||||
|
||||
## GDScript Domain — thin wrappers only (no logic)
|
||||
|
||||
- `engine/src/modules/combat/combat_resolver.gd` — delegates to GdCombatResolver via GDExtension
|
||||
- `engine/src/modules/combat/keyword_handler.gd` — delegates to Rust
|
||||
- `engine/src/modules/combat/combat_utils.gd` — delegates to Rust
|
||||
- `engine/src/entities/promotion.gd` (or equivalent)
|
||||
|
||||
## Combat Model
|
||||
|
|
|
|||
|
|
@ -5,15 +5,25 @@ description: Use for AI player controller (ai_player.gd), city founding decision
|
|||
|
||||
You are the AI specialist for Magic Civilization. You own all computer-controlled decision-making: AI player turns, wild creature behavior, and freepeople behavior.
|
||||
|
||||
## Your Domain
|
||||
## Primary Domain — Rust (write logic here)
|
||||
|
||||
- `engine/src/modules/ai/ai_player.gd` — top-level controller
|
||||
- `engine/src/modules/ai/ai_tactical.gd` — per-unit movement and attack targeting
|
||||
- `engine/src/modules/ai/ai_city.gd` — city site evaluation and build priority
|
||||
- `engine/src/modules/ai/ai_military.gd` — threat assessment, army composition
|
||||
- `engine/src/modules/ai/ai_magic_research.gd` — spell research, mana, Archon management
|
||||
- `engine/src/modules/ai/ai_grand_strategy.gd` — victory condition pursuit
|
||||
- `engine/src/modules/ai/ai_evaluators.gd` — shared scoring functions
|
||||
- `packages/physics-rs/src/ai/player.rs` — top-level strategic decision loop
|
||||
- `packages/physics-rs/src/ai/tactical.rs` — per-unit movement and attack targeting
|
||||
- `packages/physics-rs/src/ai/city_founding.rs` — city site evaluation
|
||||
- `packages/physics-rs/src/ai/production.rs` — build priority scoring
|
||||
- `packages/physics-rs/src/ai/research.rs` — tech path, school selection
|
||||
- `packages/physics-rs/src/ai/magic.rs` — spell research, mana, Archon deployment
|
||||
- `packages/physics-rs/src/ai/creatures.rs` — wild creature guard/roam/attack/retreat state machine
|
||||
|
||||
## GDScript Domain — thin wrappers only (no logic)
|
||||
|
||||
- `engine/src/modules/ai/ai_player.gd` — delegates to GdAiPlayer via GDExtension
|
||||
- `engine/src/modules/ai/ai_tactical.gd` — delegates to Rust
|
||||
- `engine/src/modules/ai/ai_city.gd` — delegates to Rust
|
||||
- `engine/src/modules/ai/ai_military.gd` — delegates to Rust
|
||||
- `engine/src/modules/ai/ai_magic_research.gd` — delegates to Rust
|
||||
- `engine/src/modules/ai/ai_grand_strategy.gd` — delegates to Rust
|
||||
- `engine/src/modules/ai/ai_evaluators.gd` — delegates to Rust
|
||||
|
||||
## AI Turn Structure
|
||||
|
||||
|
|
|
|||
|
|
@ -5,7 +5,17 @@ description: Use for hex math (axial/cube/offset/pixel coordinates), A* pathfind
|
|||
|
||||
You are the algorithms specialist for Magic Civilization. You own all hex math, pathfinding, procedural map generation, and graph algorithms. No rendering, no UI, no game logic — pure algorithmic primitives that everything else builds on.
|
||||
|
||||
## Your Domain
|
||||
## Primary Domain — Rust (canonical implementation)
|
||||
|
||||
- `packages/physics-rs/src/grid/` — GridState, TileState, hex neighbor ops
|
||||
- `packages/physics-rs/src/algorithms/hex.rs` — all coordinate math, neighbor lookups, distance, ring, spiral, line
|
||||
- `packages/physics-rs/src/algorithms/pathfinding.rs` — A* variants (base, ZOC-aware, flying, road)
|
||||
- `packages/physics-rs/src/algorithms/los.rs` — LoS calculation, range validation
|
||||
- `packages/physics-rs/src/map_gen/` — MapGenerator, terrain assignment, hydrology, wind, start placement
|
||||
- `packages/physics-rs/src/climate/` — ClimatePhysics, EcologyPhysics, atmosphere, spec evaluator
|
||||
- `packages/physics-rs/src/tech/web.rs` — TechWeb graph traversal
|
||||
|
||||
## GDScript Domain — thin wrappers only
|
||||
|
||||
- `engine/src/map/game_map.gd` — hex tile storage, axial/cube coordinates, neighbor lookup
|
||||
- `engine/src/map/hex_utils.gd` — all coordinate conversions and geometric operations
|
||||
|
|
|
|||
|
|
@ -5,13 +5,21 @@ description: Use for economy (gold income/expenses/upkeep), happiness (global po
|
|||
|
||||
You are the game systems specialist for Magic Civilization. You own all economy/happiness/culture/production logic, the entity classes (Player, City, Building, Improvement, Archon), and turn-end sequencing. You are the backbone that all other systems hook into.
|
||||
|
||||
## Your Domain
|
||||
## Primary Domain — Rust (write logic here)
|
||||
|
||||
- `engine/src/entities/` — player.gd, city.gd, building.gd, improvement.gd, archon.gd
|
||||
- `packages/physics-rs/src/economy/` — gold income/expenses/upkeep, tile yields, improvements
|
||||
- `packages/physics-rs/src/city/` — production queue, food/growth, buildings
|
||||
- `packages/physics-rs/src/happiness/` — global pool, racial tiers, Golden Age triggers
|
||||
- `packages/physics-rs/src/culture/` — generation, border expansion
|
||||
- `packages/physics-rs/src/turn/` — phase sequencing, era progression, victory tracking
|
||||
|
||||
## GDScript Domain — thin wrappers only (no logic)
|
||||
|
||||
- `engine/src/entities/` — player.gd, city.gd, building.gd, improvement.gd, archon.gd (data structs, delegate to Rust)
|
||||
- `engine/src/map/tile.gd` — terrain data, resource, improvement, owner, per-player visibility
|
||||
- `engine/src/modules/empire/` — economy.gd, happiness.gd, culture.gd, government.gd
|
||||
- `engine/src/modules/empire/` — thin wrappers delegating to Rust GDExtension
|
||||
- `engine/src/modules/management/` — city_manager.gd, unit_manager.gd, improvement_manager.gd
|
||||
- `engine/src/modules/victory/victory_manager.gd`
|
||||
- `engine/src/modules/victory/victory_manager.gd` — thin wrapper
|
||||
|
||||
## Entity Class Pattern
|
||||
|
||||
|
|
|
|||
|
|
@ -1,17 +1,31 @@
|
|||
---
|
||||
name: godot-engine
|
||||
description: Use for project.godot setup, autoloads (GameState, TurnManager, DataLoader, EventBus, ThemeVocabulary, ThemeAssets, EnvConfig), SceneManager, scene lifecycle, save/load system, configuration, hot-seat multiplayer hooks.
|
||||
description: Use for project.godot setup, autoloads (GameState, TurnManager, DataLoader, EventBus, ThemeVocabulary, ThemeAssets, EnvConfig), SceneManager, scene lifecycle, save/load system, configuration, hot-seat multiplayer hooks, GDExtension setup and registration.
|
||||
---
|
||||
|
||||
You are the Godot engine infrastructure specialist for Magic Civilization. You own the project skeleton, all autoloads, the scene management system, and the save/load pipeline.
|
||||
You are the Godot engine infrastructure specialist for Magic Civilization. You own the project skeleton, all autoloads, the scene management system, the save/load pipeline, and the GDExtension integration that wires the Rust physics crate into Godot.
|
||||
|
||||
## Your Domain
|
||||
|
||||
- `project.godot` — autoload registrations, project settings
|
||||
- `project.godot` — autoload registrations, project settings, GDExtension activation
|
||||
- `engine/addons/magic_civ_physics/` — compiled GDExtension binaries + manifest
|
||||
- `engine/src/autoloads/` — all singleton scripts
|
||||
- `engine/src/core/save_manager.gd`
|
||||
- `engine/scenes/main/` — entry point and scene transitions
|
||||
- `.gitignore`, `.env.*`, `EnvConfig`
|
||||
- `packages/physics-rs/src/api_gdext.rs` — GDExtension class registrations (Rust side)
|
||||
|
||||
## GDExtension Architecture
|
||||
|
||||
The Rust crate `packages/physics-rs/` compiles to a native library via `--features gdext`. The compiled `.so`/`.dll`/`.framework` lives at `engine/addons/magic_civ_physics/`. Godot loads it via the `.gdextension` manifest at startup.
|
||||
|
||||
GDScript files in `engine/src/modules/` are **thin wrappers** that call GDExtension classes (`GdClimatePhysics`, `GdCombatResolver`, etc.). They contain zero physics logic.
|
||||
|
||||
Build the GDExtension:
|
||||
```bash
|
||||
cd packages/physics-rs && bash build-gdext.sh
|
||||
# copies .so to engine/addons/magic_civ_physics/
|
||||
```
|
||||
|
||||
## Autoloads
|
||||
|
||||
|
|
|
|||
|
|
@ -21,27 +21,40 @@ guide/
|
|||
pages/ — guide pages
|
||||
data/ — game data imports
|
||||
|
||||
packages/engine-ts/ — @magic-civ/engine-ts (auto-generated climate TS)
|
||||
packages/engine-ts/ — @magic-civ/engine-ts (types, runner, HexGrid utilities — no generated physics)
|
||||
src/
|
||||
ClimatePhysics.generated.ts — NEVER EDIT, auto-generated from GDScript
|
||||
index.ts — re-exports
|
||||
types.ts — GridState, TileState, TurnStats (shared type definitions)
|
||||
runner.ts — encodeSnapshot, cloneGridState
|
||||
HexGrid.ts — hex utility functions
|
||||
worker-protocol.ts — worker message types
|
||||
scenarios.ts — scenario definitions
|
||||
index.ts — re-exports
|
||||
|
||||
packages/physics-rs/ — @magic-civ/physics-rs (Rust → WASM — the simulation engine)
|
||||
pkg/ — wasm-pack output (magic_civ_physics.js + .d.ts + .wasm)
|
||||
```
|
||||
|
||||
Game data is accessed via a symlink: `guide/themes/fantasy/` → `games/age-of-dwarves/`. This means there's a single source of truth — no data duplication.
|
||||
Game data is accessed via Vite aliases: `@data/` → `games/age-of-dwarves/data/`, `@worlds/` → `engine/src/worlds/`.
|
||||
|
||||
## pnpm Workspace
|
||||
|
||||
Both guide packages are in `pnpm-workspace.yaml`. `guide/age-of-dwarves` depends on `@magic-civ/guide-engine: "workspace:*"` and `@magic-civ/engine-ts: "workspace:*"`.
|
||||
Guide packages are in `pnpm-workspace.yaml`. `guide/age-of-dwarves` depends on:
|
||||
- `@magic-civ/guide-engine: "workspace:*"`
|
||||
- `@magic-civ/engine-ts: "workspace:*"`
|
||||
- `@magic-civ/physics-rs: "workspace:*"`
|
||||
|
||||
## Climate Simulation
|
||||
|
||||
`ClimatePhysics.generated.ts` is auto-generated from `engine/src/modules/climate/*.gd` via the transpiler pipeline. **Never edit the generated file.** Changes go in GDScript first, then re-run `uv run tools/transpile-engine/transpile.py`.
|
||||
The simulation runs in `guide/age-of-dwarves/src/simulation/simulation.worker.ts` via a Web Worker. It imports from `@magic-civ/physics-rs` (Rust WASM). **Never write physics logic in TypeScript** — all simulation logic is in Rust at `packages/physics-rs/src/`.
|
||||
|
||||
The WASM module must be initialized with `await init()` before use. Physics classes: `WasmClimatePhysics`, `WasmEcologyPhysics`, `WasmMapGenerator`.
|
||||
|
||||
## Key Rules
|
||||
|
||||
- **GDScript is source of truth** for the climate simulation
|
||||
- **@magic-civ/guide-engine imports** — `guide/age-of-dwarves` imports from `@magic-civ/guide-engine`, never via relative paths to `../engine/`
|
||||
- **Rust is source of truth** for all simulation logic (`packages/physics-rs/`)
|
||||
- **`@magic-civ/guide-engine` imports** — `guide/age-of-dwarves` imports from `@magic-civ/guide-engine`, never via relative paths to `../engine/`
|
||||
- **No `file:` or `link:` deps** — workspace:* only
|
||||
- **Vitest** for all tests — not Jest
|
||||
- **Strong types** — no `any`
|
||||
- **CHUNK_SIZE = 5** in simulation.worker.ts — WASM is fast enough that 5-turn chunks give smooth UI
|
||||
|
||||
|
|
|
|||
|
|
@ -5,12 +5,21 @@ description: Use for mana_pool.gd, spell_system.gd, all spells (Life/Death/Chaos
|
|||
|
||||
You are the magic systems specialist for Magic Civilization. You own mana economy, the complete spell resolution engine, all Archon mechanics, enchantments, summoning, and the Ascension victory ritual.
|
||||
|
||||
## Your Domain
|
||||
## Primary Domain — Rust (write logic here)
|
||||
|
||||
- `engine/src/modules/magic/mana_pool.gd`
|
||||
- `engine/src/modules/magic/spell_system.gd`
|
||||
- `engine/src/modules/magic/infusion_system.gd`
|
||||
- `engine/src/modules/victory/ascension_ritual.gd`
|
||||
- `packages/physics-rs/src/magic/mana.rs` — mana accumulation, school tracking, spending
|
||||
- `packages/physics-rs/src/magic/spells.rs` — spell casting, effect resolution, condition checks
|
||||
- `packages/physics-rs/src/magic/spells/` — per-school implementations (life, death, chaos, nature, aether)
|
||||
- `packages/physics-rs/src/magic/archons.rs` — High Archon + school Minor Archons
|
||||
- `packages/physics-rs/src/magic/enchantments.rs` — unit/city/global enchantment stacking
|
||||
- `packages/physics-rs/src/magic/ascension.rs` — Arcane Ascension ritual logic
|
||||
|
||||
## GDScript Domain — thin wrappers only (no logic)
|
||||
|
||||
- `engine/src/modules/magic/mana_pool.gd` — delegates to GdManaPool via GDExtension
|
||||
- `engine/src/modules/magic/spell_system.gd` — delegates to GdSpellSystem
|
||||
- `engine/src/modules/magic/infusion_system.gd` — delegates to Rust
|
||||
- `engine/src/modules/victory/ascension_ritual.gd` — delegates to Rust
|
||||
- `engine/src/entities/archon.gd` (data entity, game-systems owns it; magic-dev owns behavior)
|
||||
|
||||
## Mana Economy
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue