Skip to content

Auto Warz — Ship & Mothership Editor Design

Document Type: System Design Version: 0.7 Status: In Progress — design agreed, numbers not yet set Last Updated: 2026-09-13 Phase: Phase 1 — Space Update Author: Solo Developer Parent Document: [01_Master GDD](<../01_Master GDD.md>) Related Documents: [07_Space Exploration Design](<../Unwritten/07_Space Exploration Design.md>) · [30_Ship Construction System](<./30_Ship Construction System.md>) · [33_Mothership & Fleet Design](<./33_Mothership & Fleet Design.md>) · [31_War & Combat System Design](<./31_War & Combat System Design.md>) · [24_Module System Design](<./24_Module System Design.md>) · [15_Ship & Army Points Design](<../Content/15_Ship & Army Points Design.md>) · [06_Vertical Layers & Core Power System](<./06_Vertical Layers & Core Power System.md>) · [00_Canonical Design Facts](<../../04_Project Management/00_Canonical Design Facts.md>) Closes: OI-344 (the editor is unspecified) and OI-345 (the component list has no owner) Supersedes: the remainder of the Unwritten/05_Spaceship Design & Building System stub

Table of Contents

Purpose of This Document

[30_Ship Construction System](<./30_Ship Construction System.md>) establishes that a ship's bill of materials is computed from the player's design rather than authored, and then states in §10 that the editor producing that design is unwritten. Without it, nothing can be computed.

This document defines both editors, the component catalogue they draw from, the rules that make a design valid, and the data shape of a saved design.

One Editor, One Model, One Kind of Thing

Decided 2026-09-13, closing OI-386. This replaces Two Editors, One Reason.

Everything is a hull. A Scout and a mothership are the same kind of object at different sizes, built in the same editor, on the same grid, saved in the same data shape.

Why the split was there, and why it went

v0.1 gave escorts concentric layers and the mothership a freeform grid, arguing that an escort is judged only by combat performance, that evaluating geometry for combat needs a damage simulation, and that [31_War & Combat System Design](<./31_War & Combat System Design.md>) rules one out. Therefore freeform on an escort "would be decoration".

That was a sound argument on the information available, and two things undid it.

First, an evaluator appeared that is not combat. Power runs on wires and fuel runs on pipes, inside the hull. A layout is now valid or invalid, efficient or wasteful, whether or not anything ever shoots at it. The premise that only combat can judge a ship no longer holds.

Second, ⚠️ this document already refuted itself. What the Mothership's Geometry Controls §1 computes directional exposure per face from a freeform grid, with no simulation, and calls it "the mechanic that makes freeform building matter". That is precisely the thing the escort section said could not be done.

What standardising collapses

Was Is
Escort classes with layers, motherships with frames One hull catalogue
Two data shapes One
Two validity systems One, with rules that apply where they apply
Class profiles by layer count Hull profiles by envelope and heights
Mothership Frame Mk1/2/3 Three more hulls in the same list

Everything that made a mothership special stops being a system and becomes a property of a hull: it is very large, it has many heights, you may hold only one, and it accepts payloads the small hulls cannot fit. None of those needed an editor of their own.

What stays split is readouts, not editors. A freighter and a cruiser are judged by different numbers, and What the Editor Shows already handles that.

The First Ship Is a Freighter

The editor opens in the Space Update, still Phase 1, and there is no war yet when it does. That matters more than it looks, because this document was drafted war-first and the priority is the wrong way round.

The first ship a player designs has to reach another planet, carry something useful, and come back. The first mothership they design has to run a supply chain without them.

Neither of those jobs involves a weapon.

What that changes about the editor

The editor has to be good at hauling before it is good at fighting, because hauling is the only thing it is used for until the War Update, which is a whole phase away rather than a few months:

Solved first Solved later
Cargo volume, and what fits in it Weapon mounts and firing arcs
Fuel and range — can this reach that planet and return Armour coverage
Loading and unloading: ports, and what the drones do at each end Class profiles for combat roles
Mass against thrust, since a full hold flies differently from an empty one Escort layering under fire
The mothership as a route it can be given, and an automation ladder that runs it Retreat doctrine

It is the same editor, not a cut-down one

This is not another prescribed hull. The Space Update ships the whole editor, frames, layers, validation and catalogue, exactly as specified below. What changes is which readouts the player is looking at on day one, and therefore which ones have to be right first.

A player who never joins a war should still find the editor worth using, because designing a better freighter is its own reward: more cargo per trip, less fuel, a shorter turnaround. Those are factory problems wearing a hull, which is what this game is about.

The combat half of this document is not wrong. It is later, and it is designed against a frame and a layer model that the freighter will already have proven.

The Rule That Governs Both

The editor shows consequences, never a score.

