zfxaction26_2/docs/design.md

Game Design: Reactor Maintenance

Core Concept

The player controls a maintenance robot inside a failing reactor facility.

The game is a deterministic, turn-based systems puzzle. The player studies a visible machine, predicts its failures, and chooses which systems to stabilize first.

The revised simulation model is intentionally narrow:

• a surface grid
• an underground fuel network
• an underground coolant network
• an underground electricity network
• surface props that connect vertically into exactly one underground network
• a reactor that must be supplied and kept cool
• a diagnostic UI that exposes the current state and the next predicted changes

Each turn has three phases:

1. Player phase: the player spends a limited number of actions.
2. Simulation phase: local network, leak, and heat rules are resolved deterministically.
3. Event phase: scheduled failures or scripted level events advance.

The main fantasy is:

"I understand this machine well enough to prevent the next disaster."

The game should feel:

• logical
• tactical
• deterministic
• readable
• systemic

It should not feel:

• hectic
• random
• action-heavy
• dependent on hidden information

Goal

The reactor starts offline.

To win a level, the player must:

• restore electricity delivery to the required consumers
• restore coolant delivery to the reactor path
• restore fuel delivery to the required fuel consumer
• reach a stable enough state to activate the reactor

When all required systems are ready, the game shows:

REACTOR READY

The player can then spend an action at the reactor control site to activate the core and win.

Loss Conditions

The player loses if the level reaches a clearly predicted terminal state.

Primary loss conditions:

• reactor overheating reaches terminal heat
• required consumers remain starved long enough to force shutdown
• cascading heat makes the level irrecoverable

Failure should not be instant unless the player knowingly allows a predicted critical state to mature.

Turn Structure

1. Player Phase

The player has a fixed number of actions per turn, usually 3.

Possible actions:

• move
• interact with a flow prop
• interact with a consumer prop
• repair a leaking network cell
• inspect a cell or prop
• activate the reactor

2. Simulation Phase

The facility updates all active systems.

Examples:

• outside connections feed enabled networks
• enabled consumers draw from their bound network
• leaking underground cells emit their element into the surface cell above them
• neighboring surface cells exchange leaked matter or heat through deterministic lookup rules
• coolant reduces heat
• electricity interacting with coolant or fuel raises heat

3. Event Phase

Predicted events advance by one turn.

Examples:

• a leak worsens
• a consumer disables itself after starvation
• a scripted level event adds heat or disables a prop

Events are not hidden. The player sees upcoming failures before they happen.

Information Design

All relevant information is visible and predictable.

The player can see:

• the state of each underground network cell: absent, intact, or leaking
• the local amount band of leaked fuel, coolant, and electricity
• the local heat band
• whether each surface prop is enabled or disabled
• which consumer is currently starved
• the current global level state
• scheduled upcoming events

The question is not:

"What is behind the corner?"

It is:

"What happens if I let this pair of cells interact for one more turn?"

Simulation Model

Layered Grid

Each map coordinate contains:

• one surface cell
• zero or one fuel network cell underground
• zero or one coolant network cell underground
• zero or one electricity network cell underground
• zero or one surface prop
• optionally the robot

The three underground networks are disjunct. They do not share edges and do not directly interact underground.

Each network has:

• its own outside-of-level connection
• exactly one flow prop type on the surface
• exactly one consumer prop type on the surface

The surface prop is an abstract vertical connection to one underground cell.

Network Semantics

The three network families are intentionally symmetric.

• Fuel: used by its consumer, dangerous when leaked next to electricity or high heat.
• Coolant: used by its consumer, safe by itself, lowers heat, dangerous when leaked next to electricity.
• Electricity: used by its consumer, safe by itself, dangerous when leaked next to coolant or fuel.

Each underground network cell has only three structural states:

• Absent
• Intact
• Leaking

Each element amount uses the same three thresholds:

• Safe = 0-9
• Caution = 10-19
• Critical = 20-29

Heat uses the same thresholds:

• HeatSafe = 0-9
• HeatCaution = 10-19
• HeatCritical = 20-29

Why This Formalization

This model keeps the simulation small enough for a table lookup:

• network topology is stored underground
• leaked matter and heat are projected onto the surface
• only the projected surface bands participate in the lookup matrix
• props, robot, and global level state modify or consume those projected bands before or after the matrix pass

State Inventory

Cell State

Surface cell states:

• Open
• Blocked
• HeatSafe
• HeatCaution
• HeatCritical

Underground network states, repeated for fuel, coolant, and electricity:

• Absent
• Intact
• Leaking
• Safe
• Caution
• Critical

Notes:

• Absent / Intact / Leaking describe the underground cell itself.
• Safe / Caution / Critical describe the local amount currently present in that layer or leaked onto the surface.
• A leaking underground cell injects its element into the surface cell above it during simulation.

Prop State

Each network has exactly two prop types on the surface:

• flow prop
• consumer prop

Each prop has exactly two states:

• Enabled
• Disabled

Concrete prop states:

• FuelFlowEnabled
• FuelFlowDisabled
• FuelConsumerEnabled
• FuelConsumerDisabled
• CoolantFlowEnabled
• CoolantFlowDisabled
• CoolantConsumerEnabled
• CoolantConsumerDisabled
• ElectricityFlowEnabled
• ElectricityFlowDisabled
• ElectricityConsumerEnabled
• ElectricityConsumerDisabled

Level State

The whole level has exactly five states:

• Stable
• Caution
• Critical
• Ready
• Lost

Meaning:

• Stable: all required consumers are fed and no terminal heat path is active.
• Caution: one or more required systems are degrading but recovery remains straightforward.
• Critical: the simulation predicts a loss without near-term intervention.
• Ready: the reactor activation prerequisites are met.
• Lost: terminal failure has already occurred.

Robot State

The robot has exactly four states:

• Ready
• Interacting
• Blocked
• Damaged

Meaning:

• Ready: free to move and act.
• Interacting: currently spending an action on a prop or repair.
• Blocked: the target move is refused because the destination is blocked or too hazardous.
• Damaged: the robot entered or remained in an unresolved hazardous cell.

Events That Modify State

Cell And Network Events

• CreateCellBlock: changes a surface cell from Open to Blocked.
• ClearCellBlock: changes a surface cell from Blocked to Open.
• StartLeak[n]: changes an underground network cell from Intact to Leaking.
• RepairLeak[n]: changes an underground network cell from Leaking to Intact.
• InjectLeak[n]: adds one band of leaked element from a leaking underground cell into the surface cell above.
• Equalize[n]: transfers one band of the same element from the higher local band to the lower local band between neighboring cells.
• HeatTransfer: transfers one heat band from the hotter cell to the cooler cell.
• HeatUp[1]: increases local heat by 1 band-equivalent.
• HeatUp[2]: increases local heat by 2 band-equivalents.
• CoolDown[1]: decreases local heat by 1 band-equivalent.
• CoolDown[2]: decreases local heat by 2 band-equivalents.
• Short[1]: electricity and coolant interact, raising heat and discharging electricity.
• Short[2]: a stronger version of Short[1].
• Ignite[1]: fuel and electricity or fuel and heat interact, raising heat in both participating cells.
• Ignite[2]: a stronger version of Ignite[1].
• ClampBand: clamps all element and heat values back into 0-29.

[n] means one of the three carriers: fuel, coolant, or electricity.

Prop Events

• EnableFlow[n]: changes a flow prop from Disabled to Enabled.
• DisableFlow[n]: changes a flow prop from Enabled to Disabled.
• EnableConsumer[n]: changes a consumer prop from Disabled to Enabled.
• DisableConsumer[n]: changes a consumer prop from Enabled to Disabled.
• FeedFromOutside[n]: an enabled flow prop pulls supply from the level boundary into its bound network.
• ConsumeFromNetwork[n]: an enabled consumer removes one band from its bound network and emits its intended service.
• StarveConsumer[n]: a consumer receives too little supply and degrades the level state.

Level Events

• EscalateLevel: Stable -> Caution -> Critical, and Ready -> Caution if readiness is lost.
• RecoverLevel: Critical -> Caution -> Stable.
• MarkReady: Stable or Caution becomes Ready when all activation prerequisites are satisfied.
• LoseLevel: Critical or Ready becomes Lost when a terminal rule fires.

Robot Events

• MoveRobot: moves the robot into a valid neighboring open cell.
• StartInteraction: changes Ready -> Interacting.
• FinishInteraction: changes Interacting -> Ready.
• BlockRobot: changes Ready -> Blocked for the attempted move or action.
• DamageRobot: changes Ready or Blocked -> Damaged.
• RecoverRobot: changes Blocked -> Ready after the blocking condition is removed.

Projection Into The Lookup Matrix

Not every stored state belongs in the pairwise neighbor table.

The pairwise table only operates on projected surface fields:

• FuelSafe
• FuelCaution
• FuelCritical
• CoolantSafe
• CoolantCaution
• CoolantCritical
• ElectricitySafe
• ElectricityCaution
• ElectricityCritical
• HeatSafe
• HeatCaution
• HeatCritical

Projection rules:

• within a single cell, unordered pairs of projected field states use the same lookup table as neighboring cells
• Blocked cells do not participate in neighbor lookup across that edge.
• Leaking underground cells first emit their carrier into the surface cell above them through InjectLeak[n].
• flow props and consumers act before the neighbor lookup, because they modify underground supply
• level state is derived after the lookup, because it is global rather than local
• robot state is resolved after the lookup, because it reacts to the final local hazard state of its cell

This keeps the spatial interaction system small while still identifying the full set of cell, prop, level, and robot states.

Simulation Order

The revised simulation loop for one turn is:

1. Resolve player actions.
2. Apply FeedFromOutside[n] for every enabled flow prop.
3. Apply ConsumeFromNetwork[n] or StarveConsumer[n] for every enabled consumer.
4. Apply InjectLeak[n] for every leaking underground cell.
5. For every open cell, evaluate every unordered pair of projected field states inside that same cell.
6. For every open cell, evaluate the current cell against its right neighbor and bottom neighbor.
7. For each pair, read the projected field-state table below and emit the listed event.
8. Apply all emitted deltas.
9. Clamp all values with ClampBand.
10. Update robot state from the final local surface cell it occupies.
11. Derive level state from required consumers, reactor prerequisites, and terminal heat conditions.
12. Advance scheduled turn events.

