752 lines
28 KiB
Markdown
752 lines
28 KiB
Markdown
# Reactor Maintenance V1 Design
|
|
|
|
## Status
|
|
|
|
This document is the authoritative v1 design for Reactor Maintenance.
|
|
|
|
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.
|
|
|
|
## 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 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.
|
|
|
|
## Turn Structure
|
|
|
|
Each gameplay 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.
|
|
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.
|
|
|
|
## Goal
|
|
|
|
Each reactor starts offline.
|
|
|
|
To win a level, the player must:
|
|
|
|
- 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 every bound required consumer is enabled, supplied, and producing service, and no terminal reactor condition is active, the level 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 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
|
|
- 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
|
|
|
|
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.
|
|
|
|
After interacting with an all-seeing-eye terminal prop, the player can inspect all underground layers:
|
|
|
|
- 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
|
|
|
|
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
|
|
|
|
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 surface prop
|
|
- zero or more 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.
|
|
|
|
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:
|
|
|
|
- `Absent`
|
|
- `Intact`
|
|
- `Leaking`
|
|
|
|
Each underground network cell stores:
|
|
|
|
- carrier amount
|
|
- pressure for fuel and coolant
|
|
- voltage for electricity
|
|
|
|
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
|
|
- active elemental remedy blocks
|
|
|
|
There is no v1 smoke, fire, pressure-pipe, cell-integrity, or facility-stability system.
|
|
|
|
### Robot
|
|
|
|
The robot stores:
|
|
|
|
- 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.
|
|
- `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.
|
|
- `Lost`: terminal failure has occurred.
|
|
- `Won`: the reactor has been activated successfully.
|
|
|
|
Level state is derived after each simulation step and after successful activation.
|
|
|
|
## Props
|
|
|
|
Surface prop categories:
|
|
|
|
- flow prop
|
|
- consumer prop
|
|
- T-junction prop
|
|
- cross-junction prop
|
|
- door prop
|
|
- all-seeing-eye terminal prop
|
|
- 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.
|
|
|
|
### Flow Props
|
|
|
|
A flow prop is bound to exactly one carrier family:
|
|
|
|
- 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.
|
|
|
|
### Consumer Props
|
|
|
|
A consumer prop is bound to exactly one carrier family:
|
|
|
|
- fuel consumer
|
|
- coolant consumer
|
|
- electricity consumer
|
|
|
|
Consumer props have two player-controlled states:
|
|
|
|
- `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.
|
|
|
|
### Reactor Control Props
|
|
|
|
A reactor control prop is the activation site for one reactor.
|
|
|
|
Each reactor stores required consumer bindings by grid 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.
|
|
|
|
### Junction Props
|
|
|
|
Junction props regulate flow after it leaves a source.
|
|
|
|
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:
|
|
|
|
- `0/4`
|
|
- `1/3`
|
|
- `2/2`
|
|
- `3/1`
|
|
- `4/0`
|
|
|
|
Cross-junction props split one incoming path into three outgoing branches. Allowed 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.
|
|
|
|
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. It does not need to label live downstream effects in v1.
|
|
|
|
### Door Props
|
|
|
|
Door props have two states:
|
|
|
|
- `Open`
|
|
- `Closed`
|
|
|
|
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.
|
|
|
|
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:
|
|
|
|
- `FuelRemedySupply`
|
|
- `CoolantRemedySupply`
|
|
- `ElectricityRemedySupply`
|
|
- `HeatRemedySupply`
|
|
|
|
Each supply prop provides one fixed remedy type once. After pickup it becomes depleted.
|
|
|
|
## Leaks
|
|
|
|
Each leak stores:
|
|
|
|
- carrier type
|
|
- underground coordinate
|
|
- accessible floor coordinate
|
|
- current repair state
|
|
|
|
Fuel and coolant leak rules:
|
|
|
|
- may only occur when the underground leak coordinate is under a floor cell
|
|
- 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:
|
|
|
|
- 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
|
|
|
|
All authored and rule-created leaks must have valid floor access. Invalid leaks are validation errors for authored state and rejected events at runtime.
|
|
|
|
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:
|
|
|
|
- `FuelNeutralizer`
|
|
- `CoolantNeutralizer`
|
|
- `ElectricityNeutralizer`
|
|
- `HeatShield`
|
|
|
|
Element neutralizers:
|
|
|
|
- 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.
|
|
|
|
## 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.
|
|
- `ApplyHeatShield`: activate a carried heat shield.
|
|
- `ActivateReactor`: activate a 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.
|
|
|
|
`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.
|
|
|
|
## Network Flow
|
|
|
|
The network flow step runs independently for fuel, coolant, and electricity.
|
|
|
|
For each carrier:
|
|
|
|
1. Clear transient carrier amount and pressure or voltage values from the previous turn.
|
|
2. Start from every enabled flow prop connected to that carrier.
|
|
3. Walk through connected intact and leaking underground cells of that carrier.
|
|
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.
|
|
7. Assign each reached cell its best incoming carrier amount and best incoming pressure or voltage.
|
|
8. Clamp final values to balance min/max.
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
## Surface Hazards
|
|
|
|
A leaking underground cell remains part of network propagation while leaking.
|
|
|
|
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
|
|
|
|
Leak injection magnitudes are 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.
|
|
|
|
Closed doors block pair evaluation across their authored edge.
|
|
|
|
## Condition Bands And Pair Table
|
|
|
|
Authoritative simulation values are numeric floats. Balance thresholds project values into UI/forecast bands:
|
|
|
|
- safe
|
|
- caution
|
|
- critical
|
|
|
|
Projected labels:
|
|
|
|
- `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:
|
|
|
|
- `Hold`: no direct change.
|
|
- `FuelFlow`: equalize leaked fuel.
|
|
- `CoolFlow`: equalize leaked coolant.
|
|
- `ChargeFlow`: equalize leaked electricity.
|
|
- `HeatFlow`: transfer heat.
|
|
- `HeatFlow2`: stronger heat transfer.
|
|
- `Warm1`: small heat increase from fuel exposure.
|
|
- `Warm2`: larger heat increase from fuel exposure.
|
|
- `Quench1`: small heat reduction from coolant exposure.
|
|
- `Quench2`: larger heat reduction from coolant exposure.
|
|
- `Short1`: electricity and coolant interaction causing heat and discharge.
|
|
- `Short2`: stronger short.
|
|
- `Ignite1`: fuel interaction with electricity or high heat.
|
|
- `Ignite2`: stronger ignition.
|
|
|
|
| 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 |
|
|
|
|
Design intent:
|
|
|
|
- fuel only becomes dangerous through electricity or heat
|
|
- coolant only 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
|
|
|
|
## Rule Events
|
|
|
|
V1 supports deterministic rule-triggered events.
|
|
|
|
Each rule event stores:
|
|
|
|
- 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
|
|
- level state comparisons
|
|
- reactor readiness/loss/won comparisons
|
|
- prop type/state at position
|
|
- consumer service state at position
|
|
- network carrier amount, pressure, or voltage band at position
|
|
- surface hazard band at position
|
|
- robot position or inventory condition
|
|
- all-seeing-eye unlocked state
|
|
|
|
Supported 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
|
|
|
|
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:
|
|
|
|
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.
|
|
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.
|
|
|
|
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.
|
|
|
|
## Forecasts
|
|
|
|
V1 forecasts guarantee:
|
|
|
|
- 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.
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
Validation warnings:
|
|
|
|
- unreachable non-required consumer
|
|
- underground cell with no possible source path
|
|
- required consumer initially starved
|
|
- reactor initially not ready
|
|
- unused remedy supply
|
|
- visible hazard with no nearby remedy or route, when detectable by static analysis
|
|
|
|
## Editor Requirements
|
|
|
|
The v1 editor must be able to author every v1 concept:
|
|
|
|
- surface terrain
|
|
- underground fuel, coolant, and electricity cells
|
|
- flow props
|
|
- consumer props
|
|
- reactor controls and reactor consumer bindings
|
|
- T-junction and cross-junction props
|
|
- junction ratio modes
|
|
- door props and door edges
|
|
- all-seeing-eye terminals
|
|
- remedy supplies
|
|
- fuel/coolant floor leaks
|
|
- electricity wall leaks and emission faces
|
|
- 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 editor save command must run validation and refuse to save on errors.
|
|
|
|
## Serialization
|
|
|
|
V1 level files use serialization version `1`.
|
|
|
|
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.
|