nucleation 0.6.0 → 0.8.0

package/DefinitionRegion.d.mts

@@ -0,0 +1,274 @@
+// generated by diplomat-tool
+import type { BlockPos } from "./BlockPos.mjs"
+import type { Dimensions } from "./Dimensions.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { RegionBounds } from "./RegionBounds.mjs"
+import type { Schematic } from "./Schematic.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * A named sub-volume of a schematic: a union of boxes plus a metadata map.
+ */
+export class DefinitionRegion {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Create a new empty region (no boxes, no metadata).
+     */
+    static create(): DefinitionRegion;
+
+    /**
+     * A region consisting of a single inclusive box. Min/max are swapped
+     * per axis if given out of order.
+     */
+    static fromBounds(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): DefinitionRegion;
+
+    /**
+     * Build a region from single-block positions crossing as flat `[i32]`
+     * chunked in threes (PORTING rule 7). Errors with `InvalidArgument` if
+     * the length is not a multiple of 3.
+     */
+    static fromPositions(positions: Array<number>): DefinitionRegion;
+
+    /**
+     * Build a region from bounding boxes crossing as flat `[i32]` chunked in
+     * sixes (`min_x, min_y, min_z, max_x, max_y, max_z` per box). Errors
+     * with `InvalidArgument` if the length is not a multiple of 6.
+     */
+    static fromBoundingBoxes(boxes: Array<number>): DefinitionRegion;
+
+    /**
+     * Add an inclusive box to the region. Min/max are swapped per axis if
+     * given out of order.
+     */
+    addBounds(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): void;
+
+    /**
+     * Add a single block position (a 1x1x1 box) to the region.
+     */
+    addPoint(x: number, y: number, z: number): void;
+
+    /**
+     * Set a metadata entry (insert or overwrite the key).
+     */
+    setMetadata(key: string, value: string): void;
+
+    /**
+     * Errors with `NotFound` when the key is absent.
+     */
+    getMetadata(key: string): string;
+
+    /**
+     * The full metadata map, written as a JSON object string (the old ABI
+     * returned an array of `"key=value"` strings).
+     */
+    allMetadataJson(): string;
+
+    /**
+     * The metadata keys, written as a JSON array string.
+     */
+    metadataKeysJson(): string;
+
+    /**
+     * Store a filter expression in the region's metadata under the `filter`
+     * key.
+     */
+    addFilter(filter: string): void;
+
+    /**
+     * `true` if the region contains no boxes.
+     */
+    isEmpty(): boolean;
+
+    /**
+     * The total volume in blocks, summed box by box: positions covered by
+     * several overlapping boxes are counted once per box.
+     */
+    volume(): bigint;
+
+    /**
+     * Whether the position lies inside any of the region's boxes.
+     */
+    contains(x: number, y: number, z: number): boolean;
+
+    /**
+     * Translate every box by (`dx`, `dy`, `dz`) in place.
+     */
+    shift(dx: number, dy: number, dz: number): void;
+
+    /**
+     * Grow every box in place by (`x`, `y`, `z`) outward on both sides of
+     * each axis. Negative values contract; boxes that shrink away are
+     * removed.
+     */
+    expand(x: number, y: number, z: number): void;
+
+    /**
+     * Shrink every box in place by `amount` on all sides (the inverse of
+     * a uniform `expand`); boxes that shrink away are removed.
+     */
+    contract(amount: number): void;
+
+    /**
+     * A new region: the intersection of `self` and `other`.
+     */
+    intersected(other: DefinitionRegion): DefinitionRegion;
+
+    /**
+     * A new region: the union of `self` and `other`.
+     */
+    unionWith(other: DefinitionRegion): DefinitionRegion;
+
+    /**
+     * A new region: `self` minus `other`.
+     */
+    subtracted(other: DefinitionRegion): DefinitionRegion;
+
+    /**
+     * Merge `other`'s boxes and metadata into `self`.
+     */
+    merge(other: DefinitionRegion): void;
+
+    /**
+     * Union `other`'s boxes into `self` in place.
+     */
+    unionInto(other: DefinitionRegion): void;
+
+    /**
+     * The overall bounding box. Errors with `NotFound` when the region is
+     * empty.
+     */
+    bounds(): RegionBounds;
+
+    /**
+     * The (width, height, length) of the overall bounding box; all zeros
+     * when the region is empty.
+     */
+    dimensions(): Dimensions;
+
+    /**
+     * The center block position. Errors with `NotFound` when the region is
+     * empty.
+     */
+    center(): BlockPos;
+
+    /**
+     * The exact (fractional) center, written as a JSON `[x, y, z]` array of
+     * floats. Errors with `NotFound` when the region is empty.
+     */
+    centerF32Json(): string;
+
+    /**
+     * Every contained position, written as a flat JSON array of ints
+     * (`[x0, y0, z0, x1, y1, z1, …]`), deduplicated, in box order.
+     */
+    positionsJson(): string;
+
+    /**
+     * Every contained position in sorted (y, z, x) order, written as a flat
+     * JSON array of ints.
+     */
+    positionsSortedJson(): string;
+
+    /**
+     * The number of boxes making up this region.
+     */
+    boxCount(): number;
+
+    /**
+     * The box at `index`. Errors with `NotFound` when out of range.
+     */
+    getBox(index: number): RegionBounds;
+
+    /**
+     * Every box, written as a flat JSON array of ints (six ints per box:
+     * `min_x, min_y, min_z, max_x, max_y, max_z`).
+     */
+    boxesJson(): string;
+
+    /**
+     * Whether all positions form a single face-connected (6-connectivity)
+     * component. `true` for empty and single-block regions.
+     */
+    isContiguous(): boolean;
+
+    /**
+     * The number of face-connected (6-connectivity) components; 0 when
+     * the region is empty.
+     */
+    connectedComponents(): number;
+
+    /**
+     * Merge overlapping/adjacent boxes into a minimal representation.
+     */
+    simplify(): void;
+
+    /**
+     * A new region containing only the positions where `schematic` has a
+     * block named `block_name`.
+     */
+    filterByBlock(schematic: Schematic, blockName: string): DefinitionRegion;
+
+    /**
+     * A new region containing only the positions where the block in
+     * `schematic` matches every property in `properties_json` (a JSON
+     * object of property name → value strings).
+     */
+    filterByProperties(schematic: Schematic, propertiesJson: string): DefinitionRegion;
+
+    /**
+     * Remove every position where `schematic` has a block named
+     * `block_name` (in place).
+     */
+    excludeBlock(schematic: Schematic, blockName: string): void;
+
+    /**
+     * Whether any of the region's boxes intersects the given inclusive
+     * box (useful for frustum culling).
+     */
+    intersectsBounds(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): boolean;
+
+    /**
+     * A new region shifted by (`dx`, `dy`, `dz`).
+     */
+    shifted(dx: number, dy: number, dz: number): DefinitionRegion;
+
+    /**
+     * A new region expanded by (`x`, `y`, `z`) on each axis.
+     */
+    expanded(x: number, y: number, z: number): DefinitionRegion;
+
+    /**
+     * A new region contracted by `amount` on every axis.
+     */
+    contracted(amount: number): DefinitionRegion;
+
+    /**
+     * A deep copy of this region.
+     */
+    copy(): DefinitionRegion;
+
+    /**
+     * Store a display color (`0xRRGGBB`) in the region's metadata.
+     */
+    setColor(color: number): void;
+
+    /**
+     * The blocks of `schematic` inside this region, written as a JSON array
+     * of `{"x", "y", "z", "name", "properties"}` objects (the old ABI
+     * returned a `CBlockArray`).
+     */
+    blocksJson(schematic: Schematic): string;
+
+    /**
+     * Write this region into `schematic`'s definition-region map under
+     * `name` (insert or overwrite).
+     */
+    sync(schematic: Schematic, name: string): void;
+}