Pair Lookup Event Legend

The symmetric lookup matrix uses the following event names:

• Hold: no direct change.
• FuelFlow: apply Equalize[Fuel].
• CoolFlow: apply Equalize[Coolant].
• ChargeFlow: apply Equalize[Electricity].
• HeatFlow: apply HeatTransfer by 1 band.
• HeatFlow2: apply HeatTransfer by 2 bands.
• Warm1: apply HeatUp[1] to the fuel-owning side.
• Warm2: apply HeatUp[2] to the fuel-owning side.
• Quench1: apply CoolDown[1] to the heat-owning side.
• Quench2: apply CoolDown[2] to the heat-owning side.
• Short1: apply Short[1].
• Short2: apply Short[2].
• Ignite1: apply Ignite[1].
• Ignite2: apply Ignite[2].

Design intent:

• fuel only becomes dangerous through electricity or heat
• coolant only becomes dangerous through electricity
• coolant opposes heat
• heat equalizes between neighboring cells
• same-carrier amounts equalize between neighboring cells

Symmetric Pair Lookup Table

Rows and columns are identical projected field states. Only the upper-right triangle is filled. The lower-left triangle is intentionally empty because the table is symmetric.

Row\Col	FuelSafe	FuelCaution	FuelCritical	CoolantSafe	CoolantCaution	CoolantCritical	ElectricitySafe	ElectricityCaution	ElectricityCritical	HeatSafe	HeatCaution	HeatCritical
FuelSafe	Hold	FuelFlow	FuelFlow	Hold	Hold	Hold	Hold	Warm1	Warm2	Hold	Warm1	Warm2
FuelCaution		Hold	FuelFlow	Hold	Hold	Hold	Warm1	Ignite1	Ignite2	Warm1	Ignite1	Ignite2
FuelCritical			Hold	Hold	Hold	Hold	Warm2	Ignite2	Ignite2	Warm2	Ignite2	Ignite2
CoolantSafe				Hold	CoolFlow	CoolFlow	Hold	Short1	Short2	Hold	Quench1	Quench1
CoolantCaution					Hold	CoolFlow	Short1	Short1	Short2	Hold	Quench1	Quench2
CoolantCritical						Hold	Short2	Short2	Short2	Hold	Quench2	Quench2
ElectricitySafe							Hold	ChargeFlow	ChargeFlow	Hold	Hold	Hold
ElectricityCaution								Hold	ChargeFlow	Hold	Hold	Hold
ElectricityCritical									Hold	Hold	Hold	Hold
HeatSafe										Hold	HeatFlow	HeatFlow2
HeatCaution											Hold	HeatFlow
HeatCritical												Hold

Prop Rules

Props do not appear in the neighbor table. They are local vertical controls on top of the underground layers.

Flow prop rule:

• if enabled, the prop allows FeedFromOutside[n] or onward transport through its bound network
• if disabled, its bound network path is isolated at that cell

Consumer prop rule:

• if enabled and supplied, it consumes one band and produces its service
• if enabled and unsupplied, it triggers StarveConsumer[n]
• if disabled, it neither consumes nor produces

Required consumer mapping:

• Fuel consumer: required for reactor fuel path
• Coolant consumer: required for reactor cooling path
• Electricity consumer: required for reactor activation path

Robot Rules

The robot is intentionally simple.

• The robot moves only on the surface.
• The robot can occupy only Open cells.
• A move into a cell that resolves to HeatCritical changes the robot to Damaged.
• A move into a blocked or forbidden cell changes the robot to Blocked.
• Interacting with a prop or repairing a leak changes the robot to Interacting until the action resolves.

Level Rules

Level state is derived, not spatially diffused.

Suggested derivation:

• Stable: all required consumers supplied and no reactor-adjacent HeatCritical
• Caution: at least one required consumer is unstable or one reactor-adjacent cell is HeatCaution
• Critical: any required consumer is starved for too long or any reactor-adjacent cell is HeatCritical
• Ready: all required consumers supplied and the reactor area is not HeatCritical
• Lost: a scripted terminal rule or unrecoverable reactor heat condition fires

Design Pillars

Deterministic Systems

The same actions in the same state always produce the same result.

Visible Consequences

The player sees both the local field bands and the global state they imply.

Meaningful Tradeoffs

Turning one network on may feed a required consumer while making a leak more dangerous.

Small Formal Core

The simulation should be explainable as:

• underground network structure
• surface leaks
• one shared threshold system
• one pairwise lookup table

Extensible Later

The current code and earlier design are treated as a prototype. This reduced model is the new formal core. More mechanics can be added later only if they preserve table-driven readability.

Summary

The revised design reduces the simulation to a small layered system:

• three disjunct underground networks
• two prop types per network
• one shared threshold model
• one projected surface interaction table
• one derived global level state

That gives a solid basis for a deterministic simulation that can be visualized, forecast, and extended without reintroducing hidden complexity.