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.

README.tex

@@ -0,0 +1,155 @@
+\section*{Naval Composition Roguelite — Primary Design Document}
+
+\subsection*{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.
+
+\subsection*{1. Core Pillars}
+
+\begin{itemize}
+  \item Composition over Control: No real-time input during combat. All meaningful decisions occur before battles.
+  \item Tags over Fixed Classes: Ship type biases starting stats only. Identity emerges from equipment and mods via derived tags.
+  \item Commitment with Tradeoffs: Mods are semi-permanent within a run. Equipment is swappable. Strong builds create clear weaknesses.
+  \item Short, Finite Runs: Approximately 30 minutes per run. Loss is final. Meta-progression unlocks options, not raw power.
+\end{itemize}
+
+\subsection*{2. High-Level Game Loop}
+
+Start Run $\rightarrow$ Choose Starting Fleet (approximately 3 ships) $\rightarrow$ Navigate Branching Map (Combat, Refit, Events, Elite, Boss) $\rightarrow$ Final Boss $\rightarrow$ Run Ends (Win or Loss) $\rightarrow$ Meta Unlocks
+
+\subsection*{3. Fleet and Ship Model}
+
+\subsubsection*{3.1 Ship = Hull + Mods + Equipment + Tags}
+
+\paragraph{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.
+
+\paragraph{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.
+
+\paragraph{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.
+
+\subsection*{4. Tag System}
+
+\subsubsection*{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.
+
+\subsubsection*{4.2 Example Tags}
+
+AVIATOR, SCREEN, CAPITAL, SCOUT, TORPEDO\_SPECIALIST, ARTILLERY
+
+\subsubsection*{4.3 Tag Derivation (Illustrative)}
+
+If a ship has flight-capable equipment and deck capacity exceeds a threshold, then the AVIATOR tag is added.
+
+\subsection*{5. Fleet Chemistry}
+
+Fleet-level effects depend on composition patterns rather than individuals.
+
+Examples:
+\begin{itemize}
+  \item Screen plus Capital ships allow screens to absorb the first torpedo hit.
+  \item Fleets without Screen ships gain firepower but suffer increased torpedo vulnerability.
+  \item Multiple Aviator ships strengthen the air phase but weaken surface engagements.
+\end{itemize}
+
+Negative synergies are intentional and desirable.
+
+\subsection*{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.
+
+\subsection*{7. Combat System}
+
+\subsubsection*{7.1 Resolution Style}
+
+Combat is auto-resolved, phase-based, and deterministic given an RNG seed.
+
+\subsubsection*{7.2 Phase Order (Initial Proposal)}
+
+\begin{enumerate}
+  \item Detection / Initiative
+  \item Air Operations
+  \item Surface Gunnery
+  \item Torpedo Attacks
+  \item Damage Control / Morale
+\end{enumerate}
+
+Each phase queries tags, triggers equipment and mods, and emits events.
+
+\subsection*{8. Event Log}
+
+Combat resolution produces a structured event log.
+
+Examples include:
+\begin{itemize}
+  \item PHASE\_START(AIR)
+  \item ATTACK(attacker\_id, target\_id, weapon\_tag, hit, damage)
+  \item SHIP\_DISABLED(ship\_id)
+  \item TAG\_GAINED or TAG\_LOST
+\end{itemize}
+
+The UI renders logs. The core simulation never prints or draws.
+
+\subsection*{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.
+
+\subsection*{10. Roguelite Progression}
+
+\paragraph{In-Run}
+Fleet persists, structural commitments accumulate, and loss is final.
+
+\paragraph{Meta-Progression}
+Unlock new hull templates, mods, equipment, and tags or mechanics. No permanent stat buffs.
+
+\subsection*{11. Minimal Viable Scope}
+
+\begin{itemize}
+  \item 3 hull types
+  \item 8 to 10 equipment items
+  \item 5 to 6 tags
+  \item 1 mod slot per ship
+  \item 1 formation system
+  \item Phase-based combat
+  \item 1 boss
+  \item CLI interface
+  \item Deterministic RNG
+  \item JSON or YAML data definitions
+\end{itemize}
+
+\subsection*{12. Technical Architecture}
+
+\paragraph{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.
+
+\paragraph{Data}
+Definitions stored in JSON or YAML. Validated at load time. Immutable during simulation.
+
+\paragraph{Testing}
+Golden tests using fixed seeds, known fleets, and expected outcomes.
+
+\paragraph{Frontends}
+CLI first. Web frontend later as a thin layer. Game engines may only act as viewers and must never own rules.
+
+\subsection*{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.
+
+\subsection*{14. Design North Star}
+
+A run should be winnable or losable primarily because of strategic commitments, not execution or luck alone.