Initial commit

README.md

@@ -0,0 +1,147 @@
+# Naval Composition Roguelite — Primary Design Document
+
+## 0. Design Intent
+
+A 30-minute, composition-first naval roguelite focused on decision density rather than execution.
+
+The player acts as an admiral or manager. Combat is auto-resolved, phase-based, and legible. Mastery comes from structural commitment under uncertainty. The system must be engine-agnostic and data-driven. Characters and cosmetics are optional overlays, not core mechanics.
+
+## 1. Core Pillars
+
+- Composition over Control: No real-time input during combat. All meaningful decisions occur before battles.
+- Tags over Fixed Classes: Ship type biases starting stats only. Identity emerges from equipment and mods via derived tags.
+- Commitment with Tradeoffs: Mods are semi-permanent within a run. Equipment is swappable. Strong builds create clear weaknesses.
+- Short, Finite Runs: Approximately 30 minutes per run. Loss is final. Meta-progression unlocks options, not raw power.
+
+## 2. High-Level Game Loop
+
+Start Run $->$ Choose Starting Fleet (approximately 3 ships) $->$ Navigate Branching Map (Combat, Refit, Events, Elite, Boss) $->$ Final Boss $->$ Run Ends (Win or Loss) $->$ Meta Unlocks
+
+## 3. Fleet and Ship Model
+
+### 3.1 Ship = Hull + Mods + Equipment + Tags
+
+**Hull (Base, Immutable In-Run)**
+Base stats such as HP, speed, armor, and capacity. Biases toward roles. Examples include Destroyer, Cruiser, Battleship, Carrier, and Submarine.
+
+**Mods (Semi-Permanent)**
+Structural alterations that are hard or costly to remove. Mods change the decision space rather than only numeric values. Typically limited to zero or one per ship in MVP.
+
+Examples include Flight Deck, Catapult, Superfiring Platform, Reinforced Armor, and Extended Torpedo Bays.
+
+**Equipment (Swappable)**
+Tactical loadout providing flexibility. Equipment grants stats, flags, triggers, and tags.
+
+Examples include main guns, torpedoes, aircraft, radar, fire control systems, and AA suites.
+
+## 4. Tag System
+
+### 4.1 Principles
+
+Tags are derived, never manually assigned. Each tag must affect at least two systems. Tags must be queryable by combat phases and events.
+
+### 4.2 Example Tags
+
+AVIATOR, SCREEN, CAPITAL, SCOUT, TORPEDO_SPECIALIST, ARTILLERY
+
+### 4.3 Tag Derivation (Illustrative)
+
+If a ship has flight-capable equipment and deck capacity exceeds a threshold, then the AVIATOR tag is added.
+
+## 5. Fleet Chemistry
+
+Fleet-level effects depend on composition patterns rather than individuals.
+
+Examples:
+
+- Screen plus Capital ships allow screens to absorb the first torpedo hit.
+- Fleets without Screen ships gain firepower but suffer increased torpedo vulnerability.
+- Multiple Aviator ships strengthen the air phase but weaken surface engagements.
+
+Negative synergies are intentional and desirable.
+
+## 6. Enemy Construction
+
+Enemies are built using the same grammar as player fleets: Hull plus Mods plus Equipment plus Tags.
+
+Enemies may intentionally break one construction rule or use asymmetrical constraints. There are no bespoke cheat mechanics; advantages are structural or numeric.
+
+## 7. Combat System
+
+### 7.1 Resolution Style
+
+Combat is auto-resolved, phase-based, and deterministic given an RNG seed.
+
+### 7.2 Phase Order (Initial Proposal)
+
+- Detection / Initiative
+- Air Operations
+- Surface Gunnery
+- Torpedo Attacks
+- Damage Control / Morale
+
+Each phase queries tags, triggers equipment and mods, and emits events.
+
+## 8. Event Log
+
+Combat resolution produces a structured event log.
+
+Examples include:
+
+- PHASE_START(AIR)
+- ATTACK(attacker_id, target_id, weapon_tag, hit, damage)
+- SHIP_DISABLED(ship_id)
+- TAG_GAINED or TAG_LOST
+
+The UI renders logs. The core simulation never prints or draws.
+
+## 9. Map and Nodes
+
+Node types include Combat, Elite Combat, Boss, Refit or Dockyard, Event, and Salvage.
+
+Non-combat nodes must force commitment or introduce risk. No pure free-upgrade nodes are allowed.
+
+Target ratio is approximately 50 to 60 percent combat-adjacent nodes and 40 to 50 percent logistics or events.
+
+## 10. Roguelite Progression
+
+**In-Run**
+Fleet persists, structural commitments accumulate, and loss is final.
+
+**Meta-Progression**
+Unlock new hull templates, mods, equipment, and tags or mechanics. No permanent stat buffs.
+
+## 11. Minimal Viable Scope
+
+- 3 hull types
+- 8 to 10 equipment items
+- 5 to 6 tags
+- 1 mod slot per ship
+- 1 formation system
+- Phase-based combat
+- 1 boss
+- CLI interface
+- Deterministic RNG
+- JSON or YAML data definitions
+
+## 12. Technical Architecture
+
+**Core Rules Engine**
+Implemented in Python. Pure functions only. No IO, UI, globals, or side effects. Deterministic RNG. Input is GameState plus Action plus Seed. Output is NewGameState plus EventLog.
+
+**Data**
+Definitions stored in JSON or YAML. Validated at load time. Immutable during simulation.
+
+**Testing**
+Golden tests using fixed seeds, known fleets, and expected outcomes.
+
+**Frontends**
+CLI first. Web frontend later as a thin layer. Game engines may only act as viewers and must never own rules.
+
+## 13. Explicit Non-Goals
+
+Real-time control, long-term training or XP bars, fuel or ammo micromanagement, strict historical accuracy, gacha mechanics, and idle gameplay are explicitly excluded.
+
+## 14. Design North Star
+
+A run should be winnable or losable primarily because of strategic commitments, not execution or luck alone.