Design Session Decision Log¶

Document Type: Project Management Last Updated: 2026-08-29 Vault destination: 04_Project Management

Session date: 2026-08-25 Status: Live document, updated as decisions are made Vault destination: 04_Project Management Purpose: Single running record of decisions made during mobile design discussion, to be merged into the relevant vault documents when back at the PC.

0. Working Mode¶

Agreed approach: discuss and design every system broadly and deeply first, so the mechanics are well designed and internally consistent. Early Access scope is decided later, once the full picture exists. Fleshing out and cutting comes after design, not during it.

Scope concerns are therefore recorded, not used to halt design.

0a. Camera — RESOLVED (read from code, 2026-08-26)¶

The blocker that gated three separate things is closed. Read directly from src/world/CameraRig.gd and scenes/main.tscn.

Property	Value
Projection	Perspective, 75° vertical FOV (Godot default, no override)
Pitch	Fixed 50° from horizontal — oblique, not top-down
Zoom	5 to 40, default 20, step 2
Rotation	Yaw orbit EXISTS (right-drag)

⚠️ Doc error found: 01_Game Overview & Scope says "pan and zoom camera". Orbit is implemented. This matters — it is what lets players see behind tall buildings.

Resolution budget at 1920 wide:

Zoom	Visible width	px/metre	Smallest readable feature
5	13.6 m	141	0.02 m
20 (default)	54.6 m	35	0.085 m
40	109 m	17.6	0.17 m

Consequences for decisions already locked:

Decision	Verdict
0.25 m port band	✅ Survives at 4.4 px. Tight but above the floor.
Physical port geometry over chevrons	✅ Validated. A flat chevron would be 2–3 px and dissolve.
Mk accent tabs	⚠️ At risk. Counting needs visible gaps; a 0.3 m pitch gives ~1.4 px gaps that blur. Pitch must be ≥ 0.4 m.
1×1 Silo	❌ Confirmed problem. Whole building is 17.6 px; after a 0.25 m band each side the machine is 8.8 px. 1×1 needs a 0.15 m band.
Tall buildings occluding	⚠️ Real at 50° pitch, but mitigated by yaw orbit. Not a blocker.

Style Bible §2 (Form Language) is now written: chamfer 0.04 m, panel lines 0.08–0.10 m at minimum 0.3 m spacing, base ring corner radius 0.15 m.

Silhouette rule: pitch is fixed and only yaw rotates, so a building is always seen obliquely and from all four sides. Height contributes to silhouette (which is why the Silo column works), and underside detail is wasted.

1. Art Direction¶

1.1 Style change confirmed¶

The art direction has moved away from voxel-like blocky squares with cel-shading to a clean chamfered hard-surface style.

Reference images: 3 OpenAI-generated concepts (Mining Drill, chest/container, Genesis bot), generated via OpenArt.

New style definition:

Attribute	Specification
Form language	Chamfered hard-surface, rounded corner blocks, clear panel divisions
Surface finish	Matte with soft highlights, low specular. Reference standard: Image 3 (Genesis)
Wear and grime	Minimal to none. Image 1 (drill) to be dialled back to match Image 3
Palette: base	Light warm grey / off-white panels
Palette: accent	Warm orange (mechanical joints, clamps, trim caps)
Palette: emissive	Cyan, recessed strips and circular ports
Palette: structure	Mid-to-dark grey for frames, struts, recessed areas
Shading model	Standard PBR + emission mask. No cel-shader
Outlines	None (previous inverted-hull approach dropped)

1.2 Consequences¶

Removed: - Cel-shader implementation - M5.2 Art Pass as currently scoped no longer required in its existing form. Milestone needs rescoping or removal. - Inverted hull outline work

Added: - Higher per-asset modelling cost (chamfers, panel lines, greebles vs. simple cubes) - Need for a locked style bible to prevent drift across 40+ buildings

1.3 Top-down camera rule¶

At gameplay camera distance, only three things read clearly: 1. Silhouette 2. One or two large colour blocks 3. Emissive placement

Rule: Model silhouette and emissive to a high standard. Fine panel-line detail and greebling is for marketing renders and the Steam page only, not required on gameplay assets.

1.4 Consistency controls (to be authored)¶

A style bible must lock: - Exact palette hex values (base, accent, emissive, structure) - Standard bevel/chamfer size - Panel line density and width - Emissive colour and intensity values - A reference render to paste into every future concept prompt

Action: Author 07_Art Direction Style Bible.md in 03_Art & Audio.

2. Asset Pipeline¶

2.1 AI-to-3D rejected¶

Direct AI image-to-mesh conversion (Meshy, Tripo, Rodin) rejected for building assets.

Reasons: 1. Moving parts. Buildings have articulated components (drill auger, drill head). AI-to-3D produces a single fused mesh with no separated components, requiring a full rebuild before animation. 2. Grid constraints. Buildings must match exact grid footprints (e.g. Mining Drill = 2×2) with outputs on known edges. AI meshes come out at arbitrary scale and proportion. 3. Baked lighting. AI-to-3D textures have shadows and highlights painted in, which fights Godot's lighting and conflicts with the cyan emissive mask.

2.2 Confirmed pipeline¶

AI images = concept reference only. All modelling done by hand in Blender.

Blockout rule: Build the exact grid-dimension box first, then add form inside it. Never model first and scale to fit afterwards.

2.3 Modular kit approach¶

To make 40+ buildings tractable for a solo developer:

One shared base plate set
One shared panel set
One shared emissive strip set

Each building is then a unique top on a common foundation. This cuts modelling time and structurally enforces visual consistency.

Action: Author Modular Kit Specification.md in 03_Art & Audio.

2.4 Blender MCP¶

Decision: adopt for parametric and batch work only.

Official Blender MCP server, maintained by the Blender development team and endorsed for use with Claude. Exposes the bpy Python API. Runs locally, works with Claude Desktop and Claude Code.

Use it for: - Generating kit primitives parametrically (exact grid dimensions, bevel sizes, emissive strip insets) - Batch material application across assets - Verifying export scale consistency - Batch .glb export with naming convention enforcement - Fixing the outstanding Mining Drill .glb size issue

Do not use it for: - Artistic silhouette work - Reproducing concept images - Anything requiring aesthetic judgement

Caveat: Executes arbitrary Python in the live Blender session. Always work on a saved file.

3. Port System (Donut Base)¶

Decision: IoConnector and PipeConnector removed. Replaced by ports on a universal building base.

Full spec in 23_Port System Design.md (destination: 01_Design Documents).

Key calls made: - Base footprint always equals building footprint (2×2 building = 2×2 base) - Ports per face = footprint edge length (2×2 gives 2 per face, 8 total) - Central aperture is internal to the building, machine body transfers down into the base layer - Ports are player-configurable as input/output (not auto-assigned by connection) - Power does not use ports. Separate mechanism, still to be designed. - Buildings no longer rotate. Any port can serve any role. - Existing saves break. No migration path will be written.

Buffer Chest: stays 1×1 with one port per face (4 total). Accepted as-is, no special case.

Two blockers before implementation: 1. Direct building-to-building transfer (touching ports, no belt) must be resolved: allow, reduce rate, or disallow. Recommendation: allow at reduced rate. 2. Check git history for why the pre-Feb 2026 port/connector-slot system was removed. Developer recalls connectors solved problems now forgotten.

4. Module System¶

Decision: buildings have fixed module slots on the roof. Full spec in 24_Module System Design.md.

Slot count from footprint size plus Mk level. Range 1 to 6. Small 1×1 buildings get 1 at Mk1, a 4×5 Advanced Press gets 6 at Mk3.
Fixed slot positions, not free placement. Module position carries no mechanical meaning.
Stacking rejected. Slots by Mk and stack depth by Mk are two mechanisms doing one job.
Phase 1 modules: Power Pole, Efficiency, Productivity, Status.
Power poles: ground-placed by default, research-gated upgrade to roof-mounted. Power stays area-based, never port-based. Deliberately not a required tax on every building.
Status is free on every building. The Status module upgrades the readout, it does not enable it. An unmodded building is never blind.
Closes an existing open loop: the Module Crafter building was already specced as producing "modules for building upgrades" with no definition of what those were.

Building visual signalling (locked in 07_Art Direction Style Bible §1.6–1.7d). Three channels, three locations, none can mask another:

Where	Carries	Healthy	Fault
Machine body	Alive / working	Cyan working-lights on	Off
Base ring (whole perimeter)	Fault status	Unlit	Amber or red, pulsing
Base edge tabs	Mk level	Always visible	Always visible
Port geometry	Port direction	Always visible	Always visible

The inversion: healthy is glowing on top with a dark edge, broken is dark on top with a glowing edge. Factory health readable from the cyan-to-amber balance on screen.
Two independent upgrade tracks: Base Mk and Machine Mk. Base Mk governs port throughput and filtering; Machine Mk governs processing speed, recipe capability and module slots. Shown as two tab rows, outer for base and inner for machine, sharing an anchor and pitch so matching levels pair up and mismatches go visibly ragged. Base Mk is a universal upgrade path: one recipe, one research line, applied to any building, so separating the tracks costs far less than doubling.
Mk level = accent tab count, not colour. 1/2/3 tabs per side. Left-aligned, fixed pitch, clockwise from each side's start, so the count reads identically at any footprint size. Tabs protrude past the silhouette to stay countable at distance.
The cyan/violet/magenta emissive ramp is DROPPED. Superseded by tab count. Palette stays at a single accent colour.
Cyan is diegetic: windows, viewports, readouts, indicator pips belonging to that specific machine. Not an abstract strip. Authored via the emissive_mesh child the asset spec already requires, so no new pipeline cost.
Whole ring lights, not just chevrons. The earlier objection (rainbow effect) no longer holds once healthy is unlit, since a working factory has zero lit rings.
Port mode is shown by built geometry, not a drawn symbol. INPUT = recessed intake slot. OUTPUT = protruding nozzle breaking the footprint edge. DISABLED = flush cover plate. Chevrons were prototyped and rejected: a flat symbol dissolves at gameplay distance, while geometry changes the silhouette and casts shadow, so it survives zoom-out. Also diegetic, matching the working-lights principle. Three mesh variants of one kit piece swapped at runtime; the building mesh is untouched.
Colour was unavailable for this channel: orange is accent and Mk tabs, cyan is alive, amber and red are fault. Geometry had to carry it.
No power fires two agreeing signals: ring red and cyan off. Stalled lights the ring but keeps cyan on.
Machine body fills the footprint minus a 0.25 m chevron band per side.

Storage building redesign (Store / column): the 1×1 flat chest reads badly under the fixed 0.25 m chevron band (only 25% of the plot is machine). Redesigned as a vertical column with a fill gauge, since a vertical silhouette reads well on a small footprint.

