zfxaction26_2/docs/design.md

Reactor Maintenance Design

Concept

The player controls a maintenance robot inside a failing reactor facility. The game is a deterministic, turn-based systems puzzle about reading a visible machine, forecasting failure, and choosing between local stabilization and longer-term network control.

The simulation uses a small formal core:

• static floor and wall terrain
• underground fuel, coolant, and electricity networks
• surface props for controls, terminals, supplies, doors, and reactor activation
• reachable leaks that project hazards onto floor cells
• explicit reactor requirements bound to consumer props
• deterministic rule events and forecasts

The game should feel logical, tactical, readable, and systemic. It should avoid randomness, action pressure, and hidden information after the player earns the relevant diagnostic access.

Turn Structure

Each turn has three phases:

1. Player phase: the player spends the level action budget.
2. Simulation phase: networks, consumers, leaks, hazards, doors, robot safety, and level state resolve.
3. Event phase: rule events, remedy block durations, and heat immunity duration advance.

The simulation advances once after the player spends or ends the turn action budget. Individual player actions do not tick the simulation.

Goal And Failure

Each reactor starts offline. A reactor becomes ready when:

• its bound fuel consumer is enabled, supplied, and producing
• its bound coolant consumer is enabled, supplied, and producing
• its bound electricity consumer is enabled, supplied, and producing
• reactor heat is below the terminal condition

When a reactor is ready, the level shows REACTOR READY. The player wins by spending an action at that reactor control site.

The level is lost when:

• reactor heat reaches the terminal threshold
• the robot occupies an unsafe final hazard state without applicable protection
• a rule event marks terminal failure
• level-authored unrecoverable conditions are met

Consumer starvation blocks readiness but does not directly cause loss.

Information

The player can always inspect:

• surface terrain
• surface props and visible prop state
• visible leaks and repair faces
• visible surface hazards
• door state
• remedy inventory and supply props
• consumer state: disabled, starved, supplied, producing, or unknown
• level state
• forecasted warnings the simulation can prove

Underground topology and numeric network values are hidden until all-seeing-eye terminal access is unlocked. With access, the player can inspect underground fuel, coolant, and electricity topology, network structural state, carrier amount, pressure or voltage, and source-to-consumer connectivity.

The editor always sees and authors every layer.

Safe, caution, and critical labels are display and forecast bands derived from balance thresholds. Numeric simulation values remain authoritative.

Grid And State

Each map coordinate contains:

• one static surface terrain cell: Floor or Wall
• zero or one underground fuel cell
• zero or one underground coolant cell
• zero or one underground electricity cell
• zero or one surface prop
• visible hazard amounts on floor cells
• optionally the robot, only on a floor cell

Terrain is authored and does not change during play. Wall cells are not walkable and do not store surface hazards.

Underground cells use one structural state:

• Absent
• Intact
• Leaking

Underground cells store carrier amount plus pressure for fuel/coolant or voltage for electricity. Same-carrier underground cells connect by inferred cardinal adjacency.

Surface floor cells store:

• leaked fuel
• leaked coolant
• leaked electricity
• heat
• active elemental remedy blocks

Simulation values use C# float. Runtime values are clamped and retain full float precision. UI shows visible values rounded to one decimal plus the safe/caution/critical band.

Level State

The derived level states are:

• Stable: no terminal path is near and required systems are not deteriorating.
• Caution: required service is missing, a consumer is starved or disabled, a hazard is growing, or reactor heat is concerning.
• Critical: forecast predicts loss without near-term intervention, or reactor heat is close to terminal.
• Ready: a reactor can be activated.
• Lost: terminal failure has occurred.
• Won: a reactor has been activated successfully.

Props

Surface prop categories:

• flow prop
• consumer prop
• junction prop
• door prop
• all-seeing-eye terminal prop
• remedy supply prop
• reactor control prop

Props exist on floor cells. Props do not directly participate in the surface hazard pair table.

Flow Props

A flow prop is bound to fuel, coolant, or electricity. It can be Enabled or Disabled.

During network flow, an enabled flow prop injects source carrier amount and pressure or voltage into its connected underground network cell. A disabled flow prop injects nothing.

Consumer Props

A consumer prop is bound to fuel, coolant, or electricity. It can be Enabled or Disabled.

An enabled consumer derives one service state after network propagation:

• Supplied: enough carrier and pressure or voltage reaches the bound underground cell.
• Starved: supply predicates fail.
• Producing: the consumer was supplied this simulation step and emits service.

A disabled consumer consumes nothing, produces nothing, and cannot satisfy reactor readiness.

Reactor Control Props

A reactor control prop is the activation site for one reactor. Each reactor stores required consumer bindings by grid position:

• fuel consumer position
• coolant consumer position
• electricity consumer position

The level is invalid if any binding is missing, out of bounds, or points to the wrong prop type.

Junction Props

A junction prop must be on a floor cell whose coordinate has exactly one underground carrier. That carrier is the regulated network.

