nucleation 0.7.0 → 0.9.1

package/TickSimulation.d.ts

@@ -0,0 +1,312 @@
+// 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;
+
+    /**
+     * 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;
+
+    /**
+     * 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;
+
+    changesJson(): 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;
+}