Fill gauge is a physical window, not an emissive bar. Contents visibly stack up inside. Avoids colliding with cyan = "alive and working", and matches the diegetic principle from §1.7a. Contents could tint by resource type when a port filter is set.
Occlusion risk: tall buildings hide what is behind them on a top-down camera, and stores are numerous. Keep the column slim, or plan a fade when it occludes.
Same mesh across Mk levels. Do NOT make Mk2/Mk3 taller columns. Tabs carry level here as everywhere else, or the no-extra-modelling rule gains exceptions.
NAMING RESOLVED: Silo for solids, Tank for fluids. Gas is already ResourceTier.FLUID, so Tank covers liquids and gases with no third building needed. "Silo" also describes the vertical column form directly, which no other candidate did.
Enum rename: ChestMode → StorageRole, values UNASSIGNED / GENERAL / CONSTRUCTION. "Construction" describes a build-supply silo far better than "BUILD".
⚠️ Superseded 2026-08-26: GENERAL renamed DEPOSIT. GENERAL read as the broad everything role, which is what UNASSIGNED already means, so the narrow mining-deposit role was left unnamed. Roles are now named for the Genesis action they control. Canonical Design Facts §7 v1.1.
⚠️ Rename blast radius. "Chest" appears in: 05_Asset List (buffer_chest), 04_Factory & Resource System Design (building_storage_chest, building_buffer_chest), 10_Tutorial steps 10–11, 11_Achievements (chest_vault skin), 03_Prompt Library, build toolbar (button label "Chest", letter code "Ch"), genesis_queue_ui_v5.html (SUBJ_MAP), and code (ChestMode, get_chests_sorted_by_distance()).

MODULE STACKING REMOVED. Confirmed. 08_Research Tree Design Branch 8 must be rewritten, since it currently states modules "enable advanced stacking combinations". Slot count by Mk replaces it.

Quantum Silo: DEFERRED to late game, planet-local only. Filed to 00_Ideas. See Idea - Quantum Store.md. Cross-planet was rejected because it contradicts the GDD principle "resources belong to the planet, no per-player inventory" and would undercut the planned Trade Station and transport ship layer.

Network / IoT / automation logic: DEFERRED. Filed to 00_Ideas per Risk Register D1. See 03_Idea - Network, IoT & Factory Automation.md. To be discussed in detail in a later session.

5. Power System¶

Correction: power was NOT undesigned. It is specified across 04_Factory & Resource System Design, 06_Vertical Layers & Core Power System, 08_Research Tree Design and 17_HUD Panel Flap. Full spec in 25_Power System Design.md.

Design goal confirmed: semi-teach real-world power engineering, matching the approach already used in 06_Outpost/02_Power Systems. The two modes now teach the same concepts at different scales.

Three tiers: generation (already specced) → transmission (new) → distribution (transmitters exist, poles are new).

Poles reinstated. 04_Factory currently states "There are no separate power poles". Poles now exist at the distribution tier, alongside the integrated transmitters, not replacing them.
Distribution loss is LOAD-DEPENDENT, not a fixed range limit. Voltage drop is current × resistance, so heavier circuit load sags voltage further and the far end fails first. Physically correct, and it is the concept the tier teaches.
Pacing falls out of it: few buildings = generous reach, no early friction. As the factory grows, reach contracts and the edge browns out. The problem emerges from the player's own success rather than from a wall.
Brownout reads on the base rings: the outer edge faults while the core stays healthy, so a red perimeter closing inward diagnoses it at a glance.
Transmission: reach, but with line loss. Step-up and step-down transformers reduce loss. Crossover around 20 tiles, so high voltage is deliberately not automatically better, which is the correct real-world lesson.
Two valid answers when the edge browns out, neither "correct": research transmission (build infrastructure once) or place local generators per cluster (fuel logistics forever, a belt to every generator). The real trade is move power vs move fuel. This is what makes path-choice research viable here.
⚠️ Implementation trap logged: brownout oscillation. A shed building stops drawing, load falls, reach recovers, it powers on, load rises, it sheds again, every tick. Needs hysteresis, staged shedding, and a higher recovery threshold than the shutdown threshold.

Hard constraint — research is path-choice, not a timeline. Players spend limited credits on a chosen direction. Transmission may be taken early, late, or never. Therefore the game must be winnable on distribution alone. Transmission is reach and efficiency, never a required rung.

"Configurable connection range" is a backend tuning value, not a player setting. The existing wording in 04_Factory reads as a player control and must be relabelled or it will be built as one.

Multi-grid tooling now earns its place. Under the old model any contiguous factory formed one grid, so the HUD's per-grid breakdowns and merge/split toasts described a situation the mechanic prevented. Regions now stay separate until deliberately linked by transmission.

Generation sources expanded to nine, differentiated on four axes (fuel burden, variability, planet suitability, byproducts) rather than output alone. New: Biomass Burner (wood), Coal Generator, Wind Turbine, Nuclear Reactor. Existing: Fuel Generator, Solar Panel, Geothermal Tap, Core Power Station. Interplanetary power raised but not designed.

Planet type becomes strategic. Rogue has no star so solar is dead, forcing nuclear or core. Lava is a geothermal paradise. Ocean is water-rich so nuclear cooling is easy. Uses the nine planet types and seeded CER values already in 06_Vertical Layers.
Wind scales with altitude, giving Sky Levels a purpose beyond stacking floors.
Nuclear needs cooling water and produces waste, tying power to the pipe system, the Silo, and a disposal problem.
⚠️ Scope flag: four new generator buildings plus a uranium chain, cooling requirement and waste handling. Which ship in Early Access is an open decision.

All balance values are backend-tunable, including the hysteresis margin, shutdown and recovery thresholds, and shed stagger interval. Recommend a single PowerTuning resource so none are hardcoded.

Mk levels increase power draw — both tracks. Machine Mk is faster, processes more at a time, and unlocks additional recipes. Draw rises slightly faster than output (placeholder: Mk2 = 2× output, 2.4× draw), so a Mk3 machine produces more per tile but costs more per unit produced. This makes efficiency modules genuinely valuable, keeps power a real constraint on scaling, and feeds the pollution loop. Base Mk also draws power, scaling with port throughput, because a free upgrade is one everyone maxes and the choice disappears.

Mk is NOT researched. Recipes are. The Mk level simply indicates what level a building is. A researched recipe may require a Mk-N building to run, exactly as a better assembler is a prerequisite rather than a research subject. Research gates the recipe directly; the Mk requirement is only a material cost on top. This removes the path-choice concern entirely — no recipe can be stranded behind an unreachable Mk.

UPGRADE KITS CONFIRMED. Four items cover the entire upgrade economy across all ~47 buildings: Base Upgrade Kit Mk2/Mk3 and Machine Upgrade Kit Mk2/Mk3, all universally applicable. Per-building recipes would have meant ~94 recipes for the same result. Produced by the Module Crafter, giving it a second product line.

Applied in place to an already-placed building, never deconstruct-and-rebuild. In-place upgrade is what makes the same-mesh-plus-tabs approach work.
Genesis applies them via the existing task queue. New task type UPGRADE_BUILDING: fetch kit from Silo, travel, apply. RULE: an upgrade changes level and NOTHING else. It is a property change, not a replacement. Preserved untouched: installed modules, every port's mode/filter/buffer, storage contents, StorageRole, and any queued or in-progress work.

This needs stating explicitly because tear-down-and-recreate is the natural shape in code for a stats change, and it silently discards all of the above unless someone wrote "carry these across". A specification requirement, not an implementation detail.

Other defaults to confirm: brief downtime showing the grey-blue disabled ring state; kit recoverable (or partial) on downgrade; expensive to craft.

Transformers are not special-cased. They use the standard donut base with all ports DISABLED, reading as flush cover plates all round. They consume no items or fluids. The universal base rule survives with no exception.

Transmission lines run at height. Buildings below clearance let the line pass overhead with no conflict, so belts, pipes and low buildings run freely underneath. Buildings at or above clearance block it. Gives tall buildings a spatial cost beyond footprint. Sky Level interaction still open.

Outpost and main game share the power SOLVER, not the content. Nodes, edges, load summing, loss, staged shedding with hysteresis are the same problem at both scales. Outpost's breakers and per-storey panels, and the main game's pylons and CER, stay separate. Deciding before either is built avoids merging two implementations later.

Power module redefined: no longer a roof-mounted pole. It is a range extender on the building's integrated transmitter, turning any building into a distribution relay. 04_Factory already anticipated relay buildings.

6. Pollution, Waste & Organic Systems¶

Full spec in 26_Pollution, Waste & Organic Systems Design.md.

Core insight: nobody on the planet breathes. No organic player, no biters, so pollution needed a real victim. The answer: air pollution blocks sunlight, and sunlight powers both Solar Panels and farms. Burn fossil fuel → atmosphere thickens → solar output and farm yields both fall → need more power → burn more fuel. The clean path self-reinforces, the dirty path self-undermines, with no punishment mechanic bolted on.

Three pollutants: - Air / smog — atmosphere, zonal → solar output down, farm yields down, decay up. Does not travel between levels. - Ground & water table — soil, zonal, leaches downward → farm yields down, extraction yields down (including Core Drills), nuclear cooling water quality degraded, decay up - Solid waste — items on belts → slag, chemical byproduct, nuclear waste, e-waste. Inert while contained, becomes ground contamination when dumped.

Corrected from earlier in the session: water contamination was modelled as living inside the fluid network. Wrong. Real water pollution is in the ground and water table, from discharge and leaking waste. Contaminated water inside the player's own pipes is a separate problem and an over-complication.

Ground contamination leaches downward, never up, each level receiving a diminished share, and slowly.

Produces a delayed consequence that is physically intuitive. Dump freely on the surface early, excavate Underground L1 twenty hours later, find it already contaminated. Never warned, but not cheated: obvious in hindsight. Effects like this are hard to design deliberately; here it falls out of the physics.
Disciplines the underground-dumping strategy. The deepest level becomes the sink where everything accumulates, which is exactly where Core Drills and the best Geothermal Taps live.

Building decay included, under one hard rule: decay is caused by the player's own pollution, never a universal tax. A clean factory decays at near zero. It never destroys a building, only reduces efficiency, and Genesis repairs it automatically via the task queue, keeping the game AFK-safe and consistent with Outpost's no-failure principle. Maintenance module counters it.

Waste handling: three options, applied identically to solid waste AND contaminated water, so the player learns one structure for two media. - Store → Silo (solids) / Tank (water). Space and logistics forever, fills and backs up the line. - Treat / Recycle → Recycler (solids) / Water Treatment plant (water). Significant power draw. The clean answer always costs electricity, same as the Air Scrubber, so choosing it means first solving generation. - Dump / Discharge → nearly free, produces ground contamination, and e-waste attracts hostiles.

Contamination is RESTORABLE. A poisoned planet is recoverable, not permanently ruined. Soil Remediation building consumes power plus an organic input from farms to slowly reduce ground contamination.

⚠️ Guard rail: poisoning must be fast, healing slow. If remediation cleared contamination near the rate the player creates it, dumping becomes consequence-free with a delay and the entire waste decision collapses into a chore. The rate ratio is a design constraint, not just balance.
Bio-remediation closes a loop. Real bio-remediation uses plants and microbes to absorb contaminants, so farming gains a second customer beyond fuel and polymers. Restoring a planet requires having built the renewable side, not just throwing power at it.
Restoration is per level. Cleaning the surface does not clean below, and the deepest level is hardest because it is the sink.
Full cleanup suite: Air Scrubber (air), Water Treatment (prevents water contamination), Soil Remediation (the only reversal tool).

