Ship Construction System¶

Document Type: Design Document Version: 0.2 (Draft) Status: In Progress Last Updated: 2026-09-13 Vault destination: 01_Design Documents Phase: Phase 1 — Launch release (the Shipyard and the one prescribed hull). The full computed-bill system in the Space Update Supersedes: the construction half of Unwritten/05_Spaceship Design & Building System (OI-313). The ship editor remains unwritten. Related: [15_Ship & Army Points Design](<../Content/15_Ship & Army Points Design.md>) · [21_Drone Logistics Design](<../Logistics/21_Drone Logistics Design.md>) · [20_Belt Logistics - The Router](<../Logistics/20_Belt Logistics - The Router.md>) · [23_Port System Design](<./23_Port System Design.md>) · [29_Metallurgy & Alternate Recipes Design](<./29_Metallurgy & Alternate Recipes Design.md>) · [14_Win Conditions & Faction Allegiance](<../Content/14_Win Conditions & Faction Allegiance.md>) · [08_Research Tree Design](<../Content/08_Research Tree Design.md>)

1. Summary¶

How a ship the player designed becomes a ship that exists.

A ship is not a recipe. Everything else in the factory has a fixed bill of materials authored by the designers. A ship's bill is computed from the player's design, which nothing in RecipeDefinition can express and which is the reason this system needs a document of its own.

The short version:

The player designs a ship in the editor. Designs are saved and reused, like factory blueprints.
A Shipyard is required. Genesis cannot build ships; only a building can.
The Shipyard computes the bill of materials from the design.
Materials arrive by belt, by drone, or both. The Shipyard requests only what it is short.
The build is progressive. It stalls when short, and says what it is waiting for.
The finished ship sits in the yard and becomes a movable unit. It does not block the next build.

This document does not cover the editor, ship classes, or Army Power Rating. Classes and APR are [15_Ship & Army Points Design](<../Content/15_Ship & Army Points Design.md>). The editor is still unwritten (§9).

2. A ship is not a recipe¶

	Ordinary production	Ship construction
Bill of materials	Fixed, authored	Computed from the design
Where it lives	`RecipeDefinition`	The saved design
Who builds it	The building, from `accepted_recipe_ids`	The Shipyard, from a design
Varies per instance	No	Yes

Components are still ordinary recipes. A Laser Cannon has a fixed recipe like anything else. Only the ship is computed, and it is computed by summing the components placed on it. So ship component recipes are a prerequisite for this system, not an alternative to it (OI-343).

This also has a tooling consequence. The Chain Explorer and Ratio Calculator cannot precompute "what does a ship cost", because the answer depends on a design that does not exist until a player makes one. They can compute it per design, once designs exist.

3. Designs are blueprints¶

A design is saved, named and reused. Building a squadron of ten fighters means drawing one fighter and queueing ten, never drawing ten ships.

This mirrors factory blueprints, which 01_Master GDD already lists ("factory blueprinting and copy-paste"), and it should feel like the same feature to the player.

The data shape of a design is not settled here (OI-344). 01_Master GDD describes a "modular ship editor, player selects ship class first, then builds within that class's constraints" and 02_Scope & MVP Document says "hull + component attachment", which reads spatial rather than as a flat parts list. If position is real then designs can be invalid as well as expensive, and the editor has to say so.

4. Only buildings build ships¶

Genesis cannot build ships. Genesis places buildings; buildings make ships. The two builders never overlap.

This is a deliberate asymmetry, and it is worth stating because the alternative is tempting: Genesis already constructs things, so it could plausibly construct ships too. It does not. A ship is a factory product, and making it one keeps the whole loop pointed at the factory rather than at the companion bot.

Relationship to OI-342. Whether buildings cost materials to construct is undecided and lives in OI-342. If it resolves as yes, the pattern in §5 to §7 (a bill, a requester, reservation, progressive consumption, a stall that names what is missing) is directly reusable, and the question shrinks to "does Genesis use the Shipyard's machinery". That is not decided here.

