Auto Warz — Data Dictionary¶

Document Type: Reference Version: 0.1 (Draft) Status: In Progress Last Updated: 2026-08-28 Vault destination: 05_Reference Related: [00_Canonical Design Facts](<../04_Project Management/00_Canonical Design Facts.md>) · [[AGENTS.md]] · [06_Design Session Decision Log](<../04_Project Management/06_Design Session Decision Log.md>)

Purpose¶

One term, one meaning, everywhere. This document exists because the same thing has repeatedly been given several names across the vault and the code, and the drift was only ever caught by accident.

Real examples that motivated it: a storage building called both Storage Chest and Buffer Chest in two documents while being one building; Solar Panel and Solar Collector for one building across two documents; Wood first named as the Biomass Burner's fuel, then wrongly deleted as a duplicate, then restored as a substance once biomass was recognised as a category; and tier, form, medium and phase used interchangeably for four different ideas.

Rules for this document:

If a term is here, use exactly this word. Do not introduce a synonym.
If a term is not here and you need one, add it here first, then use it.
Deprecated words are listed with their replacement. Do not reintroduce them, including in code identifiers, UI labels and asset filenames.
Where a term's meaning is not yet decided, it says so and names the open item. Do not resolve it by usage.
This document defines vocabulary and schema. It does not make design decisions. Where it disagrees with 00_Canonical Design Facts, the canonical page wins.

1. Resource Vocabulary¶

Term	Meaning
Resource	Anything the factory produces, consumes or moves. Identified by a stable `id`.
Category	The family a substance belongs to — biomass, metal, mineral, chemical. Load-bearing: a recipe may accept any substance in a category. Decided, not yet implemented.
Substance	What a thing is specifically — wood, algae, iron, water, coal. The identity. Never changes. Decided, not yet implemented.
Type	Processing state: `RAW` / `REFINED` / `COMPONENT`. What `tier` was reaching for. Decided, not yet implemented.
Wood	A substance in category `biomass`. Not deprecated — an earlier pass wrongly collapsed it into the category name.
Algae	A substance in category `biomass`. Not a fuel — it feeds biofuel, which is.
`unit_size`	How much Silo capacity one of this substance consumes. A Silo of capacity 10 holds two things of `unit_size` 5. Makes storage spatial rather than a count. Decided, not yet implemented.
`fuel_value`	Energy per unit, on the substance. There is no `fuel_type`; burners carry their own accepted-fuel list.
Phase	`SOLID` / `LIQUID` / `GAS`. The state a substance is in. Changed by heat and chemistry. Determines transport. Decided, not yet implemented.
Item	A resource in `SOLID` phase. Discrete, ordered, countable. Rides belts.
Fluid	A resource in `LIQUID` or `GAS` phase. Rides pipes. Fungible — see pool below.
Gas	A fluid whose phase is `GAS`. Mechanically a fluid; the distinction matters only at the Router.
Barrel	A steel container holding a fluid. A filled barrel is an ordinary `SOLID` item, so it rides belts like any other solid. Barrelling and debarrelling are ordinary recipes. There is no "form" axis.
Queue	How belts behave. Items keep identity, order and position, so they can be filtered and counted individually.
Lossy loop	Any recovery, capture, reprocessing or recycling mechanic. Recovers most, never all — a loop that closes completely removes the decision it was meant to create. Canonical §12b.
Pool	How pipes behave. `PipeNetwork` pair-equalises, so fluid has no position and no order and a connected network drifts toward one level. This is why belts can filter per item and pipes cannot.

⚠️ tier is deprecated. See §5.

2. Building Vocabulary¶

Term	Meaning
Building	A placed structure that sits on a base, has ports, a base ring and at least one module slot.
Base	The universal donut base every building sits on. Footprint identical to the building. Carries the port band, the base ring and the Mk accent tabs.
Port	A cell on the base's top face, configurable `DISABLED` / `INPUT` / `OUTPUT` with an optional resource filter. Carries `ITEM` and `FLUID` only; power never uses ports.
Base ring	The perimeter band carrying fault status. Unlit when healthy.
Head	The building half of a head-plus-extension pair. Ordinary building in every respect. Examples: Station Head, Control Hut, Pond Head.
Extension	A piece attached to a head that is not a building: no ports, no module slots, no base ring. Examples: Freight Platform, Fuel Platform, Greenhouse Bay, Pond Bay.
Bay	An extension belonging to a farm head. Specific case of extension.
Module	A crafted item installed into a fixed roof slot. Adds capability.
Module slot	A fixed roof position. Count derives from footprint size class plus Machine Mk, range 1 to 6. Never researched.
Base Mk	Upgrade track governing port throughput and filtering. Shown by the outer tab row.
Machine Mk	Upgrade track governing processing speed, recipe capability and module slots. Shown by the inner tab row.
Upgrade kit	One of four crafted items that raise a building's Base or Machine Mk in place. An upgrade changes level and nothing else.