package/DefinitionRegion.d.ts

@@ -1,9 +1,9 @@
 // generated by diplomat-tool
-import type { BlockPos } from "./BlockPos"
-import type { Dimensions } from "./Dimensions"
-import type { NucleationError } from "./NucleationError"
-import type { RegionBounds } from "./RegionBounds"
-import type { Schematic } from "./Schematic"
+import type { BlockPos } from "./BlockPos.mjs"
+import type { Dimensions } from "./Dimensions.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { RegionBounds } from "./RegionBounds.mjs"
+import type { Schematic } from "./Schematic.mjs"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 

package/Diff.d.mts

@@ -0,0 +1,88 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * A computed diff between two schematics.
+ */
+export class Diff {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Diff two schematics with the given preset (default cost model).
+     * Errors with `InvalidArgument` on an unknown preset.
+     */
+    static compute(a: Schematic, b: Schematic, preset: string): Diff;
+
+    /**
+     * Diff two schematics with optional cost/symmetry overrides. Negative
+     * cost ints mean "unset" (use the preset default); an empty `symmetry`
+     * string means "unset". Errors with `InvalidArgument` on an unknown
+     * preset or symmetry name.
+     */
+    static computeWithOpts(a: Schematic, b: Schematic, preset: string, costAdd: number, costDelete: number, costChange: number, costSwap: number, symmetry: string): Diff;
+
+    /**
+     * Reconstruct a diff from its JSON representation.
+     */
+    static fromJson(json: string): Diff;
+
+    /**
+     * The edit distance of the diff.
+     */
+    distance(): bigint;
+
+    /**
+     * The support (alignment confidence) of the diff.
+     */
+    support(): number;
+
+    /**
+     * Serialize the diff to its full JSON representation.
+     */
+    toJson(): string;
+
+    /**
+     * Serialize the diff to its compact summary JSON.
+     */
+    summaryJson(): string;
+
+    /**
+     * A new schematic containing only the blocks added in this diff.
+     */
+    added(): Schematic;
+
+    /**
+     * A new schematic containing only the blocks removed in this diff.
+     */
+    removed(): Schematic;
+
+    /**
+     * A new schematic containing only the blocks changed in this diff.
+     */
+    changed(): Schematic;
+
+    /**
+     * A new schematic containing only the blocks swapped in this diff.
+     */
+    swapped(): Schematic;
+
+    /**
+     * A new schematic with marker blocks summarizing this diff.
+     */
+    markers(): Schematic;
+
+    /**
+     * Render a diff overlay on top of an "after" GLB buffer, returning the
+     * new GLB as base64 (PORTING rule 6). Requires the `meshing` feature;
+     * errors with `Mesh` when compiled without it.
+     */
+    toOverlayGlbB64(afterGlb: Array<number>): string;
+}