5. Supply: belts and drones, into one buffer¶

The Shipyard holds one buffer per component type in the bill. Two things can fill it:

Belts, through ordinary input ports, per [23_Port System Design](<./23_Port System Design.md>)
Drones, through the requester, per [21_Drone Logistics Design](<../Logistics/21_Drone Logistics Design.md>)

Most ships will use both. A ship draws on up to ten component types plus structure, and a building with a dozen belt inputs is not buildable, so belts carry the few high-volume components and drones cover the long tail.

5.1 The requester asks only for the shortfall¶

No configuration is needed to choose the mix. The requester asks for what the buffer lacks. If a belt of circuit boards keeps that buffer full, no request for circuit boards ever fires. If the player belts half the bill and lets drones cover the rest, that simply happens.

The player chooses the split by what they plumb, not by setting a flag on the building.

This is the existing pull rule from 21_Drone Logistics Design §2.1 ("a drone flies because the destination is short") applied unchanged.

5.2 Reservation, and why the belt is the one that yields¶

21_Drone Logistics Design §7 requires that a destination have space at dispatch. That check does not survive the flight: a belt can fill the space while the drone is in the air, and the drone arrives with nowhere to put its load.

A requested item counts as already present. Dispatching against a buffer reserves that space, so a belt arriving afterwards finds no room and backs up.

A belt can wait; a drone in flight cannot. So the belt is the one that yields.

This adds no new mechanic. 20_Belt Logistics - The Router §3b already specifies that a blocked belt backpressures upstream rather than voiding, "because a system that silently voided surplus would hide overproduction entirely". Reservation just gives the belt something to press against.

5.3 Releasing a reservation¶

A reservation is released when the trip ends in one of exactly two ways:

Outcome	Reservation
Delivered	Released, buffer filled
Aborted	Released, buffer unchanged
Stranded	Held

A stranded carrier keeps its reservation. 21_Drone Logistics Design §5 strands a drone in place at Simulation Level 2 and above when its route loses power, and that drone is still holding a slot. This is deliberate: a stranded drone is a logistics problem the player must fix, exactly like every other stranding case, and quietly releasing the slot would hide it.

The stall must name it. A held reservation with no visible cause is the one way this becomes bad: the build waits on a component the player has plenty of, for no stated reason. The Shipyard must report it, in the shape of "waiting on 12 circuit boards, 1 reserved in transit (stranded)". That is the same job 21_Drone Logistics Design §7's configuration warning already does, and it belongs in the Building Detail Panel.

Cancelling a build aborts its outstanding requests, so §8's cancel is also a release condition.

5a. The Shipyard Has a Store¶

Decided 2026-09-13. The Shipyard holds an internal store, and it is the hinge the rest of this document's second half turns on.

It behaves like a chest, not like a silo. One general store, mixed contents, a total capacity.

That distinction is deliberate and worth stating, because [00_Canonical Design Facts](<../../04_Project Management/00_Canonical Design Facts.md>) §7 makes Silos hold one substance each. A ship's bill draws on a dozen part types at once, so a dozen single-substance buffers would be unusable, and the store is full, empty it would not mean anything — there would only ever be one type full and eleven empty.

5a.1 It fills from both ends¶

Fills it	Empties it
Belts and drones, per §5	Building a ship
Salvage from a refit or a decommission (§12, §13)	Ordinary output ports, belts and drones

⚠️ A yard with no out-line jams. A player who decommissions a ship without having plumbed an output watches the store fill and the yard stop. That is the same lesson the game teaches everywhere else and it needs no special case: forgetting the output belt is an ordinary factory mistake.

5a.2 The shortfall rule already covers it¶

§5.1 says the requester asks only for what the buffer lacks. The store is that buffer, so:

Pulling a reactor out of an old ship stops the next build asking for one.

No new rule. Decommissioning automatically reduces what the yard requests, and a player who scraps three freighters to build two watches the parts move across rather than watching a number change.