RESTORATION CONFIRMED as a third endgame path. Full spec in 28_Restoration - Third Endgame Path.md. Peaceful route alongside war effort and supply chain provider.

The core idea is inheriting a factory, not the cleanup. You arrive at a working but filthy base and retool a live system: swap dirty generation for clean, reroute belts around dumps you are clearing, dismantle what should not be there without stopping what should, fit scrubbers and remediation into a layout that never planned for them, and restore the deepest levels last because the sink is at the bottom. Fixing a bad factory is a different puzzle from designing a good one, and almost nothing in the genre offers it.
Only works because the galaxy persists. Player A industrialises fast and dirty then moves on; the wrecked planet becomes content for Player B. Player A is not punished — dirty was a legitimate speed choice. Player B gets a challenge no generator could author, because a real person made it while solving a real problem badly.
Damaged planets also seeded procedurally, so the path exists before enough players have wrecked anything.
Planet Health rating derived from contamination per level (weighted by depth), atmospheric pollution, open dumps, clean-vs-dirty generation ratio, and ecosystem presence.
Service economy: a player posts a restoration contract, another fulfils it and is paid. Uses the Trade Station and transport ships already planned for async trade. Restoration becomes a specialisation, like supply chain provider.
No new core system required. It is a goal and a starting condition assembled from parts that already exist. Restoration also works as a standalone GAME MODE, complementary to the endgame path. The endgame version is open-ended and lives in the persistent galaxy; the mode is bounded, repeatable and competitive.
Solves the gating problem. Available in hour one rather than behind Milestone 3. Also a strong teacher: a wrecked factory shows what not to do more memorably than a tutorial explaining it.
It can carry a LEADERBOARD, which factory games are normally bad at. Conventional factory games cannot support meaningful competition because everyone starts from open ground with no shared problem. A restoration scenario is a closed problem with a measurable outcome: identical wrecked factory, identical start. Score on time, material spent, Planet Health achieved, or fewest demolitions.
Mirrors Outpost Mode's existing three-mode structure (Progression fixed seeds / Seasonal monthly rotation with leaderboard / Sandbox). The pattern applies directly.
Scenarios come from harvesting real player wrecks. Authoring them by hand is expensive, and procedurally generating a factory that reads as badly built by a person rather than random noise is genuinely hard. The persistent galaxy is already full of abandoned contaminated planets built by real people. Player A's mess becomes next month's Seasonal scenario. Free content generation, authentic in a way no generator could match. Needs a consent/anonymisation model.
Strong Steam demo candidate. A bounded two-hour scenario shows every system in a package with a beginning and an end, unlike a slice of open-ended sandbox.
⚠️ Naming collision: Outpost Mode already uses RECLAIM for locking in a restored building (OM7). Same word at two scales is either pleasing consistency or confusing overload. Decide deliberately. Alternatives: Restore, Rehabilitate, Terraform, Renew.

Nuclear waste is the exception. It does not attract scavengers; its distinct character is severe, long-lasting ground contamination when dumped or leaked. The one waste stream a player genuinely cannot be lazy about.

Hostiles are scavengers, not biters. Rogue machines and scrap drones attracted to electronic waste and power signature, not pollution generally. Fits a robot world, and connects to the drone hostiles already designed for Outpost Mode.

Farming is feedstock, not food. Nobody eats. Fast-growth timber → Biomass Burner. Algae → biofuel. Bio-polymer crops → plastics. Needs water, land and light, so air pollution hits farms and solar from the same cause. Strategic axis: renewable but slow and land-hungry vs fossil which is fast, finite and polluting. Makes terraforming a polluted planet a real late-game goal.

Decay affects productivity only. It is a gradient, not a fault, so it does not appear on the base ring. Ring status stays reserved for binary faults. Decay feeds the existing Analytics tab, which already shows per-building efficiency percentage colour-coded and sortable worst-first. No new UI needed.

In-world, decay dims the cyan working lights on the machine body (emission energy 2.5 → ~0.9, scaled continuously). Correct channel: decay is continuous and brightness is continuous, while the ring stays for binary faults. A neglected district reads visibly duller across the factory. Brightness became available when Mk moved from an emissive ramp to tab count. It is an ambient hint, not a readout — the number stays in Analytics.

Note: decay cannot dim the ring, since the ring is unlit when healthy. There is no brightness there to reduce, and a decayed building would only look different once already faulting.

Status colour contest RESOLVED. With decay off the ring, two fault states remain and they split by system:

State	Colour	Rhythm
Output full / input starved	Amber `#F5A623`	Slow pulse (1.6s)
Under-voltage / brownout	Red `#E8433A`	Double-blink (heartbeat)
No power	Red `#E8433A`	Fast pulse (0.55s)
Manually disabled	Grey-blue `#5A6A72`	Steady

Amber means logistics, red means power. The two have completely different fixes, so colour tells the player where to look before they read anything. Three distinct rhythms keep all states readable for players who cannot separate amber from red at all.

Pollution tab added as Tab 7 of the right flap. Full spec in HUD Pollution Tab Specification.md, structured to mirror the existing Power tab (planet overview → per-zone breakdown → click-to-highlight → attention triggers). The key section is the effects readout: solar output penalty, farm yield penalty, decay rate, so the player reads what pollution is costing rather than a raw number.

7. Vertical Transport & Cross-Level Power¶

Correction: vertical layers was already thoroughly designed (06_Vertical Layers & Core Power System, v0.2, Feb 2026). Full spec of today's additions in Vertical Transport & Cross-Level Power.md.

One shaft per type. Items, fluids and power each get a dedicated vertical structure: Item Lift, Fluid Riser, Power Conduit. No shared capacity, no contention.

The cost becomes footprint, not contention. Three separate vertical alignments, each on matching cells across both levels. Clearer puzzle, easier to balance.
Simplifies the existing model. The current design is a Shaft structure containing Lift Belts, pumped pipes and conduits. Now the container and contents are the same object: three standalone buildings replace shaft-plus-contents. The generic Shaft building and PLACE_SHAFT task are replaced.
They are ordinary buildings using the standard donut base. Item Lift and Fluid Riser have ports on both levels; Power Conduit has all ports disabled, same as transformers.
Throughput scales with Mk, answering an existing open question: conduits ARE upgradeable, via Machine Mk. Lifts and Risers via Base Mk.

Cross-level power: capacity cap, no distance loss. A conduit is a short purpose-built conductor, so loss is negligible and rating is the constraint. Mechanically: the player builds a building to move power between levels, so the building's rating is the limit. Does not contradict the horizontal voltage-drop model; different geometry, different physics, learned as two distinct problems.

Conduits LINK grids, they do not MERGE them. Each level keeps its grid identity, so the HUD per-grid breakdown stays meaningful, and a conduit at capacity can leave a lower level in deficit while the surface has surplus.
Transmission is horizontal only. Conduits and Pylons are the sole vertical paths, at distribution voltage. No underground transformers, no vertical loss model.
Clearance rule applies to horizontal lines only, so Sky Pylons are unaffected.

Pollution does not travel between levels, but affects each level differently. Each level holds its own pollution state.

Level	Dispersal	What it hurts	Character
Sky	Above the smog layer	Little to nothing	Refuge. Clean generation.
Surface	Normal	Solar, farms, decay	Standard
Underground	None (sealed)	Decay only, but far more severe	Dirty industry zone, at a corrosion cost

Sky sits above the smog, so dirtying the surface increases the value of building upward. Gives Sky Levels a concrete purpose beyond their efficiency table.
Underground has nothing to ruin but nowhere to vent. No sunlight, no farms, so only decay applies, but concentration climbs to a much higher ceiling. Counter-pressure: underground is already valuable (Core Drills, Deep Scanners, best Geothermal Taps), so filling it with smelters costs that access.
New building: Air Scrubber. Consumes power to neutralise local pollution. Essential underground, or a level eventually becomes unusable, which is a dead end rather than a decision. Ties pollution to power the same way recycling does. Does not vent to another level.

⚠️ Correction to today's power doc: Wind Turbine already exists, with a full efficiency table (surface 70% → Sky L3+ 130%, 0% on Rogue). Atmospheric Harvester also exists and was unaccounted for. Only Biomass, Coal and Nuclear are genuinely new.

⚠️ Pre-existing naming conflict found: Research Branch 2 unlocks a "Solar Panel"; 06_Vertical Layers describes a "Solar Collector" with its own efficiency table. Almost certainly one building with two names.

8. Tooling — Data Pipeline & Console (PLANNED, NOT BUILT)¶

Full plan in 03_Data Pipeline & Design Console - Plan.md.

Core principle: never draw the production chain by hand. A hand-drawn diagram desyncs from the data the first time a recipe changes, leaving two sources of truth. The graph must be generated from the data every time. Rules out Canvas, Miro, draw.io and markdown as the source; they are fine as outputs.

One source, four outputs: SQLite → .tres resources (game), JSON (visualiser), markdown (vault wiki), in-game recipe browser.

SQL over spreadsheet because foreign keys catch "recipe references a non-existent item" automatically. That error class is invisible in a spreadsheet.
⚠️ The database does NOT ship. Authoritative host networking means every client must hold byte-identical recipe data. Baked .tres guarantees it; a runtime-editable database is a deliberate desync vector. Also: native GDExtension dependency, useless git diffs, no editor integration, and no actual runtime need (a few hundred recipes is a dictionary).
Validation is the real value: orphaned items, dead-end items, circular dependencies, buildings with no recipe, recipes needing an unreachable Mk, recipes no research unlocks, and win-critical recipes behind optional branches.
Wiki is nearly free. Generate one markdown page per item and building into the vault with [[wikilinks]] for inputs and outputs, and Obsidian's graph view visualises the chain with zero extra work. Same pages feed the in-game recipe browser.
Do not build the editing UI first. DB Browser for SQLite edits tables fine, for free. Stage 1 is schema, seed data, validator, exporters, with no UI at all.
Standalone web tool for the visualiser (design-time, wants to sit beside Obsidian). Extend the existing F3 debug overlay for in-context recipe inspection while debugging.

Also consolidates recipe data currently scattered across 04_Factory & Resource System Design and 08_Research Tree Design.

9. Belt Logistics — The Router¶

Gap found: belt special pieces get one line in the entire vault — "Special pieces: Splitter, Merger, Underground Belt, Filter Splitter". No behaviour, no throughput rules, no priority handling, for the pieces players touch most in the genre. Full spec in 20_Belt Logistics - The Router.md.

Collapsed into ONE building: the Router. 1×1, four ports, each configurable as input or output with an optional filter.

A splitter, a merger and a filter splitter are the same object with different port configurations. Today's port system already made them identical.
1 in / 3 out = splitter. 3 in / 1 out = merger. Filters set = filter splitter. 2 in / 2 out = balancer.
Removes three buildings, their recipes, assets and build-menu entries. Player learns one thing instead of four.
3-way and 4-way splitting for free. Factorio requires chaining splitters for this.