The engine infers incoming and outgoing branch directions from valid network topology and enabled source paths. A valid junction has one incoming branch and either two or three outgoing branches. Ambiguous junction flow is invalid. Ratio numbers are balance-defined weights that divide carrier amount and pressure or voltage. A zero-weight branch receives no intentional outflow.

The gameplay UI exposes a single junction tool and cycles through balance-defined ratio presets for the inferred outgoing branch count.

Doors

A door stores one edge between two adjacent floor cells. Door states are Open and Closed.

Closed doors block fuel, coolant, electricity, and heat propagation across their edge. They do not block robot movement, underground network flow, source feeding, consumer supply, or hazards already present on either side.

Terminals And Supplies

An all-seeing-eye terminal unlocks underground inspection for the level.

Remedy supply props are single-use pickups:

• FuelRemedySupply
• CoolantRemedySupply
• ElectricityRemedySupply
• HeatRemedySupply

Each supply provides one matching inventory item and then becomes depleted.

Leaks And Remedies

Each leak stores carrier type, underground coordinate, accessible floor coordinate, and repair state.

Fuel and coolant leaks:

• occur under floor cells
• use the same coordinate as their accessible floor coordinate
• can be repaired or remediated by the robot standing on that floor cell

Electricity leaks:

• occur in wall cells
• store exactly one adjacent floor cell as the emission face
• can be repaired or remediated from that floor cell
• emit only to that stored face

All leaks must have valid floor access. Repair changes the underground cell from Leaking to Intact and stops future injection. Repair does not clean existing surface hazards.

The robot carries remedial consumables with balance-defined inventory capacity:

• FuelNeutralizer
• CoolantNeutralizer
• ElectricityNeutralizer
• HeatShield

Element neutralizers remove the matching surface element from a target floor cell or reachable leak face, then apply a temporary same-element re-entry block. They do not remove other elements, reduce heat, or repair leaks.

Heat shield gives the robot heat immunity for a balance-defined number of movement steps. It does not remove heat, block heat propagation, or protect against fuel, coolant, or electricity hazards.

Player Actions

Player actions:

• MoveRobot: move to an adjacent floor cell.
• InteractProp: use the prop on the robot's current floor cell.
• InteractLeak: repair a reachable leak or apply a matching elemental remedy.
• ApplyHeatShield: activate a carried heat shield.
• ActivateReactor: activate a ready reactor at the current reactor control prop.
• EndTurn: forfeit remaining actions and run the simulation/event phases.

Each valid action costs one action unless balance or level data defines otherwise. Invalid actions report refusal and do not mutate gameplay state.

InteractProp covers flow toggles, consumer toggles, junction ratio changes, door toggles, terminal unlock, and remedy pickup.

Network Flow

Network flow runs independently for fuel, coolant, and electricity.

For each carrier:

1. Clear transient carrier amount and pressure or voltage.
2. Start from every enabled flow prop connected to that carrier.
3. Walk through connected intact and leaking underground cells.
4. Stop at absent cells and disconnected topology.
5. Apply distance falloff.
6. Apply valid junction ratio weights.
7. Assign each reached cell its best incoming carrier amount and best incoming pressure or voltage.
8. Clamp final values.

Multiple non-ambiguous source paths may reach the same non-junction cell; the cell uses the best carrier amount and best pressure or voltage. Junction ambiguity is a validation error.

A consumer is supplied when carrier amount, pressure or voltage, and connectivity predicates pass.

Surface Hazards

Leaking underground cells remain part of network propagation.

During leak injection:

• fuel leaks add leaked fuel to the accessible floor cell
• coolant leaks add leaked coolant to the accessible floor cell
• electricity leaks add leaked electricity to the stored floor emission face
• active matching remedy blocks prevent matching element entry

Injection magnitude is balance data and may depend on local carrier amount, pressure, or voltage.

After injection, the engine evaluates local interactions between leaked fuel, leaked coolant, leaked electricity, and heat on the same floor cell and across unblocked adjacent floor cells.

Hazard Bands And Pair Table

Balance thresholds project numeric values into safe, caution, and critical bands:

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

The pair table maps projected bands to deterministic effects:

• Hold: no direct change. The pair table maps projected bands to parameterized verbs:

• Hold: no direct change.

• Flow(amount): equalize a surface quantity by a balance-defined transfer amount.

• Warm(amount): increase heat by a balance-defined amount.

• Quench(amount): reduce heat by a balance-defined amount.

• Short(heat, discharge): add heat and discharge electricity by balance-defined amounts.

• Ignite(heat, fuel): add heat and consume fuel by balance-defined amounts.