5a.3 Store capacity rides with Shipyard Mk¶

§9 already makes Shipyard Mk gate ship class. Capacity rides along: a Mk1 yard holds barely one ship's worth of parts and chokes the moment recycling starts, while a Mk3 can hold a fleet's worth in hand. That gives the yard tiers a second reason to exist beyond unlocking hulls.

6. Progressive build¶

The Shipyard consumes materials as it builds, not all at once up front.

A half-built ship that stalls is information: it names the component your factory is short of. Requiring the full bill before starting hides that until the moment nothing happens, and turns a diagnosable shortage into an unexplained idle building.

Progress advances only while materials are being drawn. No materials, no progress, and the building says which ones.

7. Completion¶

A finished ship sits in the yard and becomes a movable unit: the player can move it like any other unit.

It does not block the next build. A player who forgets to move a finished ship is not punished by a stalled yard, and a Shipyard left running produces a row of ships rather than one ship and a jam.

Launching is [14_Win Conditions & Faction Allegiance](<../Content/14_Win Conditions & Faction Allegiance.md>)'s concern, not this document's. Milestone 1 fires on launch, not on completion.

8. Cancelling, by Simulation Level¶

A part-built ship has consumed real materials. What happens on cancel scales with Simulation Level, per the mechanism in [19_Transport & Logistics](<../Logistics/19_Transport & Logistics.md>) §4:

Level	On cancel
1	Full refund. Everything consumed comes back
2	Partial refund. What has not yet been consumed comes back; what has is lost
3	Total loss. Nothing comes back

Higher level, less forgiveness, which is the pattern every other Simulation Level table already follows.

In all three cases, outstanding requests abort and their reservations release (§5.3).

9. Shipyard tiers¶

Shipyard Mk gates ship class. The Shipyard is not one building constructed once; it has a progression, and that progression is what unlocks larger hulls.

Mk	Unlocks	Note
Mk1	Scout, Fighter, Freighter	The cheap hulls
Mk2	Frigate, Mining Vessel
Mk3	Cruiser, Carrier	Carrier is the APR ×2.0 hangar class

⚠️ Corrected 2026-09-13. v0.1's table listed six classes across three tiers and omitted the Scout entirely. This document was written on 1 September; [15_Ship & Army Points Design](<../Content/15_Ship & Army Points Design.md>) added the Scout as a seventh class on the 5th, and said of it that "the first ship a player ever launches is a non-combat one". As written, the finale of the Launch release was a class no Shipyard could build.

The tier split is no longer two-per-tier, and should not be: the cheapest yard should make the cheap hulls.

Milestone 1 is reachable on a Mk1. 14_Win Conditions & Faction Allegiance fires M1 on "any ship of any type launched", and M1 is meant to be an early cinematic beat rather than a late grind, so the cheapest yard must be able to produce a launchable ship.

08_Research Tree Design currently has a single "Shipyard Basics (300 RP)" node unlocking "Shipyard building". Tiers give that branch more to hang on than one node.

9a. Drafts and buildable designs¶

[34_Ship & Mothership Editor Design](<./34_Ship & Mothership Editor Design.md>) gives designs two states. A draft is always saveable and never buildable.

The Shipyard accepts only buildable designs, and its design picker shows drafts greyed with their failing rule, so a design is never silently missing from the list.

10. A Ship Remembers Its Block¶

Decided 2026-09-13. A blueprint can be revised, and a ship remembers which version it was built from.

New builds use the current design. Existing ships keep the one they were built from.

Nothing breaks and nothing is forced. Improve a design, build three more, and you have six ships on one version and three on another, all working. That is [00_Canonical Design Facts](<../../04_Project Management/00_Canonical Design Facts.md>) §19 pointed at a ship: disabled, never deleted, and nothing is taken from you because you moved on.

10.1 They are called Blocks¶

⚠️ Not Mk. Canonical §4 makes Mk a building concept — two tracks, applied in place by universal upgrade kits — and ships sit directly beside buildings that genuinely have Mk levels. This would have been the fourth word in this vault doing two jobs, and the most confusing one yet.

