# FOUNDATION

Long-lived engineering principles. Change only if the project itself changes.

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

## Project nature

Single-player PvE card roguelike: light presentation, heavy rules, data, and simulation.

Serve:

- Fast add/edit of cards, characters, enemies, and fields
- Dense rule interaction and deterministic resolution
- AI simulating action sequences within the current turn
- Automated tests, headless batch simulation, and balance analysis
- High-frequency AI coding, refactor, and iteration

Do not prioritize AAA graphics, physics, multiplayer sync, or open-world systems.

## Simulation vs presentation

| World | Owns | Must not own |
| --- | --- | --- |
| Simulation | Rules, entities, zones, cost, events, triggers, responses, AI, RNG, combat state | Godot, UI, animation, audio, scene nodes |
| Presentation | Display `GameState`, input, play `GameEvent`, UI, VFX, SFX | Rules |

UI may express rules. UI must not possess rules.

## Technology direction

- Godot .NET: client / presentation
- C#: primary language and a Godot-free simulation core
- JSON (or similar text) for content
- Git for code and data
- Automated tests on core rules

Engine, library, and tool versions are implementation details, not this document.

## Deterministic simulation

Same initial state, seed, and action sequence → identical result. All randomness comes from game RNG state.

Must support `Seed + Action Log →` full combat replay. Determinism underpins AI search, bug reproduction, tests, balance sims, and playback.

## Simulation first

Every core mechanic must run without Godot, graphics, or animation. The AI simulator and the player rules engine are the same code. Do not ship a simplified second ruleset for AI.

## State must be simulatable

`GameState` must copy, mutate, compare, enumerate legal actions, and simulate a short distance.

v1 may deep-copy. Snapshot, copy-on-write, undo, or structural sharing only after a real performance need.

The goal is future-optimizable semantics, not premature optimization.

## Data-driven content

Most content is data + standard effects/events/conditions + tags. Rare designs may use `CustomEffect` / C# handlers.

Not “100% zero-code cards.” Ordinary content should be cheap; special content may still need code.

## Rules before cards

Do not change primitives to ship one card. A new mechanic must state: event type, atomic step, whether it is an effect, whether it opens a response window, who can listen, and how it is tested.

## AI consumes the rules engine

AI does not own rules. The engine exposes visible state and legal actions; AI only simulates and chooses.

v1 is not global-optimal play. Enemies should notice simple in-turn combos and express style through result weights.

## AI evaluation language

Score **outcomes**, not card names: player damage, board clear, own board, heal, draw, energy, hand value, countdown, status, etc.

Per-enemy weights may shift with the board (e.g. draw weight rises when the hand is empty). Weights are not shown to the player.

## Content value model (PT)

Internal PT / value model for easy-to-quantify effects (damage, heal, draw, stats, cost, delayed value). PT is a balance reference, not an auto-card formula. Context-heavy copy, conversion, and open combos need not have exact PT.

## Tests are design work

Core rules have automated tests. Important bugfixes should leave a reproduction test. Prefer coverage of zones, event order, cost, effects, text, responses, destroy, graveyard, countdown, energy, and RNG determinism.

## AI coding

Prefer strong types, clear module edges, small APIs, tests, searchability, little implicit behavior, little global state.

The human does not need to read every implementation file, but must understand data, rule docs, test names, logs, and debug output.

## Documentation hierarchy

| Doc | Role |
| --- | --- |
| `FOUNDATION.md` | Stable principles |
| `ARCHITECTURE.md` | Current implementation; may be rewritten |
| `RULES.md` | Game rule grammar |
| `CONTENT_SCHEMA.md` | Data formats |
| `AI.md` | AI v1 |
| `DESIGN.md` | Design freeze (world + action dictionary) |
| `AGENTS.md` | Coding-agent constraints |

## Engineering loop

Design mechanic → change data/code → compile → tests → content validate → headless sim → client play → tune data → repeat.