3. Transport Vocabulary¶

Term	Meaning
Belt	Carries `SOLID` resources. Passive: no power draw, a one-time material cost that runs free forever.
Pipe	Carries `LIQUID` and `GAS` resources. Pressure-based, pair-equalising.
Router	1×1 building, four configurable ports. Replaces Splitter, Merger and Filter Splitter. Configured `ITEM`, `LIQUID` or `GAS` at placement; a gas Router cannot route liquid.
Underground Belt	A belt variant, not a routing decision.
Rail / track	Passive like a belt: a one-time material cost that runs free. The locomotive burns fuel, not the track.
Station Head	The building half of a station. Holds schedule and name.
Freight Platform	An extension, one per wagon.
Item Lift	Vertical structure carrying items between levels. Paired: same grid cell on both levels.
Fluid Riser	Vertical structure carrying fluids and gases between levels. Paired.
Power Conduit	Vertical structure carrying power between levels. All ports `DISABLED`. A rated link between two grids, not a merge.
Drone	Flying carrier. Battery-limited, recharges by hooking onto power poles. Cannot fly underground; changes level via a vertical shaft.
Cache box	The container a drone carries. Payload capacity is a property of the box, not the drone.
Quantum travel	Late-game player-to-player async trade channel. Never to yourself.

Transport is derived from phase, never stored on a resource. Solids ride belts; liquids and gases ride pipes.

4. Storage Vocabulary¶

Term	Meaning
Silo	Solid storage. Vertical column with a physical fill window. Holds one substance, never mixed — a fill window cannot display a mixture. Capacity is a number of units, so what it holds depends on each substance's `unit_size`.
Tank	Fluid and gas storage. Single-fluid, by the same rule the pipe no-mixing rule already implies.
Packing station	A building that packs loose substance into cache boxes for drones. The centralised route: belt or pipe in, drones collect.
Packing module	A roof-slot module that packs on the building itself. The local route: no belt run, costs a slot.
Buffer	What a building holds — its recipe inputs and outputs, per substance, in a small amount. Machines buffer; Silos store. Different rules, deliberately.
StorageRole	`UNASSIGNED` / `DEPOSIT` / `CONSTRUCTION`. Named for what Genesis does with the building. `UNASSIGNED` = both, the default.

4a. Power Vocabulary¶

Term	Meaning
PU	Power Units. A rate. Generator output, building draw, conduit capacity and transformer ratings are all PU.
PU·s	Energy. A rate held for a time. Accumulator capacity and the energy content of a fuel item are PU·s. A Smelter drawing 30 PU for ten seconds spends 300 PU·s.
Grid	A set of buildings sharing supply. Regions joined only by distribution stay separate grids until linked by transmission or a Power Conduit. Conduits link grids; they never merge them.
Connection	Whether a building is on a grid at all. A fixed radius, topological.
Reach	Whether usable power actually arrives. Electrical, and it contracts as circuit load rises. A building can be connected and still receive nothing.
Shed	A building switched off by the power system to protect the grid. Not a fault in the building. Two independent causes: grid deficit and local under-voltage.
Brownout	The condition, not the mechanism. Covers both shed causes; say which one is meant.
CER	Core Energy Rating. Seeded per planet, 200–2800 PU, and the only generation figure unknown until the planet exists.

Authority for all of these is [25_Power System Design](<../01_Design Documents/25_Power System Design.md>). Storage is measured in PU·s and not in PU, which is the one unit error already made once in the vault.

5. Deprecated Words¶

Do not use these, anywhere — prose, code identifiers, UI labels or asset filenames.

Deprecated	Use instead	Why
Chest, Storage Chest, Buffer Chest	Silo (solids), Tank (fluids and gases)	Canonical §7 deprecates the word entirely
ChestMode	StorageRole	Same rename
`STORE` (StorageRole value)	`DEPOSIT`	`GENERAL` and `STORE` both read as the broad role, which is what `UNASSIGNED` means
`GENERAL` (StorageRole value)	`DEPOSIT`	Superseded before implementation
Organic carbon, bio-polymer crops	`wood` or `algae`	Both duplicated a substance that already existed
Fast-growth timber	`wood`	Same duplication
`raw_biomass`	`wood` / `algae`, or category `biomass`	Named at the category level, not the substance level. See §1
Solar Collector	Solar Panel	One building, two names. Solar Panel wins: 13 documents to 6, and `solar_panel.tres` ships
Shaft, generic Shaft, `PLACE_SHAFT`	Item Lift, Fluid Riser, Power Conduit	Container-plus-contents is replaced by three specific structures
Splitter, Merger, Filter Splitter	Router	Collapsed into one building
IoConnector, PipeConnector	Port	Replaced by configurable ports on the base
Tier, `ResourceTier`	`substance` and `phase`	Conflated production depth with transport medium, so some resources could not be described
Form (as a stored field)	`phase`	A stored form would be a denormalised copy of phase — the same mistake tier made
Medium (as a resource property)	`phase`	Medium describes the mechanism, not the resource
Module Expansion (research node)	Module Technology	Slots are not researched
Module stacking, stack order	(nothing — removed)	Modules sit in fixed roof slots and do not stack
Cel-shader, outline pass	(nothing — removed)	Style is PBR plus emission mask
Category accent colour	(nothing — removed)	Buildings are distinguished by silhouette
Factory Overview (`F`)	Right flap tabs	Removed in `09_UI-UX` v0.6

