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

Document coolant sprinkler evaporation design

Browse Source
This commit is contained in:
Frank Tovar
2026-05-14 00:36:08 +02:00
parent 7777800a5d
commit 57dd5d1e36
2 changed files with 82 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/UX.md
View File

@@ -163,10 +163,10 @@ Primary controls:
- selected cell coordinates
- terrain and prop summary
- underground values when visible through terminal access
- visible hazards with safe/caution/critical bands
- visible hazards, sprinkler water, and wet-electricity risk with safe/caution/critical bands
- forecast warnings
- `ActionBar`
- contextual action buttons: move, interact, repair, remedy, heat shield, activate reactor
- contextual action buttons: move, interact, activate sprinkler valve, repair, remedy, heat shield, activate reactor
- disabled buttons must show why the action is unavailable
- `InventoryPanel`
- fuel neutralizer count
@@ -178,7 +178,7 @@ Behavior:
- Selection and inspection are quick actions and must not trigger a pulse.
- Movement is a quick action and must update robot position without triggering a pulse.
- Interact, repair, remedy, and heat shield are environment-changing actions and must trigger one animated pulse when accepted.
- Interact, sprinkler valve activation, repair, remedy, and heat shield are environment-changing actions and must trigger one animated pulse when accepted.
- Activate reactor must be visually prominent when ready and should resolve immediately without requiring a wait or extra pulse.
- Invalid actions should produce a short refusal message and not mutate level state.
- When the level state becomes `Lost`, show `LoseOverlay`.
@@ -187,7 +187,10 @@ Behavior:
Pulse playback behavior:
- During a pulse, animate the configured steps as one short cascade of hazard motion, leak growth, quenching, ignition, shorts, and readiness updates.
- During a pulse, animate the configured steps as one short cascade of hazard motion, leak growth, quenching, evaporation, ignition, electrical conduction, and readiness updates.
- Sprinkler valve activation must visibly release blue sprinkler water at authored outlet cells and show the affected coolant service area losing pressure.
- Evaporation must be communicated through shrinking wet overlays and stronger steam/cooling feedback on hot cells.
- Wet cells that can spread electricity must use a distinct warning treatment so the player can distinguish helpful suppression water from dangerous electrified water.
- Disable conflicting action commands while pulse playback is running so the player cannot queue hidden actions into an unresolved environment state.
- Present the final post-pulse state as the next decision point.
- Do not make pulse length vary by action type, forecast outcome, or danger level.
@@ -302,7 +305,7 @@ Controls:
Behavior:
- Keep tutorial text focused on action economy, pulses, hazards, forecasts, remedies, and reactor activation.
- Keep tutorial text focused on action economy, pulses, sprinkler suppression, evaporation, wet-electricity hazards, forecasts, remedies, and reactor activation.
- Tutorial level can reuse `LevelScreen` with a tutorial mode flag and guided prompts.
## Reusable Controls
@@ -310,7 +313,7 @@ Behavior:
- `PrimaryButton`: consistent command button style and focus behavior.
- `StateBadge`: color-coded label for `Stable`, `Caution`, `Critical`, `Ready`, `Lost`, and `Won`.
- `LevelHeader`: level metadata, global state, and campaign progress.
- `CellInspector`: selected cell details, visible hazards, prop state, underground details when available.
- `CellInspector`: selected cell details, visible hazards, sprinkler water, wet-electricity risk, prop state, underground details when available.
- `ForecastList`: ordered warnings from soonest to latest pulse.
- `InventoryStrip`: remedy and heat shield counts.
- `OutcomeOverlay`: shared base layout for win and loss overlays.
@@ -333,9 +336,10 @@ Keep repeated controls as separate scenes so the level screen, tutorial, and ove
- Use restrained panels and clear hierarchy: grid first, status second, supporting details third.
- Color roles:
- fuel: red
- coolant: blue
- coolant/sprinkler water: blue
- electricity: yellow
- heat: orange or white-hot accent
- wet-electricity risk: yellow over blue or a distinct charged-water pattern
- safe: neutral or green
- caution: amber
- critical/lost: red
@@ -352,5 +356,6 @@ Keep repeated controls as separate scenes so the level screen, tutorial, and ove
- Final campaign win reaches `GameWonScreen`.
- Full failure endpoint reaches `GameOverScreen`.
- The level screen distinguishes quick actions from lengthy actions.
- The level screen makes sprinkler valve outlets, evaporation, and wet-electricity risk readable before and after a pulse.
- Forecasts, inventory, selected cell inspection, and global level state have dedicated UI space.
- Documentation stays aligned with `docs/design.md` when simulation rules change.

