card_game/docs/ARCHITECTURE.md

ARCHITECTURE

Current prototype implementation. May be rewritten.

Source: AI-First Technical Architecture Plan · v0.1, Layer 2.

Stack

• Godot .NET — later Steam/desktop presentation
• Game.Client — current playtest browser; no rules
• C# / .NET 8 — rules and tools
• JSON + JSON Schema — content
• xUnit — tests
• First platform: Windows desktop / Steam prototype

Repository layout

src/Game.Core
src/Game.AI
src/Game.Content
src/Game.Client
tests/Game.Core.Tests
tests/Game.AI.Tests
tests/Game.Content.Tests
content/cards
content/characters
content/enemies
content/encounters
schemas
tools
docs
AGENTS.md

Game.Core

Pure C#; no Godot reference.

v1 types: GameState, PlayerState, Entity, CardDefinition, CardInstance, Zone, GameAction, GameEvent, Effect, Condition, Trigger, ResponseWindow, GameRng.

Do not build a universal framework. Implement only what current rules need.

Core API

GetLegalActions(state)
Execute(state, action)
CloneState(state)
ResolveUntilStable(state)

AI and the player client must call this same pair of legal-action and execute paths.

Action vs event

• GameAction: intent — PlayCard, Attack, Activate, Respond, EndTurn, ChooseTarget
• GameEvent: what happened — Damage, Heal, Draw, Discard, Destroy, EnterField, LeaveField, CountdownChanged, SupplyGenerated

Rules process actions. UI plays events.

Atomic resolution and response

Complex effects split into atomic steps. An atomic step is an engine unit, not a player-response unit. Response windows open only at rule-defined timings.

Do not implement free “anywhere second-speed.” Responses bind to events (on attack, before damage, on target, on enter, about to destroy). Response is not a card type. Show a window only if a legal response exists.

Content model

Card types v1: Creature / Spell / Field. Long-lived entities share one battlefield. Board size 10 is a test parameter.

Standard effects

Damage, Heal, Draw, Discard, Destroy, Summon, MoveCard, ModifyStat, ModifyCountdown, AddKeyword, RemoveKeyword, GenerateEnergy, AddStatus, RemoveStatus.

Ordinary cards compose these. Custom C# handlers only when composition is unreasonable. Do not invent a card scripting language.

Validation, RNG, replay

CLI validator (later): unique IDs, dangling refs, structure, required fields, numeric ranges, tags, effect args. PT and dead-ref reports later.

All randomness: GameRng. GameState stores RNG. Tests pin seed. A battle records initial state, seed, and action sequence for 100% replay.

AI v1 (see docs/AI.md)

Current-turn only. No MCTS, minimax, multi-turn planning, opponent-future prediction, response prediction, or LLM AI.

Shallow beam search + near-optimal randomness among scores ≥ BestScore × Threshold.

Performance depends on clone + Execute speed, not algorithm prestige. Deep-copy until it hurts.

PT v1

Linear value table for damage, heal, draw, energy, attack, health. DelayedValue ≈ BaseValue × DelayDiscount. No forced PT for highly contextual effects.

Godot client (Phase F)

Render(GameState) and Input → GameAction → Core.Execute → GameEvents → Animation. Never “fix” a rules bug in animation code.

Prototype order

Phase	Focus	Deliverable
A	Core skeleton	Entities, zones, state, action, event, RNG, clone, tests; no UI
B	Basic combat	Draw, hand, energy, creatures, fields, attack, damage, heal, destroy, GY, turns
C	Special rules	Cost, effect text, trigger, response, countdown, supply, fatigue, tags
D	Headless battle	Full fight in CLI
E	AI	Random legal → utility → current-turn beam
F	Godot client	Hand, board, HP, energy, targeting, response prompt, basic anim
G	Content tools	Schema, validator, PT report, load tests
H	Vertical slice	First characters, cards, fields, enemies, one boss

Current milestone: Phase A. Do not start Godot until Core + tests + a CLI fight can draw, play, attack, end turn, and run a simple AI.

Success

Headless full combat; full replay; automated core tests; ordinary new cards usually need no code; AI legal turns and 2–4 card combos; sim fast enough for live decisions; Godot only presents the same simulation.