xTr1m/zfxaction26_2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Condense reactor design spec

Browse Source
This commit is contained in:
Frank Tovar
2026-05-10 14:33:09 +02:00
parent 071e6a1d48
commit 79f3219a72
1 changed files with 183 additions and 492 deletions
Download Patch File Download Diff File Expand all files Collapse all files

675
docs/design.md
View File

@@ -1,224 +1,112 @@
# Reactor Maintenance V1 Design
# Reactor Maintenance Design
## Status
## Concept
This document is the authoritative v1 design for Reactor Maintenance.
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 earlier prototype simulation, editor tools, save files, effects, tests, and terminology are not compatibility targets. V1 is a clean replacement. Serialization version `1` belongs to this design. Prototype-shaped JSON must be rejected with a clear unsupported-format or invalid-level error; no migration is required.
The simulation uses a small formal core:
## Core Concept
- 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 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 between short-term on-site stabilization and longer-term network control.
The simulation model is intentionally narrow:
- a static surface grid of walkable floor cells and blocked wall cells
- an underground fuel network
- an underground coolant network
- an underground electricity network
- surface props that expose controls, terminals, supplies, doors, and repair access
- leaks that are always reachable by the robot from a floor cell
- one or more reactors with explicitly bound required consumers
- a diagnostic UI that exposes visible state, forecasts, and all underground layers only after all-seeing-eye terminal access
The main fantasy is:
> "I understand this machine well enough to prevent the next disaster."
The game should feel logical, tactical, deterministic, readable, and systemic. It should not feel hectic, random, action-heavy, or dependent on hidden information after the correct inspection tool is acquired.
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 gameplay turn has three phases:
Each turn has three phases:
1. Player phase: the player spends the level's action budget.
2. Simulation phase: network flow, consumers, leaks, local hazards, doors, robot safety, and level state resolve deterministically.
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's action budget. Individual player actions do not tick the simulation.
The simulation advances once after the player spends or ends the turn action budget. Individual player actions do not tick the simulation.
## Goal
## Goal And Failure
Each reactor starts offline.
Each reactor starts offline. A reactor becomes ready when:
To win a level, the player must:
- 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
- restore fuel delivery to the reactor's bound fuel consumer
- restore coolant delivery to the reactor's bound coolant consumer
- restore electricity delivery to the reactor's bound electricity consumer
- keep the reactor area below the terminal heat condition
- reach the reactor control site and activate the core
When a reactor is ready, the level shows `REACTOR READY`. The player wins by spending an action at that reactor control site.
When every bound required consumer is enabled, supplied, and producing service, and no terminal reactor condition is active, the level shows:
The level is lost when:
> REACTOR READY
- 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
The player can then spend an action at the reactor control site to activate the core and win.
Consumer starvation blocks readiness but does not directly cause loss.
## Loss Conditions
## Information
The player loses if the level reaches a clearly predicted terminal state.
The player can always inspect:
Primary loss conditions:
- reactor overheating reaches the terminal heat threshold
- the robot occupies a hazardous final cell state without applicable protection
- a rule event resolves to terminal failure
- cascading hazards make the level explicitly unrecoverable according to level-authored rules
Required consumer starvation does not directly cause loss. A starved or disabled required consumer prevents `Ready`, but failure still comes from terminal heat, robot loss, rule terminal events, or other explicit terminal rules.
Failure should not be instant unless the player knowingly allows a predicted critical state to mature or moves the robot into an unsafe final hazard state.
## Information Design
All surface information is visible and predictable. Underground information is controlled by terminal access during gameplay.
The player can always see:
- floor and wall terrain
- surface props and their visible states
- visible leaks and their reachable repair faces
- visible surface hazards on floor cells
- door open or closed state
- surface terrain
- surface props and visible prop state
- visible leaks and repair faces
- visible surface hazards
- door state
- remedy inventory and supply props
- whether each consumer is producing, starved, disabled, or unknown
- current level state
- scheduled and rule-based upcoming warnings that the forecast can prove
- consumer state: disabled, starved, supplied, producing, or unknown
- level state
- forecasted warnings the simulation can prove
Before all-seeing-eye access, the player cannot freely inspect underground layers. Underground causes may be inferred from visible leaks, prop state, and forecasts, but exact underground topology and numeric network values are hidden.
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.
After interacting with an all-seeing-eye terminal prop, the player can inspect all underground layers:
The editor always sees and authors every layer.
- underground fuel, coolant, and electricity topology
- structural state of each underground network cell
- carrier amount
- pressure for fuel and coolant
- voltage for electricity
- source-to-consumer connectivity
Safe, caution, and critical labels are display and forecast bands derived from balance thresholds. Numeric simulation values remain authoritative.
The editor is not gated by all-seeing-eye access. It always sees and authors every layer.
Safe, caution, and critical labels are UI and forecast labels derived from balance thresholds. They are not stored as authoritative simulation state.
## Layered Grid
## Grid And State
Each map coordinate contains:
- one static surface terrain cell: `Floor` or `Wall`
- zero or one fuel network cell underground
- zero or one coolant network cell underground
- zero or one electricity network cell underground
- zero or one underground fuel cell
- zero or one underground coolant cell
- zero or one underground electricity cell
- zero or one surface prop
- zero or more visible hazard amounts on floor cells
- visible hazard amounts on floor cells
- optionally the robot, only on a floor cell
Cells cannot change between floor and wall during gameplay. Terrain is level-authored and static.
Terrain is authored and does not change during play. Wall cells are not walkable and do not store surface hazards.
The three underground networks are disjunct. They do not share edges and do not directly interact underground.
Same-carrier underground cells connect by inferred cardinal adjacency. There are no per-edge connection flags in v1. The validator rejects topology that cannot produce unambiguous source-to-consumer and source-to-junction flow.
Each network has:
- one or more outside-of-level source connections exposed through flow props
- zero or more consumer props
- optional T-junction props on surface floor cells
- optional cross-junction props on surface floor cells
## Numeric Model
Simulation values use C# `float`.
Runtime values are not rounded internally. Balance constants define minimum and maximum clamps. The UI rounds visible numeric values to one decimal place and displays the corresponding safe/caution/critical band.
Tests should not assert arbitrary exact float values. Tests assert:
- safe/caution/critical bands
- readiness and loss transitions
- validation outcomes
- connectivity outcomes
- monotonic direction of numeric effects
- exact values only for isolated formulas where the formula itself is the behavior under test
## State Inventory
### Surface Terrain
Surface terrain states:
- `Floor`: walkable, can hold the robot, props, visible hazards, fuel/coolant leaks, and repair access to electricity wall leaks.
- `Wall`: not walkable, can hold wall-routed underground cells and electricity wall leaks.
Wall cells do not store surface hazard amounts.
### Underground Network Cells
Each underground network cell has one carrier family:
- `Fuel`
- `Coolant`
- `Electricity`
Each underground network cell has one structural state:
Underground cells use one structural state:
- `Absent`
- `Intact`
- `Leaking`
Each underground network cell stores:
Underground cells store carrier amount plus pressure for fuel/coolant or voltage for electricity. Same-carrier underground cells connect by inferred cardinal adjacency.
- carrier amount
- pressure for fuel and coolant
- voltage for electricity
Surface floor cells store:
Fuel and coolant use pressure. Electricity uses voltage. Fields that do not apply to the carrier are ignored by simulation and should not be shown as meaningful UI values.
### Surface Hazards
Each floor cell stores:
- leaked fuel amount
- leaked coolant amount
- leaked electricity amount
- heat amount
- leaked fuel
- leaked coolant
- leaked electricity
- heat
- active elemental remedy blocks
There is no v1 smoke, fire, pressure-pipe, cell-integrity, or facility-stability system.
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.
### Robot
## Level State
The robot stores:
The derived level states are:
- current floor position
- carried remedial consumables
- active heat-immunity duration
Robot damage is not a recoverable v1 state. If the robot occupies a cell whose final hazard values exceed safety predicates and no applicable protection is active, the level is lost.
### Level State
The whole level has these states:
- `Stable`
- `Caution`
- `Critical`
- `Ready`
- `Lost`
- `Won`
Meaning:
- `Stable`: no terminal path is near and required systems are not actively deteriorating.
- `Caution`: a required service is missing, a consumer is starved or disabled, a hazard is growing, or reactor heat is concerning.
- `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's bound required consumers are producing and reactor conditions allow activation.
- `Ready`: a reactor can be activated.
- `Lost`: terminal failure has occurred.
- `Won`: the reactor has been activated successfully.
Level state is derived after each simulation step and after successful activation.
- `Won`: a reactor has been activated successfully.
## Props
@@ -233,66 +121,41 @@ Surface prop categories:
- remedy supply prop
- reactor control prop
Props exist on floor cells unless the prop type explicitly stores a wall-facing repair/emission relationship. Props do not participate directly in the local hazard pair condition table.
Props exist on floor cells. Props do not directly participate in the surface hazard pair table.
### Flow Props
A flow prop is bound to exactly one carrier family:
A flow prop is bound to fuel, coolant, or electricity. It can be `Enabled` or `Disabled`.
- fuel flow prop
- coolant flow prop
- electricity flow prop
Flow props have two states:
- `Enabled`
- `Disabled`
During network flow, an enabled flow prop injects source carrier amount and pressure or voltage into its connected underground network cell. The injected values are balance constants. A disabled flow prop injects nothing and isolates its bound source from outside supply.
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 exactly one carrier family:
A consumer prop is bound to fuel, coolant, or electricity. It can be `Enabled` or `Disabled`.
- fuel consumer
- coolant consumer
- electricity consumer
An enabled consumer derives one service state after network propagation:
Consumer props have two player-controlled states:
- `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.
- `Enabled`
- `Disabled`
Each consumer derives one current service state:
- `Disabled`: prop is off, consumes nothing, produces no service, and does not starve.
- `Supplied`: prop is enabled and receives enough carrier amount plus pressure or voltage.
- `Starved`: prop is enabled but receives too little carrier amount, pressure, or voltage.
- `Producing`: prop was supplied this simulation step and its required service is active.
`Supplied` is the input condition. `Producing` is the output condition used by reactor readiness.
If enabled and supplied, the consumer removes or reserves demand and produces service for the turn. If enabled and unsupplied, it emits a visible starvation warning and blocks readiness. If disabled, it cannot satisfy readiness.
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.
A reactor control prop is the activation site for one reactor. Each reactor stores required consumer bindings by grid position:
Each reactor stores required consumer bindings by grid position:
- fuel consumer position
- coolant consumer position
- electricity consumer position
- required fuel consumer position
- required coolant consumer position
- required electricity consumer position
The level is invalid if any binding is missing, out of bounds, not a floor prop, or points to a consumer of the wrong carrier family.
The level is invalid if any binding is missing, out of bounds, or points to the wrong prop type.
### Junction Props
Junction props regulate flow after it leaves a source.
A junction prop must be on a floor cell whose coordinate has exactly one underground carrier. That carrier is the regulated network.
A junction prop must be placed on a floor cell whose coordinate has an underground network cell for exactly one carrier family. That network cell defines the carrier regulated by the junction.
T-junction props split one incoming path into two outgoing branches. Allowed modes:
T-junction modes:
- `0/4`
- `1/3`
@@ -300,202 +163,125 @@ T-junction props split one incoming path into two outgoing branches. Allowed mod
- `3/1`
- `4/0`
Cross-junction props split one incoming path into three outgoing branches. Allowed modes:
Cross-junction modes:
- `0/3/3`
- `3/0/3`
- `3/3/0`
- `2/2/2`
The engine auto-infers incoming and outgoing branch directions from valid network topology and enabled source paths. The editor and engine must reject maps where a junction's incoming direction or outgoing branches are ambiguous.
The engine infers incoming and outgoing branch directions from valid network topology and enabled source paths. Ambiguous junction flow is invalid. Ratio numbers are weights that divide carrier amount and pressure or voltage by balance-defined math. A zero-weight branch receives no intentional outflow.
Ratio numbers are weights. They divide available carrier amount and pressure or voltage according to balance-defined ratio math. A zero-weight branch receives no intentional outflow from that junction.
The gameplay UI exposes ratio modes.
The gameplay UI exposes ratio modes. It does not need to label live downstream effects in v1.
### Doors
### Door Props
A door stores one edge between two adjacent floor cells. Door states are `Open` and `Closed`.
Door props have two states:
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.
- `Open`
- `Closed`
### Terminals And Supplies
Each door stores one authored propagation edge between two adjacent floor cells. When open, surface fuel, coolant, electricity, and heat may propagate across that edge. When closed, those hazards do not propagate across that edge.
An all-seeing-eye terminal unlocks underground inspection for the level.
Closed doors do not:
- block robot movement
- block underground network flow
- block source feeding
- block consumer supply
- extinguish hazards already present on either side
The level is invalid if a door edge is missing, non-adjacent, out of bounds, or does not connect two floor cells.
### All-Seeing-Eye Terminal Props
All-seeing-eye terminal props have two player states:
- `Locked`: underground layer inspection is unavailable.
- `Unlocked`: interacting with the terminal has enabled all underground layer inspection for the level.
No other action or prop grants full underground inspection.
### Remedy Supply Props
Remedy supply props are single-use typed pickups:
Remedy supply props are single-use pickups:
- `FuelRemedySupply`
- `CoolantRemedySupply`
- `ElectricityRemedySupply`
- `HeatRemedySupply`
Each supply prop provides one fixed remedy type once. After pickup it becomes depleted.
Each supply provides one matching inventory item and then becomes depleted.
## Leaks
## Leaks And Remedies
Each leak stores:
Each leak stores carrier type, underground coordinate, accessible floor coordinate, and repair state.
- carrier type
- underground coordinate
- accessible floor coordinate
- current repair state
Fuel and coolant leaks:
Fuel and coolant leak rules:
- may only occur when the underground leak coordinate is under a floor cell
- 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 leak rules:
Electricity leaks:
- may only occur when the underground leak coordinate is in a wall cell
- must store exactly one adjacent floor cell as its accessible emission face
- can be repaired or remediated by the robot from the chosen floor cell
- emits only to the stored floor face
- 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 authored and rule-created leaks must have valid floor access. Invalid leaks are validation errors for authored state and rejected events at runtime.
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.
A repaired leak changes the underground network cell from `Leaking` to `Intact` and stops future injection. Repairing does not clean existing surface hazards.
## Remedies
The robot has a small inventory for remedial consumables. Inventory capacity is balance data.
Remedy types:
The robot carries remedial consumables with balance-defined inventory capacity:
- `FuelNeutralizer`
- `CoolantNeutralizer`
- `ElectricityNeutralizer`
- `HeatShield`
Element neutralizers:
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.
- are consumed when applied to a target floor cell or reachable leak face
- remove the current matching surface element from that target
- apply a temporary block preventing that same element from re-entering the target
- do not remove or block any other element
- do not reduce heat
- do not repair the underlying leak
Heat shield:
- is consumed when activated by the robot
- makes the robot immune to heat damage for a balance-defined number of robot movement steps
- does not reduce heat
- does not block heat propagation
- does not protect against fuel, coolant, or electricity hazards
Mixed hazards require multiple remedies. A floor cell containing fuel, electricity, and heat requires a fuel neutralizer, an electricity neutralizer, and heat immunity or another heat-management solution to be locally safe.
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
Each player action costs one action unless balance or level data explicitly says otherwise.
Player actions:
- `MoveRobot`: move to an adjacent floor cell.
- `InteractProp`: interact with the prop on the robot's current floor cell.
- `InteractLeak`: repair a reachable leak or apply a matching carried elemental remedy.
- `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 reactor at the current reactor control prop.
- `ActivateReactor`: activate a ready reactor at the current reactor control prop.
- `EndTurn`: forfeit remaining actions and run the simulation/event phases.
Invalid actions do not mutate gameplay state except for reporting a refused action. Invalid actions do not spend an action unless a future balance rule explicitly says otherwise.
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:
- enabling or disabling flow props
- enabling or disabling consumer props
- cycling or selecting T-junction ratio modes
- cycling or selecting cross-junction ratio modes
- opening or closing doors
- unlocking all-seeing-eye terminal access
- picking up a remedy from a supply prop
`ActivateReactor` wins only if the level is `Ready` for that reactor. Otherwise it reports that the reactor is not ready.
`InteractProp` covers flow toggles, consumer toggles, junction ratio changes, door toggles, terminal unlock, and remedy pickup.
## Network Flow
The network flow step runs independently for fuel, coolant, and electricity.
Network flow runs independently for fuel, coolant, and electricity.
For each carrier:
1. Clear transient carrier amount and pressure or voltage values from the previous turn.
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 of that carrier.
3. Walk through connected intact and leaking underground cells.
4. Stop at absent cells and disconnected topology.
5. Apply distance falloff to carrier amount and pressure or voltage.
6. Apply junction ratio weights at valid junction props.
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 to balance min/max.
8. Clamp final values.
If multiple non-ambiguous source paths reach the same non-junction cell, the cell uses the best carrier amount and best pressure or voltage. Ambiguous junction flow is invalid and must be caught by validation.
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.
Consumers evaluate after propagation.
A consumer is supplied if all required balance predicates pass:
- enough carrier amount reaches the bound underground cell
- enough pressure reaches a fuel or coolant consumer
- enough voltage reaches an electricity consumer
- the bound network path is not disconnected by topology or junction ratios
A consumer is supplied when carrier amount, pressure or voltage, and connectivity predicates pass.
## Surface Hazards
A leaking underground cell remains part of network propagation while leaking.
Leaking underground cells remain part of network propagation.
During leak injection:
- fuel leaks inject leaked fuel into the accessible floor cell
- coolant leaks inject leaked coolant into the accessible floor cell
- electricity leaks inject leaked electricity into the stored accessible floor face
- active matching remedy blocks prevent the matching element from entering the protected floor cell
- 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
Leak injection magnitudes are balance data and may depend on local carrier amount, pressure, or voltage.
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 each floor cell and between adjacent floor cells.
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.
Closed doors block pair evaluation across their authored edge.
## Hazard Bands And Pair Table
## Condition Bands And Pair Table
Authoritative simulation values are numeric floats. Balance thresholds project values into UI/forecast bands:
- safe
- caution
- critical
Projected labels:
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 event effects. It is implemented in code using balance thresholds and effect magnitudes, not loaded from data in v1.
Pair event legend:
The pair table maps projected bands to deterministic effects:
- `Hold`: no direct change.
- `FuelFlow`: equalize leaked fuel.
@@ -527,43 +313,32 @@ Pair event legend:
| HeatCaution | | | | | | | | | | | Hold | HeatFlow |
| HeatCritical | | | | | | | | | | | | Hold |
Design intent:
Design rules:
- fuel only becomes dangerous through electricity or heat
- coolant only becomes dangerous through electricity
- 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 active remedy blocks gate local interactions
- doors and remedy blocks gate local interactions
## Rule Events
V1 supports deterministic rule-triggered 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.
Each rule event stores:
Predicate families:
- enabled state
- once or repeat behavior
- priority/order
- predicate list
- effect list
- optional player-facing forecast text
All predicates in the predicate list must pass for the event to trigger.
Supported predicate families:
- turn number comparisons
- turn comparisons
- level state comparisons
- reactor readiness/loss/won comparisons
- prop type/state at position
- reactor readiness/loss/win comparisons
- prop type or state at position
- consumer service state at position
- network carrier amount, pressure, or voltage band at position
- network value band at position
- surface hazard band at position
- robot position or inventory condition
- all-seeing-eye unlocked state
Supported effects:
Effects:
- start a valid leak
- worsen an existing leak
@@ -575,177 +350,93 @@ Supported effects:
- mark terminal loss
- emit warning text
Rule events must be deterministic and forecastable. Random predicates and random effects are not part of v1.
## Simulation Order
The simulation loop for one completed turn is:
One completed turn resolves in this order:
1. Apply all player actions already accepted during the player phase.
2. Validate that runtime state remains valid enough to simulate.
3. Apply start-of-simulation rule events whose predicates pass.
4. Resolve source injection and underground network propagation for each carrier.
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 into accessible floor cells, respecting remedy blocks.
7. Evaluate local same-cell surface interactions.
8. Evaluate right and bottom neighbor interactions when no closed door blocks the edge.
9. Accumulate emitted deltas.
10. Apply deltas in deterministic priority order.
11. Clamp numeric values.
12. Resolve robot safety; unsafe final robot state marks the level `Lost`.
13. Derive reactor readiness and level state.
14. Apply end-of-turn rule events whose predicates pass.
15. Advance remedy block durations and heat immunity duration.
16. Refresh forecasts.
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, their deltas are accumulated before clamping unless a specific event consumes, reserves, or blocks a value earlier in the order.
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
V1 forecasts guarantee:
Forecasts are deterministic simulations over copied state. Forecasting does not mutate the actual level.
Forecast output includes:
- terminal loss forecasts
- reactor ready forecasts
- near-term warnings for starved required consumers
- near-term warnings for growing hazards that cross caution or critical bands
- rule event warnings when predicates can be proven for the forecast horizon
Forecasts are deterministic simulations over copied state. Forecasting must not mutate the actual level.
- 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 must block run and save when validation errors exist. Warnings may allow save/run but must be visible.
The editor blocks run and save when validation errors exist. Warnings are visible and non-blocking.
Validation errors:
- level dimensions below minimum
- cell array dimensions mismatch
- robot is out of bounds or not on floor
- wall cell stores surface hazards
- prop is out of bounds or on invalid terrain
- reactor binding is missing, out of bounds, or points to the wrong consumer type
- door edge is missing, non-adjacent, out of bounds, or not floor-to-floor
- fuel or coolant leak is not under a floor cell
- electricity leak is not in a wall cell or lacks exactly one adjacent floor emission face
- rule-created leak target would be invalid
- junction is not on a floor cell with exactly one underground carrier
- junction incoming or outgoing flow is ambiguous
- inferred network topology contains loops or ambiguous equal source paths at a junction
- rule predicate or effect references an invalid target
- all required v1 data is absent or malformed
- 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 possible source path
- required consumer initially starved
- reactor initially not ready
- underground cell with no source path
- initially starved required consumer
- initially unready reactor
- unused remedy supply
- visible hazard with no nearby remedy or route, when detectable by static analysis
- visible hazard with no detectable nearby remedy or route
## Editor Requirements
## Editor And Schema
The v1 editor must be able to author every v1 concept:
The editor authors:
- surface terrain
- underground fuel, coolant, and electricity cells
- flow props
- consumer props
- flow props and consumer props
- reactor controls and reactor consumer bindings
- T-junction and cross-junction props
- junction ratio modes
- junction props and ratio modes
- door props and door edges
- all-seeing-eye terminals
- remedy supplies
- fuel/coolant floor leaks
- electricity wall leaks and emission faces
- floor leaks and electricity wall leaks
- initial surface hazards and heat
- robot start position
- rule events
The editor always shows all layers. Gameplay preview may include a locked/unlocked diagnostic display mode, but authoring is never hidden from the designer.
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 editor save command must run validation and refuse to save on errors.
The loader accepts only schema-valid level data and returns clear errors for malformed data.
## Serialization
## Balancing And Tests
V1 level files use serialization version `1`.
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.
The serialized schema stores:
- level metadata
- dimensions
- terrain cells
- underground network layers
- surface props and prop state
- reactor consumer bindings by grid position
- leaks
- doors and door edges
- robot state
- inventory
- rule events
- initial all-seeing-eye unlocked state
- current dynamic state for saved games, if save-game support is enabled
Prototype-shaped files are not compatible, even if they used an earlier `Version: 1` wrapper. The loader accepts only this v1 schema and returns a clear unsupported or invalid-level error for prototype or malformed data.
## Balancing Data
The design deliberately assigns these values to balancing:
- source strengths
- carrier amount falloff
- pressure and voltage falloff
- ratio-to-flow math
- consumer demand predicates
- leak injection magnitudes
- local interaction magnitudes
- UI safe/caution/critical thresholds
- robot safety thresholds
- terminal heat thresholds
- inventory capacity
- remedy block duration
- heat immunity duration
- action costs beyond the default one-action rule
- forecast horizon
Tests should assert behavior against configured balance values and bands, not hardcoded design numbers.
## Test Requirements
V1 test coverage must include:
- validation rejects ambiguous networks, loops, invalid leaks, invalid doors, invalid reactor bindings, invalid robot placement, and invalid rule references
- inferred adjacency propagates each carrier through valid networks
- junction ratios affect branch service or leak severity by observable band/result
- consumers derive disabled, starved, supplied, and producing states
- bound reactor readiness requires the three bound consumers and safe reactor heat
- activation wins only from `Ready`
- terminal reactor heat loses
- unsafe robot final hazard state loses
- heat immunity prevents only heat-caused robot loss while active
- fuel, coolant, and electricity leaks inject through their valid access rules
- remedies remove only matching hazards and create temporary matching blocks
- closed doors block surface propagation across their edge only
- rule events trigger deterministically from predicate lists
- forecasts report terminal loss, ready state, starved required consumers, and growing hazards
- serialization round-trips valid v1 levels and rejects prototype or malformed files
## Summary
V1 reduces Reactor Maintenance to a small deterministic formal core:
- static surface terrain
- three inferred-adjacency underground networks
- float carrier, pressure, voltage, leak, and heat values
- flow, consumer, junction, door, terminal, remedy, and reactor props
- explicit reactor-to-consumer bindings
- reachable floor and wall leak rules
- surface hazards gated by doors and remedies
- rule-triggered deterministic events
- forecastable ready, warning, and loss states
- editor validation that blocks ambiguous authored content
This is the implementation target for replacing the prototype simulation, tests, and editor.
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.