99
docs/design.md
View File

@@ -10,7 +10,7 @@ The simulation core is built from:
- underground fuel, coolant, and electricity networks,
- surface props for controls, terminals, supplies, doors, and reactor activation,
- consumers that consume whichever underground services exist under their cell,
- reachable leaks that project hazards onto floor cells,
- reachable leaks and sprinkler valves that project hazards or suppression water onto floor cells,
- transport network structural integrity,
- deterministic fixed simulation rules and forecasts.
@@ -72,7 +72,7 @@ The player can always inspect:
- surface terrain,
- surface props and visible prop state,
- visible leaks and repair faces,
- visible surface hazards,
- visible surface hazards and sprinkler water,
- door state,
- remedy inventory and supply props,
- consumer state: disabled, starved, supplied, producing, or unknown,
@@ -120,7 +120,7 @@ Same-carrier underground cells connect by inferred cardinal adjacency.
Surface floor cells store:
- leaked fuel,
- leaked coolant,
- sprinkler water from coolant discharge,
- leaked electricity,
- heat,
- active elemental remedy blocks.
@@ -148,6 +148,7 @@ Surface prop categories:
- door prop,
- all-seeing-eye terminal prop,
- remedy supply prop,
- coolant sprinkler valve prop,
- reactor control prop.
Props exist on floor cells. Props do not directly participate in the surface hazard pair table.
@@ -206,6 +207,21 @@ Door blocking is evaluated by the door cell and its inferred corridor axis:
- open doors do not block surface interaction,
- door props on invalid terrain or with ambiguous opposing walls are validation errors.
### Coolant Sprinkler Valves
A coolant sprinkler valve is a surface prop that intentionally releases coolant as sprinkler water onto authored outlet floor cells. It exists to let the player trade local fire suppression for reduced coolant service.
Valve behavior:
- activating a valve is a lengthy action and triggers one pulse,
- the valve adds a balance-defined amount of sprinkler water to each authored outlet cell,
- every outlet must be a valid floor cell,
- the valve must be connected to a present coolant network cell,
- discharge creates a local coolant pressure drop for the pulse and can starve nearby or downstream coolant consumers or the reactor feed,
- discharge does not repair coolant pipe damage and does not permanently disable the coolant network.
The local pressure drop is deterministic and spatial. It should be derived from the valve's connected coolant network branch so that the player can understand why nearby consumers or reactor feed become insufficient after a sprinkler use.
### Terminals And Supplies
An all-seeing-eye terminal allows full underground inspection when visited.
@@ -219,16 +235,18 @@ Remedy supply props are single-use pickups:
Each supply provides one matching inventory item and then becomes depleted.
## Leaks And Remedies
## Leaks, Sprinklers, And Remedies
Each leak stores carrier type, underground coordinate, accessible floor coordinate, and repair state.
Fuel and coolant leaks:
Fuel leaks:
- occur under floor cells,
- use the same coordinate as their accessible floor coordinate,
- can be repaired or remediated by the robot standing on that floor cell.
Coolant pipe failures use the same reachable-access rules as fuel leaks for repair, but their surface output is treated as sprinkler water rather than as a generic damaging liquid. Authored puzzles should prefer coolant sprinkler valves for intentional player-triggered coolant release.
Electricity leaks:
- occur in wall cells,
@@ -275,19 +293,22 @@ Leaking underground cells remain part of network propagation.
During leak injection:
- fuel leaks add leaked fuel to the accessible floor cell,
- coolant leaks add leaked coolant to the accessible floor cell,
- coolant pipe failures and sprinkler valves add sprinkler water to valid floor cells,
- electricity leaks add leaked electricity to the stored floor emission face,
- active matching remedy blocks prevent matching element entry.
Injection magnitude is balance data and may depend on local carrier amount, pressure, or voltage. If the target floor cell has an active matching remedy block, that matching element is not injected into the cell for that step. Remedy blocks do not block other elements or heat.
After injection, the engine evaluates local interactions between leaked fuel, leaked coolant, leaked electricity, and heat on the same floor cell and across unblocked adjacent floor cells.
After injection and sprinkler discharge, the engine evaluates local interactions between leaked fuel, sprinkler water, leaked electricity, and heat on the same floor cell and across unblocked adjacent floor cells.
Surface interaction resolution is deterministic:
- same-cell interactions evaluate every unordered quantity pair on each floor cell,
- coolant mitigation evaluates before ignition and electrical spread on each floor cell,
- same-cell interactions then evaluate every unordered quantity pair on each floor cell,
- adjacent interactions evaluate every unordered pair of adjacent floor cells once,
- same-carrier leaked fuel, coolant, electricity, and heat equalize across adjacent floor cells using `Flow(amount)`,
- same-carrier leaked fuel, sprinkler water, electricity, and heat equalize across adjacent floor cells using `Flow(amount)`,
- wet floor cells spread electricity faster than dry floor cells,
- sprinkler water evaporates every step using ambient evaporation plus heat-driven evaporation,
- wall cells never store surface hazards and do not participate,
- closed doors and remedy blocks gate the interactions they explicitly block,
- deltas accumulate during an interaction pass and are applied together before clamping.
@@ -305,19 +326,21 @@ The pair table maps projected bands to parameterized verbs:
- `Hold`: no direct change,
- `Flow(amount)`: equalize a surface quantity by a balance-defined transfer amount,
- `Dilute(amount)`: reduce fuel by a balance-defined amount,
- `Warm(amount)`: increase heat by a balance-defined amount,
- `Quench(amount)`: reduce heat by a balance-defined amount,
- `Short(heat, discharge)`: add heat and discharge electricity by balance-defined amounts,
- `Evaporate(amount, cooling)`: reduce sprinkler water and reduce heat by balance-defined amounts,
- `Conduct(multiplier)`: spread electricity through wet floor cells faster than normal adjacent electrical flow,
- `Ignite(heat, fuel)`: add heat and consume fuel by balance-defined amounts.
| Row\Col | FuelSafe | FuelCaution | FuelCritical | CoolantSafe | CoolantCaution | CoolantCritical | ElectricitySafe | ElectricityCaution | ElectricityCritical | HeatSafe | HeatCaution | HeatCritical |
| ------- | -------- | ----------- | ------------ | ----------- | -------------- | --------------- | --------------- | ------------------ | ------------------- | -------- | ----------- | ------------ |
| FuelSafe | Hold | Flow | Flow | Hold | Hold | Hold | Hold | Warm | Ignite | Hold | Warm | Ignite |
| FuelCaution | | Hold | Flow | Hold | Hold | Hold | Warm | Ignite | Ignite | Warm | Ignite | Ignite |
| FuelCritical | | | Hold | Hold | Hold | Hold | Ignite | Ignite | Ignite | Ignite | Ignite | Ignite |
| CoolantSafe | | | | Hold | Flow | Flow | Hold | Short | Short | Hold | Quench | Quench |
| CoolantCaution | | | | | Hold | Flow | Short | Short | Short | Hold | Quench | Quench |
| CoolantCritical | | | | | | Hold | Short | Short | Short | Hold | Quench | Quench |
| FuelSafe | Hold | Flow | Flow | Hold | Dilute | Dilute | Hold | Warm | Ignite | Hold | Warm | Ignite |
| FuelCaution | | Hold | Flow | Dilute | Dilute | Dilute | Warm | Ignite | Ignite | Warm | Ignite | Ignite |
| FuelCritical | | | Hold | Dilute | Dilute | Dilute | Ignite | Ignite | Ignite | Ignite | Ignite | Ignite |
| CoolantSafe | | | | Hold | Flow | Flow | Hold | Conduct | Conduct | Hold | Quench | Quench |
| CoolantCaution | | | | | Hold | Flow | Conduct | Conduct | Conduct | Quench | Quench | Quench |
| CoolantCritical | | | | | | Hold | Conduct | Conduct | Conduct | Quench | Quench | Quench |
| ElectricitySafe | | | | | | | Hold | Flow | Flow | Hold | Hold | Hold |
| ElectricityCaution | | | | | | | | Hold | Flow | Hold | Hold | Hold |
| ElectricityCritical | | | | | | | | | Hold | Hold | Hold | Hold |
@@ -325,17 +348,28 @@ The pair table maps projected bands to parameterized verbs:
| HeatCaution | | | | | | | | | | | Hold | Flow |
| HeatCritical | | | | | | | | | | | | Hold |
Blank lower-triangle entries mirror the corresponding upper-triangle entry. Fuel and coolant do not directly react with each other; leaked coolant plus leaked fuel is `Hold` unless another pair on that cell or an adjacent cell involves heat, electricity, or same-carrier flow.
Blank lower-triangle entries mirror the corresponding upper-triangle entry.
Design rules:
- fuel becomes dangerous through electricity or heat,
- coolant becomes dangerous through electricity,
- coolant opposes heat,
- coolant is a sprinkler suppression system,
- coolant dilutes fuel before ignition is checked,
- coolant quenches heat and never directly increases heat,
- coolant becomes dangerous when electricity reaches wet cells,
- wet cells conduct electricity faster than dry cells,
- sprinkler water evaporates over time, with hot cells evaporating faster than cold cells,
- heat equalizes between neighboring floor cells,
- same-carrier leaked surface amounts equalize between neighboring floor cells,
- doors and remedy blocks gate local interactions.
Evaporation is value-based, not a fixed-duration wetness timer:
1. Every step computes evaporation from `AmbientEvaporationPerStep + (surface heat * HeatEvaporationScale)`.
2. Evaporation is capped by the current sprinkler water amount on the cell.
3. Evaporated sprinkler water reduces heat by `evaporated amount * EvaporationCoolingScale`, clamped at zero heat.
4. Heat-driven evaporation can remove wetness quickly from hot cells, while ambient evaporation slowly clears cold wet cells.
## Structural Integrity
Structural integrity is resolved after network propagation and before leak injection. It is deterministic and uses balancing values:
@@ -354,7 +388,7 @@ For every present underground cell:
Automatic leak access follows the same rules as authored leaks:
- fuel and coolant leaks use the underground cell as their floor access and can only auto-start under floor cells,
- fuel leaks and coolant pipe failures use the underground cell as their floor access and can only auto-start under floor cells,
- electricity leaks require one adjacent floor access face; if multiple valid faces exist, the deterministic order is north, east, south, west,
- if no valid floor access exists, the weakened cell remains damaged but no reachable leak state is created.
@@ -368,7 +402,7 @@ Data-driven rule predicates and effects are not part of level data. Effects happ
- network propagation clears transient amount and intensity, then recomputes flow from enabled sources,
- consumer resolution derives per-carrier service states from present underground layers,
- structural integrity resolution weakens damaged high-pressure cells and creates leaks from low-integrity positive-pressure cells,
- leak injection adds carrier hazards to valid floor access cells,
- leak injection and sprinkler discharge add carrier hazards or sprinkler water to valid floor access cells,
- surface interaction resolution spreads and reacts hazards according to the hazard pair table,
- robot safety resolves terminal loss from unsafe final hazard states after surface interactions,
- reactor state derives readiness or terminal heat loss,
@@ -394,11 +428,13 @@ One accepted lengthy interaction resolves one pulse in this order:
Each step inside the pulse resolves in this order:
1. Inject leaks fractionally for this step.
2. Evaluate same-cell surface interactions.
3. Evaluate adjacent floor interactions across unblocked door cells.
4. Accumulate and apply deltas in deterministic priority order.
5. Clamp values.
1. Inject leaks and sprinkler discharge fractionally for this step.
2. Resolve coolant mitigation against fuel and heat.
3. Resolve evaporation and latent cooling.
4. Evaluate same-cell surface interactions, including ignition and electrical conduction.
5. Evaluate adjacent floor interactions across unblocked door cells.
6. Accumulate and apply deltas in deterministic priority order.
7. Clamp values.
## Forecasts
@@ -410,6 +446,8 @@ Forecast output includes:
- reactor ready forecasts,
- starved required consumer warnings,
- growing hazard warnings when values cross caution or critical bands,
- wet-electricity spread warnings,
- coolant pressure-drop warnings from sprinkler valve use,
- structural integrity leak warnings when weakened cells are expected to leak.
Forecast timing is reported in pulses, for example `Pulse +2`. The forecast horizon is balance data.
@@ -427,6 +465,7 @@ Validation errors:
- invalid required consumer counts,
- invalid door cell,
- invalid leak access,
- invalid coolant sprinkler valve outlet or missing coolant network connection,
- junction without exactly one underground carrier,
- ambiguous junction flow,
- network loop or equal-source ambiguity at a junction,
@@ -439,6 +478,7 @@ Validation warnings:
- initially starved required consumer,
- initially unready reactor,
- unused remedy supply,
- sprinkler valve with no useful suppression target,
- visible hazard with no detectable nearby remedy or route.
## Editor And Schema
@@ -452,10 +492,11 @@ The editor authors:
- required fuel, coolant, and electricity consumer counts,
- junction props and balance-defined ratio mode index,
- door props,
- coolant sprinkler valves and their authored outlet cells,
- all-seeing-eye terminals,
- remedy supplies,
- floor leaks and electricity wall leaks with authored access faces,
- initial surface hazards and heat,
- initial surface hazards, sprinkler water, and heat,
- robot start position.
The editor includes layer selection for Surface, Electricity, Fuel, and Coolant:
@@ -474,6 +515,6 @@ The loader accepts only schema-valid level data and returns clear errors for mal
## Balancing And Tests
Balancing defines source strengths, falloff, ratio math, consumer predicates, leak magnitudes, structural integrity thresholds and damage scale, interaction magnitudes, display thresholds, robot safety thresholds, terminal heat thresholds, inventory capacity, remedy duration, heat immunity duration, and forecast horizon.
Balancing defines source strengths, falloff, ratio math, consumer predicates, leak magnitudes, sprinkler discharge, coolant pressure drops, evaporation, wet-electricity conduction, structural integrity thresholds and damage scale, interaction magnitudes, display thresholds, robot safety thresholds, terminal heat thresholds, inventory capacity, remedy duration, heat immunity duration, and forecast horizon.
Tests assert behavior against configured balance values and bands. Coverage includes validation, inferred connectivity, junction effects, multi-service consumer states, reactor readiness and activation, terminal loss, robot hazard loss, heat immunity, structural integrity degradation and leak creation, leak access, remedies, door blocking, forecasts, and serialization round trips.
Tests assert behavior against configured balance values and bands. Coverage includes validation, inferred connectivity, junction effects, multi-service consumer states, reactor readiness and activation, terminal loss, robot hazard loss, heat immunity, structural integrity degradation and leak creation, leak access, sprinkler valves, coolant pressure drops, coolant mitigation, evaporation, wet-electricity spread, remedies, door blocking, forecasts, and serialization round trips.