dota_factory/docs/content_design.md

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.