# Content Design — Ships & Modules

First real-content iteration (June 2026). This pass defines ship hull grids
and module surface masks only. Stats, materials, recipes, and threat costs in
the config files are placeholders; the recipe pass and the balancing pass
come later.

## Design principle: footprint gating

Which module fits on which hull is controlled purely by geometry — no
explicit allow-lists. Each hull grid is shaped so that it physically cannot
contain the footprint of modules from a larger size class. This keeps the
rules transparent to the player ("it doesn't fit because there is no room")
and makes them trivially moddable through the config files alone.

### Module footprint ladder

| Footprint | Modules | Smallest hull that fits it |
|-----------|---------|----------------------------|
| 1x1 | laser_cannon_s, salvager, repair_tool | drone |
| 1x2 | maneuvering_thrusters, sensor_booster, armor_plates | frigate |
| 1x3 | afterburner | frigate (eats most of it) |
| L-shape (3 cells) | weapon_stabilizer, weapon_primer, weapon_upgrade | frigate |
| 2x2 | laser_cannon_m, drone_bay | cruiser |
| 3x3 | laser_cannon_l | battleship |
| 2x6 | drone_hangar | dreadnought / carrier |

### Hull grids

`O` = buildable cell, `X` = hull structure (not buildable).

**drone (xs, 1 cell)** — exactly one 1x1 module: a small gun, a salvager, or
a repair tool. This is what makes drone roles swappable.

    O

**frigate (s, 5 cells)** — plus shape. Every 1x2 placement crosses the center
cell, so at most ONE 1x2 support fits; alternatively one L-shaped weapon
modifier or one afterburner through the center line. Gun-boat with one or two
support modules, as intended.

    XOX
    OOO
    XOX

**destroyer (s, 8 cells)** — gun deck with three turret bumps. More cells
than the frigate (more small guns), but still no 2x2 area anywhere, so medium
hardware can never be mounted.

    OXOXO
    OOOOO

**cruiser (m, 12 cells)** — notched corners. Fits at most two 2x2 m guns
(stacked through the middle), leaving the side cells for supports. No 3x3
area.

    XOOX
    OOOO
    OOOO
    XOOX

**battlecruiser (m, 16 cells)** — split bow with two gun cheeks, tapered
stern. Fits three 2x2 m guns — one more than the cruiser — with small support
slots left over. The bow split and stern taper prevent any 3x3 area (no l
gun) and any 2x6 area (no drone hangar).

    OOXXOO
    OOOOOO
    XOOOOX
    XXOOXX

**battleship (l, 20 cells)** — 5 wide, so at most ONE 3x3 l gun fits, and
mounting it consumes nearly half the grid, leaving only narrow strips for
supports. Without an l gun it flexibly fits several m guns. Too narrow for a
drone hangar.

    XOOOX
    OOOOO
    OOOOO
    OOOOO
    XOXOX

**dreadnought (xl, 42 cells)** — 11-wide, 3-deep main battery deck: three 3x3
l guns fit side by side with spacer columns to spare, plus bow/stern strips
for supports. Wide enough for a drone hangar too, if the player wants to
trade a gun battery for one.

    XXXOOOOOXXX
    OOOOOOOOOOO
    OOOOOOOOOOO
    OOOOOOOOOOO
    XXOOXXXOOXX

**carrier (xl, 37 cells)** — the top flight deck (rows 0–1) is the only
region wide enough for the 2x6 drone hangar, and exactly one fits. The middle
deck row is broken up by elevator shafts (X cells placed so every 3-column
window hits one), which is what prevents any 3x3 l gun from ever fitting.
Lower decks hold supports and 2x2 point-defense m guns.

    XOOOOOOOOX
    OOOOOOOOOO
    OOXOOXOOXO
    XOOOOOOOOX
    XXXOOOOXXX

### Verified gating matrix

Checked programmatically against the configs (all four mask rotations,
all placements):

| Footprint | drone | frigate | destroyer | cruiser | battlecruiser | battleship | dreadnought | carrier |
|-----------|:-:|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| 1x1 | x | x | x | x | x | x | x | x |
| 1x2 | | x | x | x | x | x | x | x |
| 1x3 | | x | x | x | x | x | x | x |
| L-shape | | x | x | x | x | x | x | x |
| 2x2 | | | | x | x | x | x | x |
| 3x3 | | | | | | x | x | x* |
| 2x6 | | | | | | | x | x |

\* dreadnought only; the carrier's elevator shafts block all 3x3 placements.
Max disjoint l guns: battleship 1, dreadnought 3. Max disjoint m guns:
cruiser 2, battlecruiser 3.

## Deliberate placeholders / open questions for later passes

- All new hulls have `threat.cost_formula = "0"` so enemy waves do not spawn
  them yet (WaveSystem treats any ship with positive threat cost as wave-
  eligible, regardless of unlock level). The balancing pass should set real
  threat costs together with `default_modules` loadouts so waves spawn them
  armed.
- All new hulls are `unlock_at_station_level = -1` (available from the start)
  to make layout testing easy; the progression pass should stagger these.
- Ship hull material items (`frigate_hull` … `carrier_hull`) and the new
  module items (`laser_cannon_m_module`, `laser_cannon_l_module`,
  `drone_bay_module`, `drone_hangar_module`, …) have no recipes yet — that is
  the recipe pass. The old `laser_cannon_xs_module` recipe is orphaned (the
  module was renamed to `laser_cannon_s`, consuming `laser_cannon_s_module`,
  which already has a recipe).
- `drone_bay` and `drone_hangar` are footprint-only placeholders: the drone
  launching capability does not exist in the simulation yet, so they define
  no capability section.
- Renames in this pass: `laser_cannon_xs` → `laser_cannon_s` (the old 2x2
  `laser_cannon_s` became `laser_cannon_m`), `armor_plate` → `armor_plates`,
  `manuvering_thrusters` → `maneuvering_thrusters` (typo fix). Test data
  under `bin/test/data/config` intentionally still uses the old ids — it is
  an independent fixture set.