Module System Design¶

Document Type: Design Document Version: 0.1 (Draft) Status: In Progress Last Updated: 2026-08-25 Vault destination: 01_Design Documents Related: [23_Port System Design](<./23_Port System Design.md>) · [04_Factory & Resource System Design](<./04_Factory & Resource System Design.md>) · [07_Art Direction Style Bible](<../03_Art & Audio/07_Art Direction Style Bible.md>) · [[08_Economy & Progression Design]]

1. Summary¶

Buildings have module slots on the roof. Modules are crafted items that add capability to a building: power distribution, efficiency, productivity, status readout, and (later) network connectivity.

This closes an existing loop. The Module Crafter building (3×3, gold accent) is already specified in 04_Factory & Resource System Design as producing "modules for building upgrades", but what those modules are has never been designed. This document defines them.

2. Slot Model¶

2.1 Fixed positions¶

Module slots are at fixed positions on the roof, not freely placed. A module's position carries no mechanical meaning, so free placement would cost a per-building roof grid, footprint-dependent validation, and art that must read correctly with modules anywhere, in exchange for nothing the player can use.

2.2 Slot count¶

Slot count is driven by footprint size and Mk level. Bigger buildings have more roof, so they hold more.

Base slots by footprint:

Size class	Cells	Base slots	Example buildings
Small	1–4	1	Silo, Mining Drill, Solar Panel, Accumulator
Medium	6–9	2	Smelter, Gas Pump, Assembly Machine, Research Lab
Large	12–16	3	Refinery, Press Machine, Chemical Plant, Advanced Assembly
Huge	20+	4	Advanced Press

Mk bonus: +1 slot per **Machine** Mk level above Mk1

Module slots come from Machine Mk, not Base Mk. Base Mk governs port throughput and filtering. See 23_Port System Design §5.4.

	Machine Mk1	Machine Mk2	Machine Mk3
Small	1	2	3
Medium	2	3	4
Large	3	4	5
Huge	4	5	6

Range is 1 to 6. This gives Mk levels real mechanical weight rather than a flat stat bump, and it means the inner accent tab row (07_Art Direction Style Bible §1.7) tells the player something meaningful: a three-tab machine has slot capacity a one-tab machine does not.

2.3 No stacking¶

Rejected and confirmed removed. Slot count by Mk and stack depth by Mk are two mechanisms doing one job. Slots are simpler to build, explain, and read from above.

⚠️ Conflict to resolve: 08_Research Tree Design Branch 8 (Modules) currently states it "enables advanced stacking combinations". That branch must be rewritten to match. Modules were already partly designed there before this document existed.

3. Module Types (Phase 1)¶

Module	Effect	Unlock
Efficiency	Reduces power draw	Research — Module Crafting (the branch entry node)
Power Pole	Distributes power over an area from the building roof	Research — Module Technology I
Status	Upgrades the free base-ring status to detailed / remote readout	Research — Module Technology II
Productivity	Increases output per input	Research — Module Technology III

Power Pole placement is specified in §4; the Status module in §5.

3.1 Efficiency is the starter module¶

Efficiency is unlocked by the Module Crafting node itself, not by any capability node. The moment a player can craft modules at all, they can craft Efficiency.

The Module Crafter is not free from the start. It also produces the four Upgrade Kits (§5a), so an unresearched Module Crafter would put Mk3 upgrades in the player's hands inside the first hour. It stays the entry node of the Modules branch.

What this solves. Every building has at least one roof slot the moment it is placed (§2.2). If all four module types sat behind capability nodes, slots would stand visibly empty with nothing that could fill them through the whole early game — which does not read as anticipation, it reads as broken — and then an entire system would arrive at once.

Unlocking the system and one usable module in the same node solves both halves. A player who can install a module immediately understands what a slot is, and every later unlock lands on a mechanic they already grasp.

Efficiency is the right starter because it is the least conditional: it has a legible effect on every building that draws power, needs no supporting infrastructure, and cannot be misapplied.

3.2 Research node names¶

The three module research nodes are Module Technology I / II / III. They unlock module capability, never slot count — slot count comes from footprint and Machine Mk (§2.2) and is not researchable. The nodes were previously named Module Expansion and described as unlocking slots; that name is retired because it names a mechanic that no longer exists.

The tree itself is specified in [04_Factory & Resource System Design](<./04_Factory & Resource System Design.md>) and [08_Research Tree Design](<./08_Research Tree Design.md>).

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

4. Power Poles¶

Power distribution is area-based, not port-based. Ports carry ITEM and FLUID only.

