Skip to main content

Per-reactor diagnostic files

Mod version shipped with FlammiCraft: 0.556.0

Reactor history · Check startup conditions · Deutsch

Find the cause of a trip

  1. Keep cooling running. At the linked Control Desk, hover over AUTO SCRAM. Note the trigger, cause, time and controller position. Open Log for the sequence and readings around the trip.
  2. If that is insufficient, enable capture before the next attempt. On a dedicated server, use the server's game directory.
  3. Match the controller position in the file header. Keep the parts covering the action and the readings just before and after it.

Enable recording

Record only for the time you need. The mod starts a new file part at 32 MiB and keeps the old parts. Disk use grows with the number of loaded reactors and the length of the capture. Set the option back to false when finished. The writer flushes accepted records and keeps the existing files.

Enable recording in the world's effective nucleus-server.toml.

[monitoring]
reactorDiagnostics = true

The default is false. Edit the existing section; do not add a second [monitoring] table. Let the server reload its config or apply the change at the next manual server start. No extra config file is needed. The desk's action history remains independent of diagnostic recording.

Each loaded controller receives a saved UUID when first recorded. Files appear under logs/nucleus/ in the running server or single-player client's game directory, named reactor-<uuid>_<utc-timestamp>_<part>.log. Each header identifies the world, dimension, controller position, mod version and effective common/server settings. Unload/reload, switching recording back on, config reload and server restart start a new capture with the same ID. A newly placed controller receives a new ID; /reactorreset retains the reset controller's ID.

Each line is a JSON record with UTC time and world tick, requested rod percentage, actual regulating and shutdown banks, power, reactivity contributions, xenon, iodine, samarium, boron, fuel temperatures, decay heat, cached cooling measurements and their original tick, supply, protection masks and actions/actors. Simple and realistic model data are labelled separately; each line states the physics mode. Non-finite numbers are recorded as null. Recording does not load chunks or initialize a simulation. Cooling data comes from the last normal simulation read.

Complete state captures since schema 2

Fast readings remain at five-tick intervals. The first record, records at least every 20 ticks and operator actions also contain a complete checkpoint. At 20 TPS this means four fast readings and at least one checkpoint per second. Loaded setup data is refreshed after 40 ticks or a normal reactor scan; its own tick identifies its age. Unloading does not trigger another setup read.

Field Contents
controller_saved_snbt Complete controller save, including inherited behaviours, action history, alarms, reserves and saved model state. SNBT is Minecraft's text representation of NBT and retains types and extra data.
controller_save_complete Whether this export completed. A failed export includes controller_save_error; its saved text is only a partial capture.
fluid_tanks All seven tanks, including the normally unsaved internal steam tank: fluid registry ID, mB, capacity, empty flag and complete stack SNBT with components. Codec failures appear as stack_serialization_error.
core_layout Width, depth, moderation, leakage, peaking, rod coverage, layout reactivity and each column's power factor and uncovered fraction. columnKind: 0 coolant, 1 graphite, 2 fuel, 3 rod; index x + z*width.
plant_model / simple_model Complete internal simulation state: targets and actual rods, six delayed neutron groups, kinetics, fuel/cladding nodes, iodine/xenon, samarium/promethium, decay heat groups, boron, feedback, boiling crisis, damage, random state and submodels. Existing models unused in the current mode remain visible.
physics_readout / physics_history Last calculated physics values and operating history; cached values are not extra calculations.
safety_agent ARGUS input history, outputs, thresholds, delays and learning/network state.
physical_vessel / physical_containment / physical_power Physical water, energy, gas and supply state, including derived caches.
runtime Controller data not fully saved: scanned position lists, rod/port positions, heat/steam accumulators, transitions, boiler reports, holds, scan flags and alarm delays.
setup.reactor Loaded three-dimensional block layout, exact registry IDs and properties, world fluid states, counts by block type and saved data of this mod's block entities. Rod, nozzle and pump data stays associated with its position.
setup.generator Linked loaded steam generator: full saved/circuit state, fluid stacks, known hot/cold pipe segments, pump directions, tanks, buffers, ports and their loaded block/device data.

The block map uses a palette. cells holds palette indices in the order x + z*width + y*width*depth, relative to min. -1 means unloaded, never air. complete only confirms the requested block cells were readable, not that the reactor is valid. Also check own_block_entity_data_complete, device statuses, assembled and the actual structure problem. Unknown or excessive bounds are not expanded. Foreign block entities are identified by type without serializing their private inventories. Generator pipe data describes its last recognized segments; recording does not rescan every remote pipe block. Missing generator chunks are marked unloaded.

Headers also list loaded mod versions and hashes of the controller, generator and logger class resources. These identify delivered code, not changes applied later by other mixins. capture_sequence orders records within a capture. A new file part can include checkpoint_context.source, the last complete capture with its original tick. This context is not a new measurement.

Reading fluid types

The fuel tank normalizes accepted fuel solutions to one internal fluid type. Actual mean enrichment and MOX share are separate controller fields; the fluid ID alone does not describe the mixture. An executed fuel_input event therefore records the original stack, enrichment, MOX flag and actually accepted mB before normalization. Transport simulations are not recorded as completed fills. Likewise, visible world water inside the core does not establish that the primary circuit contains ordinary water: check tank stacks and generator state.

Deciding between instructions and code changes

First match code versions, operating mode and effective settings. Then compare the setup, moderator/fuel positions, rod coverage, fluid mixture, power supply and cooling circuit with the building and operating instructions. An unknown chunk or old cached capture does not establish a missing block or a current reading. Fill documentation gaps from the confirmed setup.

For a power jump, compare records before and after the action: requested rods, model target, actual rods, reactivity contributions, kinetics, temperature, poisons and protection response. Keep UTC time, world ticks and accelerated model time separate. Use that evidence to decide whether instructions are missing or a reproducible code bug or optimization needs work.

Samples are taken every five server ticks, four per second at 20 TPS; actions and random controller incidents add records. For the 60 to 59 percent case, enable before startup and keep the steady operation and subsequent change in the same recording, then retain the relevant parts. The logger does not move rods. Diagnose the power rise from the captured data rather than assuming its cause.

A separate writer uses a bounded queue. Overload warns in latest.log, and the next written record reports queue_overflow and the missing record count. An I/O error stops that capture with a message while simulation continues; after fixing the cause, switch recording off and back on. Normal server shutdown allows five seconds to drain accepted records and reports a timeout/interruption. A process crash can leave the last part incomplete.

Recording leaves physics settings, fuel and coolant as they are. The new controller UUID remains saved.

Complete captures are much larger than scalar readings and are copied on the server thread for a consistent state; only file output runs in the background. Queued text is additionally limited to 64 MiB. Overload or an oversized record is reported as a gap. A single complete capture or its retained context can exceed the part-size threshold; captures are not truncated.

File output, error paths and state preservation have offline regression coverage. A recording of an actual running plant and the cause of the reported power rise remain unverified without an appropriate game/server capture.