Smarts arrive through Mk, not all at once. Factorio's splitter mechanics are a permanent community FAQ topic because all the complexity is present on the first splitter you place.

Machine Mk	Capability	When needed
Mk1	Even split and merge	Immediately
Mk2	Priority, in and out	As soon as they have storage
Mk3	Filters and ratio splitting	Once belts carry mixed goods

Reordered by actual need: "feed my smelters before my storage" is an immediate problem; mixed belts needing filters come later.

Priority is a different tool from ratios (reference point: Captain of Industry). Ratio is proportional (70/30 always). Priority is a waterfall (fill output 1, overflow to 2, then 3).

Priority OUT: factory on priority 1, Silo on priority 2. Factory always eats first, leftovers fill storage. No maintenance, no jams.
Priority IN: mine on priority 1, Silo on priority 2. Runs off the mine normally; Silo drains to cover shortfalls.
Together the Silo becomes a flywheel — absorbs surplus, releases under load, automatically. Far better than being a box things sit in, and it makes Mk storage capacity worth investing in.
✅ Priority IS the overflow mechanic. Resolves the earlier open question about backed-up filtered outputs. A blocked output loses its turn and the item waterfalls to the next priority. No separate Overflow mode needed.

Base Mk raises throughput as everywhere else.

Two improvements on the genre standard: - Explicit ratios (70/30, 50/25/25) rather than Factorio's inferred behaviour from priority flags. The player states what they want instead of deducing it. - Live throughput readout per port in the Building Detail Panel. Shows that an output set to 70% is only getting 40% because upstream is starved — the most common source of confusion in factory logistics. The panel is already on the M2.7 list and unbuilt, so this lands in planned work.

Backpressure when all outputs are full: the Router stops and it propagates upstream. Deliberate. Backpressure is what makes a factory legible — something stops, you trace the belt forward, you find the blockage. Silent voiding would hide overproduction entirely.

⚠️ "Backed up" and "starved" must be signalled separately. They look identical and are opposite problems: output-full is success (consumers satisfied, storage full), input-starved is failure. Priority routing makes full storage a normal steady state, so sharing one amber signal would leave a healthy factory permanently in alarm. Now split by rhythm: output-full = slow pulse, starved = double-blink, under-voltage moved to red slow pulse.

New building: Incinerator. Consumes power to destroy surplus, produces air pollution, and recovers some heat as power.

⚠️ Guard rail: recovery is always a fraction of the item's embodied energy, never more. Otherwise the optimal strategy becomes manufacturing items purely to burn them. Ordinary items recover near-nothing; genuinely combustible materials already have dedicated generators. Net-negative or break-even in normal use — heat recovery softens the cost of disposal, never pays for it.

DEFERRED: per-building waste heat recovery (smelters, refineries) is a separate system for a later session. The controlled counterpart to open dumping, and the two carry different costs: dumping creates ground contamination that leaches downward; incineration creates air pollution that does not. The player chooses which pollutant to create, rather than getting a free escape hatch. Answers the inevitable "what do I do with 40,000 spare stone".

Underground Belt stays separate — a belt variant, not a routing decision.

⚠️ Review needed: the Smart Buffer (building_buffer_chest, "configurable filter") is partly superseded by port filters. Is it still a distinct building?

Still undesigned, flagged not addressed: drones/delivery bots (four bullet points), and trains and rail (in the Phase 1 content list with a placeholder colour and no design at all).

10. Trains & Rail¶

Full spec in 22_Trains & Rail.md. Previously five bullet points in 04_Factory plus a roadmap task list carrying the note "Trains are the most complex logistics system. Budget extra time for edge cases."

Belts are PASSIVE — no power draw. A belt is a one-time material spend that runs free forever, so rail is more expensive to operate than the thing it replaces. Distance alone cannot justify rail.

Rail is justified by volume at distance, and by districts. - Belt cost scales with distance × throughput; rail scales with distance and throughput separately. Doubling belt throughput doubles the tiles; doubling train throughput adds a wagon and a platform at no per-tile cost. - At 200 tiles, one commodity at 4/sec: belts win, correctly. Nobody should build a railway to replace one belt. Four commodities at 16/sec: rail wins roughly 4:1 on materials and on space. - The bigger argument is districts. The cost of belts is space and mental load, not materials. Spaghetti compounds because every new line threads past the existing ones. Rail lets a smelting district and a circuits district each be reasoned about alone, and a fifth district does not mean rerouting the other four. Rail wins when the factory stops being one thing and starts being several — a layout trigger, not a distance number. - Pollution already pays for this. Air pollution is zonal and ground contamination leaches downward, so separating dirty smelting from solar and crops is mechanically rewarded. Separation only works with cheap long-distance transport. Three systems reinforce each other unintentionally: zonal pollution makes separation valuable, rail makes it practical, priority routing and Silos absorb the burstiness. - Also strengthens vertical layers: an underground level is already a natural module with its own pollution state, and rail plus Item Lifts turns a level into a district rather than an annexe. - Honest cost: latency. A train delivers 400 items every 90 seconds rather than 4/sec, so it needs Silos at both ends — exactly the flywheel role priority routing created. Trains make the storage system matter. - Only two balance dials with belts passive: belt material cost per tile, and loading/unloading speed. - Consequence: ongoing fuel cost is rail's permanent disadvantage, which pushes serious networks toward Electric or Nuclear. The endgame locomotives earn their place rather than just being faster.

Signalling: automatic by default, manual optional. - Default reserves the whole route as one block. One train runs it safely, collisions impossible. A player who never learns signalling has a working railway, just slower. - Manual signals subdivide blocks, allowing more trains on the same track. Research-gated, purely an optimisation tool. - The manual layer adds throughput only, never capability. Nothing is ever locked behind understanding signals. - Avoids Factorio's mandatory-signal model, which is the steepest learning cliff in the genre and produces the worst edge cases (deadlocks, stuck trains, unreadable junction failures) in the most edge-case-heavy system in the game. Significant for a solo developer.

Three locomotive types, distinguished by fuel:

Locomotive	Fuel	Logistics burden	Pollution
Steam	Coal, belt-fed	Coal to every depot, forever	Heavy
Diesel	Liquid fuel, piped	Fuel to every depot, forever	Moderate
Electric	Electrified rail	None onboard, catenary along the whole route	None locally
Nuclear	Rare fuel swap	Effectively none	None locally, but produces waste

Electric and Nuclear are opposites, not a ladder. Electric = catenary across the entire network, no waste. Nuclear = no infrastructure at all, waste forever. The choice is between building catenary everywhere and handling nuclear waste permanently. Neither is the obvious answer.

The same trade as the power system: move fuel, or build infrastructure once.
An electric train is only as clean as your grid. Coal-powered electrification moves the smoke rather than removing it. True in reality, and it falls out of the existing pollution model without being scripted.

Stations are MODULAR. Station design depends on train setup, so a station is not one building: Station Head (locomotive stop, schedule, name) + one Freight Platform per wagon + optional Fuel Platform. All ordinary buildings with donut bases and ports, so the Router feeds a platform exactly as it feeds anything else. No special loading mechanic.

One train, several commodities — for free. Each platform's ports are configured independently, so a four-wagon train with four platforms carries four different goods, each filtered at its own platform. No new mechanic.
Fuel type physically changes station layout. Steam needs a coal belt at the head, diesel a fuel pipe, electric needs electrified track instead, nuclear needs almost nothing. A steam railway looks different from an electric one, and converting a network means rebuilding stations. The locomotive choice is a commitment, not a swap.
Station priority uses the same waterfall model as the Router, so the pattern transfers with no new explanation.

✅ Resolves an existing open question in 04_Factory: "Do trains require Fuel Cells or is locomotive power abstracted?" — neither. Fuel type is what distinguishes locomotive types.

11. Documentation Review Approach¶

Created 00_Canonical Design Facts.md — one page of load-bearing decisions that every other document must agree with. When a doc contradicts it, the canonical page wins.

Method for the review pass: - Do not read the docs in order. Every conflict found this session came from searching for a specific claim, never from reading. A linear read-through builds fluency without revealing disagreement. - The review question becomes "does this doc contradict the canonical list", not "does this doc contradict any of the other twenty-nine". - Claude Code runs the pass via the existing documentation-engineer subagent. Reading thirty docs and cross-checking claims is what it is good at and what humans are bad at. - Have it report, not fix. A subagent silently correcting a design doc could bury a real decision. - Clear the known conflicts in docs/open-items.md first, so the report is not dominated by things already known. - Data conflicts are separate — recipe and item inconsistencies are caught by the validator, not by reading prose.

12. Documentation Debt Identified¶

Item	Issue	Action
`CLAUDE.md` (repo root)	Badly stale. Still describes M1.7 Prototype Session Loop. No pipes, no HUD, no Genesis carry inventory.	Full rewrite required. Claude Code reads this every session.
Art Direction doc	Describes voxel + cel-shade direction	Rewrite to new style
Blender docs (×2)	`04_Blender Setup & Asset Standards.md` and `02_Blender Pipeline Standards.md` both in `03_Art & Audio`	Consolidate into one, incorporate modular kit + MCP workflow
Milestone plan	M5.2 Art Pass assumes cel-shader	Rescope or remove
`01_Art Direction Document.md`	Specifies cel-shader, thick outlines, flat colour only. Recraft Master Style Prompt now wrong.	Rewrite to new direction
`05_Asset List & Delivery Specification.md`	Quality checklist requires "cel-shader applies cleanly". Tech spec says "flat colour `StandardMaterial3D` only, no texture maps". Also lists `io_connector` and `pipe_connector` as assets to build, now obsolete.	Update material spec and checklist. Remove connector assets. Add `building_base` kit asset.
`08_Research Tree Design.md`	Branch 8 — Modules states modules "enable advanced stacking combinations". Stacking rejected.	Rewrite Branch 8. Decision confirmed: today's fixed-slot model wins.
`04_Factory & Resource System Design.md`	Module System section describes a completely different design: modules are stacked cubes on top of buildings, a fully upgraded building becomes "a tower of cubes", buildings start with 0 slots unlocked by research, and stacking order matters (effects apply bottom to top). Incompatible with this session's fixed roof slots derived from footprint + Machine Mk.	Full section rewrite. Today's model wins.
`04_Factory & Resource System Design.md`	States "There are no separate power poles." Poles are reinstated at the distribution tier.	Rewrite Power System section
`04_Factory & Resource System Design.md`	"Configurable connection range" reads as a player-facing setting. It is a backend tuning value.	Relabel
(undocumented)	`ChestMode` system is nowhere in the vault. `BuildingInstance` has `ChestMode` = `UNASSIGNED` / `STORE` / `BUILD`. `BUILD` marks a chest as a construction supply source Genesis draws from before building; `STORE` is ordinary storage; `UNASSIGNED` is the placement default. Shipped behaviour with no design doc.	Document in `04_Factory & Resource System Design`
`04_Factory & Resource System Design.md`	Chemical Gas listed as "(fluid)" on Gas Pump but absent from the fluid table. M2.1 shipped only 4 fluids. Likely raw-tier in code.	Verify against `ResourceDefinition` and correct