No efficiency rating, no design grade, no percentage out of a hundred. The moment a number exists to be maximised, every player builds the same layout and the editor stops being creative.

Instead the editor reports facts about the design: rear armour coverage 12%, reactor exposed on two faces, ammunition draw 14 per minute at full rate, retreat speed 0.6 of baseline. The player decides whether they meant that.

This matters most for armour, because of the following:

There is no correct armour face. There is a layout and a flying style, and they have to match.

A mothership armoured on its flanks wants to run parallel to a threat. One armoured forward wants to approach and withdraw along the same axis. Neither is better. A rating system would declare one of them wrong and delete the decision.

The Hull Is an Envelope, and Exposure Is Measured

The envelope

A hull class gives you a fixed outline you cannot exceed. Inside it, place cells and parts however you like.

That is what keeps free placement from producing blobs. A Light envelope is small and narrow, a Heavy Lift envelope is large and boxy, a Command envelope is enormous. You may build sparse or packed inside it and you can never build a forty-cell cross, so every ship reads as a ship from the outside while the inside is entirely the player's.

Heights are part of the envelope, and they are what hull difference is mostly made of. A Light hull is flat, which is why it is cheap and long-ranged. A Heavy Lift is deep, which is exactly what a cargo ship is buying. The differences fall out rather than being declared in a table.

The one number that decides everything

Added 2026-09-20. A cell is internal only if it touches no outside face. In a box of width × depth × height:

internal = (w − 2) × (d − 2) × (h − 2)

Which has a consequence nobody had to design:

Height Internal cells
1 Zero. Every cell is skin
2 Zero. Both levels touch top or bottom
3 One internal layer appears
5 Three

⚠️ You cannot protect anything until height 3.

That is a hard gate, it is pure geometry, and it says what v0.1 wanted a table to say about class depth. A flat hull has no inside: its reactor is always exposed, its cargo always reachable, and — pleasingly — it is always cheap to refit, because there is nothing buried to cut through to.

Internal volume also grows far faster than size. A 5×5×3 hull is 12% internal; a 9×9×5 is 36%.

Small hulls are all skin. Large hulls have guts.

Square cells, not hexagonal. The factory is a square grid — belts, buildings, ports, everything — so a hex editor would be a second spatial language for no gain, hexes do not stack into heights, and hexes are bad at the straight runs the conduits in §Wires and Pipes need.

Parts occupy more than one cell

Decided 2026-09-20. A part has a footprint, exactly as a building does on the factory floor. A reactor might be 2×2×2 and a cargo hold 3×3×1.

⚠️ This is what keeps the largest hulls placeable. A Command III at 13×15×6 is over a thousand cells. One part per cell would be an unplaceable amount of clicking; with footprints the same hull holds perhaps forty parts, the way a thousand factory tiles hold a few dozen buildings.

Edge and internal

One distinction does most of the remaining work:

Rule
Edge cells Touch the outside. Thrusters, sensors, weapons, heat shield, armour, docking and salvage gear must go here
Internal cells Do not. Reactor, tanks, cargo, bridge

That is a placement constraint with an in-fiction reason, and it means the silhouette always has engines at the back and sensors facing out without the game ever enforcing looks like a ship.

Layers are not gone. They are derived.

Everything the layer model taught survives, and stops being declared. A layer is a distance from the outside, and on a grid that is measured rather than authored:

The old layer rule On the grid
Weapons on the shell to fire A weapon needs an edge cell
Every gun is a piece of armour you did not fit An edge cell holds a gun or plating, never both. Identical trade
Hangar bays need shell access Same rule, spatially
Reactor and bridge belong in the core They want cells with things in front of them, now a choice rather than a constraint
Only a deep class can bury a reactor Falls out. A thin envelope has no buried cells to put one in
Exposure weights attrition Computed per face, exactly as the mothership section already specifies

It also fixes something the layer model got slightly wrong. Layers gave every class the same kind of decision, two to four rings. An envelope gives design depth proportional to hull size: a Fighter is so constrained it is nearly determined, a mothership is a genuine problem. That matches the progression, and it degrades gracefully at the small end instead of needing a special case.

Wires and Pipes

Decided 2026-09-13. What makes placement mean something on any hull, combat or not.

A ship is the factory in miniature, with the same two carriers, on a small board.

Network Runs The problem it creates
Wires Reactor to everything that draws Everything must be reachable. A big hull means long runs
Pipes Tank to drive Tanks far from drives means plumbing through the ship

No new vocabulary and no new mental model: the player already thinks in power networks and fluid lines.

Conduits occupy cells

A wire takes a cell, the same way a belt takes floor.