Block is the real aerospace term for a versioned airframe, reads correctly in this game's engineering register, and collides with nothing:

Vantage Block 1 · Vantage Block 2 · Longhaul Block 4

10.2 The fleet has to show it¶

A version badge per ship in the Fleet Overview, and a line reading four ships on an older design. Without it the upgrade path is invisible and no player will ever use it.

11. Refit¶

A ship can be brought up to a newer Block, per ship, at a cost, at a Shipyard.

11.1 Where, and why that is the good part¶

At a Shipyard, which means the ship has to come back to one. That turns fleet upgrades into a logistics problem rather than a button: a freighter on a distant route has to be pulled off it and flown home, or you build a yard out there. Suddenly a remote Shipyard is worth something, and upgrade the fleet is a decision about downtime.

11.2 What it costs: the salvage rule¶

Refitting and decommissioning are the same operation at different depths. Both mean opening the ship up, so the only question either one asks is what survives being pulled out:

Every part is either salvageable or consumed.

	Survives	Why
Discrete parts — reactor, drive, tanks, sensor array, cargo hold	✅ Come out whole	You unbolt them
Continuous material — wiring, piping, plating, structure	❌ Destroyed	You cut through it to reach everything else

So:

Refit cost = the new parts, plus the continuous material you cut through to reach them
Decommission return = all the salvageable parts, and none of the continuous material

This replaces the flat overhead considered and rejected on 2026-09-12. A percentage surcharge is a fudge factor a player cannot see. The salvage rule is legible: you can look at a design and know it will be expensive to modify, because you can see how buried everything is.

11.3 Why decommission-and-rebuild cannot undercut it¶

The obvious exploit is to scrap a ship and build a new one instead of paying to refit. The salvage rule closes it without an anti-exploit clause:

Decom and rebuild costs all the continuous material, twice over
Refit costs only the material you cut through

So refitting is strictly cheaper for a small change, and the two converge as the change grows. When they meet, you genuinely are building a new ship, so it is correct that the price is the same.

[00_Canonical Design Facts](<../../04_Project Management/00_Canonical Design Facts.md>) §12b already does half the work: a ship going to parts and back to a ship is a closed loop, so it cannot return everything. The tuning rule that follows is one line and it must hold:

⚠️ What a refit destroys must always be less than what decommissioning destroys.

11.4 A refit never changes the hull¶

The hull is the envelope. Changing it is building a different ship. A refit changes what is inside, which keeps a clean line and stops refit quietly becoming replace with something else at a discount.

11.5 What it does to the editor¶

A design can be built to be refitted: changeable parts near the edge with short runs to them, accepting a slightly worse ship now so every future upgrade is cheap. Or pack it tight, get a better ship today, and pay every time you touch it.

Nobody designed that trade-off. It falls out of you have to cut through things to reach things.

12. Decommission¶

A ship can be broken up at a Shipyard.

Decommissioning is not a refund. It is logistics.

The parts do not become money. They come out into the yard's store (§5a) as ordinary items and sit there, and the player has to do something with them: build the next ship, or belt them away. Scrap three old freighters to build two new ones becomes an operation you watch happen.

Return is the salvage rule in §11.2: every discrete part, none of the continuous material.

13. Destroyed Ships, and the Wreck¶

Decided 2026-09-13. A destroyed ship is destroyed — it does not come back, and nothing is refunded. But it leaves a wreck, and a wreck can be recovered.

A destroyed building is restored in place. A destroyed ship has to be gone and got.

That is not an inconsistency with [37_Planet Threats & Defence Design](<./37_Planet Threats & Defence Design.md>), it is the fiction being honest. A building dies on the ground and the planet still has it. A ship dies somewhere out there, and getting it back is a trip.

13.1 What a wreck yields¶

A subset of its salvageable parts. The rest went with whatever killed it.

