diff --git a/README.md b/DESIGN.md similarity index 100% rename from README.md rename to DESIGN.md diff --git a/README.tex b/README.tex deleted file mode 100644 index 8853357..0000000 --- a/README.tex +++ /dev/null @@ -1,155 +0,0 @@ -\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.