⚠️ This is the detail that decides whether the envelope means anything. It creates the real tension: a fully packed ship cannot be wired. Room has to be left for the nervous system, and the more you cram in the harder it is to feed. That is what makes envelope size and extra heights worth buying.

If conduits ran along cell walls for free there would be no reason not to fill every cell, and the envelope would collapse back into a capacity number.

Throughput: inherit the planet's rules, do not invent new ones

Decided 2026-09-15, closing OI-392.

A ship's wires behave like the planet's power grid. A ship's pipes behave like the planet's pipes.

No new mechanic, no new vocabulary, and no flow solver:

  • A power network's capacity is set by its weakest conduit. Exceed it and the player either upgrades the conduit tier or splits into two networks. That is a sum and a minimum, not a flow problem.
  • A large hull therefore carries several internal grids rather than one spine, which is exactly how a planet-side factory works and exactly the pressure that should exist at that size.
  • Fuel lines inherit pipe behaviour, including whatever pipe_complexity resolves to under Simulation Level. The ship does not get its own answer; it gets the planet's.

Why not unlimited throughput, which was the cheaper option: ⚠️ it inverts the difficulty curve exactly where it should be steepest. One thin spine would feed a mothership, and a mothership has ample room for one, so the largest hull would be easier to wire than a small one. Conduits would stop competing for space in any real way, the refit axis would flatten (cutting one thin spine is always cheap), and wiring would become a formality repeated from memory.

And the best consequence arrives free. A ship whose grid runs short sheds tiers in flight, the same way a base does. The First Blackout lesson transfers intact: the player already knows what a shed looks like, and now it can happen to a freighter halfway to another planet because they fitted one cargo hold too many.

Heat is a constraint, not a third network

Hot parts have a radius, and what sits inside it suffers. Put the reactor against the fuel tank and you have made a visible mistake.

Deliberately not a coolant loop. A third routed network inside every ship is one system too many, and fld_coolant already has a job in power generation.

What the wiring is, and is not

Wiring is craft. Payload mix is strategy.

There will be a near-optimal layout per hull and it will end up on a wiki. That is fine, and the same is true of belt patterns, which players still enjoy laying. The interesting decision is never how do I route this, it is what am I building this ship for.

The Hull Catalogue

One list. A mothership is the largest entry in it, not a different kind of object.

Revised 2026-09-20: hulls are named by size and shape, never by role. Before this, Scout was three things at once — a hull, a class and a job — which is the word-doing-two-jobs pattern that has bitten this vault repeatedly. Now:

Name hulls by size. Name the blueprints by role.

A Scout is a Light hull fitted with a sensor array, shipped as a stock blueprint. A Freighter is a Heavy Lift with holds. The catalogue shrinks from seven-plus role hulls to five, and roles become data rather than systems: a new role is a blueprint somebody saved, not a hull somebody has to model, balance and gate.

Hull Geometry Character Phase
Light Small, height 1–2 Zero internal cells. All skin, nothing can be buried. Cheap, long-ranged, always cheap to refit Space Update
Medium Mid, height 3 The first hull with an inside at all, one layer of it Space Update
Heavy Lift Large footprint, shallow Volume. Lots of it, and lots of skin to be hit on Space Update
Heavy Line Compact footprint, deep Less volume, far higher internal fraction. The first hull that can properly bury a reactor War Update
Command I / II / III Very large, heights 3 / 4 / 6 A factory you fly. Holds payloads no other hull fits War Update

Heavy Lift and Heavy Line are the branch, and it is worth seeing the numbers:

Footprint × height Cells Internal Edge
Heavy Lift 9 × 9 × 3 243 49 (20%) 194
Heavy Line 7 × 7 × 5 245 75 (31%) 170

Near-identical size, completely different ships. The Lift carries more, can protect less of it, and has far more surface to be hit on. The Line carries less and can bury its reactor. Neither is an upgrade of the other, which is the no carrier is an upgrade of another rule from [19_Transport & Logistics](<../Logistics/19_Transport & Logistics.md>) §2 applied to hulls.

Shape decides the ratio of what you can carry to what you can protect.

The Space Update needs three hulls, not ten, and transport exists at all three: a Light with a small hold is the cheap first hop, a Heavy Lift with a big one is the serious route. That is a considerably smaller thing to build and balance for the release that has to prove the editor is worth using.

Envelope dimensions and height counts are a tuning table, not a design decision, and live in [06_Tuning Values](<../../05_Reference/06_Tuning Values.md>) once set. The design decision is the shape of the ladder, which is that size buys both volume and the ability to protect what is inside it.

Shipyard Mk gates hull, per [30_Ship Construction System](<./30_Ship Construction System.md>) §9.

Two gates, and the line between them

Decided 2026-09-15, closing OI-391. Folding motherships into one catalogue put two different gates on one list. They stay different, and the reason is a phase boundary rather than an oversight:

A ship is world content. The mothership is how you show up.

Hull Gated by Scope
Every ordinary hull Shipyard Mk World. Built and used in your own world
Mothership Engineering Research Account. Exists only to take you into someone else's

Planet-to-planet hauling, mining and scouting are things a player does at home, so a Shipyard is gate enough. A mothership is the vehicle by which a player is present at a shared instance, which makes it the same shape as the admission-control exception [36_Progression Arc Design](<../Content/36_Progression Arc Design.md>) §7.2 already allows, rather than a breach of levels never gate world content. That document's §7.3 now records the reasoning, and its Engineering Points line is amended to match.

⚠️ A mothership is commissioned in your own world (OI-393). Otherwise a high-level guest could spend a host's materials on a hull the host cannot build, which is account progress arriving as capability in somebody else's factory. It also reads correctly: the mothership is your home base that flies.

The Mothership Is Just the Biggest Hull

A mothership is a vertical factory in a fixed footprint, with heights instead of levels.

It reuses the planet's vertical building model from [06_Vertical Layers & Core Power System](<./06_Vertical Layers & Core Power System.md>): a stack of levels, each its own 2D grid, modules placed on cells with footprints. Same grid, same placement verbs, same oblique camera, same footprint vocabulary.

This is the single largest reuse in the design, and since v0.5 it is the reuse every hull gets, not a mothership privilege. The mothership is simply where the envelope is large enough for the depth to matter most. It also makes the fantasy land: the mothership genuinely is a factory you fly, which is why letting it manufacture was the right call in [33_Mothership & Fleet Design](<./33_Mothership & Fleet Design.md>).

Modules do not rotate, consistent with [00_Canonical Design Facts](<../../04_Project Management/00_Canonical Design Facts.md>) §2, which establishes that buildings do not rotate either.

What the Mothership's Geometry Controls

Four things, none of which require combat simulation.

1. Directional exposure

A module's exposure is computed per face: how much hull and armour sits between it and the outside, in each direction. Armour is therefore directional.

A mothership with heavy plating forward and a soft rear can be flanked. Combined with the [31_War & Combat System Design](<./31_War & Combat System Design.md>) rule that position sets the distribution of attrition, this gives the reposition-the-depot verb real weight: you turn your armoured face toward the threat.

This is the mechanic that makes freeform building matter, and it is why the player choosing to armour the flanks instead of the bow is a real strategy rather than a mistake.

2. Validity by connectivity, not routing

  • A docking bay needs a clear path to the outside
  • The drone pit needs outer access
  • Storage must be reachable from the pit

A connectivity check: binary, cheap, and enough to stop a player filling the interior with silos and bolting bays onto the skin.

It is deliberately not internal belt routing. That really would be a second factory, and the mothership must not become one.

3. Mass

Total mass is the sum of the parts. Mass drives transit fuel, which drives reach, which decides which wars the mothership can attend at all (see [33_Mothership & Fleet Design](<./33_Mothership & Fleet Design.md>) → The Two Fuel Budgets). A bloated mothership is a short-ranged one.

4. The plain sums

Storage capacity in units, umbrella radius from emitter count, docking bay count, logic capacity, tank volume, production slots.

Mass, and What It Is Made Of

Decided 2026-09-20. Mass is the spine of every number a player actually feels, and it comes from two places.

Mass = the parts + what is in them.

Source Detail
Part mass Every part weighs something. A reactor is not a sensor
Cargo mass ⚠️ Every resource weighs something too. A hold of ore and a hold of circuit boards are not the same ship

Cargo mass is the half that changes play

A freighter's range depends on what it is carrying.

A hold of ore is heavy and short-ranged. A hold of components is light and goes far. Which means a player works out for themselves that you refine at the mine and ship the refined thing, because the alternative costs fuel — rather than being told. That is the same economics that governs real freight, and it compounds with [39_Space Layer Design](<./39_Space Layer Design.md>) §6a.2, where the expensive leg is the lift: mass matters most exactly where the energy goes.

Two things to get right

⚠️ Mass is not unit_size. The vault already has unit_size for Silo capacity ([00_Canonical Design Facts](<../../04_Project Management/00_Canonical Design Facts.md>) §12a). A barrel of foam and a barrel of lead occupy the same space at very different weights, so conflating them would be the one-word-two-jobs error again. mass is a separate property on the resource.

⚠️ Range stops being a number. It becomes range at this load, which is more honest and fits shows consequences, never a score: the editor reports a curve from empty to full rather than a single figure that is wrong for every real trip.

Nothing Is Declared. Everything Is Derived.

Decided 2026-09-20, and it is the rule that stops the hull catalogue ever growing a stat block.