package/Diff.d.ts

@@ -1,6 +1,6 @@
 // generated by diplomat-tool
-import type { NucleationError } from "./NucleationError"
-import type { Schematic } from "./Schematic"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 

package/Dimensions.d.mts

@@ -0,0 +1,28 @@
+// generated by diplomat-tool
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+export type Dimensions_obj = {
+    x: number;
+    y: number;
+    z: number;
+};
+
+
+
+export class Dimensions {
+    get x(): number;
+    set x(value: number);
+    get y(): number;
+    set y(value: number);
+    get z(): number;
+    set z(value: number);
+    /** @internal */
+    static fromFields(structObj : Dimensions_obj) : Dimensions;
+
+    /**
+    * Create `Dimensions` from an object that contains all of `Dimensions`s fields.
+    * Optional fields do not need to be included in the provided object.
+    */
+    constructor(structObj: Dimensions_obj);
+
+}

package/DistanceField.d.mts

@@ -0,0 +1,39 @@
+// generated by diplomat-tool
+import type { Schematic } from "./Schematic.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+export class DistanceField {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Distance transform of a build's occupied voxels: every solid block
+     * learns how many blocks it sits below the surface, and the gradient of
+     * that depth gives the outward normal. Computed once over the
+     * schematic's bounding box.
+     */
+    static fromSchematic(schematic: Schematic): DistanceField;
+
+    /**
+     * Blocks below the surface at a voxel: 0 for empty/outside, 1 at the
+     * surface, increasing inward.
+     */
+    depth(x: number, y: number, z: number): number;
+
+    /**
+     * The upward component of the outward surface normal: 1 on flat ground,
+     * 0 on a vertical face, negative under an overhang. The scalar to key
+     * slope-based landscaping on (grass on the flats, stone on the steeps).
+     */
+    slope(x: number, y: number, z: number): number;
+
+    /**
+     * The full outward surface normal as JSON `[nx, ny, nz]`.
+     */
+    normalJson(x: number, y: number, z: number): string;
+}

