\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.