Row\Col	FuelSafe	FuelCaution	FuelCritical	CoolantSafe	CoolantCaution	CoolantCritical	ElectricitySafe	ElectricityCaution	ElectricityCritical	HeatSafe	HeatCaution	HeatCritical
FuelSafe	Hold	Flow	Flow	Hold	Hold	Hold	Hold	Warm	Ignite	Hold	Warm	Ignite
FuelCaution		Hold	Flow	Hold	Hold	Hold	Warm	Ignite	Ignite	Warm	Ignite	Ignite
FuelCritical			Hold	Hold	Hold	Hold	Ignite	Ignite	Ignite	Ignite	Ignite	Ignite
CoolantSafe				Hold	Flow	Flow	Hold	Short	Short	Hold	Quench	Quench
CoolantCaution					Hold	Flow	Short	Short	Short	Hold	Quench	Quench
CoolantCritical						Hold	Short	Short	Short	Hold	Quench	Quench
ElectricitySafe							Hold	Flow	Flow	Hold	Hold	Hold
ElectricityCaution								Hold	Flow	Hold	Hold	Hold
ElectricityCritical									Hold	Hold	Hold	Hold
HeatSafe										Hold	Flow	Flow
HeatCaution											Hold	Flow
HeatCritical												Hold

Design rules:

• fuel becomes dangerous through electricity or heat
• coolant becomes dangerous through electricity
• coolant opposes heat
• heat equalizes between neighboring floor cells
• same-carrier leaked surface amounts equalize between neighboring floor cells
• doors and remedy blocks gate local interactions

Rule Events

Rule events are deterministic and forecastable. Each event stores enabled state, once/repeat behavior, priority, predicates, effects, and optional forecast text. All predicates must pass for the event to trigger.

Predicate families:

• turn comparisons
• level state comparisons
• reactor readiness/loss/win comparisons
• prop type or state at position
• consumer service state at position
• network value band at position
• surface hazard band at position
• robot position or inventory condition
• all-seeing-eye unlocked state

Effects:

• start a valid leak
• worsen an existing leak
• repair or disable a network cell
• enable or disable a prop
• add or remove surface hazard
• add or remove heat
• add or remove inventory
• mark terminal loss
• emit warning text

Simulation Order

One completed turn resolves in this order:

1. Apply accepted player actions.
2. Validate runtime state.
3. Apply matching start-of-simulation rule events.
4. Propagate underground networks.
5. Resolve consumers and service production.
6. Inject leaks.
7. Evaluate same-cell surface interactions.
8. Evaluate adjacent floor interactions across unblocked edges.
9. Accumulate and apply deltas in deterministic priority order.
10. Clamp values.
11. Resolve robot safety.
12. Derive reactor readiness and level state.
13. Apply matching end-of-turn rule events.
14. Advance remedy blocks and heat immunity.
15. Refresh forecasts.

If multiple events modify the same value in one step, deltas accumulate and then clamp. Event priority may consume, reserve, or block a value first.

Forecasts

Forecasts are deterministic simulations over copied state. Forecasting does not mutate the actual level.

Forecast output includes:

• terminal loss forecasts
• reactor ready forecasts
• starved required consumer warnings
• growing hazard warnings when values cross caution or critical bands
• rule event warnings when predicates can be proven within the forecast horizon

The forecast horizon is balance data.

Validation

The editor blocks run and save when validation errors exist. Warnings are visible and non-blocking.

Validation errors:

• invalid dimensions or cell counts
• robot out of bounds or not on floor
• wall cell with surface hazards
• prop on invalid terrain
• missing or invalid reactor consumer binding
• invalid door edge
• invalid leak access
• invalid rule target
• junction without exactly one underground carrier
• ambiguous junction flow
• network loop or equal-source ambiguity at a junction
• malformed required data

Validation warnings:

• unreachable non-required consumer
• underground cell with no source path
• initially starved required consumer
• initially unready reactor
• unused remedy supply
• visible hazard with no detectable nearby remedy or route

Editor And Schema

The editor authors:

• surface terrain
• underground fuel, coolant, and electricity cells
• flow props and consumer props
• reactor controls and reactor consumer bindings
• junction props and balance-defined ratio mode index
• door props and door edges
• all-seeing-eye terminals
• remedy supplies
• floor leaks and electricity wall leaks
• initial surface hazards and heat
• robot start position
• rule events

The serialized level schema stores level metadata, dimensions, terrain, underground layers, props and prop state, reactor bindings, leaks, doors, robot state, inventory, rule events, all-seeing-eye state, and dynamic state when saving active play.

The loader accepts only schema-valid level data and returns clear errors for malformed data.

Balancing And Tests

Balancing defines source strengths, falloff, ratio math, consumer predicates, leak magnitudes, interaction magnitudes, display thresholds, robot safety thresholds, terminal heat thresholds, inventory capacity, remedy duration, heat immunity duration, action costs, and forecast horizon.

Tests assert behavior against configured balance values and bands. Coverage includes validation, inferred connectivity, junction effects, consumer states, reactor readiness and activation, terminal loss, robot hazard loss, heat immunity, leak access, remedies, door blocking, rule events, forecasts, and serialization round trips.