chenmoranzhiandCursor
06eb360fbf
后续改内容或结算顺序时有冻结依据，不必再翻原始稿才能对齐。 Co-authored-by: Cursor <cursoragent@cursor.com>
109 lines
4.3 KiB
Markdown
109 lines
4.3 KiB
Markdown
# 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.
|