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.