State	Placement	Unlock
Default	Ground-placed pole, standalone building	Available from start
Upgraded	Roof-mounted module on an existing building	Research-gated

Why this shape works: power poles are inherently placement-dependent, since coverage area is the whole point. Moving them onto roofs is a genuine spatial upgrade (reclaimed ground, tighter factories) rather than a stat bump. Other modules are not placement-dependent and need no equivalent.

Design note: the power module is deliberately not a required tax. If every building needed a power module, slot one would be spent identically every time and the real slot count would be one lower across the board. Ground poles keep base power free.

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

5. Status Display¶

Status is free on every building, not gated behind a module. An unmodded building must never be blind.

The Status module upgrades the readout, it does not enable it. Candidate upgrades: precise throughput figures, remote readout in the HUD without selecting the building, longer fault history.

Full visual specification in 07_Art Direction Style Bible §1.7.

5a. Upgrade Kits¶

Mk levels are not researched. Research unlocks recipes; a recipe may require a building at a given Mk to run it. Raising a building's Mk is a crafting and construction action, not a research one.

5a.1 Four items, universally applicable¶

Kit	Raises
Base Upgrade Kit Mk2	Any building's base, Mk1 → Mk2
Base Upgrade Kit Mk3	Any building's base, Mk2 → Mk3
Machine Upgrade Kit Mk2	Any building's machine, Mk1 → Mk2
Machine Upgrade Kit Mk3	Any building's machine, Mk2 → Mk3

Four items cover the entire upgrade economy across all ~47 buildings. This works because the base is a universal kit piece. Per-building upgrade recipes would mean roughly ninety-four recipes for the same result.

Produced by the Module Crafter, giving that building a second product line alongside modules.

5a.2 Application¶

Applied to an already placed building. Upgrades happen in place, never by deconstruct-and-rebuild.
In-place upgrade is what makes the same-mesh-plus-tabs approach work (07_Art Direction Style Bible §1.7). A Mk3 building is a Mk1 with more tabs, so there is nothing to rebuild.
Genesis applies the kit via the existing task queue: fetch kit from a Silo, travel, apply. New task type UPGRADE_BUILDING.

5a.3 An upgrade changes level and NOTHING else (RULE)¶

An upgrade is a property change, not a replacement. Everything configured on the building survives untouched.

Must be preserved across an upgrade:

Preserved	Why it is at risk
Installed modules	Machine Mk grants an extra slot; losing modules would mean progressing costs you what you already built
Port configuration — every port's mode, filter and buffer	A player may have set eight ports individually. Losing that is a serious punishment for upgrading.
Storage contents	Upgrading a Silo must not empty it
`StorageRole` (`UNASSIGNED` / `DEPOSIT` / `CONSTRUCTION`)	Genesis relies on this for construction supply
Queued or in-progress work	Mid-recipe state

Why this needs stating explicitly: an upgrade that changes a building's stats is easily implemented as tear-down-and-recreate. That is the natural shape in code, and it silently discards everything above unless someone wrote "carry these across". This is a specification requirement, not an implementation detail.

5a.4 Other defaults (confirm)¶

Question	Recommendation	Reasoning
Downtime during upgrade?	Brief. Building shows the manually-disabled ring state (grey-blue, steady) while Genesis works.	Reuses an existing status state, and makes upgrades visible in the world
Kit recoverable on downgrade?	Yes, or partial return.	Consistent with the no-punishment principle. Lets players experiment without fear.
Kit cost	Expensive. A major progression step, not a routine consumable.	Balance work

6. Interaction With Other Systems¶

System	Interaction
Ports (`23_Port System Design`)	Independent. Ports are on the base ring, modules on the roof. No competition for space.
Accent tab count (`07_Art Direction Style Bible` §1.7)	Machine Mk determines slot count, so the inner tab row signals capability, not just speed
Module Crafter	Already specified as the producer. Also produces the four Upgrade Kits (§5a). Recipes to be defined.
Genesis task queue	New task type `UPGRADE_BUILDING`: fetch kit from Silo, travel, apply in place
Research	Gates the roof-mounted power pole. Likely gates higher-value modules too.

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

8. Revision History¶

Version	Date	Changes
0.1	2026-08-25	Initial draft. Slot model, module types, power pole placement, status free-by-default.
0.2	2026-08-29	Repointed the two Mk-level readout references from the dropped emissive level ramp (`Style Bible` §1.6) to accent tab count (§1.7). The ramp was superseded when Mk moved to tab count; §1.6 now records it as dropped, so both references pointed at a section that contradicted them.