Confirmed correct, no change needed: - Scale: 1 Godot unit = 1 grid cell = 1 metre - Origin: bottom-centre of building footprint - emissive_mesh as a separate named mesh (already fits the new emissive spec) - Naming convention and delivery paths

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

13. Organic Farming & Biomass¶

Full spec in 27_Organic Farming & Biomass Design.md. Resolves OI-247.

The register was wrong about the size of the problem. OI-247 recorded the organic production chain as entirely missing: no resources, no buildings, no recipes. Checked against 04_Factory, most of it was already there under a different name.

raw_biomass has existed since Phase 1, and it was already load-bearing. ref_polymer is raw_biomass + Chemical Gas at the Chemical Plant, and Polymer Sheets feed Hull Plating, Energy Conduit and the Advanced Science Drive. Biomass has been on the critical path to Milestone 1 the whole time.

Two of the three promised crops were duplicates, and the third was a naming error.

Bio-polymer crops → organic carbon → Polymer Sheet. Already exists, as raw_biomass.
Fast-growth timber → Wood → Biomass Burner. Naming drift. The building is the Biomass Burner; its fuel is biomass. No Wood resource was ever defined, and none is needed.
Algae → Biofuel → Fuel Generator. Genuinely new. The only new chain in the document.

Three resources deleted rather than defined. raw_wood, "organic carbon" and "bio-polymer crops" are removed from the design. Defining them would have created three resources, three icons, three recipes and three research nodes for no mechanical gain. This is the second time a document asserting something exists has stopped anyone checking whether it did, after the Geothermal Tap and Core Power Station note in 04_Factory. Recorded rather than repeated.

Control Hut plus Bays, for both families. Biomass Farm is a Control Hut plus Greenhouse Bays; Algae Farm is a Pond Head plus Pond Bays. The head is an ordinary building with base, ports, base ring, module slots, power and crop selection. The bays are the field.

This is the Station Head plus Freight Platform pattern from 22_Trains & Rail, and the area-based model already used by power poles. One composition rule, transferring across three systems.

Bays are extensions, not buildings: no ports, no module slots, no base ring. Module slot count derives from footprint, so a bay built as an ordinary building would carry at least one slot, and a six-bay farm would hold seven slots for one production unit — the most module-dense structure in the game, inverting the whole slot economy.

The point is that this preserves the slot rule rather than excepting it. Every building still has at least one slot from the moment it is placed. A bay is not a building. Exception-casing the rule would have been the easy fix and the wrong one.

Trains inherit the same correction. 22_Trains & Rail described Freight Platforms as ordinary buildings with ports, which gave a four-wagon station five module slots. Platforms become extensions on the same terms. That was never examined because trains were designed before this pattern had a second instance.

Wild biomass is slow and infinite; the Harvester is outscaled, never outgrown. Both the Biomass Harvester and the Biomass Farm produce the identical item. They differ in economics, not output: the Harvester is a fixed low trickle needing no inputs and no research, the Farm is volume that scales with bays and costs water, fertiliser, light and power. The Harvester stays useful in the opening hours and never becomes a dead entry in the build menu, which is a better arc than obsolescence.

Artificial lighting is allowed, and it is the escape from the smog trap. Greenhouses may trade power for independence from ambient light. The trap in §6 still closes, just through the power system instead of directly: if the lighting runs on Coal Generators, the smog thickens and the lighting bill rises with it. Same shape as the electric locomotive argument — the escape is real, and it is only as clean as the grid behind it.

Zero-pollution planet as an explicit design goal. A player should be able to run a planet at zero pollution through recycling and reuse. Not merely low. This is the constructive counterpart to Restoration: that path cleans up someone else's damage, this one is never doing the damage in the first place. It also turns the Pollution tab into a target rather than a warning light.

⚠️ Guard rail: flue capture must never reach 100%. If capture could fully close the loop, a player could burn coal forever at zero net pollution and the entire dirty-versus-clean axis would collapse into a plumbing puzzle solved once. Capture reduces emissions while you still burn. Reaching zero requires not burning, which means clean primary generation — Solar, Wind, Geothermal, Core Power, all of which already exist with the right properties. The reward for a closed loop is earned by changing what you burn, not by out-plumbing the consequences.

Same guard rail shape as the Incinerator's heat recovery. The clean path must be achievable, slower and more land-hungry than the dirty path, and sustainable indefinitely. Fossil is fast, compact and finite; organic is slow, sprawling and endless. Both stay legitimate.

Open, and deliberately not decided here: the greenhouse air input (zonal yield bonus versus a piped capture fluid, recommendation piped), whether Algae is a distinct resource, the capture ceiling value, all four building footprints, lighting power draw, bay count per head, and the fertiliser recipe. Logged as OI-261 to OI-267.

13a. Transport & Logistics — Carrier Decisions¶

Session in progress. Captured as decided rather than left in conversation; a full transport design document should be written from this once the remaining carriers are covered.

Corrections to earlier statements in the session:

Vertical transport carries gas, not only items, fluids and power. The Fluid Riser row already said "fluids and gases".
Rail track costs nothing to run, exactly like a belt. It is a one-time material cost. The locomotive burns fuel. The real asymmetry is that a belt needs no vehicle and rail does, which is a cleaner line than corridor-versus-corridor.

Belts are queues, pipes are pools¶

Stated because several existing rules look arbitrary without it.

PipeNetwork uses pair-equalisation: each tick it walks connected segment pairs and moves a fraction of the imbalance, settling toward one level across the network. Fluid therefore has no position and no order. A pipe network is a shared reservoir that takes time to settle.

A belt is the opposite: discrete items keeping identity, order and place in a queue.

This is why belts can be filtered per item and pipes cannot, why PipeConnector needs an explicit no-mixing rule at its buffer, and why belt backpressure is a jam while pipe backpressure is pressure rising everywhere.

The Router has three configurations, not two¶

ITEM, LIQUID and GAS. A gas Router cannot route liquid, even though both use the same underlying fluid mechanism and the same FLUID ports.

Three media conceptually, two mechanically. Liquid and gas are both non-item and ride the same system, so Canonical §3 is unchanged: ports still carry ITEM and FLUID only, and gas travels as FLUID. The phase restriction sits at the Router, one level above the port.
The restriction is not a purge rule. A gas Router is not a liquid Router that happens to be dirty; it is a different building configuration. The fiction carries it: gas needs compression and pressure vessels, liquid needs pumps. Different hardware.
This resolves the open question of whether a Fluid Router exists. It does, and it is the same building.

⚠️ Consequence: nothing in the code distinguishes gas from liquid. FluidDefinition has id, display_name, viscosity, density, flammable, min/max/base temp and colour. No phase field.

The phase flag goes on FluidDefinition as an enum, not on ResourceTier.

enum Phase { LIQUID, GAS }
@export var phase: Phase = Phase.LIQUID

Not a new ResourceTier value. Adding GAS = 5 beside FLUID = 4 would turn every tier == FLUID check into a two-way test, contradict Canonical §3 which says gas is fluid, and renumber an enum that is serialised as a raw int into .tres files — the same silent-corruption shape already recorded against GenesisTask.Type.
Canonical §3 stays true. The medium is still FLUID; phase is a property of the fluid.
No port code changes. Only the Router reads it, plus pipe and Fluid Riser variants if those are gated on phase later.
An enum extends where a bool does not. is_gas closes the door on anything that is neither, in a game with plasma and slurry within reach.

⚠️ Every fluid is defined twice, in two unrelated classes. data/resources/fld_coolant.tres is a ResourceDefinition carrying tier = 4; data/fluids/fld_coolant.tres is a FluidDefinition carrying the physical properties. They are separate classes, not inheritance, joined only by a shared id string, and nothing enforces that a tier = 4 resource has a matching FluidDefinition.

Chemical Gas has only the first half. There is no data/fluids/raw_chemical_gas.tres, so it has no viscosity, no density and no temperatures — and now nowhere to put a phase. That is how it ended up half-defined, and it is why the fix is three steps that must move together.

Drones¶

Fluid only via barrels or a fluid-carrier variant. A barrel turns fluid into an item, so belts and trains can carry it too.
Battery-limited, and must recharge. Range is a real constraint, not a soft one.
Drones draw power by hooking onto power poles. This gives the distribution tier a second job and makes poles worth placing for reasons beyond reach.
Drones cannot fly underground. Surface and sky only, changing level through a vertical shaft. Underground logistics stays belts, pipes and rail, which preserves the vertical spatial puzzle.

Barrels do not exist anywhere in the vault. They are a significant lever on the whole fluid story: barrelling makes pipes optional for low volume rather than mandatory for all fluid, so barrel capacity versus pipe throughput needs deciding deliberately.

Quantum travel is player-to-player only¶

Late-game quantum travel carries player-to-player async trade. You can never quantum-ship to yourself.

Why the restriction is the point. 04_Idea - Quantum Silo rejected teleporting items on the grounds that Trade Station, transport ships and async trade are the designed Phase 2/3 answer to moving goods, and a teleporting chest makes that layer decorative. 14_Win Conditions & Faction Allegiance goes further and specifies the flow physically: "Transport ship — required to physically move materials between Trade Stations. No ship, no trade."

Restricting quantum travel to another player keeps every bit of that intact. Your own interplanetary logistics still needs ships, so the shipping layer keeps its entire run, and the objection does not apply.

It also gives the mechanic a fiction rather than an arbitrary rule: the link is a handshake between two operators, so it needs a receiving station you do not control.

Open: whether quantum travel replaces ship travel time as a late-game upgrade to the trade route, or runs as a parallel channel alongside ships.

Rejected: weight affecting belt speed¶

Heavier items do not move slower on belts. Neither Factorio nor Satisfactory does this, and the reasoning holds: belt throughput is the arithmetic the whole factory-planning loop rests on. If speed varied by cargo, every ratio calculation would depend on what happened to be on the belt, and the player could do nothing about it — you cannot choose to make iron lighter. It is a cost without a decision.

Weight belongs on drones instead, where it becomes units-per-trip and is therefore a real choice about what is worth flying rather than belting.

Drone capacity comes from the cache box¶

A drone's payload is determined by the cache box it carries, not by the drone. Capacity is a property of the box, so throughput is chosen at load time.

Belt tiers are documented but not built¶

04_Factory specifies Basic 1/sec, Fast 2/sec and Express 4/sec. The code has one speed, hardcoded as BeltSegment.BELT_TICKS = 20, and no belt .tres exists among the 24 building definitions.

This is prototype scaffolding, not a design gap. The tiers were documented ahead of the data, and the hardcoded constant was there to make a prototype run. Replacing it is ordinary work, not a correction. It does raise one unanswered design question: belt tiers raise belt throughput while Base Mk raises port throughput, and nothing states how the two compose.

Dead fields are deferred, not cut¶

viscosity and density are declared on FluidDefinition and read nowhere; substance is proposed and has no consumer yet. None is being removed. The whole game has not been reviewed, and systems still to be designed may need them. Cutting a field because today's code does not read it is how a model ends up unable to describe something later — which is the same failure that produced tier, from the opposite direction.

