diff --git a/docs/design.md b/docs/design.md index 0b8d189..1324504 100644 --- a/docs/design.md +++ b/docs/design.md @@ -1,4 +1,10 @@ -# Game Design: Reactor Maintenance +# 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 @@ -8,53 +14,44 @@ The game is a deterministic, turn-based systems puzzle. The player studies a vis The simulation model is intentionally narrow: -- a static surface grid made of walkable floor cells and blocked wall cells +- 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 -- a reactor that must receive fuel, cooling, and electricity support before activation +- 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 -Each turn has three phases: - -1. Player phase: the player spends a limited number of actions. -2. Simulation phase: network flow, leaks, local hazards, doors, consumers, and level state are resolved deterministically. -3. Event phase: scheduled failures, remedy durations, and scripted level events advance. - The main fantasy is: > "I understand this machine well enough to prevent the next disaster." -The game should feel: +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. -- logical -- tactical -- deterministic -- readable -- systemic +## Turn Structure -It should not feel: +Each gameplay turn has three phases: -- hectic -- random -- action-heavy -- dependent on hidden information after the correct inspection tool is acquired +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 -The reactor starts offline. +Each reactor starts offline. To win a level, the player must: -- restore fuel delivery to the required fuel consumer -- restore coolant delivery to the required coolant consumer -- restore electricity delivery to the required electricity consumer -- keep the reactor area below terminal heat +- 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 all required consumers are enabled, supplied, and producing service, and no terminal reactor condition is active, the level shows: +When every bound required consumer is enabled, supplied, and producing service, and no terminal reactor condition is active, the level shows: > REACTOR READY @@ -67,61 +64,17 @@ The player loses if the level reaches a clearly predicted terminal state. Primary loss conditions: - reactor overheating reaches the terminal heat threshold -- a scripted terminal event resolves +- 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, scripted loss events, or other explicit terminal 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. - -## Turn Structure - -### 1. Player Phase - -The player has a fixed number of actions per turn, defined by balancing. - -Player actions are limited to: - -- move the robot -- interact with a prop -- interact with a leak or hazard cell -- activate the reactor - -Each player action costs one action unless balancing or a level rule explicitly says otherwise. Passive inspection of visible information is free; all underground inspection requires all-seeing-eye access. - -### 2. Simulation Phase - -The facility updates all active systems. - -Examples: - -- enabled flow props inject pressure or voltage into connected underground networks -- T-junction and cross-junction props split outflow by selected ratios -- enabled consumers draw from their bound network and produce service if supplied -- leaking fuel and coolant underground cells emit their carrier through a broken floor cell -- leaking electricity wall cells emit sparks through their stored adjacent floor face -- neighboring floor cells exchange leaked matter, charge, or heat through deterministic numeric rules -- closed doors block surface hazard propagation across their edge -- coolant lowers heat -- electricity interacting with coolant or fuel raises heat - -### 3. Event Phase - -Predicted events advance by one turn. - -Examples: - -- a scripted leak starts -- an existing leak worsens -- an elemental remediation block expires -- robot heat immunity expires -- a scripted level event adds heat or disables a prop - -Events are not hidden. The player sees upcoming failures before they happen. +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. +All surface information is visible and predictable. Underground information is controlled by terminal access during gameplay. The player can always see: @@ -132,8 +85,8 @@ The player can always see: - door open or closed state - remedy inventory and supply props - whether each consumer is producing, starved, disabled, or unknown -- the current global level state -- scheduled upcoming events and warnings +- 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. @@ -144,22 +97,13 @@ After interacting with an all-seeing-eye terminal prop, the player can inspect a - carrier amount - pressure for fuel and coolant - voltage for electricity -- junction split modes and downstream effects - source-to-consumer connectivity -Safe, caution, and critical labels are UI and forecast labels only. They are derived from balance constants and are not authoritative simulation state. Exact numeric values and balance predicates drive simulation. +The editor is not gated by all-seeing-eye access. It always sees and authors every layer. -The question is not: +Safe, caution, and critical labels are UI and forecast labels derived from balance thresholds. They are not stored as authoritative simulation state. -> "What is behind the corner?" - -It is: - -> "Do I spend scarce local resources now, or commit actions to fix the system that caused this?" - -## Simulation Model - -### Layered Grid +## Layered Grid Each map coordinate contains: @@ -169,29 +113,54 @@ Each map coordinate contains: - 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 floor cells +- optionally the robot, only on a floor cell -Cells cannot change between floor and wall during play. Terrain is level-authored and static. +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: -- its own outside-of-level source connection -- one flow prop type on the surface -- one consumer prop type on the surface +- 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 -The surface prop is an abstract vertical control or access point. Junction props are the only way to regulate network flow after it leaves a source. Consumers can be toggled, but consumer toggles do not alter network outflow ratios. +## Numeric Model -### Network Semantics +Simulation values use C# `float`. -The three network families are intentionally symmetric in structure but differ by carrier behavior. +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. -- Fuel: liquid carrier, uses pressure, required by the fuel consumer, dangerous when leaked near electricity or high heat. -- Coolant: liquid carrier, uses pressure, required by the coolant consumer, lowers heat, dangerous when leaked near electricity. -- Electricity: electrical carrier, uses voltage, required by the electricity consumer, dangerous when leaked near coolant or fuel. +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: @@ -199,19 +168,27 @@ Each underground network cell has one structural state: - `Intact` - `Leaking` -Each underground network cell stores exact numeric values: +Each underground network cell stores: -- local carrier amount -- local pressure for fuel and coolant -- local voltage for electricity +- carrier amount +- pressure for fuel and coolant +- voltage for electricity -Each floor cell stores exact numeric values: +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 remediation blocks +- active elemental remedy blocks + +There is no v1 smoke, fire, pressure-pipe, cell-integrity, or facility-stability system. + +### Robot The robot stores: @@ -219,83 +196,31 @@ The robot stores: - carried remedial consumables - active heat-immunity duration -All numeric values use balance-defined minimum and maximum clamps. The design intentionally does not fix numeric thresholds in this document. Balancing defines source strength, consumer requirements, leak rates, display bands, terminal thresholds, event magnitudes, inventory capacity, remedy block duration, and 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. -### Why This Formalization +### Level State -This model keeps the simulation small enough to forecast while still creating tactical decisions: +The whole level has these states: -- terrain is static and readable -- network topology is stored underground -- pressure and voltage determine whether consumers are satisfied and how severe leaks are -- junction ratios are explicit and player-controlled -- leaks project hazards onto reachable floor cells -- doors provide local surface containment -- remedies provide scarce local stabilization -- global level state is derived after deterministic local interactions +- `Stable` +- `Caution` +- `Critical` +- `Ready` +- `Lost` +- `Won` -## State Inventory +Meaning: -### Cell State +- `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. -Surface terrain states: +Level state is derived after each simulation step and after successful activation. -- `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. - -Terrain is static. There are no runtime events that create or clear floor/wall terrain. - -Surface hazard values on floor cells: - -- `Fuel` -- `Coolant` -- `Electricity` -- `Heat` - -Underground network state, repeated for fuel, coolant, and electricity: - -- `Absent` -- `Intact` -- `Leaking` -- local carrier amount -- local pressure for fuel and coolant -- local voltage for electricity - -Notes: - -- `Absent` / `Intact` / `Leaking` describe the underground cell itself. -- Numeric values describe the current simulation state. -- Safe/caution/critical labels are derived from numeric values for UI and forecasts only. -- A fuel or coolant leak injects into its own floor cell. -- An electricity wall leak injects into its stored adjacent floor emission face. - -### Leak State - -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 -- are visualized as broken floor revealing a burst underground pipe -- 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 -- are visualized as cables hanging out of the wall and emitting sparks into the chosen floor cell -- can be repaired or remediated by the robot from the chosen floor cell -- do not emit to other adjacent floor cells - -All leaks introduce hazards to the robot through their visible floor cell. Every authored or scripted leak must have at least one accessible floor cell so the player can choose an on-site response. - -### Prop State +## Props Surface prop categories: @@ -308,12 +233,66 @@ Surface prop categories: - remedy supply prop - reactor control prop -Flow and consumer props have two states: +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` -T-junction props split one incoming network path into two outgoing branches. Their allowed modes are: +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` @@ -321,27 +300,49 @@ T-junction props split one incoming network path into two outgoing branches. The - `3/1` - `4/0` -Cross-junction props split one incoming network path into three outgoing branches. Their allowed modes are: +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 ratio numbers are weights, not fixed values. They divide available carrier amount plus pressure or voltage according to balance-defined ratio math. A zero-weight branch receives no intentional outflow from that junction. +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` -Closed doors block surface leak and heat propagation across their door edge. Closed doors do not block underground network flow. +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` @@ -351,24 +352,33 @@ Remedy supply props are single-use typed pickups: Each supply prop provides one fixed remedy type once. After pickup it becomes depleted. -### Consumer State +## Leaks -Each consumer derives one current service state: +Each leak stores: -- `Disabled`: the prop is off, consumes nothing, produces no service, and does not starve. -- `Supplied`: the prop is enabled and receives enough carrier amount plus pressure or voltage. -- `Starved`: the prop is enabled but receives too little carrier amount, pressure, or voltage. -- `Producing`: the prop is supplied this simulation step and its required service is active. +- carrier type +- underground coordinate +- accessible floor coordinate +- current repair state -`Supplied` is the input condition. `Producing` is the output condition used by readiness. +Fuel and coolant leak rules: -Required consumer mapping: +- 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 -- Fuel consumer: required for reactor fuel path. -- Coolant consumer: required for reactor cooling path. -- Electricity consumer: required for reactor activation path. +Electricity leak rules: -### Remedy State +- 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. @@ -383,7 +393,7 @@ 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 for a balance-defined duration +- 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 @@ -391,185 +401,27 @@ Element neutralizers: Heat shield: - is consumed when activated by the robot -- makes the robot immune to heat damage for a balance-defined number of robot steps +- 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. For example, a floor cell containing fuel, electricity, and heat requires a fuel neutralizer, an electricity neutralizer, and heat immunity or another heat-management solution to make the robot locally safe. +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. -### Level State +## Player Actions -The whole level has five states: +Each player action costs one action unless balance or level data explicitly says otherwise. -- `Stable` -- `Caution` -- `Critical` -- `Ready` -- `Lost` +Player actions: -Meaning: +- `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. -- `Stable`: no terminal path is active and no urgent predicted intervention is required. -- `Caution`: one or more required services are unavailable, a hazard is growing, or reactor heat is concerning but not terminal. -- `Critical`: the simulation predicts a loss without near-term intervention. -- `Ready`: all reactor activation prerequisites are met. -- `Lost`: terminal failure has already occurred. - -Level state is derived. It is not diffused spatially. - -### Robot State - -The robot has four states: - -- `Ready` -- `Interacting` -- `Blocked` -- `Damaged` - -Meaning: - -- `Ready`: free to move and act. -- `Interacting`: currently spending an action on a prop, leak, hazard, or reactor activation. -- `Blocked`: the target move or action was refused because the destination or target is invalid. -- `Damaged`: the robot entered or remained in an unresolved hazardous cell without applicable protection. - -## Flow Mechanic - -### Sources - -An enabled flow prop is the source for its bound network. - -During the network flow step: - -- `FeedFromOutside[Fuel]` injects fuel amount and fuel pressure. -- `FeedFromOutside[Coolant]` injects coolant amount and coolant pressure. -- `FeedFromOutside[Electricity]` injects electricity amount and voltage. - -The injected source amount and source pressure or voltage are balance constants. A disabled flow prop injects nothing and isolates its bound source cell from outside supply. - -### Propagation - -Carrier amount, pressure, and voltage propagate through connected intact and leaking underground cells using deterministic distance falloff and junction ratios. - -For each carrier network: - -- start from every enabled flow prop connected to that carrier -- walk through connected `Intact` and `Leaking` cells of that carrier -- stop at `Absent` cells and disconnected network topology -- assign each reached cell the best available incoming carrier amount plus pressure or voltage -- subtract balance-defined amount falloff and pressure or voltage falloff for each network step -- divide outflow at T-junction and cross-junction props using the selected ratio mode -- clamp final values to the balance-defined numeric range - -If multiple sources or paths reach the same cell, the cell uses the best resulting carrier amount and the best resulting pressure or voltage. This keeps routing predictable and prevents order-dependent results. - -### Junctions - -Junction props are the only flow regulation mechanism. - -A junction prop must be placed on a floor cell and is controlled by the robot through `InteractProp`. Its underground network cell defines the carrier it regulates. - -T-junction behavior: - -- one incoming branch is split into two authored outgoing branches -- selected mode chooses the outflow ratio between those branches -- `0/4` sends all intentional outflow to branch B -- `4/0` sends all intentional outflow to branch A -- intermediate modes split by weight - -Cross-junction behavior: - -- one incoming branch is split into three authored outgoing branches -- selected mode chooses the outflow ratio between those branches -- `0/3/3`, `3/0/3`, and `3/3/0` shut off one outgoing branch while splitting between the other two -- `2/2/2` balances outflow across all three branches - -Ratio math is balance data. The intended design is readable branch commitment, not fine-grained numeric optimization. - -Strategic uses: - -- route pressure away from a leaking branch -- feed a required consumer at the cost of starving another branch -- reduce voltage near a sparking wall leak without disabling the source -- create a longer-term fix that costs more commitment than spending a consumable - -### Consumers - -An enabled consumer evaluates after network propagation. - -The 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 - -If supplied, the consumer emits `ConsumeFromNetwork[n]`, removes or reserves the balance-defined demand amount, and produces its required service for this turn. - -If enabled but not supplied, the consumer emits `StarveConsumer[n]`. Starvation blocks readiness and contributes to `Caution` or forecast warnings, but it does not directly cause loss. - -If disabled, the consumer consumes nothing, produces nothing, does not starve, and cannot satisfy readiness. Disabling a consumer is still useful as demand management, but it is not a flow-ratio control. - -### Leaks And Flow Values - -Pressure and voltage make leaks strategically meaningful. - -A leaking underground cell: - -- remains part of network propagation while leaking -- emits its carrier into the accessible floor cell during `InjectLeak[n]` -- uses balance-defined leak predicates that can depend on carrier amount, pressure, or voltage -- may inject more severe hazards when pressure or voltage is high - -Repairing a leak changes the underground cell from `Leaking` to `Intact` and stops future injection. It does not clean existing leaked surface fuel, coolant, electricity, or heat. - -Applying a matching elemental remedy does not repair the leak. It removes the matching visible hazard on the target and temporarily blocks re-entry of that same element, buying time for repair or flow regulation. - -## Doors And Surface Containment - -Doors are surface props that control local hazard spread. - -A door has an authored propagation edge between two floor cells. When open, surface fuel, coolant, electricity, and heat may propagate across that edge according to normal rules. When closed, those surface 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 - -Door use is a short-term containment tool. It can isolate a hazardous area while the player fetches remedies, repairs a leak, or changes junction ratios. - -## Remediation Loop - -Every leak creates robot-facing hazard pressure. The player should always have two broad alternatives: - -- short-term localized stability by spending a consumable or heat immunity -- long-term stability by repairing the leak, changing junction ratios, toggling consumers, or restoring required flow - -Remediation is intentionally element-specific. - -Examples: - -- A fuel spill can be neutralized with `FuelNeutralizer`, but any electricity already mixed into the cell remains. -- An electrified coolant puddle needs both `CoolantNeutralizer` and `ElectricityNeutralizer` to fully clear the elemental hazard. -- A hot leak zone can be crossed with `HeatShield`, but the heat remains dangerous after immunity expires. -- A closed door can keep a neutralized corridor safe longer by preventing new spread from adjacent cells. - -Consumables are scarce by map design. Each supply prop grants one typed item once, so spending a remedy is a commitment. - -## Events That Modify State - -`[n]` means one of the three carriers: fuel, coolant, or electricity. - -### Player Actions - -- `MoveRobot`: spends one action to move the robot to an adjacent floor cell. Invalid destinations emit `BlockRobot`. -- `InteractProp`: spends one action on the prop in the robot's current floor cell. -- `InteractLeak`: spends one action to repair a leak reachable from the robot's current floor cell, apply a matching carried elemental remedy to the robot's current floor cell, or activate a carried heat shield while the robot occupies a hazardous floor cell. -- `ActivateReactor`: spends one action at the reactor control site. It wins only if the level is `Ready`; otherwise it reports that the reactor is not ready. +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: @@ -581,160 +433,84 @@ Consumables are scarce by map design. Each supply prop grants one typed item onc - unlocking all-seeing-eye terminal access - picking up a remedy from a supply prop -`InteractLeak` covers: +`ActivateReactor` wins only if the level is `Ready` for that reactor. Otherwise it reports that the reactor is not ready. -- repairing the underlying leak -- applying `FuelNeutralizer` -- applying `CoolantNeutralizer` -- applying `ElectricityNeutralizer` +## Network Flow -`HeatShield` is activated through `InteractLeak` while targeting a hazardous floor cell. It consumes one action and affects the robot rather than the map cell. +The network flow step runs independently for fuel, coolant, and electricity. -### Cell And Network Events +For each carrier: -- `StartLeak[n]`: changes an underground network cell from `Intact` to `Leaking` if the leak placement rules are satisfied. -- `RejectInvalidLeak[n]`: refuses or reports an authored/scripted leak that has no valid floor repair access. -- `RepairLeak[n]`: changes an underground network cell from `Leaking` to `Intact`. Existing surface hazards remain. -- `FeedFromOutside[n]`: writes source carrier amount and pressure or voltage into the connected network according to propagation rules. -- `RouteThroughTJunction[n]`: divides outflow between two authored branches using the selected T-junction ratio. -- `RouteThroughCrossJunction[n]`: divides outflow between three authored branches using the selected cross-junction ratio. -- `Equalize[n]`: moves a balance-defined amount of the same leaked surface carrier from a higher-value floor cell to a lower-value adjacent floor cell unless a closed door blocks that edge. -- `InjectLeak[n]`: adds a balance-defined leaked carrier amount from a leaking underground cell into its accessible floor cell. The amount may depend on local carrier amount, pressure, or voltage. -- `HeatTransfer`: moves a balance-defined heat amount from a hotter floor cell to a cooler adjacent floor cell unless a closed door blocks that edge. -- `HeatUp[1]`: increases local heat by a small balance-defined amount. -- `HeatUp[2]`: increases local heat by a larger balance-defined amount. -- `CoolDown[1]`: decreases local heat by a small balance-defined amount. -- `CoolDown[2]`: decreases local heat by a larger balance-defined amount. -- `Short[1]`: resolves electricity and coolant interaction by raising heat, reducing leaked electricity, and optionally reducing leaked coolant by balance-defined amounts. -- `Short[2]`: stronger short event with larger balance-defined heat and discharge effects. -- `Ignite[1]`: resolves fuel with electricity or fuel with high heat by raising heat and consuming or transforming leaked fuel by balance-defined amounts. -- `Ignite[2]`: stronger ignition event with larger balance-defined heat and fuel effects. -- `ClampValues`: clamps all carrier, pressure, voltage, leaked surface, and heat values to balance-defined ranges. +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. -### Prop And Remedy Events +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. -- `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`. -- `SetTJunctionRatio[n]`: sets a T-junction to one of `0/4`, `1/3`, `2/2`, `3/1`, or `4/0`. -- `SetCrossJunctionRatio[n]`: sets a cross-junction to one of `0/3/3`, `3/0/3`, `3/3/0`, or `2/2/2`. -- `OpenDoor`: changes a door from `Closed` to `Open`. -- `CloseDoor`: changes a door from `Open` to `Closed`. -- `UnlockAllSeeingEye`: enables underground layer inspection for the level. -- `PickUpRemedy`: consumes a typed supply prop and adds its remedy to robot inventory if capacity allows. -- `ApplyElementRemedy[n]`: consumes a matching carried remedy, removes that surface element from the target floor cell, and applies a temporary same-element re-entry block. -- `ApplyHeatImmunity`: consumes a heat shield and gives the robot heat immunity for a balance-defined number of steps. -- `ExpireRemedyBlock[n]`: removes an active same-element re-entry block from a floor cell. -- `ExpireHeatImmunity`: removes robot heat immunity when its step duration reaches zero. -- `ConsumeFromNetwork[n]`: an enabled and supplied consumer removes or reserves demand and emits service for the turn. -- `StarveConsumer[n]`: an enabled but unsupplied consumer emits a visible warning and blocks readiness. It does not directly emit `LoseLevel`. +Consumers evaluate after propagation. -### Level Events +A consumer is supplied if all required balance predicates pass: -- `EscalateLevel`: derives a worse non-terminal state when required service is missing, heat is rising, a terminal forecast is near, or a scripted level condition says the situation is deteriorating. -- `RecoverLevel`: derives a better non-terminal state when required services are restored and terminal forecasts are no longer near. -- `MarkReady`: changes the derived level state to `Ready` when all required consumers are producing service and the reactor area is below terminal conditions. -- `ClearReady`: changes `Ready` back to `Stable`, `Caution`, or `Critical` when any readiness prerequisite is lost before activation. -- `LoseLevel`: changes the level to `Lost` when terminal heat, scripted terminal failure, or explicit unrecoverable conditions fire. -- `ActivateCore`: changes the level to the win state after `ActivateReactor` succeeds while the level is `Ready`. +- 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 -### Robot Events +## Surface Hazards -- `StartInteraction`: changes `Ready` to `Interacting` for the duration of an action. -- `FinishInteraction`: changes `Interacting` to `Ready` after the action resolves. -- `BlockRobot`: changes `Ready` to `Blocked` for the attempted move or action, then returns to `Ready` once the refusal is reported. -- `DamageRobot`: changes `Ready` or `Blocked` to `Damaged` when the robot occupies a cell whose final hazard values exceed robot safety predicates and no carried or active protection applies. -- `RecoverRobot`: changes `Damaged` or `Blocked` to `Ready` when recovery rules are satisfied. -- `AdvanceHeatImmunityStep`: decrements robot heat immunity when the robot spends a movement step. +A leaking underground cell remains part of network propagation while leaking. -## Condition Table +During leak injection: -The table is a design summary for pair interactions. It is not the authoritative simulation algorithm. +- 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 -Authoritative logic is defined by numeric predicates and balance constants. The UI may label values as safe, caution, or critical, and those labels may be used to explain forecasts, but implementation must evaluate the underlying numeric values. +Leak injection magnitudes are balance data and may depend on local carrier amount, pressure, or voltage. -### Projection For Readability +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` +- `FuelSafe`, `FuelCaution`, `FuelCritical` +- `CoolantSafe`, `CoolantCaution`, `CoolantCritical` +- `ElectricitySafe`, `ElectricityCaution`, `ElectricityCritical` +- `HeatSafe`, `HeatCaution`, `HeatCritical` -Projection rules: +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. -- labels are derived from balance-defined UI thresholds -- labels do not change stored simulation values -- wall cells do not participate as surface hazard cells -- closed doors block surface neighbor interaction across their authored edge -- leaks first emit their carrier into their accessible floor cell through `InjectLeak[n]` -- active elemental remedy blocks prevent the matching element from entering the protected floor cell -- flow props, junctions, and consumers act before the local surface interaction pass -- level state is derived after local interactions -- robot state is resolved after local interactions, using final local hazard values and active heat immunity - -## Simulation Order - -The simulation loop for one turn is: - -1. Resolve player actions. -2. Apply scheduled start-of-turn events that explicitly occur before flow. -3. Apply `FeedFromOutside[n]` for every enabled flow prop. -4. Propagate carrier amount plus pressure or voltage through each underground network using distance falloff and junction ratios. -5. Apply `ConsumeFromNetwork[n]` or `StarveConsumer[n]` for every enabled consumer. -6. Apply `InjectLeak[n]` for every leaking underground cell, respecting active matching remedy blocks. -7. For every floor cell, evaluate local numeric predicates between leaked surface values and heat. -8. For every floor cell, evaluate numeric predicates against right and bottom floor neighbors when no closed door blocks the edge. -9. Emit the corresponding interaction events from the condition table summary. -10. Apply all emitted deltas in a deterministic order. -11. Clamp all values with `ClampValues`. -12. Update robot state from the final floor cell it occupies and any active heat immunity. -13. Derive level state from required services, reactor prerequisites, forecasts, and terminal conditions. -14. Advance scheduled turn events, remedy block durations, and heat immunity duration. - -If multiple events modify the same value in one step, their deltas are accumulated before clamping unless a specific event states that it consumes, reserves, or blocks a value earlier in the order. - -## Pair Event Legend - -The symmetric condition table uses the following event names: +Pair event legend: - `Hold`: no direct change. -- `FuelFlow`: apply `Equalize[Fuel]`. -- `CoolFlow`: apply `Equalize[Coolant]`. -- `ChargeFlow`: apply `Equalize[Electricity]`. -- `HeatFlow`: apply `HeatTransfer` with normal magnitude. -- `HeatFlow2`: apply `HeatTransfer` with stronger magnitude. -- `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 floor cells -- same-carrier leaked surface amounts equalize between neighboring floor cells -- doors and active remedy blocks are local gates on these interactions - -## Symmetric Pair Condition Table - -Rows and columns are identical projected UI labels. Only the upper-right triangle is filled. The lower-left triangle is intentionally empty because the table is symmetric. +- `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 | | ------- | -------- | ----------- | ------------ | ----------- | -------------- | --------------- | --------------- | ------------------ | ------------------- | -------- | ----------- | ------------ | @@ -751,126 +527,176 @@ Rows and columns are identical projected UI labels. Only the upper-right triangl | HeatCaution | | | | | | | | | | | Hold | HeatFlow | | HeatCritical | | | | | | | | | | | | Hold | -## Prop Rules +Design intent: -Props do not appear as participants in the pair condition table. They are controls, access points, or resources on floor cells. +- 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 -Flow prop rule: +## Rule Events -- if enabled, the prop allows `FeedFromOutside[n]` -- if disabled, its bound source does not inject supply +V1 supports deterministic rule-triggered events. -Junction prop rule: +Each rule event stores: -- T-junctions regulate two outgoing branch ratios -- cross-junctions regulate three outgoing branch ratios -- junctions are the only flow regulation controls -- ratio math is balance data +- enabled state +- once or repeat behavior +- priority/order +- predicate list +- effect list +- optional player-facing forecast text -Consumer prop rule: +All predicates in the predicate list must pass for the event to trigger. -- if enabled and supplied, it consumes demand and produces service -- if enabled and unsupplied, it triggers `StarveConsumer[n]` -- if disabled, it neither consumes, produces, nor starves -- a disabled required consumer blocks readiness -- consumer toggling changes demand but does not alter junction outflow ratios +Supported predicate families: -Door prop rule: +- 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 -- if open, surface hazards propagate normally -- if closed, surface hazards and heat do not cross the door edge -- closed doors do not block underground flow +Supported effects: -Terminal prop rule: +- 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 -- interacting with the all-seeing-eye terminal unlocks underground inspection for the level -- no other action or prop grants full underground inspection +Rule events must be deterministic and forecastable. Random predicates and random effects are not part of v1. -Remedy supply prop rule: +## Simulation Order -- interacting with a supply prop adds its fixed remedy type to inventory if capacity allows -- the prop is depleted after one successful pickup +The simulation loop for one completed turn is: -## Robot Rules +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. -The robot is intentionally simple. +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. -- The robot moves only on floor cells. -- The robot cannot occupy wall cells. -- The robot can interact with the prop on its current floor cell. -- The robot can interact with fuel and coolant leaks from their broken floor cell. -- The robot can interact with electricity wall leaks while standing on their stored floor emission face. -- A move into a wall or forbidden cell changes the robot to `Blocked`. -- A move into or continued presence in a cell whose final hazard values exceed robot safety predicates changes the robot to `Damaged` unless active protection applies. -- Heat immunity prevents heat-caused robot damage while active, but it does not remove heat. -- Elemental remedies are inventory items and must be applied intentionally. -- Interacting with a prop, leak, hazard, or reactor changes the robot to `Interacting` until the action resolves. -- Robot safety predicates are balance data. The design does not require them to match UI band thresholds exactly. +## Forecasts -## Level Rules +V1 forecasts guarantee: -Level state is derived after each simulation step. +- 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 -Derivation: +Forecasts are deterministic simulations over copied state. Forecasting must not mutate the actual level. -- `Stable`: no terminal forecast is near, reactor heat is controlled, and the facility is not actively degrading. -- `Caution`: at least one required service is missing, a required consumer is starved or disabled, a hazard is growing, or reactor-adjacent heat is concerning. -- `Critical`: forecasts predict terminal loss without near-term intervention, or reactor heat is close to terminal. -- `Ready`: all required consumers are producing service and the reactor area is below terminal conditions. -- `Lost`: a scripted terminal rule, terminal reactor heat condition, or explicit unrecoverable state fires. +The forecast horizon is balance data. -`Ready` is reversible before activation. If a required consumer is disabled, starved, disconnected, or no longer producing service, `ClearReady` derives the appropriate non-ready state. +## Validation -## Strategic Interactions +The editor must block run and save when validation errors exist. Warnings may allow save/run but must be visible. -The flow and remediation mechanics should create tactical decisions without hidden randomness. +Validation errors: -Examples: +- 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 -- A fuel leak on a high-pressure branch can be stabilized locally with a fuel neutralizer, but the leak will remain a problem unless repaired or routed away from. -- A coolant spill mixed with electricity requires multiple element-specific remedies, or the player can close a door and change junction ratios before entering. -- A heat-shielded robot can cross a hot corridor for a limited number of steps, but the heat remains a continuing forecast problem. -- A wall electricity leak can be made less dangerous by routing voltage away through a junction, or by spending an electricity neutralizer at the spark face. -- Closing a door can protect a repaired corridor from renewed hazard spread while the player commits actions elsewhere. -- Disabling a consumer can stop demand while the player repairs or reroutes, but it also prevents the level from becoming `Ready`. +Validation warnings: -## Design Pillars +- 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 -### Deterministic Systems +## Editor Requirements -The same actions in the same state always produce the same result. +The v1 editor must be able to author every v1 concept: -### Visible Consequences +- 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 player sees exact local values, UI labels, global state, forecasted consequences, and underground state after all-seeing-eye access. +The editor always shows all layers. Gameplay preview may include a locked/unlocked diagnostic display mode, but authoring is never hidden from the designer. -### Meaningful Tradeoffs +The editor save command must run validation and refuse to save on errors. -Spending a remedy provides immediate local stability once. Adjusting junctions, repairing leaks, and restoring flow provide longer-term stability but require more commitment. +## Serialization -### Small Formal Core +V1 level files use serialization version `1`. -The simulation should be explainable as: +The serialized schema stores: -- static floor/wall terrain -- underground network topology -- numeric pressure and voltage flow -- ratio-based junction routing -- reachable leak emission -- surface hazards gated by doors and remedies -- derived global level state +- 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 -### Extensible Later +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. -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 deterministic readability and forecastability. +## Balancing Data -## Remaining Design Gaps - -No implementation-blocking design gaps are intentionally left open. - -The following values are deliberately assigned to balancing rather than fixed in this document: +The design deliberately assigns these values to balancing: - source strengths +- carrier amount falloff - pressure and voltage falloff - ratio-to-flow math - consumer demand predicates @@ -883,20 +709,43 @@ The following values are deliberately assigned to balancing rather than fixed in - remedy block duration - heat immunity duration - action costs beyond the default one-action rule +- forecast horizon -Implementation should expose these as balance data and tests should assert behavior against configured constants rather than hardcoded design numbers. +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 -The design reduces the simulation to a small layered system: +V1 reduces Reactor Maintenance to a small deterministic formal core: -- static floor and wall cells -- three disjunct underground networks -- exact numeric carrier, pressure, voltage, leak, and heat values -- flow, consumer, junction, door, terminal, and remedy props -- reachable leak rules for floor pipe bursts and wall cable sparks -- UI bands as labels rather than simulation truth -- one deterministic condition table summary backed by numeric predicates -- one derived global level state +- 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 -That gives a solid basis for a deterministic simulation that can be visualized, forecast, balanced, and extended without reintroducing hidden complexity. +This is the implementation target for replacing the prototype simulation, tests, and editor.