Only two things are authored: the envelope, and the parts. Everything a player reads about a ship is computed from those and from what is inside it.

Reads as Derived from
What class it is What payload was fitted
Speed Thrust over mass
Range Fuel over mass and burn, at this load
Capacity The sum of the holds
Survivability Internal fraction, plus armour on the edges
APR weighting Geometry and fittings

What this forbids, before anyone writes it: a per-class stat table, a hull with a declared speed, a role with a declared cost tier, and any number that exists because someone typed it rather than because the ship is shaped that way.

⚠️ It deletes most of [15_Ship & Army Points Design](<../Content/15_Ship & Army Points Design.md>)'s class table — the APR weight column (Fighter weapons ×1.5, Carrier hangars ×2.0) and the Factory Supply Cost column (Low / Medium / High) are both declared stat blocks for classes that are no longer objects. That document needs a real pass, tracked as OI-394, and it is Phase 2 so it can wait.

Mothership Hulls

There are three, and they are three entries in the hull catalogue rather than a separate tier system. ⚠️ They are hulls, not Blocks and not building Mk levels; see the vocabulary warning in Designs Are Versioned.

Hull Heights Footprint Character
Command I 3 Small Your first. Honest and cramped. Forces real choices immediately
Command II 4 Medium Room for a second role
Command III 6 Large Everything, at a mass and fuel cost

Named Command rather than Mothership, because a command ship is the vessel a commander operates from, and the player is a command intelligence ([01_World Bible](<../../05_Reference/01_World Bible.md>)). The fiction and the catalogue agree for once.

Height counts mirror the planet's vertical rules ([01_Master GDD](<../01_Master GDD.md>): underground 2 to 4, sky 3 to 6), so the scale reads consistently across the two layers.

Footprint dimensions are tuning values, not design decisions. These three are unlocked through Engineering Research, per Two Gates, and the Line Between Them above.

A larger frame is not strictly better. More decks is more mass, more mass is more transit fuel, and more fuel is less reach. A Mk3 that cannot reach the war is worse than a Mk1 that can.

Drafts and Buildable Designs

Two states, and this is what keeps the editor a place to experiment.

State Saveable Buildable
Draft Always. Named, saved, reopened, shared. No
Buildable Passes every validity rule Yes. The Shipyard accepts only these.

A design that breaks a rule is never refused a save. It is saved as a draft, and the editor says exactly which rules it fails and where. Fixing them promotes it.

This matters because the alternative — refusing to save anything invalid — punishes the player for thinking out loud, which is the opposite of what an editor is for.

The Shipyard's design picker shows drafts greyed with their failing rule, so the player is never hunting for why a design is missing.

Validity Rules

One set, applied to every hull. A rule about a part only bites on a design that has that part, so there is no longer a mothership list and an escort list.

Every hull

Rule Failure reads as
Has a bridge No bridge. It cannot take orders.
Has a reactor No reactor. Nothing runs.
Has an engine No engine. It cannot move or withdraw.
Reactor output meets total draw Draw exceeds output by 40. Add a reactor or remove a module.
Every part is connected to power Drive core is not wired. Nothing reaches it.
Fuel reaches the drive No pipe run from any tank to the drive.
Edge-only parts are on edge cells Hangar bay is buried. Hangar bays need outside access.
Nothing heat-sensitive sits inside a heat radius Fuel tank is inside the reactor's heat radius.

Where the part exists

Rule Failure reads as
Every docking bay has outside access Bay on level 2 is enclosed.
The drone pit has outside access Drone pit is enclosed. No supply can leave.
Storage is reachable from the pit 14 storage cells on level 3 cannot be reached from the pit.

The connectivity rules are what v0.5 bought. Before conduits, Drafts and Buildable Designs had a distinction with very little to enforce: almost any arrangement was valid. Wires and pipes give the draft state real content, and every failure above names a thing the player can go and fix.

Failure messages state the consequence, not the rule number. That is the same principle as the supply chain diagnostics in [09_UI-UX Design Document](<../Interface/09_UI-UX Design Document.md>).

The Component Catalogue

This document owns the catalogue (closes OI-345). [15_Ship & Army Points Design](<../Content/15_Ship & Army Points Design.md>) and [30_Ship Construction System](<./30_Ship Construction System.md>) both reference it and neither restates it.

Every component is an ordinary recipe. A Laser Cannon is manufactured in the factory like anything else. Only the ship has a computed bill (OI-343 remains the prerequisite: nothing currently makes any of these).

Placement is one column now, not two. Since v0.5 every hull uses the same grid, so a component has one rule wherever it is fitted.

Universal