Comparison checked. Satisfactory uses a single item descriptor with an EResourceForm enum — Invalid, Solid, Liquid, Gas, Heat — with solids on conveyors and liquids and gases on pipes. That is our phase field under another name, and it validates deriving transport from phase. Factorio instead keeps item and fluid as entirely separate prototype types with no phase field, modelling steam as water at temperature. Our barrel handling matches Factorio exactly: barrelled fluid is a plain item with fill and empty recipe pairs. Neither game has a substance field, which is why it is on the deferred list rather than assumed.

13b. Resource Data Model — Substance, Phase, Form¶

Continuation of 13a. ResourceTier is dropped and replaced by three orthogonal fields. Decided after the transport discussion exposed that the existing model cannot express things the game already contains.

Why `tier` goes¶

ResourceTier is RAW / REFINED / COMPONENT / ADVANCED / FLUID. It conflates two unrelated axes: the first four are production depth, FLUID is a transport medium. Chemical Gas is raw by origin and fluid by medium, so the enum makes a correct answer impossible. That is the same classification bug found in 04_Factory §Resources, and the documents inherited it from the code rather than the other way round.

It is also already wrong on its own terms, in shipped data:

cmp_structural_frame is made from cmp_hull_plating, and cmp_power_cell from cmp_circuit_board. Two of five components are made from components, so the ladder does not hold. The moment a tier consumes its own tier it is a label, not a level.
Nothing is tier 3. ADVANCED has zero resources.
No recipe outputs any fluid. All four fld_* resources exist with no way to produce them.

And it is nearly free to remove:

Not serialised. Saves reference resources by id, so there is no save impact.
Read once, as a fallback. FactoryStats already derives a resource's category from the producing building's category by walking recipes. tier is consulted only for resources no recipe produces, and the one function that reads it bypasses it for fluids with a begins_with("fld_") string check.

Production depth was always derivable from the recipe graph, which RecipeRegistry already indexes. A hand-maintained copy of a computed property can only drift, and it has.

The replacement¶

substance : StringName          # iron, water, silicon, sulphur, coal, biomass
phase     : SOLID | LIQUID | GAS

Two fields. That is the whole model.

Axis	Answers	Changed by
Substance	What is it?	Nothing. It is the identity.
Phase	Solid, liquid or gas?	Heat and chemistry

Transport is derived from phase, not stored. Solids ride belts; liquids and gases ride pipes. That is a rule in code, one line, not a field on every resource. An earlier draft of this model carried a third form axis with values BELT and PIPE; it was dropped because it was a denormalised copy of phase — the exact mistake tier was already making.

Phase	Transported by
`SOLID`	Belts, Routers, trains, drones, Genesis
`LIQUID`, `GAS`	Pipes, Fluid Risers, fluid Routers

Barrels need no special machinery¶

A filled barrel is not a liquid in a different form. It is a steel container: a discrete solid object that happens to have liquid inside. So it is an ordinary SOLID item, and barrelling is an ordinary recipe.

coolant (LIQUID) + empty_barrel (SOLID)  ->  coolant_barrel (SOLID)
coolant_barrel (SOLID)                   ->  coolant (LIQUID) + empty_barrel (SOLID)

Nothing new is required. The relationship between a barrel and its contents lives in the recipe graph, where every other production relationship already lives, and a barrel rides belts for the same reason every other solid does. This is what lets a liquid or gas cross a belt, train or ordinary drone network without the transport rule needing an exception.

What this fixes that we had already tripped over¶

Iron gets one identity. raw_metal_ore is iron / SOLID; fld_liquid_metal is iron / LIQUID. Today those are two unrelated rows, which is precisely why Liquid Metal exists with no recipe producing it: nobody modelled the phase change, because the model could not express one. Smelting becomes an honest SOLID → LIQUID on one substance rather than a mapping between two strangers.

The Router rule becomes a field read. A gas Router checks phase == GAS. No new tier value, no string prefixes.

Chemical Gas stops being a contradiction. chemical / GAS, true on both axes, nothing forced. It rides pipes because it is a gas, not because a field says so.

Ids are untouched. The triple is the natural key; the .tres id stays the stable handle that recipes and saves reference. Nothing is collapsed, so recipes and save files do not change.

Consequences accepted¶

19 .tres files gain two fields and lose one.
ResourceDefinition and FluidDefinition should collapse into one class. That split exists largely because "fluids are a different tier" pushed them into a separate file. With phase as a field, the fluid physical properties become optional fields on the same resource — and the half-defined-Chemical-Gas failure mode goes with it. Today the two classes are joined only by a shared id string, with nothing enforcing that a tier = 4 resource has a matching FluidDefinition, which is how Chemical Gas ended up with no viscosity, density or temperatures.
New work created: barrelling and debarrelling recipes plus an empty-barrel item, phase-change recipes, and a production path for Liquid Metal.

Deliberate choice: the full model now, not a cheaper additive version. The game is early; nineteen resource files and one fallback function is a very different proposition from doing this after the port refactor has spread tier assumptions further. The reason gaps like Liquid Metal keep surfacing is that the model could not describe them, so patching around it would keep producing the same class of gap.

⚠️ Sequencing: the data model goes before the port refactor. Both change how a building declares what it accepts. Ports gating on phase is a far cleaner port design than ports gating on a tier enum that is about to be deleted.

13c. Resource Properties and Simulation Level¶

Continuation of 13b. The two-field model (substance + phase) gains two more axes, and two proposed fields were killed by asking what would read them.

A resource has four descriptive axes¶

Axis	Answers	Example
Category	What family?	biomass, metal, mineral, chemical
Substance	What specifically?	wood, algae, iron, coal
Type	Processing state	`RAW` / `REFINED` / `COMPONENT`
Phase	Solid, liquid or gas	`SOLID` / `LIQUID` / `GAS`

type is what tier was reaching for. The word and the mixed-in FLUID value were wrong, not the instinct.

Category is load-bearing, and biomass proves it¶

Biomass is a category. Wood and algae are substances inside it.

This partly reverses the farming pass, which deleted raw_wood as a duplicate of raw_biomass. That was right about the duplication — three crops feeding identical outputs — but it collapsed to the category name rather than a substance name. raw_biomass is named at the wrong level, like having a resource called metal instead of iron.

Why this makes category earn its place: ref_polymer currently consumes raw_biomass. If biomass splits into wood and algae, that recipe either names one substance or accepts any substance in category biomass. The second is clearly right — polymer should not care which feedstock — and it means the recipe system reads category. That is a real consumer, which is the test tier failed.

The raw → refined → component rule already holds¶

Checked against all ten shipped recipes: no component is made directly from raw. Components consume refined or other components; refined consumes raw. The rule was being followed without being written down.

The validator should warn, not fail. In reality almost nothing skips a step, but the step is often trivial — stone is cut into blocks, logs are sawn into planks. The rule survives by modelling those as refined intermediates, at the cost of one extra resource each time. That risks padding: an intermediate existing only to satisfy a rule adds a machine and a belt for no decision. A warning flags accidents while allowing a deliberate override.

This is also what saves type from being tier again. A validator is a reader. Without one, type is a hand-maintained label nobody consumes.

Killed: `fuel_type`¶

Proposed as COMBUSTION | FISSION, then dropped.

The locomotives disprove it. Steam burns coal, Diesel burns liquid fuel, and both are combustion — so a COMBUSTION tag would let a steam locomotive eat diesel. The design deliberately wants different burners to accept different fuels within one type, so a per-burner accepted-fuel list is both simpler and more expressive, and needs no new field.

fuel_value stays. Energy per unit is a property of the substance that a burner cannot know, so it lives on the resource.

⚠️ Burning cannot be a recipe. RecipeDefinition outputs output_resource_id + output_amount, and power is not a resource — it is area-based and never touches ports. Generators are already outside the recipe system: coal_generator.tres has accepted_recipe_ids = []. So burners need a fuel mechanism of their own regardless.

Algae is not a fuel¶

Wet algae burns poorly, which is why the real path is algae into biofuel. The existing chain already says so: Algae → Biofuel → Fuel Generator. Algae has no fuel_value; biofuel does. Algae is a fuel input, which is a different thing.

Simulation Level¶

pipe_complexity generalises into a game-wide Simulation Level. It is not a new concept: pipe_complexity already has three levels with a designed payoff, stated in the Master GDD — Basic ×1.0, Standard ×1.15, Full ×1.30 on the planet's supply chain contribution multiplier, "rewards players who invest in understanding and managing the full fluid system".

Structure: a global level sets defaults, and per-system overrides are allowed. Chosen over one rigid global dial (which would force taking decay to get temperature) and over per-system dials alone (which has no single answer to "how realistic is this session"). pipe_complexity becomes one facet rather than a special case.

The payoff is deliberately not settled. The contribution multiplier is the existing precedent, and candidates recorded rather than chosen: content that only exists at higher levels (temperature-dependent recipes are meaningless at Basic, so Full has recipes Basic cannot run), separate leaderboards per simulation level, and a reduced player-to-player transfer cost.

Noted, not re-litigated: the project has already accepted that higher simulation is mechanically better, since ×1.30 is a large edge. The concern that an advantageous opt-in becomes an obligation is real, but it was settled by precedent rather than being newly introduced here. Separate leaderboards per level would remove it entirely, since you would compete only against players who chose the same rules.

Steam locomotives and water¶

A steam locomotive burns coal; water is the working fluid, not the fuel. 22_Trains & Rail §3 lists Steam as coal only, with no water.

Water for steam is a Simulation Level feature, not a baseline. Loading coal and water into every depot is a genuine burden, which is wrong for the earliest locomotive as a default and right as opt-in realism.

13d. Locomotive Power — Three Currencies¶

Canonical §7b previously framed this as Electric versus Nuclear, opposites: catenary everywhere and no waste, against no infrastructure and waste forever. That framing is replaced.

Why it broke¶

Battery-electric is infrastructure too. A battery locomotive needs a charging station at every stop, so "electric has infrastructure everywhere, nuclear has none" stops being true the moment batteries exist. With both infrastructure-free, the only remaining difference would be that nuclear makes waste and electric does not — which makes nuclear strictly worse, and an endgame option nobody takes is wasted design.

The replacement: three currencies¶

	Pays in	Infrastructure shape	Strongest
Catenary	Distance	Linear — wire every metre	Dense mainline run constantly
Battery	Time	Point — a station at each stop	Branch lines, spurs, low frequency
Nuclear	Waste	Concentrated — inside the locomotive	Long hauls, remote lines

The real difference is the shape of the infrastructure, not its presence. Catenary cost scales with route length; battery cost scales with number of stops. That is a genuine layout decision, and it survives having three options rather than two, which "opposites" never could.

Nuclear is not a penalty¶

The earlier framing made nuclear the option you avoid. That is wrong, and it does not match the real cost profile: high capital, very low running cost, one hard problem to manage. That is an excellent trade, not a drawback.

So nuclear becomes the strongest choice for a long remote haul — where you will neither wire the route nor accept charging stops. The reason to hesitate is that it obliges you to build a whole support system, never that it is weak.

