mikkeli/fleet-builder-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
70d7e1e789cca62638ed67fac8fbb3f21184aa06
fleet-builder-project/planning_docs/ARCHITECTURE.md

1436 lines
44 KiB
Markdown
Raw Normal View History

Design updates - gameplay draft - core architecture (Python core)
2026-01-10 00:02:01 +09:00
# Naval Roguelite — Architecture Design
## 0. Architecture Philosophy
This system separates **pure computation** from **effectful operations**. The core engine is a pure function: given the same state, action, and seed, it always produces the same output. IO, UI, and randomness live at the boundaries.
**Core Principle**: `GameState + Action + Seed → NewGameState + EventLog`
All game logic is deterministic, testable, and engine-agnostic. Frontends are thin viewers that translate events into visuals and user input into actions.
---
## 1. Module Structure
### 1.1 Directory Layout
```
fleet_builder/
├── core/ # Pure functional core (no IO, no side effects)
│ ├── __init__.py
│ ├── state.py # GameState and all state models
│ ├── ship.py # Ship construction and queries
│ ├── fleet.py # Fleet composition and chemistry
│ ├── tags.py # Tag derivation and queries
│ ├── combat/ # Combat resolution subsystem
│ │ ├── __init__.py
│ │ ├── resolver.py # Main combat resolver
│ │ ├── phases.py # Phase definitions and execution
│ │ ├── targeting.py # Target selection logic
│ │ ├── damage.py # Damage calculation
│ │ └── events.py # Event emission
│ ├── actions.py # All possible actions
│ ├── rules.py # Core rules and constraints
│ └── rng.py # Deterministic RNG wrapper
│
├── data/ # Data definitions (JSON/YAML)
│ ├── hulls/
│ │ ├── submarine.json
│ │ ├── destroyer.json
│ │ ├── cruiser.json
│ │ └── battleship.json
│ ├── mods/
│ │ ├── aircraft_hangar.json
│ │ ├── flight_deck.json # maybe redundant in poc with hangar but here as example anyways
│ │ └── reinforced_armor.json
│ ├── equipment/
│ │ ├── main_guns.json
│ │ ├── torpedoes.json
│ │ ├── attack_planes.json
│ │ └── radar.json
│ ├── tags/
│ │ └── derivation_rules.json
│ ├── encounters/
│ │ └── enemy_fleets.json
│ └── schema/ # JSON schemas for validation
│ ├── hull_schema.json
│ ├── mod_schema.json
│ └── equipment_schema.json
│
├── engine/ # Game loop and state transitions
│ ├── __init__.py
│ ├── game.py # Main game loop (pure)
│ ├── map.py # Map generation and navigation
│ ├── nodes.py # Node type handlers
│ └── progression.py # Run and meta-progression
│
├── loaders/ # IO boundary: data loading
│ ├── __init__.py
│ ├── loader.py # Main data loader
│ ├── validator.py # Schema validation
│ └── registry.py # Runtime lookup tables
│
├── adapters/ # IO boundary: UI integration
│ ├── __init__.py
│ ├── cli.py # CLI interface
│ ├── events_to_text.py # Event log → human text
│ └── serialization.py # GameState ↔ JSON
│
├── tests/ # Test suite
│ ├── unit/ # Unit tests per module
│ ├── integration/ # Combat + state integration
│ ├── golden/ # Golden tests with fixed seeds
│ └── fixtures/ # Test data and builders
│
└── scripts/ # Development utilities
├── run_cli.py # Entry point for CLI
├── validate_data.py # Validate all JSON files
└── seed_explorer.py # Tool for testing seeds
```
### 1.2 Dependency Flow
```
adapters/ ──→ engine/ ──→ core/
loaders/ ──→ data/ ──→ (runtime registry)
scripts/ ──→ adapters/ + loaders/
All modules depend on core/
No module in core/ imports from engine/, loaders/, or adapters/
```
**Rationale**: The core must be pure and isolated. Engine orchestrates core functions. Loaders translate files into core data structures. Adapters translate between core and the outside world.
---
## 2. Core Data Models
### 2.1 GameState
```python
@dataclass(frozen=True)
class GameState:
"""
Immutable snapshot of the entire game.
All state transitions produce a new GameState.
"""
run_id: str
player_fleet: Fleet
map_state: MapState
current_node: NodeId
meta_unlocks: frozenset[str]
rng_seed: int
turn_number: int
event_history: tuple[Event, ...] # Append-only log
def with_fleet(self, new_fleet: Fleet) -> 'GameState':
"""Return new state with updated fleet."""
return replace(self, player_fleet=new_fleet)
```
**Rationale**: Immutability enables time travel, undo, replay, and deterministic testing. All mutations return new instances.
### 2.2 Ship
```python
@dataclass(frozen=True)
class Ship:
"""
A single ship instance.
Identity = Hull + Mods + Equipment
"""
id: str
hull: HullTemplate
mods: tuple[Mod, ...] # Semi-permanent, ordered
equipment: tuple[Equipment, ...] # Swappable, ordered
current_hp: int
status_effects: frozenset[str] # TODO: Define StatusEffect after gameplay design
@property
def tags(self) -> frozenset[Tag]:
"""Derive tags from current state. No caching in PoC."""
return derive_tags(self)
@property
def stats(self) -> Stats:
"""Aggregate stats from hull + mods + equipment. No caching in PoC."""
return compute_stats(self)
def with_equipment(self, new_equipment: tuple[Equipment, ...]) -> 'Ship':
"""Return new ship with equipment replaced."""
return replace(self, equipment=new_equipment)
```
**Rationale**: Ship is the core entity. Tags and stats are derived on every access. Caching can be added later if profiling shows it's needed.
### 2.3 Fleet
```python
@dataclass(frozen=True)
class Fleet:
"""
Collection of ships with derived chemistry.
"""
ships: tuple[Ship, ...]
formation: dict | None # TODO: Define Formation after gameplay design
@property
def active_ships(self) -> tuple[Ship, ...]:
"""Ships that can still act (HP > 0, not disabled)."""
return tuple(s for s in self.ships if s.current_hp > 0)
@property
def fleet_tags(self) -> frozenset[Tag]:
"""Union of all ship tags."""
return frozenset().union(*(s.tags for s in self.ships))
def get_chemistry_effects(self) -> tuple[dict, ...]:
"""
Compute fleet-level synergies based on tag composition.
Examples: SCREEN + CAPITAL, multiple AVIATOR, etc.
TODO: Define ChemistryEffect structure after gameplay design.
Placeholder returns dicts with 'type' and 'effect' keys.
"""
return derive_chemistry(self)
```
**Rationale**: Fleet is a container but also has emergent properties. Chemistry effects are computed, not stored, to maintain derivation principle.
### 2.4 Tags
```python
@dataclass(frozen=True)
class Tag:
"""
A derived label that affects multiple systems.
Tags are never manually assigned.
"""
name: str
source: str # Derivation reason (e.g., "flight_deck_mod + carrier_hull")
# Tag rules are loaded from JSON data files, not hardcoded in Python.
# Example JSON format for tag derivation rules:
#
# {
# "tag": "AVIATOR",
# "conditions": [
# {
# "type": "equipment_has_property",
# "property": "grants_flight",
# "value": true,
# "quantifier": "any"
# },
# {
# "type": "stat_comparison",
# "stat": "deck_capacity",
# "operator": ">=",
# "value": 20
# }
# ],
# "logic": "AND"
# }
#
# This allows modders to add new tags via JSON without writing Python code.
@dataclass(frozen=True)
class TagDerivationRule:
"""
Rule for deriving a tag from ship state.
Loaded from JSON and compiled into a predicate function.
"""
tag_name: str
conditions: tuple[dict, ...] # Condition definitions from JSON
logic: str # "AND" or "OR"
def evaluate(self, ship: Ship) -> bool:
"""Evaluate all conditions against ship state."""
results = [evaluate_condition(ship, cond) for cond in self.conditions]
return all(results) if self.logic == "AND" else any(results)
def evaluate_condition(ship: Ship, condition: dict) -> bool:
"""
Evaluate a single condition from JSON rule definition.
Interpreter for the tag rule mini-language.
"""
cond_type = condition["type"]
if cond_type == "stat_comparison":
stat_value = getattr(ship.stats, condition["stat"])
return compare(stat_value, condition["operator"], condition["value"])
elif cond_type == "equipment_has_property":
prop = condition["property"]
value = condition["value"]
quantifier = condition.get("quantifier", "any")
matches = [getattr(eq, prop) == value for eq in ship.equipment]
return any(matches) if quantifier == "any" else all(matches)
elif cond_type == "hull_type":
return ship.hull.type == condition["value"]
# ... more condition types as needed
return False
def derive_tags(ship: Ship) -> frozenset[Tag]:
"""Apply all derivation rules to a ship."""
# TAG_RULES loaded from data/tags/derivation_rules.json at startup
return frozenset(
Tag(name=rule.tag_name, source=f"rule:{rule.tag_name}")
for rule in TAG_RULES
if rule.evaluate(ship)
)
```
**Rationale**: Tags are computed from observable state. Rules are data-driven and testable. Adding a tag requires adding a rule, ensuring intentional design.
### 2.5 Equipment and Mods
```python
@dataclass(frozen=True)
class Equipment:
"""
Swappable tactical loadout.
"""
id: str
name: str
slot_type: str # "WEAPON", "SENSOR", "DEFENSE"
stat_modifiers: Stats
grants_flight: bool
triggers: tuple[Trigger, ...] # Combat phase triggers
@dataclass(frozen=True)
class Mod:
"""
Semi-permanent structural alteration.
"""
id: str
name: str
stat_modifiers: Stats
adds_capacity: int
restrictions: tuple[str, ...] # Hull types this can attach to
@dataclass(frozen=True)
class Stats:
"""
Aggregated numeric attributes.
"""
hp: int = 0
speed: int = 0
armor: int = 0
firepower: int = 0
accuracy: int = 0
evasion: int = 0
deck_capacity: int = 0
torpedo_tubes: int = 0
def __add__(self, other: 'Stats') -> 'Stats':
"""Sum all stats for aggregation."""
return Stats(
hp=self.hp + other.hp,
speed=self.speed + other.speed,
armor=self.armor + other.armor,
firepower=self.firepower + other.firepower,
accuracy=self.accuracy + other.accuracy,
evasion=self.evasion + other.evasion,
deck_capacity=self.deck_capacity + other.deck_capacity,
torpedo_tubes=self.torpedo_tubes + other.torpedo_tubes,
)
```
**Rationale**: Stats are additive. Equipment and Mods are immutable templates loaded from data. Ship stats = Hull stats + sum(Mod stats) + sum(Equipment stats).
### 2.6 HullTemplate
```python
@dataclass(frozen=True)
class HullTemplate:
"""
Immutable base ship blueprint.
"""
id: str
name: str
type: str # "DESTROYER", "CRUISER", "BATTLESHIP", "CARRIER"
base_stats: Stats
mod_slots: int
equipment_slots: int
```
---
## 3. Combat Resolution Architecture
### 3.1 Combat Entry Point
```python
def resolve_combat(
player_fleet: Fleet,
enemy_fleet: Fleet,
seed: int
) -> tuple[CombatResult, tuple[Event, ...]]:
"""
Pure function: fleets + seed → outcome + event log.
Returns:
CombatResult: Final state (victory, defeat, or retreat)
Event log: Structured history of what happened
"""
rng = SeededRNG(seed)
combat_state = CombatState(
player_fleet=player_fleet,
enemy_fleet=enemy_fleet,
turn=0,
events=()
)
while not is_combat_over(combat_state):
combat_state = execute_combat_turn(combat_state, rng)
return determine_result(combat_state), combat_state.events
```
**Rationale**: Combat is a pure function. All randomness is seeded. State transitions are explicit. Events are emitted as the log, not side effects.
### 3.2 Combat Phases
```python
@dataclass(frozen=True)
class CombatState:
"""Snapshot of combat at a specific turn."""
player_fleet: Fleet
enemy_fleet: Fleet
turn: int
events: tuple[Event, ...]
def emit(self, event: Event) -> 'CombatState':
"""Append event to log and return new state."""
return replace(self, events=self.events + (event,))
# Phase execution order
PHASE_ORDER = (
"DETECTION",
"AIR_OPERATIONS",
"SURFACE_GUNNERY",
"TORPEDO_ATTACKS",
"DAMAGE_CONTROL",
)
def execute_combat_turn(state: CombatState, rng: RNG) -> CombatState:
"""Execute all phases in order."""
state = state.emit(Event(type="TURN_START", turn=state.turn))
for phase_name in PHASE_ORDER:
state = state.emit(Event(type="PHASE_START", phase=phase_name))
state = execute_phase(phase_name, state, rng)
state = state.emit(Event(type="PHASE_END", phase=phase_name))
state = state.emit(Event(type="TURN_END", turn=state.turn))
return replace(state, turn=state.turn + 1)
```
**Rationale**: Phases are executed sequentially. Each phase queries tags, triggers equipment, and updates state. All actions emit events for UI rendering.
### 3.3 Phase Handlers
```python
# Example: Surface Gunnery Phase
def execute_phase(phase_name: str, state: CombatState, rng: RNG) -> CombatState:
"""Dispatch to phase-specific handler."""
handlers = {
"DETECTION": execute_detection_phase,
"AIR_OPERATIONS": execute_air_phase,
"SURFACE_GUNNERY": execute_gunnery_phase,
"TORPEDO_ATTACKS": execute_torpedo_phase,
"DAMAGE_CONTROL": execute_damage_control_phase,
}
return handlers[phase_name](state, rng)
def execute_gunnery_phase(state: CombatState, rng: RNG) -> CombatState:
"""
Each ship with ARTILLERY or firepower > threshold attacks.
"""
# Query attackers
attackers = [
s for s in state.player_fleet.active_ships
if can_attack_in_phase(s, "SURFACE_GUNNERY")
]
for attacker in attackers:
# Select target
target = select_target(attacker, state.enemy_fleet, rng)
if target is None:
continue
# Resolve attack
hit = resolve_hit(attacker, target, rng)
damage = calculate_damage(attacker, target, hit, "GUNNERY")
# Emit event
state = state.emit(Event(
type="ATTACK",
attacker_id=attacker.id,
target_id=target.id,
weapon_type="GUNNERY",
hit=hit,
damage=damage,
))
# Apply damage
if damage > 0:
state = apply_damage(state, target.id, damage)
return state
def can_attack_in_phase(ship: Ship, phase: str) -> bool:
"""Check if ship can act in this phase."""
if phase == "SURFACE_GUNNERY":
return ship.stats.firepower > 0 or Tag("ARTILLERY", "") in ship.tags
elif phase == "TORPEDO_ATTACKS":
return ship.stats.torpedo_tubes > 0 or Tag("TORPEDO_SPECIALIST", "") in ship.tags
elif phase == "AIR_OPERATIONS":
return Tag("AVIATOR", "") in ship.tags
return False
```
**Rationale**: Each phase is a pure function. Queries use tags and stats. Randomness is explicit via RNG. State updates are immutable.
### 3.4 Event System
**STATUS: PROVISIONAL - Awaiting gameplay design finalization**
Current implementation uses a single Event dataclass with string discriminator and optional fields.
This will be replaced with a proper typed event hierarchy (tagged union) once combat events are finalized.
```python
@dataclass(frozen=True)
class Event:
"""
Structured log entry for combat or game events.
UI renders these; core never prints.
TODO: Replace with typed event hierarchy after gameplay lock.
Planned approach: Union of specific event types (AttackEvent, PhaseStartEvent, etc.)
"""
type: str # "ATTACK", "SHIP_DISABLED", "TAG_GAINED", etc.
turn: int | None = None
phase: str | None = None
attacker_id: str | None = None
target_id: str | None = None
damage: int | None = None
hit: bool | None = None
weapon_type: str | None = None
# ... extensible fields
# Event types (example subset)
EVENT_TYPES = frozenset([
"TURN_START", "TURN_END",
"PHASE_START", "PHASE_END",
"ATTACK", "DAMAGE", "MISS",
"SHIP_DISABLED", "SHIP_DESTROYED",
"TAG_GAINED", "TAG_LOST",
"CHEMISTRY_TRIGGERED",
])
```
**Rationale**: Events are data, not side effects. They form a complete audit trail. UI translates events into visuals. Testing validates event sequences. Current stringly-typed approach is acceptable for PoC but should be replaced with proper types for production.
### 3.5 Targeting
```python
def select_target(
attacker: Ship,
enemy_fleet: Fleet,
rng: RNG
) -> Ship | None:
"""
Select a valid target based on tags, chemistry, and randomness.
"""
candidates = enemy_fleet.active_ships
if not candidates:
return None
# Check for forced targeting (e.g., screen ships absorb torpedo hits)
chemistry = enemy_fleet.get_chemistry_effects()
forced_target = apply_forced_targeting(attacker, chemistry, candidates)
if forced_target:
return forced_target
# Weight by ship role and current HP
weights = [compute_target_weight(attacker, target) for target in candidates]
return rng.weighted_choice(candidates, weights)
def compute_target_weight(attacker: Ship, target: Ship) -> float:
"""
Compute targeting preference.
Example: ARTILLERY prefers CAPITAL ships.
"""
weight = 1.0
if Tag("ARTILLERY", "") in attacker.tags and Tag("CAPITAL", "") in target.tags:
weight *= 2.0
if target.current_hp < target.stats.hp * 0.3:
weight *= 1.5 # Prefer wounded targets
return weight
```
**Rationale**: Targeting is deterministic given RNG seed. Chemistry effects can force targets (e.g., screens protect capitals). Weights are derived from tags.
### 3.6 Damage Calculation
```python
def calculate_damage(
attacker: Ship,
target: Ship,
hit: bool,
weapon_type: str
) -> int:
"""
Compute damage dealt.
"""
if not hit:
return 0
base_damage = get_weapon_damage(attacker, weapon_type)
armor_reduction = target.stats.armor * 0.5
final_damage = max(1, int(base_damage - armor_reduction))
# Critical hit check (could use tags here)
# if Tag("CRITICAL_SPECIALIST", "") in attacker.tags:
# final_damage *= 2
return final_damage
def resolve_hit(attacker: Ship, target: Ship, rng: RNG) -> bool:
"""
Determine if attack hits.
"""
hit_chance = base_hit_chance(attacker.stats.accuracy, target.stats.evasion)
return rng.roll(hit_chance)
def base_hit_chance(accuracy: int, evasion: int) -> float:
"""
Accuracy vs evasion formula.
Example: 70% base, +2% per accuracy, -2% per evasion.
"""
return max(0.1, min(0.95, 0.7 + (accuracy - evasion) * 0.02))
```
**Rationale**: Damage is computed from stats and armor. Hit chance is a formula. RNG is explicit. No hidden rolls.
---
## 4. Data Loading and Validation
### 4.1 Data File Structure
```json
// data/hulls/destroyer.json
{
"id": "hull_destroyer_basic",
"name": "Fletcher-class Destroyer",
"type": "DESTROYER",
"base_stats": {
"hp": 100,
"speed": 35,
"armor": 10,
"firepower": 40,
"accuracy": 60,
"evasion": 70,
"deck_capacity": 0,
"torpedo_tubes": 10
},
"mod_slots": 1,
"equipment_slots": 3
}
```
```json
// data/equipment/main_guns.json
{
"id": "eq_5inch_guns",
"name": "5-inch/38 Dual Purpose Guns",
"slot_type": "WEAPON",
"stat_modifiers": {
"firepower": 20,
"accuracy": 10
},
"grants_flight": false,
"triggers": [
{
"phase": "SURFACE_GUNNERY",
"effect": "standard_attack"
}
]
}
```
### 4.2 Loader Architecture
```python
# loaders/loader.py
class DataLoader:
"""
IO boundary: loads files and returns pure data structures.
"""
def __init__(self, data_dir: Path):
self.data_dir = data_dir
self.validator = DataValidator()
def load_all(self) -> GameData:
"""Load and validate all game data."""
return GameData(
hulls=self._load_hulls(),
mods=self._load_mods(),
equipment=self._load_equipment(),
tag_rules=self._load_tag_rules(),
encounters=self._load_encounters(),
)
def _load_hulls(self) -> dict[str, HullTemplate]:
"""Load all hull definitions."""
hulls = {}
for file_path in (self.data_dir / "hulls").glob("*.json"):
data = json.loads(file_path.read_text())
self.validator.validate(data, "hull_schema.json")
hulls[data["id"]] = parse_hull(data)
return hulls
@dataclass(frozen=True)
class GameData:
"""
Immutable registry of all loaded game content.
Created once at startup, never modified.
"""
hulls: dict[str, HullTemplate]
mods: dict[str, Mod]
equipment: dict[str, Equipment]
tag_rules: tuple[TagDerivationRule, ...]
encounters: dict[str, EncounterTemplate]
```
**Rationale**: Loader is the IO boundary. It validates data at load time, then returns immutable structures. Core never touches files.
### 4.3 Validation
```python
# loaders/validator.py
import jsonschema
class DataValidator:
"""Validates data files against JSON schemas."""
def __init__(self, schema_dir: Path):
self.schemas = self._load_schemas(schema_dir)
def validate(self, data: dict, schema_name: str) -> None:
"""Raise exception if data doesn't match schema."""
schema = self.schemas[schema_name]
jsonschema.validate(instance=data, schema=schema)
```
**Rationale**: Validation happens at load time. Invalid data fails fast. Schemas are versioned with data.
---
## 5. Integration Points for UI/Frontends
### 5.1 Adapter Pattern
```python
# adapters/cli.py
class CLIAdapter:
"""
Translates between CLI I/O and core game logic.
"""
def __init__(self, game_data: GameData):
self.game_data = game_data
self.state: GameState | None = None
def start_new_run(self) -> None:
"""Initialize a new game state."""
# Present fleet selection
fleet = self._prompt_fleet_selection()
# Create initial state
self.state = create_initial_state(fleet, game_data=self.game_data)
# Start game loop
self.run_game_loop()
def run_game_loop(self) -> None:
"""Main CLI loop."""
while not is_run_over(self.state):
self._render_state()
action = self._prompt_action()
self.state, events = apply_action(self.state, action, self.game_data)
self._render_events(events)
def _render_state(self) -> None:
"""Print current game state."""
print(format_game_state(self.state))
def _render_events(self, events: tuple[Event, ...]) -> None:
"""Print event log as human-readable text."""
for event in events:
print(format_event(event))
```
**Rationale**: Adapter owns IO. Core is unaware of CLI. Different adapters (web UI, game engine) follow same pattern.
### 5.2 Event-to-Text Rendering
```python
# adapters/events_to_text.py
def format_event(event: Event) -> str:
"""Convert event to human-readable text."""
formatters = {
"ATTACK": format_attack_event,
"SHIP_DISABLED": format_ship_disabled_event,
"PHASE_START": format_phase_start_event,
}
formatter = formatters.get(event.type, format_generic_event)
return formatter(event)
def format_attack_event(event: Event) -> str:
"""Format: 'USS Fletcher fires at enemy cruiser (HIT, 45 damage)'"""
hit_str = "HIT" if event.hit else "MISS"
damage_str = f"{event.damage} damage" if event.hit else ""
return f"{event.attacker_id} fires at {event.target_id} ({hit_str}, {damage_str})"
```
**Rationale**: Rendering is separate from logic. Events are structured data. Different UIs can render differently.
### 5.3 Serialization
```python
# adapters/serialization.py
def serialize_game_state(state: GameState) -> str:
"""Convert GameState to JSON for saving."""
return json.dumps(dataclasses.asdict(state), indent=2)
def deserialize_game_state(json_str: str, game_data: GameData) -> GameState:
"""Reconstruct GameState from JSON."""
data = json.loads(json_str)
return parse_game_state(data, game_data)
```
**Rationale**: State is serializable. Enables save/load, replay, and debugging. Core doesn't know about serialization.
---
## 6. Testing Architecture
### 6.1 Test Structure
```python
# tests/unit/test_tags.py
def test_aviator_tag_derived_from_flight_deck():
"""AVIATOR tag should be present when flight equipment + capacity."""
hull = HullTemplate(id="test", type="CARRIER", base_stats=Stats(deck_capacity=30), ...)
mod = Mod(id="flight_deck", adds_capacity=10, ...)
equipment = Equipment(id="aircraft", grants_flight=True, ...)
ship = Ship(id="test_ship", hull=hull, mods=(mod,), equipment=(equipment,))
assert Tag("AVIATOR", ...) in ship.tags
# tests/integration/test_combat.py
def test_screen_absorbs_torpedo():
"""Screen ships should absorb first torpedo hit to capital."""
player_fleet = Fleet(ships=(
create_destroyer(tag=Tag("SCREEN", "")),
create_battleship(tag=Tag("CAPITAL", "")),
))
enemy_fleet = Fleet(ships=(create_submarine(),))
result, events = resolve_combat(player_fleet, enemy_fleet, seed=12345)
# Find torpedo attack event
torpedo_events = [e for e in events if e.type == "ATTACK" and e.weapon_type == "TORPEDO"]
assert torpedo_events[0].target_id == "destroyer_id" # Screen took hit
# tests/golden/test_determinism.py
def test_same_seed_same_outcome():
"""Same fleets and seed must produce identical results."""
player_fleet = create_test_fleet()
enemy_fleet = create_test_enemy_fleet()
seed = 42
result1, events1 = resolve_combat(player_fleet, enemy_fleet, seed)
result2, events2 = resolve_combat(player_fleet, enemy_fleet, seed)
assert result1 == result2
assert events1 == events2
```
### 6.2 Test Fixtures
```python
# tests/fixtures/builders.py
def create_test_destroyer() -> Ship:
"""Builder for test destroyer with sensible defaults."""
hull = HullTemplate(id="test_dd", type="DESTROYER", base_stats=Stats(hp=100, ...))
return Ship(id="dd_test", hull=hull, mods=(), equipment=())
def create_test_fleet(ship_count: int = 3) -> Fleet:
"""Builder for test fleet."""
ships = tuple(create_test_destroyer() for _ in range(ship_count))
return Fleet(ships=ships, formation=None)
```
**Rationale**: Fixtures reduce boilerplate. Builders enable easy test data creation. Golden tests catch regressions.
### 6.3 Golden Tests
```python
# tests/golden/test_fleet_vs_fleet.py
def test_standard_fleet_composition():
"""
Golden test: 2 destroyers + 1 cruiser vs 3 destroyers.
Expected outcome recorded and validated.
"""
player = Fleet(ships=(
load_ship("destroyer_basic"),
load_ship("destroyer_basic"),
load_ship("cruiser_basic"),
))
enemy = Fleet(ships=(
load_ship("destroyer_basic"),
load_ship("destroyer_basic"),
load_ship("destroyer_basic"),
))
result, events = resolve_combat(player, enemy, seed=99999)
# Compare against recorded golden output
expected_events = load_golden_events("standard_fleet_composition.json")
assert events == expected_events
assert result == CombatResult.VICTORY
```
**Rationale**: Golden tests validate entire combat flows. Any change to combat logic requires updating goldens. Catches unintended changes.
---
## 7. RNG Architecture
### 7.1 Deterministic RNG Wrapper
```python
# core/rng.py
import random
class SeededRNG:
"""
Deterministic random number generator.
Same seed always produces same sequence.
"""
def __init__(self, seed: int):
self._rng = random.Random(seed)
def roll(self, probability: float) -> bool:
"""Return True with given probability (0.0 to 1.0)."""
return self._rng.random() < probability
def randint(self, a: int, b: int) -> int:
"""Return random integer in [a, b]."""
return self._rng.randint(a, b)
def choice(self, seq: tuple) -> Any:
"""Select random element from sequence."""
return self._rng.choice(seq)
def weighted_choice(self, seq: tuple, weights: list[float]) -> Any:
"""Select element with weighted probability."""
return self._rng.choices(seq, weights=weights, k=1)[0]
def shuffle(self, seq: tuple) -> tuple:
"""Return shuffled copy of sequence."""
lst = list(seq)
self._rng.shuffle(lst)
return tuple(lst)
```
**Rationale**: All randomness goes through this wrapper. Seed is explicit. Testing uses fixed seeds. Replay is trivial.
### 7.2 RNG Threading
```python
def apply_action(state: GameState, action: Action, game_data: GameData) -> tuple[GameState, tuple[Event, ...]]:
"""
Process an action and return new state + events.
RNG seed is derived from current state.
"""
# Derive new seed from state (ensures determinism)
# Action may contain unhashable fields (dicts), so serialize it first
import json
action_hash = hash(json.dumps(dataclasses.asdict(action), sort_keys=True))
new_seed = hash((state.rng_seed, state.turn_number, action_hash))
rng = SeededRNG(new_seed)
# Dispatch action
if action.type == "START_COMBAT":
result, events = resolve_combat(state.player_fleet, action.enemy_fleet, new_seed)
new_state = state.with_combat_result(result)
elif action.type == "EQUIP_ITEM":
new_state = equip_item(state, action.ship_id, action.equipment_id)
events = (Event(type="ITEM_EQUIPPED", ship_id=action.ship_id),)
# ... more actions
return replace(new_state, rng_seed=new_seed), events
```
**Rationale**: Each action derives a new seed from current state + action. Ensures different branches have different outcomes but same path is deterministic. Action is serialized to JSON for stable hashing since it may contain unhashable dict fields.
---
## 8. Map and Progression
### 8.1 Map Structure
```python
@dataclass(frozen=True)
class MapState:
"""
Represents the current run's map structure and progress.
"""
nodes: dict[NodeId, Node]
edges: tuple[Edge, ...]
current_node_id: NodeId
visited_nodes: frozenset[NodeId]
@dataclass(frozen=True)
class Node:
id: NodeId
type: str # "COMBAT", "ELITE", "BOSS", "REFIT", "EVENT", "SALVAGE"
data: dict # Node-specific data (e.g., enemy fleet for combat)
@dataclass(frozen=True)
class Edge:
from_node: NodeId
to_node: NodeId
```
### 8.2 Node Handlers
```python
# engine/nodes.py
def handle_node(state: GameState, game_data: GameData) -> tuple[GameState, tuple[Event, ...]]:
"""
Execute current node and return updated state.
"""
node = state.map_state.nodes[state.current_node]
handlers = {
"COMBAT": handle_combat_node,
"REFIT": handle_refit_node,
"EVENT": handle_event_node,
"BOSS": handle_boss_node,
}
return handlers[node.type](state, node, game_data)
def handle_combat_node(state: GameState, node: Node, game_data: GameData) -> tuple[GameState, tuple[Event, ...]]:
"""Combat node: resolve battle, update fleet."""
enemy_fleet = load_encounter(node.data["encounter_id"], game_data)
result, events = resolve_combat(state.player_fleet, enemy_fleet, state.rng_seed)
if result == CombatResult.DEFEAT:
return state.with_run_ended(), events
# Apply rewards
new_state = apply_combat_rewards(state, result)
return new_state, events
def handle_refit_node(state: GameState, node: Node, game_data: GameData) -> tuple[GameState, tuple[Event, ...]]:
"""Refit node: player chooses equipment swaps or mods."""
# This is where player makes choices (via Action)
# Node handler prepares options, waits for action
available_equipment = node.data["equipment_pool"]
events = (Event(type="REFIT_AVAILABLE", options=available_equipment),)
return state, events
```
**Rationale**: Each node type has a handler. Handlers are pure functions. Player choices come via actions.
---
## 9. Action System
### 9.1 Action Definitions
```python
@dataclass(frozen=True)
class Action:
"""
Represents a player decision or game event trigger.
"""
type: str
# Action-specific fields
ship_id: str | None = None
equipment_id: str | None = None
target_node_id: NodeId | None = None
choices: dict | None = None
# Example actions:
# Action(type="MOVE_TO_NODE", target_node_id="node_5")
# Action(type="EQUIP_ITEM", ship_id="ship_1", equipment_id="eq_radar")
# Action(type="START_COMBAT")
# Action(type="SELECT_EVENT_CHOICE", choices={"option": "A"})
```
### 9.2 Action Validation
```python
def validate_action(state: GameState, action: Action, game_data: GameData) -> bool:
"""
Check if action is legal in current state.
"""
validators = {
"MOVE_TO_NODE": validate_move_action,
"EQUIP_ITEM": validate_equip_action,
}
validator = validators.get(action.type)
if validator is None:
return False
return validator(state, action, game_data)
def validate_equip_action(state: GameState, action: Action, game_data: GameData) -> bool:
"""Check if equipment swap is legal."""
ship = find_ship(state.player_fleet, action.ship_id)
if ship is None:
return False
equipment = game_data.equipment.get(action.equipment_id)
if equipment is None:
return False
# Check if ship has capacity for this equipment
return len(ship.equipment) < ship.hull.equipment_slots
```
**Rationale**: Actions are data. Validation is a pure function. Invalid actions are rejected before state transition.
### 9.3 Error Handling with Result Pattern
All state transitions use the Result pattern for explicit error handling:
```python
from typing import TypeVar, Generic
from dataclasses import dataclass
T = TypeVar('T')
E = TypeVar('E')
@dataclass(frozen=True)
class Ok(Generic[T]):
"""Successful result containing a value."""
value: T
def is_ok(self) -> bool:
return True
def is_err(self) -> bool:
return False
@dataclass(frozen=True)
class Err(Generic[E]):
"""Error result containing an error value."""
error: E
def is_ok(self) -> bool:
return False
def is_err(self) -> bool:
return True
Result = Ok[T] | Err[E]
```
**Usage in action processing:**
```python
def apply_action(
state: GameState,
action: Action,
game_data: GameData
) -> Result[tuple[GameState, tuple[Event, ...]], str]:
"""
Process an action and return new state + events, or an error.
"""
# Validate action
if not validate_action(state, action, game_data):
return Err(f"Invalid action: {action.type}")
# Derive new seed and process
try:
action_hash = hash(json.dumps(dataclasses.asdict(action), sort_keys=True))
new_seed = hash((state.rng_seed, state.turn_number, action_hash))
# Dispatch action
if action.type == "START_COMBAT":
result, events = resolve_combat(state.player_fleet, action.enemy_fleet, new_seed)
new_state = state.with_combat_result(result)
elif action.type == "EQUIP_ITEM":
new_state = equip_item(state, action.ship_id, action.equipment_id)
events = (Event(type="ITEM_EQUIPPED", ship_id=action.ship_id),)
else:
return Err(f"Unknown action type: {action.type}")
return Ok((replace(new_state, rng_seed=new_seed), events))
except Exception as e:
return Err(f"Action processing failed: {str(e)}")
```
**Benefits:**
- Errors are values, not exceptions
- Callers must explicitly handle both success and error cases
- Type system ensures error handling is not forgotten
- No hidden control flow
**Alternative:** Use existing library like `returns` or `result` for more features (map, flatmap, etc.).
---
## 10. Summary of Architectural Boundaries
### 10.1 The Pure Core
**Location**: `core/`, `engine/`
**Rules**:
- No `import os`, `import sys`, `print()`, `input()`, `open()`
- All functions are deterministic (same input → same output)
- No globals, no mutable class variables
- All data structures are immutable (frozen dataclasses, tuples, frozensets)
**Purpose**: Game logic is testable, replayable, and portable.
### 10.2 The IO Boundary
**Location**: `loaders/`, `adapters/`
**Rules**:
- These modules may perform IO (read files, print to console)
- They translate between external formats and core data structures
- They call core functions but core never calls them
**Purpose**: Isolate side effects. Core remains pure.
### 10.3 Dependency Invariants
```
adapters → engine → core
loaders → core
tests → all
core → NOTHING (except stdlib)
```
**Enforcement**: CI checks imports. Core modules that import from adapters or loaders fail the build.
---
## 11. Key Design Decisions
### 11.1 Why Immutability?
Immutable state enables:
- Time travel debugging (any past state is preserved)
- Trivial undo/redo
- Deterministic replay (just replay actions from initial state)
- Fearless parallelization (no shared mutable state)
- Golden tests (serialize state, compare)
### 11.2 Why Event Logs Instead of Callbacks?
Callbacks couple core to UI. Event logs:
- Are data, not code
- Can be serialized, filtered, replayed
- Enable multiple simultaneous UI views (CLI, GUI, replay viewer)
- Support analytics and debugging
### 11.3 Why Tags Are Derived?
Manual tagging leads to:
- Desync bugs (forgot to add tag when equipping item)
- Inconsistency (same state, different tags)
- Testing difficulty (must mock tag state)
Derived tags:
- Always reflect current state
- Are testable (just check derivation rules)
- Eliminate entire class of bugs
### 11.4 Why Pure Functions?
Side effects make testing hard. Pure functions:
- Are deterministic (same input → same output)
- Are testable (no mocking, no setup/teardown)
- Are composable (output of f is input to g)
- Enable parallelization and caching
### 11.5 Why CLI First?
CLI forces architectural discipline:
- Can't hide complexity in fancy UI
- Must expose clean APIs
- Ensures data-driven design
- Easy to test and script
Game engines come later as thin viewers. If we start with Unity/Godot, rules leak into the engine and become untestable.
---
## 12. Open Questions and Future Extensions
### 12.1 Save System
Save files are just serialized `GameState + GameData version`. Load validates version compatibility.
### 12.2 Replay System
Replay = initial state + sequence of actions + seeds. Replay viewer is just another adapter that steps through actions.
### 12.3 Modding
Mods are additional data files in `data/mods/`. Loader merges them with base data. No code mods (data-driven only).
### 12.4 Multiplayer (PvP)
Future extension: two players' fleets as input. Combat resolver is already symmetric. Add action synchronization layer.
### 12.5 Performance
Profiling will reveal bottlenecks. Likely optimizations:
- Aggressive caching of derived tags/stats
- Compile tag rules to bytecode
- Use numpy for batch damage calculations
Current architecture doesn't prevent optimization. Pure functions are easier to optimize (no hidden state).
---
## 13. Migration Plan from Scratch
### Phase 1: Core Data Models (Week 1)
1. Implement `core/state.py` (GameState, Ship, Fleet)
2. Implement `core/tags.py` (Tag, TagDerivationRule, derive_tags)
3. Write unit tests for tag derivation
4. Implement `core/rng.py` (SeededRNG)
### Phase 2: Data Loading (Week 1-2)
1. Define JSON schemas for hulls, equipment, mods
2. Implement `loaders/loader.py` and `loaders/validator.py`
3. Create sample data files (3 hulls, 8 equipment, 5 tags)
4. Write tests that load and validate data
### Phase 3: Combat Core (Week 2-3)
1. Implement `core/combat/resolver.py` (resolve_combat entry point)
2. Implement `core/combat/phases.py` (phase execution)
3. Implement `core/combat/events.py` (event emission)
4. Write golden tests for simple 1v1 combat
### Phase 4: CLI Adapter (Week 3)
1. Implement `adapters/cli.py` (game loop)
2. Implement `adapters/events_to_text.py` (event rendering)
3. Manual playtesting with CLI
### Phase 5: Map and Progression (Week 4)
1. Implement `engine/map.py` (map generation)
2. Implement `engine/nodes.py` (node handlers)
3. Implement `core/actions.py` (action system)
4. End-to-end run through CLI
### Phase 6: Polish and Testing (Week 5)
1. Add remaining equipment and enemies
2. Balance testing
3. Golden test suite for full runs
4. Documentation and examples
---
## 14. Success Criteria
Architecture is successful if:
1. **Determinism**: Same inputs always produce same outputs
2. **Testability**: >80% test coverage, golden tests pass
3. **Portability**: Core has zero external dependencies
4. **Modularity**: Can swap CLI for GUI without touching core
5. **Clarity**: New developer can understand combat flow in <1 hour
6. **Data-Driven**: Adding new hull/equipment requires zero code changes
---
## 15. Architecture Revisions
This section documents architectural corrections made to ensure implementation viability.
### 15.1 Caching Removed from Ship (Critical Fix)
**Original Issue**: Ship dataclass declared `frozen=True` with mutable cache fields that would never work.
**Resolution**: Removed caching entirely for PoC. Tags and stats are computed on every access. Caching can be added later if profiling shows performance issues.
### 15.2 Tag Rules Made Data-Driven (Critical Fix)
**Original Issue**: Tag derivation rules used Python lambdas, making them impossible to load from JSON and breaking the "data-driven" architecture promise.
**Resolution**: Tag rules now use JSON-based condition definitions with a rule interpreter. Modders can add new tags via JSON files without writing Python code.
Example JSON format:
```json
{
"tag": "AVIATOR",
"conditions": [
{"type": "equipment_has_property", "property": "grants_flight", "value": true, "quantifier": "any"},
{"type": "stat_comparison", "stat": "deck_capacity", "operator": ">=", "value": 20}
],
"logic": "AND"
}
```
### 15.3 Event System Marked Provisional
**Original Issue**: Events use stringly-typed design with optional fields, causing potential runtime errors.
**Resolution**: Marked as provisional pending gameplay design finalization. Current approach is acceptable for PoC but documented for replacement with typed event hierarchy (tagged union) later.
### 15.4 Action Hashing Fixed
**Original Issue**: `hash(action)` fails because Action contains unhashable dict fields.
**Resolution**: Serialize Action to JSON before hashing: `hash(json.dumps(dataclasses.asdict(action), sort_keys=True))`.
### 15.5 Undefined Types Marked as TODO
**Original Issue**: Formation, StatusEffect, and ChemistryEffect referenced but never defined.
**Resolution**:
- `StatusEffect` → `frozenset[str]` with TODO marker
- `Formation` → `dict | None` with TODO marker
- `ChemistryEffect` → `tuple[dict, ...]` with TODO marker
These will be properly defined after gameplay design settles.
### 15.6 Error Handling Strategy Added
**Original Issue**: No error handling approach specified.
**Resolution**: Added Result<T, E> pattern (section 9.3) for explicit error handling. All state transitions return `Result[tuple[GameState, Events], str]` instead of raising exceptions.
---
## End of Architecture Document
This architecture separates pure computation from side effects, makes all state transitions explicit, and ensures the game is deterministic and testable. The core is a pure function. Everything else is translation between core and the outside world.
**Document Status**: Revised with critical fixes applied. Ready for implementation of PoC.
Reference in New Issue Copy Permalink