nucleation 0.10.21 → 0.10.23

package/renderer/TickSimulation.d.mts

@@ -0,0 +1,572 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
+import type { TickSettleMode } from "./TickSettleMode.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * A headless, vanilla-accurate tick simulation of one structure.
+ */
+export class TickSimulation {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Why the last constructor on this thread failed, in words.
+     *
+     * The enum cannot carry a message, and "Simulation" is useless to
+     * someone holding a door that will not load: the engine already knows
+     * it is `minecraft:waxed_copper_bulb` at (4,2,1) and says so here.
+     * Empty when the last construction succeeded.
+     */
+    static lastErrorDetail(): string;
+
+    /**
+     * Largest build this will attempt, in cells.
+     *
+     * A 500x379x442 "door" is a saved world, and loading one exhausts the
+     * wasm heap — after which every later call on that instance traps,
+     * not just the one that overflowed. Refused up front instead.
+     */
+    static maxVolume(): number;
+
+    /**
+     * Load from Java structure SNBT text.
+     *
+     * `extra_states`: semicolon-separated block-state descriptors that
+     * later `place_block` calls may write (behaviours bind at
+     * construction). `minecraft:redstone_block` is always available.
+     * `origin_*`: where the build's (0,0,0) sits in world coordinates —
+     * wire update order hashes absolute positions.
+     *
+     * The text's own `DataVersion` selects `Entity.load` Motion semantics,
+     * exactly as {@link TickSimulation::from_schematic} uses the schematic's —
+     * so `gametest_snbt` → `from_snbt` keeps a nan-cart build's NaN
+     * velocities instead of quietly sanitising them. A text with no
+     * `DataVersion` gets the engine default (the modern, NaN-dropping
+     * rule); read {@link TickSimulation::motion_semantics} to see which
+     * applied.
+     */
+    static fromSnbt(snbt: string, settle: TickSettleMode, originX: number, originY: number, originZ: number, extraStates: string): TickSimulation;
+
+    /**
+     * Load from a schematic (any format nucleation can read), rendered
+     * to gametest-flavor structure SNBT for mc-tick's parser.
+     */
+    static fromSchematic(schematic: Schematic, settle: TickSettleMode, originX: number, originY: number, originZ: number, extraStates: string): TickSimulation;
+
+    /**
+     * GA fast path: construct from a flat genome-cell array — no SNBT
+     * text built or parsed. Corridor layout matches the flying-ga app:
+     * machine at `x_off`, world size `[bx + travel, by + 2, bz + 2]`,
+     * cells flattened `((y * bz) + z) * bx + x`, `air_index` = empty
+     * cell. `palette` is the run's alphabet, semicolon-separated; every
+     * entry is pre-interned so behaviours bind exactly as the SNBT
+     * path's EXTRA_STATES did.
+     */
+    static fromBlocks(bx: number, by: number, bz: number, travel: number, xOff: number, palette: string, cells: Array<number>, airIndex: number, settle: TickSettleMode, originX: number, originY: number, originZ: number): TickSimulation;
+
+    /**
+     * Evaluate a whole batch of kicked flights inside the engine — one
+     * wasm call per generation chunk instead of a dozen boundary calls
+     * per machine. `cells` holds N genomes concatenated (each
+     * `bx*by*bz` entries), `kicks` N structure-space `[x,y,z]` triples.
+     * The flight protocol, probe schedule and gait detection mirror the
+     * app's evalCore exactly; `early_exit` stops provably-frozen
+     * machines at tick 40 without changing any reported value. Writes
+     * JSON rows `[n0, startCom, startMinX, startMaxX, comAtMoveCheck |
+     * null, comAtMid, period, n1, endCom, endMinX, endMaxX]`.
+     */
+    static evalFlightBatch(bx: number, by: number, bz: number, travel: number, xOff: number, palette: string, cells: Array<number>, airIndex: number, kicks: Array<number>, evalTicks: number, seed: bigint, mustMoveByTick: number, needPeriod: boolean, earlyExit: boolean): string;
+
+    /**
+     * Seed the vanilla random source (`java.util.Random`'s LCG,
+     * bit-for-bit). Unseeded, jittering behaviours use each
+     * distribution's mean — fully deterministic, no noise.
+     */
+    setRngSeed(seed: bigint): void;
+
+    /**
+     * Advance one game tick.
+     */
+    step(): void;
+
+    /**
+     * Advance `ticks` game ticks.
+     */
+    run(ticks: number): void;
+
+    /**
+     * Run until nothing is scheduled or `budget` ticks pass. Returns
+     * whether the world went quiet.
+     */
+    runUntilQuiescent(budget: number): boolean;
+
+    /**
+     * Game ticks elapsed since settle.
+     */
+    tickCount(): number;
+
+    /**
+     * Whether nothing is scheduled or queued.
+     */
+    isQuiescent(): boolean;
+
+    /**
+     * Right-click a block with an empty hand (lever, button, note block).
+     */
+    useBlock(x: number, y: number, z: number): void;
+
+    /**
+     * Write a block state (`minecraft:air` breaks). The state must be in
+     * the structure, in `extra_states`, or `minecraft:redstone_block`.
+     */
+    placeBlock(x: number, y: number, z: number, state: string): void;
+
+    /**
+     * The block state descriptor at a position (`minecraft:air` for empty).
+     */
+    getBlock(x: number, y: number, z: number): string;
+
+    /**
+     * Batched block-state reads: `positions_json` is `[[x,y,z], ...]`,
+     * the answer a JSON array of descriptors in the same order
+     * (`"minecraft:air"` for empty).
+     *
+     * A verification sweep over a computational build is thousands of
+     * probe reads per settle; one boundary call per sweep instead of one
+     * per probe is the difference between the FFI being the throughput
+     * ceiling and not.
+     */
+    readProbes(positionsJson: string): string;
+
+    /**
+     * Who powers this cell and why — a power-source tree from the
+     * simulation's current state, as JSON.
+     *
+     * Each node carries `pos`, `state`, `kind` (`wire` / `conductor` /
+     * `source` / `block`), the `power` the cell carries or emits, and
+     * `inputs`: the per-side contributions that explain it, each with a
+     * `mechanism` (`block_signal`, `wire`, `wire_up`, `wire_down`,
+     * `strong`, `signal`), the arriving `power`, and a recursive
+     * `source` node. Cycles stop with `"cycle": true`. Coordinates are
+     * the same structure-local space `get_block` reads.
+     *
+     * This is the static complement of running the sim: an open (a dead
+     * route that settles quiescent) shows up as an empty `inputs` list
+     * exactly where the feed should have been.
+     */
+    conductionTrace(x: number, y: number, z: number): string;
+
+    /**
+     * Write every settled non-air state back into `schematic` — the bulk
+     * form of `{simulate=true}`: settle once, keep the world the engine
+     * ended on. Returns how many blocks changed.
+     *
+     * The schematic's bounding-box minimum corresponds to the
+     * simulation's `(0, 0, 0)`, which is exactly how `from_schematic`
+     * loaded it. A file baked this way carries real wire connections and
+     * power in its palette, loads quiescent under `InWorld`, and renders
+     * correctly in any static consumer. Cells the simulation turned into
+     * air (a popped-off component) are left as the schematic had them.
+     */
+    bakeTo(schematic: Schematic): number;
+
+    /**
+     * Snapshot the entire simulation; returns a checkpoint id.
+     */
+    checkpoint(): number;
+
+    /**
+     * Restore a checkpoint taken earlier on this simulation.
+     */
+    restore(id: number): void;
+
+    /**
+     * Render a schematic as gametest-flavor structure SNBT — the text
+     * `from_snbt` and the corpus/render tooling consume. Lets hosts hand
+     * a converted `.litematic`/`.schem` to the video renderer.
+     */
+    static gametestSnbt(schematic: Schematic): string;
+
+    /**
+     * Report blocks whose behaviour is defined by block-entity data the
+     * file does not carry.
+     *
+     * Some exporters write the blocks and drop the block entities. The
+     * build then loads clean and simulates *wrongly but plausibly*: a
+     * comparator with no `OutputSignal` reads 0, a barrel holding the
+     * item that latched a repeater reads empty, and the door quietly
+     * fails to reset. Two files with identical block arrays get
+     * different verdicts and nothing says why. `0.45_4x4_funnel.schem`
+     * is exactly this — 4 comparators, 2 furnaces, `BlockEntities` of
+     * length 0, while its `.litematic` twin carries all 9.
+     *
+     * This does not refuse the build; it names the doubt so a host can.
+     * JSON: `{"present":N,"missing_total":N,"missing":[{"name":..,
+     * "count":N}],"summary":"..."}` — `summary` is empty when nothing
+     * is missing, and otherwise a sentence fit to show as-is.
+     */
+    static blockEntityAuditJson(schematic: Schematic): string;
+
+    /**
+     * Start (or stop) recording every delivered redstone update.
+     *
+     * Off by default and much larger than the block-change log — a door's
+     * cycle runs several updates per change — so a propagation view asks
+     * for it explicitly and pages with
+     * {@link TickSimulation::updates_json_between}.
+     *
+     * Switching it off keeps what was recorded; use
+     * {@link TickSimulation::clear_updates} to free it.
+     */
+    recordUpdates(on: boolean): void;
+
+    /**
+     * Drop the recorded updates without changing whether recording is on.
+     *
+     * A cycle of a 6x6 door is tens of megabytes of log, so a page that
+     * certifies several builds on one instance needs to release one
+     * before recording the next.
+     */
+    clearUpdates(): void;
+
+    /**
+     * Start recording a run timeline from the current tick.
+     *
+     * A timeline is what makes a span of simulation reviewable after the
+     * fact: block deltas, the inputs that caused them and the piston
+     * strokes they drove, plus one whole-world frame to replay them from.
+     * Off by default — a simulation used for timing should not pay for it.
+     *
+     * Called again, it restarts from the current tick, and the previously
+     * stopped span is released.
+     *
+     * Starting a recording also wipes the plain block-change log that
+     * {@link TickSimulation::changes_json} and {@link TickSimulation::changes_count}
+     * read back to empty — a separate reset from
+     * {@link TickSimulation::record_updates}/{@link TickSimulation::clear_updates},
+     * which govern a different log. A host holding a cursor into the
+     * change log (the sim lab keeps a cumulative one) must reset that
+     * cursor when it calls this, or it will read past the end of a log
+     * that is no longer the one it was walking.
+     */
+    recordTimeline(): void;
+
+    /**
+     * End the recording, keeping the span readable.
+     *
+     * This is a host's Stop button, and it is not a rewind: the span stays
+     * readable and exportable until the next
+     * {@link TickSimulation::record_timeline}, while the simulation is free to
+     * run on without the recording following it. No-op if nothing was
+     * recording.
+     */
+    stopTimeline(): void;
+
+    /**
+     * Where the recorded run was busy, as JSON:
+     * `{"start":T,"end":T,"ticks":[{"tick":T,"changes":N,"inputs":N,
+     * "pistons":N}]}`.
+     *
+     * The strip a host draws to let someone pick a span worth exporting.
+     * Only ticks that did something appear: an idle tick is **absent**
+     * rather than present with zeroes, so a build that sits still does not
+     * advance the strip and a long quiet run stays cheap to send.
+     *
+     * `{"start":0,"end":0,"ticks":[]}` when nothing has been recorded.
+     */
+    timelineActivityJson(): string;
+
+    /**
+     * Exact and translated recurrence in the timeline a read query would
+     * resolve to (see {@link Self::timeline}), as JSON:
+     * `{"exact":{"start":T,"end":T,"period":N,"drift":[x,y,z]}|null,
+     * "translated":{...}|null}`.
+     *
+     * **An absent cycle is `null`, not an error.** Most builds — an
+     * adder, a door — never repeat their own state, and that is the
+     * ordinary outcome, not a failed search.
+     *
+     * **O(ticks × blocks): replays the whole recorded span to build one
+     * digest per tick boundary**, then rebuilds full frames for the
+     * handful of candidates that survive. This is an on-demand "find
+     * cycles" action for a host UI button, never something to call per
+     * tick or per frame — poll {@link Self::timeline_activity_json} instead.
+     *
+     * Materialises the whole recorded timeline once to answer this call
+     * (an owned `RunTimeline`'s `initial` frame copies every non-air
+     * block) — acceptable for one on-demand press, not for a loop.
+     *
+     * `{"exact":null,"translated":null}` when nothing has been recorded.
+     */
+    timelineCyclesJson(): string;
+
+    /**
+     * Project `[start_tick, end_tick)` of the timeline a read query would
+     * resolve to (see {@link Self::timeline}) into the animated-GLB mesher's
+     * `Timeline` JSON — `{"origin":[x,y,z],"tick_ms":F,
+     * "events":[{"kind":"set_block"|"piston",...}]}` — via
+     * `crate::tick_timeline::mesher_timeline_json`.
+     *
+     * **Materialises the whole recorded timeline to answer this call**
+     * (an owned `RunTimeline`'s `initial` frame copies every non-air
+     * block in the world) — this is an on-demand "export this
+     * selection" action, not something to call per frame or poll.
+     *
+     * Fails if no timeline has been recorded, or if `start_tick..
+     * end_tick` is empty or outside the recorded span.
+     */
+    animationTimelineJson(startTick: number, endTick: number, tickMs: number): string;
+
+    /**
+     * The selection's starting scene — `[start_tick, end_tick)` of the
+     * timeline a read query would resolve to (see {@link Self::timeline}) —
+     * as schematic bytes, base64-encoded.
+     *
+     * A WASM handle cannot cross a worker boundary, so this exists for a
+     * host to hand the bytes to a worker, which rebuilds the schematic
+     * with `Schematic.fromData`.
+     *
+     * **Materialises the whole recorded timeline to answer this call**
+     * — see {@link Self::animation_timeline_json}; an on-demand export
+     * action, not a per-frame poll.
+     *
+     * Fails if no timeline has been recorded, or if `start_tick..
+     * end_tick` is empty or outside the recorded span.
+     */
+    selectionSchematicB64(startTick: number, endTick: number): string;
+
+    /**
+     * How many updates have been recorded — page before pulling them.
+     */
+    updatesCount(): number;
+
+    /**
+     * Every recorded update, in delivery order.
+     *
+     * `seq` counts from 0 within each tick: that is the sub-tick axis, and
+     * `(tick, seq)` is the order the engine actually delivered them in.
+     * `state` is the block as it stood **at dispatch time**, which is what
+     * makes intra-tick order legible — a snapshot cannot show it.
+     */
+    updatesJson(): string;
+
+    /**
+     * The recorded updates for ticks in `[from_tick, to_tick)`.
+     *
+     * The whole log for a 6x6 door's cycle is megabytes; a scrubber only
+     * ever shows one tick, so it should ask for one tick.
+     */
+    updatesJsonBetween(fromTick: number, toTick: number): string;
+
+    /**
+     * Per-tick, per-cell update counts for ticks in `[from_tick, to_tick)`.
+     *
+     * The resolution playback should run at: `{phases, ticks:[{tick, total,
+     * cells:[{p:[x,y,z], n, nb, sh, ph:[…]}]}]}`, where `nb`/`sh` split
+     * neighbour from shape and `ph` indexes the `phases` legend. Collapses
+     * a tick's tens of thousands of updates into a few hundred cells.
+     */
+    updatesHeatJson(fromTick: number, toTick: number): string;
+
+    /**
+     * One tick's updates in delivery order, as parallel arrays.
+     *
+     * For stepping *within* a tick: `seq` is the array index, `pos` is flat
+     * x,y,z triples, `kind`/`phase`/`from` are integer codes with legends
+     * in the payload, and `state` indexes a deduplicated `states` table.
+     */
+    updatesWaveJson(tick: number): string;
+
+    /**
+     * Every block a piston currently has in flight, as JSON:
+     * `[{"to":[x,y,z],"from":[x,y,z],"state":"...","carried":"...",
+     * "carried_short":"..."|null,"remains":"..."|null,"dir":"east",
+     * "extending":bool,"started":T,"lands":T,"source_piston":bool}]`.
+     *
+     * Draw `carried` travelling `from` -> `to`, and `remains` (when it is
+     * not null) parked at `to` for the whole move. They differ from
+     * `state` — what actually lands — only for a retracting piston, whose
+     * body stays put while its head comes home; vanilla's
+     * `PistonHeadRenderer` splits exactly these two slots.
+     *
+     * `carried_short` is the same arm with `short=true`. Draw it while the
+     * head is **within half a block of its body** — `progress <= 0.5`
+     * extending, `progress >= 0.5` retracting — or the shaft passes
+     * visibly through the back of the piston as it comes home. Which form
+     * to use is yours; naming the state is the engine's.
+     *
+     * What a renderer needs to animate a stroke, from the simulator that
+     * dispatched it. The block-change stream cannot answer this: it says a
+     * cell became a `moving_piston` placeholder, not which block set off,
+     * which cell it left, or which tick it arrives — so a host that
+     * reconstructs strokes from changes is reimplementing piston mechanics
+     * downstream of the engine, and animating on a clock the simulation
+     * does not share. That desync is what draws a block twice, leaves a
+     * gap where one should be, and shears a piston head off its load.
+     *
+     * `started` and `lands` are tick numbers in the engine's frame, where
+     * {@link Self::tick_count} counts *completed* ticks: after stepping to
+     * `tick_count == t`, a flight's progress is
+     * `(t - started) / (lands - started)`, clamped to 1. Draw it while it
+     * is listed and drop it when it stops being listed — the same call
+     * that stops reporting it is the tick the real block is written, so
+     * there is no frame with both and none with neither.
+     */
+    movingBlocksJson(): string;
+
+    /**
+     * Drop the recorded block changes without stopping recording.
+     *
+     * The log grows for as long as the simulation runs and nothing
+     * empties it, so a long-running host — a browser session driving
+     * thousands of ticks — accumulates every block change forever. A
+     * host that has already consumed {@link TickSimulation::changes_json}
+     * can say so here and keep recording on. A host holding a cursor
+     * into the change log must reset that cursor when it calls this, or
+     * it will read past the end of a log that is no longer the one it
+     * was walking — the same hazard {@link TickSimulation::record_timeline}
+     * names for its own reset of this log.
+     *
+     * Refuses — and leaves the log untouched — while
+     * {@link TickSimulation::record_timeline} is recording: a run timeline
+     * is a seed frame plus this same log, and every timeline reader
+     * trusts that the log describes every mutation since recording
+     * began. Clearing it out from under a live recording would make
+     * replay silently wrong rather than fail loudly. Returns `true` if
+     * the log was cleared, `false` if the call was refused — following
+     * {@link TickSimulation::run_until_quiescent}'s convention of reporting
+     * whether the call achieved what it was asked, rather than swallowing
+     * a no-op.
+     */
+    clearChanges(): boolean;
+
+    changesJson(): string;
+
+    /**
+     * The same JSON array {@link TickSimulation::changes_json} produces,
+     * but only the entries from index `start` onward.
+     *
+     * Exists for a host draining the log every frame while a run
+     * timeline recording refuses {@link TickSimulation::clear_changes}: the
+     * log only ever grows in that state, so without this,
+     * `changes_json` re-serialises the whole backlog on every single
+     * drain — a cost that climbs for as long as the recording runs,
+     * which is exactly when a session runs longest. Reading from a
+     * cursor keeps a drain's cost to what is actually new.
+     *
+     * `start` at or past the end of the log yields `[]`, not an error —
+     * a host racing a draining cursor against a growing log should not
+     * have to special-case "nothing new yet".
+     */
+    changesJsonFrom(start: number): string;
+
+    /**
+     * Live item entities and minecarts, as JSON:
+     * `{"items":[{"id":N,"item":"...","count":N,"pos":[..],"vel":[..],
+     * "on_ground":bool,"contents":[{"id":"...","count":N}]}],
+     * "minecarts":[{"id":N,"kind":"...","pos":[..],"vel":[..]}]}`.
+     */
+    itemEntitiesJson(): string;
+
+    /**
+     * Which `Entity.load` Motion semantics this run uses:
+     * `"clamp_abs_ten"` (DataVersion <= 4556 — NaN survives a cold load)
+     * or `"drop_non_finite"` (>= 4671 — it does not).
+     *
+     * Exposed because a door built on nan carts is a *different machine*
+     * under the two, and a caller that cannot tell them apart cannot
+     * report why it came apart.
+     */
+    motionSemantics(): string;
+
+    /**
+     * How many times an entity stood in a **retracting** piston's sweep
+     * that the engine could not reproduce.
+     *
+     * A tripwire from when retraction was unmodelled — extension
+     * displacement was measured and implemented while
+     * `tools/gametest/captures/piston_pull.entities.log`'s sub-0.03
+     * movements, not uniformly backwards, had no model here. All three
+     * retraction geometries are implemented now, so this reports **0**,
+     * including on the record 3x3 door, which used to name six. It is kept
+     * because the next geometry that turns out not to be covered should be
+     * reported rather than guessed at: non-zero means this run leaned on
+     * behaviour we do not reproduce and its result is not trustworthy.
+     */
+    pistonRetractContacts(): number;
+
+    /**
+     * Per-tick aggregates over the recorded changes, as JSON:
+     * `[{"tick":N,"changes":N,"piston":N,"redstone":N}]` — `piston`
+     * counts changes touching piston blocks (base, head, moving), and
+     * `redstone` changes touching wire/torch/repeater/comparator/
+     * observer/lamp/lever/button/pressure-plate states.
+     */
+    eventsSummaryJson(): string;
+
+    /**
+     * Every non-air block, as JSON:
+     * `[{"pos":[x,y,z],"state":"..."}]`.
+     * How many non-air blocks stand in the world right now.
+     */
+    nonAirCount(): number;
+
+    /**
+     * Center of mass (x) of every non-air block — the GA's displacement
+     * metric without a JSON round-trip. NaN when the world is empty.
+     */
+    nonAirCenterX(): number;
+
+    /**
+     * Smallest x holding a non-air block; `i32::MAX` when empty.
+     */
+    nonAirMinX(): number;
+
+    /**
+     * Largest x holding a non-air block; `i32::MIN` when empty.
+     */
+    nonAirMaxX(): number;
+
+    /**
+     * How many block changes recording has captured so far.
+     */
+    changesCount(): number;
+
+    worldSnapshotJson(): string;
+
+    /**
+     * Static structural analysis of the build standing in this world.
+     *
+     * One call, one JSON document: adhesion groups, piston/observer/source
+     * nodes, the four edge kinds, every minimal self-translating subgraph
+     * (the engine), payload, kickers, dead weight, and any proof that the
+     * machine cannot move.
+     *
+     * The analysis lives in the engine rather than in the caller on
+     * purpose. Every "what would this piston move?" answer comes from
+     * `resolve_push`/`resolve_pull` — the same oracle-verified resolver the
+     * tick loop runs — and a second copy of Minecraft's push rules written
+     * on the far side of this boundary would drift from it silently.
+     */
+    machineGraphJson(): string;
+
+    /**
+     * GA pre-filter: static verdicts for a whole batch of genomes.
+     *
+     * Same flat-cell layout as {@link Self::eval_flight_batch}, and meant to run
+     * immediately before it: whatever this rejects never needs simulating.
+     * Writes one row per genome, `[rejected, rejected_for_sustained,
+     * engine_cell_count, payload_cell_count, dead_cell_count, "codes"]`.
+     *
+     * The registry, behaviour table and movability rules are built once for
+     * the batch — building them per genome costs more than the analysis.
+     */
+    static machineGraphBatchJson(bx: number, by: number, bz: number, travel: number, xOff: number, palette: string, cells: Array<number>, airIndex: number): string;
+}