Honest footnote: nuclear locomotives were never actually built. There were 1950s proposals, killed by shielding weight and crash safety, with electrification simply being easier. Nuclear power stations are a different matter and are genuinely strong. This is fantasy, but only the locomotive part is.

Nuclear waste is reducible, never eliminable¶

Spent fuel can be reprocessed to recover most of its remaining value. That turns nuclear from a penalty into a system: take nuclear, then build the chain that handles what it produces. It slots into the existing three-way waste structure (Pollution §5) as the Treat option for nuclear waste.

⚠️ Guard rail: recovery must never reach 100%. If it could, nuclear would be free and the trade would collapse into a plumbing puzzle solved once. Third instance of the same guard rail, after Incinerator heat recovery and the flue capture ceiling — each reduces a problem without removing it, and each exists to stop an option becoming consequence-free.

Nuclear waste stays what Pollution §5.1 calls it: the one waste stream a player cannot be lazy about. Reprocessing changes how much there is, not whether it matters.

13e. Drones¶

Designed from four bullet points. The old text said drones were assigned to a Drone Port, carried a fixed payload, and charged at the port. All three are now wrong.

Their niche is "no built path"¶

Belts need a corridor, rail needs track, catenary needs wire. A drone needs two endpoints. Corrected from an earlier phrasing in this session: that means no built path, not no route — and because drones fly above obstacles, the route is a straight line rather than a pathfinding search, which is also much cheaper to run.

Pairs, not a network¶

A drone is assigned one source and one destination. No pooled fleet, no job queue.

Two reasons. A network needs per-tick matching of N idle drones against M requests, which scales badly and is a well-known performance sink in the genre. And a pooled network invites drones to become general logistics, which puts them back in competition with belts and destroys the niche that justifies them.

The drone module does almost everything¶

A roof-slot module on the building it serves, acting as pickup point, dropoff point, dock and charger.

Participation costs a module slot, which is what bounds the system. Compare a coverage radius, where buildings join automatically because something was built nearby, and can drift in or out of a network by geometry.
The link is inherent — the module is on the building, so there is no registry to maintain and no orphaned interaction point when a building is demolished.
It reuses the pattern the roof-mounted Power Pole module already established.

The Drone Port is deleted¶

Every job it held moved: charging to the module, construction to a dedicated drone-making building, fleet visibility to a HUD tab. Nothing was left.

Worth recording why it survived so long: the old four bullets named it, and a document naming something is exactly what stops anyone asking whether it is needed. It was invented before the module idea existed.

Power poles are the en-route case¶

A drone charges in its module, so power cost is proportional to use. Poles are for running out along the way, which keeps battery range a real constraint on route length and makes poles along a route insurance rather than required infrastructure. Third job for the pole, after power distribution and the roof-mounted pole module.

Running out of power is a Simulation Level behaviour¶

Level	Behaviour
1	Limps home at reduced speed
2 and 3	Stranded in place until a pole is built within reach

This is a better example of Simulation Level than the candidates proposed earlier, and worth noting as the pattern to aim for: it changes the consequence of failure at higher fidelity, not the mechanic itself. An earlier suggestion — battery versus catenary as a simulation level — was rejected precisely because it would change what a locomotive is, which is a different kind of thing from modelling it more precisely.

Stranding is legible rather than punishing: nothing is destroyed, and a drone sitting motionless over open ground states "this route is too long" more clearly than any warning could.

13f. Storage Model¶

Settled before designing cache boxes, because boxes depend on it.

The storage model was never actually decided¶

BuildingInstance contains two contradictory answers to what inventory_capacity means:

receive_item() compares the count of that substance against capacity — a per-substance cap.
receive_items() sums every value in the inventory — a total across all substances cap.

So a building with capacity 10 can hold 10 iron and 10 copper when fed by a belt, but Genesis refuses to deposit once the total reaches 10. Same field, two meanings, depending on which door the items came through. There was nothing coherent to change.

A Silo holds one substance¶

Never mixed. Three independent lines of evidence, none of which was written as a rule:

The fill window already assumed it. Canonical §7 specifies a "vertical column, physical fill window", and the decision log adds "contents visibly stack up inside… contents could tint by resource type when a port filter is set". A window showing a level tinted by resource type is a single-substance display. A silo holding 40 iron, 30 stone and 12 coal cannot show a level at all.
The Tank already works this way, because the pipe no-mixing rule allows one fluid at a time. A Silo holding many substances would make the solid and fluid sides inconsistent for no reason.
It is how industrial storage actually is. A grain silo holds grain.

The cost is deliberate: storage becomes a spatial commitment per substance. Twenty substances means twenty Silos. That turns storage into a layout problem rather than a number, and forces sorting instead of letting a player hoard everything in one box.

Capacity is measured in units, not items¶

Each substance has a unit_size. A Silo of capacity 10 holds two things of unit_size 5. Bulky goods cost more room than dense ones, so what to store becomes a decision alongside how much.

This may also give density a job: it exists on FluidDefinition and is read by nothing. Solids consume units by unit_size; fluids consume units by density. Same idea, one already half-present.

Naming: unit_size on the resource, capacity on the Silo, so the sentence reads "a Silo of capacity 10 holds two things of unit_size 5". Avoids "capacity" meaning both the container's total and the contents' per-unit cost.

Buildings are not Silos¶

A smelter holds ore going in and plates coming out, so buildings cannot be single-substance. Machines buffer; Silos store. Buildings keep a small per-substance buffer, which resolves the contradiction above in favour of receive_item — receive_items is the one that is wrong.

`max_input_slots` and `max_output_slots` are deleted¶

Under the port model any port can be INPUT or OUTPUT, and port count derives from footprint edge length, so the player already decides how many of each. A separate cap is the pre-port model left behind, and the code only reads the fields as > 0 booleans meaning "does this accept input at all" — which ports answer better.

This confirms the port refactor's instinct to remove them rather than reviving them as a storage model.

Two ways to feed drones, and both stay¶

Belt or pipe → packing station → drones collect. Centralised, one station serving many routes, costs space and a building.
A packing module on the building itself. Local, no station and no belt run, but costs a module slot per building.

A genuine choice between infrastructure and slots, scaling differently.

Module stacking stays removed¶

The wish to "add a packing module on top of a drone module without losing another slot" would revive stacking, which 24_Module System Design §2.3 marks rejected and confirmed removed, and which Research Branch 8 was rewritten to strip out earlier in this session.

The need is real, and there is a way to meet it without stacking: a combined module. A single Drone Logistics Module that docks, charges and packs, produced by a recipe consuming a drone module and a packing module. One slot, both functions, combination as an ordinary recipe rather than a new mechanic — and a production investment rather than a free convenience.

Recommendation, open for overruling: research-gate the combined module. Early drone use then costs two slots, which is the real price of adopting drones the way a corridor is the price of belts, and the efficient version becomes something to work toward. This is the same shape as a decision already taken — the ground Power Pole is free and the roof-mounted pole module is research-gated.

13g. Module Installation UI, and Prerequisite Visibility¶

Modules are installed and upgraded from the Building Detail Panel¶

One screen, reached by clicking a building. It lists the roof slots, what is installed, and what can go in them. Upgrading a module happens on the same screen rather than in a separate flow.

Upgrading a module in place, not crafting a replacement¶

An earlier proposal in this session was a combined Drone Logistics Module, crafted from a drone module and a packing module and swapped in. Upgrading the installed module in place is better, and it reuses a mechanism that already exists.

Upgrade Kits are four crafted items applied by Genesis in place, and canonical already rules that an upgrade changes level and nothing else. A packing upgrade applied to an installed drone module is the same pattern one level down: the module gains capability where it sits.

This delivers the outcome the stacking idea was reaching for — two functions, one slot — without reviving stacking. Nothing stacks; a module is upgraded.

Prerequisites must be visible at the point of choice¶

A drone module with no packing anywhere is a dead investment, and the player currently discovers that only when nothing moves. So the Building Detail Panel and the research tree must both surface the dependency before the choice, not after.

Generalised, because it is not only a drone problem: the Building Detail Panel's job is not only to show state, but to show what this building still needs in order to work. The same trap exists elsewhere — ports default to DISABLED, so a freshly placed building does nothing at all until configured, and nothing tells the player that.

⚠️ The document specifying this screen is built on removed decisions¶

09_UI-UX Design Document already contains a Building Detail Panel and a Module UI. Both describe things that no longer exist:

In the document	Status
`Modules 0 / 0 slots`, "greyed if no slots researched yet"	Slots are not researched. Count derives from footprint plus Machine Mk
"Module Stack UI — modules are physical cubes stacked on top of buildings"	Stacking is removed
`Stack position: 2 of 3`	Removed
`Combined effect: +45%`	Combination bonuses are removed
`Speed Module II`	Module tiers are OPEN, not confirmed design
Status "uses building state colours (green/yellow/orange — matches building mesh colour)"	Two removed decisions at once: green-for-running was replaced by healthy-is-unlit, and whole-building tint is what the code does and the design forbids

Six removed decisions still specified in the one document that describes the screen. It needs a pass before anyone implements from it.

13h. Drone Routing — Pull, and the Pit¶

Amends 13e, which recorded routes as pairs, not a network. That was too absolute.

Demand pulls¶

A drone flies because the destination is short, not because the source has surplus.

Pull means an idle factory has idle drones. Push would fly them constantly regardless of need and waste trips against a full destination. It also matches the Router, which backpressures rather than voiding: nothing moves unless there is room for it.

The pit exists because dedicated drones idle¶

Twenty drones assigned to one route are twenty drones idle when demand falls. One or two assigned per route, plus a shared reserve drawn on for spikes, means the factory needs far fewer drones in total. That is a real efficiency, not a convenience.

	Belongs to	Stationed at	Charges at
Assigned	A route	Its source module	Its module
Reserve	The pit	The pit	The pit

Reserve drones charge at the pit because that is where they are stationed and where they fly from. Assigned drones keep charging at their module. You charge where you live.

Why this is not the pooled network that was rejected¶

The objection to a pool was per-tick matching of idle drones against outstanding requests, which grows badly, and drones creeping into general logistics.

A reserve serving existing routes is bounded differently. The matching set is the list of routes the player explicitly configured — small, deliberate, and under their control — rather than everything inside a radius. The pit never creates a route; it only reinforces one that already exists.

Compare a roboport, which enrols every building in its coverage automatically, so the matching set grows with the factory whether or not the player wanted it to.

Three rules that keep it honest¶

A pit serves any selected route, however far. No coverage radius. Distance is not prohibited, it is paid for: a long trip may exhaust the battery, leaving the drone dependent on power poles or stranded per the Simulation Level rule. This is the same principle the power design already uses — long distribution runs are allowed, they just become lossy and unreliable, which is the lesson rather than a prohibition.

A trip always finishes. No recall mid-route, which avoids a half-loaded drone with nowhere to put its cargo.

When the pit is empty, nothing happens. The route continues at assigned capacity. There are no more drones, and that is the signal to assign one permanently — the player's problem to solve, not the game's to paper over.

