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.