From 5bea0fe75b872964f6dadbb9648148b29b023618 Mon Sep 17 00:00:00 2001 From: Mikkeli Matlock Date: Fri, 9 Jan 2026 21:09:50 +0900 Subject: [PATCH] Initial commit --- README.md | 147 ++++++++++++++++++++++++++++++++++++++++++++++++++ README.tex | 155 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 302 insertions(+) create mode 100644 README.md create mode 100644 README.tex diff --git a/README.md b/README.md new file mode 100644 index 0000000..83967f0 --- /dev/null +++ b/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. diff --git a/README.tex b/README.tex new file mode 100644 index 0000000..8853357 --- /dev/null +++ b/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.