Cache boxes: one substance, several per drone¶

A box holds one substance, consistent with the Silo, the Tank and the pipe no-mixing rule. A drone carries several boxes, so a four-input Research Lab is served in one trip.

That gets the multi-input trip — the one job drones do better than belts — without making boxes the only container in the game that mixes. Capacity then has two numbers: box capacity in units, and boxes per drone.

It also settles the swap question. With several boxes per drone, swapping full boxes for empties would need empties in circulation per slot per route. Contents are transferred; boxes are not swapped.

13i. Cache Boxes¶

Boxes are the barrel pattern¶

A box is an ordinary item that happens to contain something — exactly what was already decided for barrels. Packing and unpacking are ordinary recipes, and the relationship lives in the recipe graph. No new machinery.

A box holds one substance, consistent with Silo, Tank and pipe buffers. A drone carries several boxes, which gets the multi-input trip — the one job drones do better than belts — without making boxes the only container in the game that mixes.

Boxes belong to nobody. The drone picks them up and moves them; it does not own them.

Flat boxes break a recursion¶

If an assembled box were the only box item, shipping empty boxes to a module would mean putting boxes inside boxes. That is not an identification problem, it is a loop with no bottom.

Flat box is a flat-packed normal item that ships on belts or inside a box. Assembled box is a container in use, existing only at modules and in drone cargo. The module assembles a flat box when it needs one, so empty containers never ship.

This is also how real logistics works, which is usually a good sign.

Two materials, two shapes of cost¶

	Supply	Waste	Wears
Cardboard	Permanent supply line to every module	Spent boxes recycled	n/a
Metal / plastic	Deliver once, rides the return leg	None normally	Yes, at Level 3

The belt-versus-rail shape again: pay once, or pay forever. A player who understands that trade already understands this one, which is worth more than a novel mechanic.

The difference is in logistics shape, not just cost. Cardboard needs a belt in and a belt out at every drone module, forever. Metal needs one delivery.

Capacity per type is a tuning value, not a design decision.

Degradation at Level 3 fixes a balance problem¶

Metal circulating forever would be strictly better than cardboard once the up-front cost was paid, reducing cardboard to a starter option. Wearing out makes metal cheaper ongoing, not free ongoing, so the trade survives into the late game as a difference of rate rather than a difference between costing something and costing nothing.

It also matches an existing concept: buildings decay, so consumables wearing out is the same idea, and precisely what a realism dial should add.

Worn boxes are recycled, not repaired¶

A worn box goes to the Recycler and returns as material for new ones. This reuses a building that already exists — and currently has almost nothing to do — rather than inventing a repair mechanism for items.

It keeps the loop lossy, so metal stock needs slow topping up, which is the intended "replace, but not frequently" behaviour. And it adds a real logistics step at Level 3: worn boxes accumulate at modules and must be collected.

Two decay patterns coexist, deliberately. Buildings decay and are repaired in place by Genesis via the task queue. Boxes decay and are recycled, never repaired.

The difference is fixed versus mobile. A building has a location, so Genesis can be sent to it, and repairing preserves everything configured on it — ports, modules, contents. A box is a mobile consumable with nothing configured on it, so there is nothing to preserve, and having Genesis chase boxes around the factory would be a new behaviour invented for one case.

This is not an inconsistency to resolve. It is two different kinds of thing treated differently for a reason.

Degradation rate is configured per substance. Metal and plastic wear at different rates, and both are tuning values rather than design decisions.

Trip conditions¶

All three must hold: the destination has space, the source has stock (full load, or partial if the module allows), and demand exists — pull, never push.

⚠️ Full-load-only against a destination that never has a full box of free space means no trip ever happens. A configuration error rather than a system flaw, and exactly what the Building Detail Panel's show what this building still needs rule should catch.

The drone module's full job¶

Pickup, dropoff, dock, charger, multi-substance buffer, flat-box assembler, packer and unpacker at Level 2 and above. It is building-ish, so its buffer follows the building rule — several substances, per-substance — rather than the Silo rule.

That is a long list, and it is the argument for the packing capability being a real cost rather than free.

⚠️ Fourth instance of the same guard rail¶

Box recycling must recover less than 100%, or cardboard becomes free and metal has no reason to exist. That is now the fourth:

Incinerator heat recovery — always a fraction of embodied energy
Flue capture ceiling — never fully closes
Nuclear reprocessing — reduces waste, never eliminates it
Box recycling — recovers most, never all

Four occurrences is a principle, not a coincidence: a loop that closes completely removes the decision it was meant to create. It should be stated once and referenced, rather than restated per system.

14. Session Log¶

2026-08-25 - Confirmed art style change, Image 3 set as surface standard - Rejected AI-to-3D for buildings, confirmed hand-modelling in Blender - Adopted modular kit approach - Adopted Blender MCP for parametric and batch work - Identified CLAUDE.md as critically stale - Extracted and locked the 9-colour palette by pixel-clustering the reference images. Created 07_Art Direction Style Bible.md. - Confirmed Image 1 (drill) is out of spec on grime/gloss and needs rebuilding to Image 3 standard - Confirmed GUT already integrated (M2.2, 70 tests passing). Earlier note to install it was wrong. - Roadmap stale: last entry M2.3 completed 2026-03-13. Five months of work including the full HUD build is unrecorded. - Designed the donut base / port system. Agreed to remove IoConnector and PipeConnector. Created 23_Port System Design.md. - Confirmed gas needs no third port medium. Gases travel as FLUID on pipes. Ports carry ITEM and FLUID only. - Corrected port count rule for non-square footprints (Gas Pump 2×3, Refinery 3×4, Advanced Press 4×5). Base is a rectangular ring on these. - Surfaced the category-accent-colour vs locked-palette conflict, then resolved it: colour denotes upgrade level, not category. - Locked the Mk1/Mk2/Mk3 emissive ramp (cyan → violet → magenta) with lit-segment-count redundancy. - Split emissive duties: machine body = upgrade level, base ring = operational status. - Buffer Chest confirmed 1×1, one port per face. - Designed the roof module system. Created 24_Module System Design.md. - Locked the base-ring status strip spec: healthy is unlit, faults pulse. - Parked the network/IoT/automation concept in 00_Ideas rather than scoping it into Phase 1. - Moved status from an inset side strip to top-face chevrons. Added chevron orientation as a free second channel showing port mode. - Confirmed ~90% of buildings get Mk levels. - Replaced the Mk emissive colour ramp with accent tab count, left-aligned at fixed pitch. - Moved status from chevrons to the whole base ring perimeter. - Reassigned cyan from "level" to "alive and working", diegetic per building. - Built an interactive top-down explainer: base_chevron_explainer.html. - Redesigned the storage building as a vertical column with a physical fill window. - Captured the Quantum Store idea, scoped planet-local and late-game, filed to 00_Ideas. - Found Research Tree Branch 8 (Modules) already exists and assumes module stacking, conflicting with this session's decision. - Found the ChestMode system is entirely undocumented in the vault. - Correction: power was already extensively designed. Found four docs covering it. - Found 04_Factory has a second, incompatible module design (stacked cubes). Confirmed today's fixed-slot model wins; that section and Research Branch 8 both need rewriting. - Designed the three-tier power model (generation / transmission / distribution) to teach real grid concepts. Created 25_Power System Design.md. - Established that research is path-choice rather than a timeline, so the game must be winnable without transmission. - Replaced fixed distribution range with load-dependent voltage drop, matching real distribution engineering. - Identified the brownout oscillation trap before implementation. - Built the nine-source generation table, differentiated by fuel burden, variability, planet suitability and byproducts. - Made all power balance values backend-tunable via a PowerTuning resource. - Confirmed upgrade kits: four universal items, applied in place by Genesis. - Designed vertical transport: one shaft per type, conduits as rated links. Created Vertical Transport & Cross-Level Power.md. - Corrected the Wind Turbine double-count and found the Solar Panel / Solar Collector naming conflict. - Resolved pollution across vertical levels: air does not travel, ground contamination leaches downward. Added the Air Scrubber. - Corrected the water contamination model: it lives in the ground and water table, not inside the pipe network. - Unified waste handling across solid and liquid: store / treat / dump. Added the Water Treatment plant. - Made contamination restorable via Soil Remediation, fed by farm output, with the poisoning-fast/healing-slow guard rail. - Confirmed restoration as a third, peaceful endgame path. Created 28_Restoration - Third Endgame Path.md. - Found the RECLAIM naming collision with Outpost Mode. - Extended restoration into a standalone game mode with leaderboard potential, scenarios harvested from real player wrecks. - Found belt special pieces were a single line of text. Collapsed splitter/merger/filter splitter into one Router building. Created 20_Belt Logistics - The Router.md. - Added priority in / priority out to the Router (Captain of Industry pattern), which turns the Silo into a flywheel and removes the need for a separate Overflow mode. - Split the output-full and input-starved ring signals, since priority routing makes full storage normal. - Added the Incinerator as controlled disposal, trading ground contamination for air pollution, with heat recovery capped below embodied energy. - Deferred per-building waste heat recovery to a later session. - Designed trains and rail: automatic signalling with optional manual, four locomotive types by fuel, modular stations. - Established the economic and spatial case for rail: belts are passive so rail costs more to run; rail is justified by volume at distance and by enabling districts. Confirmed pollution zoning reinforces it. Created 22_Trains & Rail.md. - Created 00_Canonical Design Facts.md as the single reference for future consistency reviews. - Planned the documentation review method: canonical page + Claude Code reporting contradictions, not fixing them. - Corrected an overlap I created: scavengers already exist in Outpost Mode as external drones attracted to power. Resolved by reusing them on the planet surface rather than inventing a parallel enemy. - Planned the data pipeline: SQLite as single source of truth, four generated outputs, database does not ship. Created 03_Data Pipeline & Design Console - Plan.md. Nothing built; still in plan mode. - Resolved four power questions: Mk increases draw on both tracks, transformers use the standard base with ports disabled, transmission blocks by height clearance, and Outpost shares the solver but not the content. - Designed pollution, waste and organic farming as three linked systems. Created 26_Pollution, Waste & Organic Systems Design.md. - Reframed hostiles as scavenger machines drawn to e-waste and power signature rather than pollution-attracted creatures. - Established the decay-from-own-pollution rule so upkeep stays a controllable feedback loop rather than a chore. - Added brightness as the in-world decay channel: cyan working lights dim as a building degrades. - Resolved the status colour contest by moving decay off the ring into Analytics. Split amber (logistics) from red (power), with three distinct rhythms. - Specced the Pollution tab as Tab 7 of the right flap. Created HUD Pollution Tab Specification.md. - Confirmed removal of module stacking. - Named the storage family: Silo (solids), Tank (fluids and gases). - Collapsed the two solid storage buildings into one Silo with capacity by Mk. The 500-unit "Storage Chest" and 1×1 "Buffer Chest" appear to have been one building with two names across two docs. - Split upgrades into Base Mk and Machine Mk, with two tab rows to show them. - Compared three port indicator styles in the explainer and locked Physical geometry, rejecting chevrons.