package/DistanceField.d.ts

@@ -1,5 +1,5 @@
 // generated by diplomat-tool
-import type { Schematic } from "./Schematic"
+import type { Schematic } from "./Schematic.mjs"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 

package/ExecutionMode.d.mts

@@ -0,0 +1,42 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { OutputCondition } from "./OutputCondition.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * How long to run the circuit for one `execute` call (PORTING rule 10).
+ */
+export class ExecutionMode {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Run for exactly `ticks` ticks.
+     */
+    static fixedTicks(ticks: number): ExecutionMode;
+
+    /**
+     * Run until the output named `output_name` meets `condition`,
+     * checking every `check_interval` ticks, giving up after `max_ticks`
+     * ticks (the result's `condition_met` reports which happened).
+     */
+    static untilCondition(outputName: string, condition: OutputCondition, maxTicks: number, checkInterval: number): ExecutionMode;
+
+    /**
+     * Run until any output changes from its initial reading, checking
+     * every `check_interval` ticks, giving up after `max_ticks` ticks.
+     */
+    static untilChange(maxTicks: number, checkInterval: number): ExecutionMode;
+
+    /**
+     * Run (one tick at a time) until all outputs have been unchanged for
+     * `stable_ticks` consecutive ticks, giving up after `max_ticks`
+     * ticks (the result's `condition_met` reports stability).
+     */
+    static untilStable(stableTicks: number, maxTicks: number): ExecutionMode;
+}

package/ExecutionMode.d.ts

@@ -1,6 +1,6 @@
 // generated by diplomat-tool
-import type { NucleationError } from "./NucleationError"
-import type { OutputCondition } from "./OutputCondition"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { OutputCondition } from "./OutputCondition.mjs"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 

package/Field3.d.mts

@@ -0,0 +1,40 @@
+// generated by diplomat-tool
+import type { FieldRange } from "./FieldRange.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Immutable scalar field evaluated over world-space `(x, y, z)`.
+ *
+ * A `Field3` has scalar semantics only. It may be shared by geometry and
+ * material consumers without being reinterpreted as a signed-distance field.
+ */
+export class Field3 {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Deterministic value-noise FBM normalized to `[-1, 1]`.
+     */
+    static valueNoiseFbm(frequency: number, seed: number, octaves: number): Field3;
+
+    evalAt(x: number, y: number, z: number): number;
+
+    /**
+     * The field's analytically proven output range.
+     *
+     * Returns `NotFound` when no range can be proven — callers mapping a
+     * field onto a gradient must handle that rather than silently
+     * propagating a sentinel into their `lo`/`hi` bounds.
+     */
+    outputRange(): FieldRange;
+
+    static fromJsonString(json: string): Field3;
+
+    toJson(): string;
+}

package/Field3.d.ts

@@ -0,0 +1,40 @@
+// generated by diplomat-tool
+import type { FieldRange } from "./FieldRange.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Immutable scalar field evaluated over world-space `(x, y, z)`.
+ *
+ * A `Field3` has scalar semantics only. It may be shared by geometry and
+ * material consumers without being reinterpreted as a signed-distance field.
+ */
+export class Field3 {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Deterministic value-noise FBM normalized to `[-1, 1]`.
+     */
+    static valueNoiseFbm(frequency: number, seed: number, octaves: number): Field3;
+
+    evalAt(x: number, y: number, z: number): number;
+
+    /**
+     * The field's analytically proven output range.
+     *
+     * Returns `NotFound` when no range can be proven — callers mapping a
+     * field onto a gradient must handle that rather than silently
+     * propagating a sentinel into their `lo`/`hi` bounds.
+     */
+    outputRange(): FieldRange;
+
+    static fromJsonString(json: string): Field3;
+
+    toJson(): string;
+}