Component Placement Contributes Critical
Bridge / Command Deck Any cell Command. Its loss makes the ship adrift. ✅
Reactor Core Any cell. Has a heat radius Power output ✅
Engine Thruster Edge only Thrust. Thrust over mass sets retreat speed. ✅
Armour Plating Edge only Protects what sits behind it, directionally
Fuel Tank Any cell. ⚠️ Heat-sensitive Operating and transit range
Logic Module Any cell Automation tiers
Repair Module Any cell Repair-kit efficiency
Sensor Array Edge only Detection radius and resolution
Power Conduit Any cell Carries power. Occupies the cell
Fuel Line Any cell Carries fuel. Occupies the cell

Combat

Component Placement Contributes
Laser Cannon Edge only Kill rate. Ammunition draw.
Pulse Cannon Edge only Higher kill rate. Power draw.
Missile Launcher Edge only Highest kill rate. Heavy ammunition draw.
Point Defence Edge only Reduces incoming missile effect
EMP Emitter Edge only Disabling
Shield Generator Internal only Reduces incoming across the whole hull
Hangar Bay Edge only Launches drone fighters. Drones are a consumable.

Role

Component Placement Contributes
Cargo Hold Any cell Capacity in units. The Freighter's reason to exist.
Mining Head Edge only Orbital extraction
Salvage Module Edge only Works derelicts and ship wrecks ([30_Ship Construction System](<./30_Ship Construction System.md>) §13). Slow and exposed while working.

Large hulls only

These need an envelope big enough to hold them, which in practice means a mothership. That is a size constraint, not a class rule: a hull with the room can fit one.

Component Placement rule Contributes Critical
Drone Pit Needs outside access Supply throughput. Umbrella radius is drone round-trip range from here. ✅
Umbrella Emitter Outer surface Umbrella radius ✅
Docking Bay Needs outside access How many ships resupply at once
Storage Bay Must be reachable from the pit Capacity in units, using unit_size
Production Module Anywhere Field refining and war-consumable assembly

Data Shapes

Deliberately flat, serialisable and diffable. The bill of materials is a count of component_id, so [30_Ship Construction System](<./30_Ship Construction System.md>)'s computed bill is a one-line sum.

One design shape, for every hull

{
  hull_id:    "frigate",          // or "mothership_ii", or "scout"
  name:       "Kestrel",
  block:      3,                  // the design revision. NOT "mk"
  status:     "draft" | "buildable",
  cells: [ { level: 0, x: 3, y: 5, component_id: "reactor_core" },
           { level: 0, x: 4, y: 5, component_id: "conduit_power" }, ... ]
}

Conduits are cells like anything else, which is what makes them cost space (§Wires and Pipes) and what keeps the shape flat.

No rotation field, because modules do not rotate.

v0.5 deleted the second shape. v0.1 carried a slots[] form for escorts and a cells[] form for motherships. One shape means one serialiser, one diff, one validator and one editor, and the bill of materials stays what [30_Ship Construction System](<./30_Ship Construction System.md>) wants: a count of component_id.

Both are account-scoped blueprints per [33_Mothership & Fleet Design](<./33_Mothership & Fleet Design.md>). Unlimited designs may be saved; what is limited is the commissioned instance.

What the Editor Shows

A live readout beside the design, updating as components are placed. Facts, never a grade.

Three kinds of number, and they are not interchangeable

Sloppy naming is how a score sneaks back in. Every readout is exactly one of these.

Kind Test Reads as
Efficiency Has a denominator. Output per unit of something spent. 0.8 km per fuel unit
Power Has units over time. A capability expressed as a rate. 2.4 kills per minute
Coverage / capacity A fact. Spatial or counted. No ratio, no aggregate. rear coverage 12%

Efficiency needs a denominator. Power needs units. Coverage is a fact. Never combine across the three.

That last clause is the real guard. A single efficiency 62/100 was wrong not because the word was wrong, but because it aggregated dissimilar things into one rankable number. Three honest numbers cannot be gamed the same way, because raising one costs another.

Explicitly forbidden: armour efficiency — armour has no output, so no denominator exists — along with design efficiency, overall rating, and any single number standing for the whole design.

The readouts

Efficiency. Each one names what it spends.

Readout Denominator
Fuel efficiency Transit distance per fuel unit
Ammunition efficiency Kills per ammunition unit
Repair efficiency Hull restored per repair kit
Supply efficiency (mothership) Units delivered per drone charge

Power. Each one carries units.

Readout Units
Offensive power Kills per minute at full supply
Defensive power Survival time under standard pressure, stated per face

Defensive power per face is the reading that makes directional armour land as a consequence rather than a statistic:

Survives 4.2 minutes bow-on. 1.8 minutes stern-on.

That sentence tells a player they have built something which must be flown a particular way, which is exactly the decision the freeform mothership exists to create. It is a prediction with units, not a grade.

Coverage and capacity. Plain facts.