Words that are still fine but often confused: tier remains correct for research tiers and alien tiers. It is only deprecated as a resource field.

6. Schema — as it exists today¶

Recorded so the gap between current code and the decided model is visible. This is the current state, not the target.

`ResourceDefinition`¶

Field	Type	Notes
`id`	`String`	Stable handle. Referenced by recipes and save files.
`display_name`	`String`
`category`	`StringName`	The family. Optional — populated only where substances are interchangeable in recipes. Empty on all five components.
`substance`	`StringName`	What it is specifically.
`type`	`Type`	`RAW` / `REFINED` / `COMPONENT`.
`phase`	`Phase`	`SOLID` / `LIQUID` / `GAS`. Determines transport.

`FluidDefinition`¶

Separate class from ResourceDefinition, joined only by a shared id. Nothing enforces that a fluid resource has one — this is how Chemical Gas ended up with no fluid properties (OI-277).

Field	Type	Notes
`id`	`String`
`display_name`	`String`
`viscosity`	`float`	0.1 thin to 1.0 thick. Currently unread (OI-283).
`density`	`float`	Currently unread (OI-283).
`flammable`	`bool`
`min_temp` / `max_temp` / `base_temp`	`float`
`colour`	`Color`

`BuildingDefinition`¶

Field	Type	Notes
`id`, `display_name`	`String`
`category`	`BuildingCategory`	No Environmental or Waste value exists (OI-017).
`grid_size`	`Vector2i`	Footprint. Determines port count per face and module slot count. Some values disagree with the docs (OI-256).
`model_scene`	`PackedScene`
`base_color`	`Color`	⚠️ Category colour-coding is removed from design.
`power_draw`, `power_output`	`float`	Read by nothing; power is unsimulated.
`max_input_slots`, `max_output_slots`	`int`	⚠️ To be deleted (OI-301). Ports replace them: any port can be `INPUT` or `OUTPUT` and port count derives from footprint.
`inventory_capacity`	`int`
`accepted_recipe_ids`	`Array[String]`	Resolved against `RecipeRegistry` at runtime.
`output_resource_id`	`String`	For non-recipe producers.
`production_ticks`	`int`
`fluid_output_id`	`String`
`fluid_output_pressure`	`float`
`behaviour_script`	`Script`
`base_module_slots`	`int`	⚠️ Design derives slots from footprint + Machine Mk. Relationship to this field undecided.

`RecipeDefinition`¶

Field	Type	Notes
`id`	`String`
`inputs`	`Dictionary`	`resource_id → count`. ⚠️ Item-only. No building can consume a fluid as a production input (OI-001).
`output_resource_id`	`String`	Single output.
`output_amount`	`int`
`production_ticks`	`int`

7. Terms Not Yet Defined¶

Listed so they are not settled by accident. Do not invent a meaning; add it here when it is decided.

Term	Open item
Barrel capacity, and how it compares to pipe throughput	OI-272
Cache box sizes, and whether size affects drone speed or battery	OI-281
Whether `substance`, `viscosity` and `density` earn their place	OI-283
Whether Algae is a distinct resource or an intermediate	OI-262
Flue capture ceiling	OI-263
How belt Mk tiers compose with Base Mk port throughput	OI-282
How a player reconfigures a port	OI-259
Whether quantum travel replaces ship travel time or runs parallel	OI-274
Simulation Level payoff — what higher levels actually reward	OI-285
Which systems get a per-system simulation override	OI-285

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

8. Revision History¶

Version	Date	Changes
0.4	2026-08-29	Lossy loop added, pointing at the new Canonical §12b.
0.3	2026-08-29	Storage vocabulary: Silo holds one substance, capacity in units, Tank mirrors it, packing station and packing module added, and buffer distinguished from storage. `unit_size` added. §6 schema updated now `ResourceTier` is actually gone.
0.2	2026-08-28	`category`, `substance`, `type` and `fuel_value` added. Wood and Algae un-deprecated — they are substances in category `biomass`; `raw_biomass` is deprecated instead, being named at the category level.
0.1	2026-08-28	Initial draft. Resource, building, transport and storage vocabulary; deprecated word list with replacements; current schema for the four definition classes; undefined terms listed against their open items.
0.3	2026-08-29	Added §4a Power Vocabulary: PU against PU·s, grid, connection against reach, shed, brownout, CER. The PU/PU·s split is recorded because the vault had already made that error once, describing accumulator storage as a rate.