⚠️ No per-part condition tracking. Damaged-part state would be a whole new system for very little; a lossy subset reads the same to the player and costs nothing. Canonical §12b covers the loss without needing its own justification.

13.2 Salvage is a payload, not a class¶

[34_Ship & Mothership Editor Design](<./34_Ship & Mothership Editor Design.md>) already lists a Salvage Module. A salvage ship is therefore a hull someone fitted for the job, and a player who rarely loses ships never builds one. No new ship class is required.

The cost of salvage is distance. A wreck near home is worth collecting; one across the galaxy is a question of whether the trip pays, which is the question every other route in this game already asks.

13.3 It cannot be farmed¶

Could a player destroy their own ship to harvest it? No. Decommissioning is strictly better: it happens at a yard, costs no travel, and returns all the salvageable parts rather than some. There is no third route that undercuts building, refitting or decommissioning.

13.4 Why this matters more than it looks¶

The game opens with the player picking through The Wreck, and [01_World Bible](<../../05_Reference/01_World Bible.md>) describes Genesis as a salvage and construction bot. Salvage is the origin story. Making it a real mechanic turns the opening scene into the first instance of a verb the player uses forever, and it extends [28_Restoration - Third Endgame Path](<../Content/28_Restoration - Third Endgame Path.md>) off the planet in the Space Update.

14. Not designed here¶

~~The ship editor.~~ Written. [34_Ship & Mothership Editor Design](<./34_Ship & Mothership Editor Design.md>) covers layers, cells, class constraints, validity and the data shape of a saved design. OI-344 closed. The bill of materials is a count of component_id over the design's slots.
~~The shared component list.~~ Owned by [34_Ship & Mothership Editor Design](<./34_Ship & Mothership Editor Design.md>). This document and 15_Ship & Army Points Design both reference it and neither restates it. OI-345 closed.
Ship component recipes. The ten components in 15_Ship & Army Points Design have APR values and no recipes. Nothing makes a Laser Cannon (OI-343). Still the prerequisite for everything here.
Shipyard footprint, power draw and build times.
Queueing. Whether a yard holds a queue of builds, and whether designs can be queued mixed.
Fuel. 14_Win Conditions requires fld_fuel reserves for launch, and fuel has no producer.

Changelog¶

Version	Date	Change
0.2	2026-09-13	The ship economy, and a defect. ⚠️ §9's tier table omitted the Scout, which `15_Ship & Army Points Design` added four days after this document was written and named as the first ship a player ever launches — the Launch release finale was a class no Shipyard could build. Mk1 now unlocks Scout, Fighter and Freighter. §5a: the Shipyard has a chest-like store, one general mixed capacity rather than per-substance silo buffers, filling from belts, drones and salvage, emptying through builds and ordinary output ports; a yard with no out-line jams, and §5.1's shortfall rule means pulling a reactor from an old ship stops the next build asking for one. §10: a ship remembers its Block — new builds use the current design, existing ships keep theirs, and the versions are called Blocks rather than Mk because Mk is a building concept (Canonical §4). §11: refit, at a Shipyard, priced by the salvage rule — discrete parts survive being unbolted, continuous material is destroyed being cut through — which replaces a flat overhead with something the player can see, and makes designed to be refitted a real axis. §11.3: decom-and-rebuild cannot undercut refit, because it destroys all the continuous material twice; the tuning rule is that a refit must always destroy less than a decommission. §12: decommission is logistics, not a refund — parts land in the store and must be dealt with. §13: a destroyed ship leaves a wreck that must be recovered rather than restored in place, yielding a lossy subset with no condition tracking, salvaged by a payload rather than a class, and unfarmable because decommissioning is strictly better.
0.1	2026-09-01	Initial draft. Ships as computed bills rather than recipes; designs as blueprints; only buildings build ships; belt and drone supply into one buffer with shortfall-only requests; reservation with the belt yielding; stranded carriers hold their reservation; progressive build; completion as a movable unit that does not block the yard; cancel scaling with Simulation Level; Shipyard Mk gating ship class.