Escort Mothership
Armour coverage per face Armour coverage per face
Exposure per critical component Exposure per critical component
Retreat speed, as a multiple of baseline Storage capacity in units
Total mass Umbrella radius · docking bays · tank volume
Power output against draw Production and logic capacity · total mass

Both editors also show the computed bill of materials, which is the number the player is really deciding about.

Armour coverage bars are the input view: what you built. Defensive power per face is the output view: what it means. Show both, side by side, and the relationship teaches itself.

This replaces the Real-Time APR Display During Ship Building section in [15_Ship & Army Points Design](<../Content/15_Ship & Army Points Design.md>), which showed a single APR number. APR is now a rate, and a single number is exactly the aggregate this document forbids.

Relationship to Building Modules

[24_Module System Design](<./24_Module System Design.md>) §2.1 states that on buildings, a module's position carries no mechanical meaning, and free placement was rejected for costing a roof grid and validation in exchange for nothing.

That remains correct and this document does not overturn it.

⚠️ The two systems differ deliberately. Do not harmonise them.

Nothing shoots a building. Things shoot a ship. Position is decoration in one case and the entire design decision in the other. A future consistency pass that unifies them would delete the ship editor.

Open items for this document are tracked in docs/open-items.md, area editor.

Designs Are Versioned, And Ships Remember

Added 2026-09-13. A design is not a static thing. A player revises it, and the revision is a new Block ([30_Ship Construction System](<./30_Ship Construction System.md>) §10).

The editor edits the design. It never edits a ship.

Revising Vantage Block 1 into Vantage Block 2 changes what the Shipyard builds next. Every Vantage already flying stays Block 1 and keeps working, and each one can be brought up individually by a refit, at a Shipyard, at a price ([30_Ship Construction System](<./30_Ship Construction System.md>) §11).

⚠️ Blocks are not Mk. Canonical §4 makes Mk a building concept and ships stand beside buildings that genuinely have Mk levels, so this document uses Block throughout for design revisions and reserves Mk for the Shipyard and the mothership frame.

What that adds to designing

A design can be built to be refitted. Because a refit destroys the continuous material it has to cut through to reach a part, a design that keeps its changeable components shallow is cheaper to improve later, at the cost of being slightly worse now.

That is a genuine axis and it was not authored: it falls out of the salvage rule. It also means the editor should eventually surface it, since a player cannot otherwise see that one of two similar designs is far more expensive to live with.

Sharing

One of this document's open questions — whether escort designs can be shared between players like factory blueprints — now has a constraint on it rather than an answer. Designs are account-scoped, and [36_Progression Arc Design](<../Content/36_Progression Arc Design.md>) §7a already has a guest carrying saved designs into a host's world. So:

A design crosses. The ability to build it does not.

A guest brings a beautiful freighter into a fresh world and cannot build it until that world has researched the parts. The design shows as unbuildable with the missing research named, which is capacity crosses, stock does not (Canonical §20) applied to knowledge, and it stops account progress from gating world content.

Open Questions

  • Mothership frame footprint dimensions per Mk, and the mass cost of each frame
  • Exposure computation: how many rays or faces, and how armour thickness maps to protection
  • Whether Shield Generator protection is flat across faces or shaped by placement
  • Define standard pressure for defensive power: the reference attrition rate a survival time is quoted against. A tuning constant, but it must be one constant, or the numbers stop being comparable between designs
  • Component recipes (OI-343 — nothing currently makes any of them)
  • Component mass values, which drive the whole transit-fuel relationship
  • Whether escort designs can be shared between players, which is now narrower: designs are account-scoped and cross into a host's world already, so the open part is player-to-player exchange
  • Whether a commissioned mothership can be refitted in place, or only replaced. 30_Ship Construction System §11 answers this for ships; the mothership is larger, rarer and possibly deployed, so it is not automatically the same answer
  • Envelope dimensions and height counts per hull, and the mass cost of each
  • Conduit tiers: how many rungs, and what capacity each carries. The model is settled (capacity per network, set by the weakest conduit); the ladder is not
  • Heat radius shape and size per hot part
  • Whether a mothership may be commissioned anywhere or only in the player's own world (OI-393)

Revision History

