Document Type: Reference — single source of truth
Version: 1.2
Last Updated: 2026-08-28
Vault destination:04_Project Management
Purpose: the load-bearing decisions that every other document must agree with.
When any document contradicts this page, this page wins and the other document is wrong. When this page needs to change, change it here first, then propagate.
Vocabulary is defined in [04_Data Dictionary](<../05_Reference/04_Data Dictionary.md>). One term, one meaning; it also lists deprecated words and their replacements. Where the two disagree, this page wins.
Use this as the reference for documentation review passes: check each doc against this list, rather than against the other twenty-nine documents.
DISABLED / INPUT / OUTPUT, plus an optional resource filter
Port defaults
All DISABLED. A newly placed building moves nothing and is flush plate on every face.
Configuration order
Recipe, then ports. Placing a building says nothing about how it connects.
Recipe selection
Instant, in the Building Detail Panel, like port config. A selector only where there is a choice; a label on single-recipe and extraction buildings, which never get a dead control.
Changing a recipe
In-progress job abandoned, consumed inputs lost, warned first. Unusable buffered stock is kept, never voided. Auto-enabled ports follow; explicit filters are surfaced, never silently cleared.
Draining stranded stock
An OUTPUT port with an explicit filter pushes that resource out, whether or not it is the recipe's output. Without this a building can soft-lock on stock it cannot use.
Inbound auto-enable
A never-touched port, on a building with a recipe, with something connected inbound, becomes INPUT with an empty filter. Outputs are never automatic. The recipe gate is what makes it coherent: when the rule can fire, the accepted set is always defined.
The player always wins
An explicitly set port is never overridden, including one deliberately set DISABLED. Needs one bit, player_set, since mode cannot tell never touched from closed on purpose.
Reconfiguring a port
Instant UI action, never a Genesis task. The no instant placement rule governs placement; a port is already there and DISABLED is closed, not absent. A valve, not a pipe.
Ports are passive
A port never pulls.OUTPUT pushes, INPUT receives what is pushed into it, DISABLED does neither.
Belt/port connection
Connected, not adjacent, and it works both ways: a belt is connected when its travel direction aligns with the port, whether pointing at it (delivers in) or leading away from it (port pushes out). A belt running alongside is adjacent, not connected.
Port throughput visual
None of its own. Mk is the accent tabs, mode is the base geometry. Do not add a third channel.
Visual indication
Built geometry, not a drawn symbol. Recessed slot = input, protruding nozzle = output, flush cover plate = disabled.
IoConnector / PipeConnector
Removed. Replaced by ports.
Port count
Face length. One port per grid cell along each edge. A 1×1 has four.
The port is the rate limiter
A port moves at its throughput regardless of what is on the other side — belt, pipe, or another port. The port is this game's inserter.
Direct building-to-building
Allowed, at port rate. Touching OUTPUT and INPUT ports transfer with no belt. Not a special case and not throttled.
What balances adjacency
Ports are finite and spent. A port doing adjacency is not also taking a belt, and adjacency cannot split, merge, filter or cross distance.
Base Mk throughput
1 / 2 / 4 items per sec, matching Basic / Fast / Express belts exactly. A belt upgrade does nothing for one machine until Base Mk matches it.
Four channels, four physical properties, none competing.
Channel
Carries
Behaviour
Accent tab count
Mk level
Outer row = Base Mk, inner row = Machine Mk. Left-aligned, fixed pitch, clockwise from each side's start.
Port geometry
Port direction
Slot / nozzle / cover plate
Base ring colour + rhythm
Fault status
Unlit when healthy. Amber = logistics, red = power. Rhythm distinguishes states. Output-full (success) and input-starved (failure) must never share a signal.
Cyan working-light brightness
Alive, and decay
On when working. Dims 2.5 → ~0.9 as the building decays.
Decay is NOT a ring state. It is a gradient, shown by brightness in-world and as a percentage in the Analytics tab.
One substance. Never mixed. The fill window shows a level tinted by that substance — a window cannot display a mixture, so the art direction already assumed this. Matches the Tank, which the pipe no-mixing rule already made single-fluid.
Silo capacity is
A number of units, not a number of items. Each substance has a unit_size, so a Silo of capacity 10 holds two things of unit_size 5. Storage is therefore spatial: bulky goods cost more room than dense ones.
Buildings store
Their recipe inputs and outputs, per substance, in a small buffer. Machines buffer; Silos store. They are different things and must not share a rule.
Fluids and gases
Tank
Number of solid storage buildings
One — the Silo. The Smart Buffer / Buffer Chest is deleted: ports filter, and a Silo already holds one substance, so its distinguishing feature became standard.
Silo capacity by Mk
500 / 1000 / 2000 units. Mk buys depth, not variety — a Silo holds one substance at every level, because the fill window cannot show a mixture.
Enum
StorageRole — UNASSIGNED / DEPOSIT / CONSTRUCTION
Role names describe
What Genesis does with the building, which is the only thing the role controls. DEPOSIT = Genesis deposits mined ore here. CONSTRUCTION = Genesis draws build materials from here. UNASSIGNED = both, the default.
1×1, four ports, each configurable INPUT/OUTPUT with optional filter
Router capability
Mk1 even split/merge · Mk2 priority in and out · Mk3 filters and ratios
Priority
Waterfall. Fill output 1, overflow to 2, then 3. Also works on inputs.
Ratios
Explicit (70/30), not inferred from priority flags
Overflow
Priority is the overflow mechanic. No separate Overflow mode exists.
All outputs full
Router stops, backpressure propagates upstream. Nothing is ever silently voided.
Deliberate disposal
Incinerator — costs power, produces air pollution, recovers some heat as power. Open dumping produces ground contamination instead. Player chooses which pollutant.
Incinerator recovery
Always a fraction of embodied energy. Never profitable to manufacture items in order to burn them. See §12b.
Passive. No power draw. A belt is a one-time material cost that then runs free forever.
Why rail exists
Volume at distance, and districts. Not distance alone — rail costs fuel to run, belts do not.
Rail's real value
Lets the factory be several self-contained districts instead of one spaghetti mat
Rail's honest cost
High latency, arrives in bursts. Requires Silo buffering at both ends.
Signalling
Automatic by default. Whole route is one block. Manual signals are optional and add throughput only, never capability.
Locomotive types
Steam (coal, belt-fed) · Diesel (liquid fuel, piped) · Electric — catenary or battery · Nuclear (rare fuel swap)
The three currencies
Not a ladder. Each pays in something different.Catenary pays in distance — wire along every metre of route. Battery pays in time — charging stops, and a station at each. Nuclear pays in waste — a permanent stream to manage. Each is strongest exactly where the others are weak.
Battery is infrastructure too
Charging stations are point infrastructure; catenary is linear. Catenary scales with route length, battery with number of stops. That difference is the trade, not the presence or absence of infrastructure.
Nuclear is not a penalty
High capital, very low running cost, one hard problem to manage. Strongest for long hauls and remote lines, where neither wiring nor stopping is acceptable. The reason not to take it is that it demands a whole support system, never that it is weak.
Nuclear waste
Reducible by reprocessing, never eliminable. ⚠️ Recovery must never reach 100%, or nuclear becomes free and the trade collapses — the same guard rail as Incinerator heat recovery and flue capture.
The trade
Move fuel, or build infrastructure once — the same decision as power transmission
Electric trains
Only as clean as the grid. Coal-powered electrification moves the smoke.
Train Station
Modular. Station Head + one Freight Platform per wagon + optional Fuel Platform. All ordinary buildings with ports.
Multi-commodity trains
Free — each platform's ports are configured independently
Fuel type
Physically changes station layout. Steam and diesel need a Fuel Platform; electric needs electrified track instead.
Load-dependent voltage drop. Reach contracts as circuit load rises.
Transmission loss
Per-tile, reduced by higher voltage. Transformers cost a fixed percentage each.
Must the game be winnable without transmission?
Yes. Research is path-choice, not a timeline.
Transmission direction
Horizontal only. Conduits and Pylons are the sole vertical paths.
Transmission blocking
Height clearance. Buildings below it let lines pass overhead.
Cross-level power
Capacity cap, no distance loss. Conduits link grids, they do not merge them.
Brownout shedding
Requires hysteresis, and hysteresis alone is not sufficient. Recovery threshold must exceed shutdown threshold, and restoration must test the predicted post-restore state, or a building whose own draw breaks the circuit still flickers. Two independent triggers: grid deficit and local undervoltage. 25_Power System Design §4a.
Balance values
All live in a single PowerTuning resource. Nothing hardcoded.
PU is a rate
Power. Output, draw and capacity are PU. Energy is PU·s — accumulator storage and fuel content. Do not mix them.
Generation scale
Anchored on the Coal Generator at 100 PU. Every other source is a multiple of it, so generation_scale rebalances all of them at once.
Fuel burden
One Basic Belt of coal sustains 200 PU.fuel_density_scale moves this without changing how much power exists.
Distribution reach
usable radius x circuit load = 16 000 PU·tiles. The grid has a budget, not a range: spend it on size or on draw.
Connection vs reach
Different things. Connection is a fixed radius deciding grid membership; reach is electrical and contracts with load. A building can be connected and still receive nothing.
Partial power
Does not exist. A building runs at full draw or is shed. Priority orders shedding, it does not ration supply.
The family — biomass, metal, mineral, chemical. Load-bearing: recipes may accept any substance in a category, so polymer takes any biomass rather than naming wood and algae separately.
substance
What it is specifically — wood, algae, iron, coal. The identity. Never changes.
type
RAW / REFINED / COMPONENT. Processing state. What tier was reaching for.
phase
SOLID / LIQUID / GAS. Changed by heat and chemistry.
unit_size
How much storage one of this substance consumes. Makes storage spatial rather than a count. The fluid analogue is density, which already exists on FluidDefinition and is currently read by nothing.
Refining rule
A component is never made directly from raw. True in all ten shipped recipes. Enforced by a validator that warns rather than fails, so a deliberate override stays possible.
fuel_value
Energy per unit, on the substance. There is no fuel_type — burners carry their own accepted-fuel list, because Steam and Diesel are both combustion yet must not share fuel.
ResourceTier
Removed. It conflated production depth with transport medium, so a resource that is raw by origin and fluid by medium could not be described.
Production depth
Derived from the recipe graph, never stored. It was already wrong as stored: two of five components are made from components.
Transport
Derived from phase, never stored. Solids ride belts; liquids and gases ride pipes.
Same substance, different phase
One substance, two resources. Iron ore is iron / SOLID; molten iron is iron / LIQUID. Smelting is a phase change, not a mapping between strangers.
A filled barrel is
An ordinary SOLID item — a steel container that happens to hold liquid. Barrelling is an ordinary recipe. There is no "form" axis.
Resource ids
Unchanged. The pair is the natural key; the .tres id stays the stable handle recipes and saves reference.
A loop that closes completely removes the decision it was meant to create.
Every recovery, capture, reprocessing or recycling mechanic in the game recovers most, never all. This is not a balance figure to tune toward 100%; it is a design rule, and a mechanic written without it is wrong regardless of its numbers.
Why. Each of these mechanics exists to soften a cost the player chose to incur. If it removed the cost entirely, the choice that created it stops mattering, and a system meant to pose an ongoing question collapses into a plumbing puzzle solved once and then forgotten.
Manufacturing items purely to burn them becomes profitable
Flue capture
Part of the emissions while you still burn
Coal forever at zero net pollution; the dirty-versus-clean axis collapses
Nuclear reprocessing
Most of the spent fuel's value
Nuclear becomes free and stops being a trade
Box recycling
Most of a worn box's material
Cardboard becomes free and metal has no reason to exist
Reaching zero always requires stopping the thing, never out-plumbing it. Zero pollution requires not burning; zero waste requires not producing it. Capture, recovery and recycling reduce the cost of a choice — they never refund it.
Any new mechanic that returns something consumed falls under this rule. State the ceiling explicitly and say what would break without it, rather than leaving a rate that someone later tunes upward without knowing why it was capped.
Initial. Consolidated from the mobile design session.
1.6
2026-08-29
§12b added: closed loops are always lossy, stated once as a principle after being independently derived four times.
1.5
2026-08-29
§7 Silos hold one substance and measure capacity in units, with unit_size added to §12a. Buildings buffer per substance and follow a different rule from Silos.
1.4
2026-08-28
§7b locomotives reframed. The Electric-versus-Nuclear "opposites" pairing is replaced by three currencies — distance, time, waste — since battery-electric is also infrastructure and nuclear is not a penalty. Nuclear waste is reducible by reprocessing, with a below-100% guard rail.
1.3
2026-08-28
§12a extended: category and type added, refining rule recorded, fuel_value kept and fuel_type rejected.
1.2
2026-08-28
§12a added. ResourceTier removed and replaced by substance + phase. Transport and production depth are both derived, never stored.
1.1
2026-08-26
§7 — StorageRole value GENERAL renamed DEPOSIT. GENERAL read as the broad everything role, which is what UNASSIGNED already means, leaving the narrow mining-deposit role unnamed. Roles are now named for the Genesis action they control, making DEPOSIT and CONSTRUCTION symmetrical.