Version Date Changes
0.7 2026-09-20 The hull model. The internal-cell rule: internal = (w−2)(d−2)(h−2), so ⚠️ nothing can be protected below height 3 — a hard gate from pure geometry that says what a class-depth table was trying to say, and small hulls are all skin, large hulls have guts. Parts occupy more than one cell, which is what keeps a thousand-cell Command III placeable. Hulls renamed by size and shape, never by role, ending Scout meaning a hull, a class and a job at once: Light / Medium / Heavy Lift / Heavy Line / Command I–III, with roles demoted to stock blueprints so a new role is data rather than a system. Heavy Lift and Heavy Line are the branch — 243 cells at 20% internal against 245 at 31% — near-identical size, opposite ships, neither an upgrade of the other. The Space Update needs three hulls, not ten. New Mass section: mass is parts plus cargo, ⚠️ mass is separate from unit_size, and range becomes a curve rather than a number. New rule: nothing is declared, everything is derived — only the envelope and the parts are authored — which ⚠️ deletes most of 15_Ship & Army Points Design's class table (OI-394).
0.6 2026-09-15 Both gate questions closed. OI-391: two gates, and the line between them is a phase boundary — a ship is world content, the mothership is how you show up. Ordinary hulls stay on Shipyard Mk (world), motherships on Engineering Research (account), which is the same shape as the admission-control exception 36_Progression Arc Design §7.2 already allows rather than a breach of levels never gate world content; that document's §7.3 now carries the reasoning and its Engineering Points line is amended. ⚠️ A mothership is commissioned in your own world (OI-393), so a guest cannot spend a host's materials on a hull the host cannot build. OI-392: conduit throughput inherits the planet's rules rather than inventing new ones — a power network's capacity is its weakest conduit, exceed it and split or upgrade, which is a sum and a minimum rather than a flow solver, and large hulls carry several internal grids like a real factory. Unlimited throughput was rejected because ⚠️ it inverts the difficulty curve, making the largest hull the easiest to wire. The free consequence: a ship whose grid runs short sheds tiers in flight, so the First Blackout lesson transfers to a freighter halfway to another planet.
0.5 2026-09-13 One editor, one model, one kind of thing — closing OI-386. Two Editors, One Reason is struck and everything is a hull: a Scout and a mothership are the same object at different sizes. The layer/freeform split rested on only combat can judge an escort, and two things undid it — wires and pipes are an evaluator that is not combat, and ⚠️ the document already refuted itself, computing directional exposure per face from a freeform mothership grid with no simulation. The hull is an envelope, a fixed outline that cannot be exceeded, with heights, so free placement inside still reads as a ship outside; square cells, since the factory is square and hexes neither stack nor run straight. Edge and internal cells replace shell and core. Layers are not gone, they are derived — every layer rule re-derived from geometry, including every gun is a piece of armour you did not fit — and the envelope improves on them by giving design depth proportional to hull size. New section Wires and Pipes: the ship is the factory in miniature, ⚠️ conduits occupy cells (without which the envelope is just a capacity number), heat as a radius rather than a third network, and wiring is craft, payload mix is strategy. Class Profiles becomes the Hull Catalogue with the mothership as its largest entry; frame tiers become three ordinary hulls. Validity rules unified into one set, and the connectivity rules finally give the draft/buildable distinction something to enforce. Two data shapes collapse into one. ⚠️ Mothership unlock flagged as OI-391, since an account-scoped gate would rub against levels never gate world content.
0.4 2026-09-13 Designs are versioned. A revision is a Block, the editor edits the design and never a ship, and existing ships keep the Block they were built from until individually refitted (30_Ship Construction System §10 and §11). ⚠️ Block rather than Mk, because Canonical §4 makes Mk a building concept and ships stand beside buildings that have real Mk levels. Designed-to-be-refitted recorded as an axis that falls out of the salvage rule. Sharing narrowed: designs are account-scoped and already cross into a host's world, so a design crosses, the ability to build it does not — unbuildable until that world researches the parts, which is Canonical §20 applied to knowledge. ⚠️ The layer-versus-freeform question reopened (OI-386): this document rejects freeform for escorts because only combat can judge them, and connectivity is an evaluator that is not combat. Header version corrected — it had been left at 0.1 while the history reached 0.3.
0.3 2026-09-05 The First Ship Is a Freighter added. The editor opens in the Space Update, where there is no war, so it must be good at hauling before it is good at fighting: cargo, fuel and range, loading, mass against thrust, and the mothership as a route it can be given. Same editor, not a cut-down one; what changes is which readouts have to be right first.
0.2 2026-09-04 Readouts split into three kinds that may never be combined: efficiency (has a denominator), power (has units over time), coverage and capacity (a fact). Armour efficiency forbidden explicitly, since armour has no output and therefore no denominator. Defensive power defined as survival time under standard pressure, stated per face, which is the output view of the armour coverage the player built.
0.1 2026-09-04 Initial. Two editors with different build systems and the reason for the split. Escort layer model with the weapons-versus-armour shell trade. Mothership as a bounded vertical factory with directional exposure, connectivity validity and mass. Frame Mk tiers. Drafts always saveable, buildable requires validity. The component catalogue, owned here. Flat data shapes. Shows consequences, never a score. Closes OI-344 and OI-345.