nucleation 0.3.17 → 0.3.19

package/Curve3D.d.ts

@@ -0,0 +1,27 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * A sampled 3D polyline. Closed curves include the final segment back to
+ * the first point and retain arc-length parameterisation for animation.
+ * Oversized point sets and overflowing segment lengths are rejected.
+ */
+export class Curve3D {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Create a curve from flat `[x0, y0, z0, x1, y1, z1, …]` coordinates.
+     */
+    static fromPoints(coordinates: Array<number>, closed: boolean): Curve3D;
+
+    pointCount(): number;
+
+    isClosed(): boolean;
+}

package/Curve3D.mjs

@@ -0,0 +1,101 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const Curve3D_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.Curve3D_destroy(ptr);
+});
+
+/**
+ * A sampled 3D polyline. Closed curves include the final segment back to
+ * the first point and retain arc-length parameterisation for animation.
+ * Oversized point sets and overflowing segment lengths are rejected.
+ */
+export class Curve3D {
+    // Internal ptr reference:
+    #ptr = null;
+
+    // Lifetimes are only to keep dependencies alive.
+    // Since JS won't garbage collect until there are no incoming edges.
+    #selfEdge = [];
+
+    #internalConstructor(symbol, ptr, selfEdge) {
+        if (symbol !== diplomatRuntime.internalConstructor) {
+            console.error("Curve3D is an Opaque type. You cannot call its constructor.");
+            return;
+        }
+        this.#ptr = ptr;
+        this.#selfEdge = selfEdge;
+
+        // Are we being borrowed? If not, we can register.
+        if (this.#selfEdge.length === 0) {
+            Curve3D_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Create a curve from flat `[x0, y0, z0, x1, y1, z1, …]` coordinates.
+     */
+    static fromPoints(coordinates, closed) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const coordinatesSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.slice(wasm, coordinates, "f64")));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Curve3D_from_points(diplomatReceive.buffer, coordinatesSlice.ptr, closed);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return new Curve3D(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    pointCount() {
+
+        const result = wasm.Curve3D_point_count(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    isClosed() {
+
+        const result = wasm.Curve3D_is_closed(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/DistanceField.d.ts

@@ -0,0 +1,39 @@
+// generated by diplomat-tool
+import type { Schematic } from "./Schematic"
+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.mjs

@@ -0,0 +1,114 @@
+// generated by diplomat-tool
+import { Schematic } from "./Schematic.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const DistanceField_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.DistanceField_destroy(ptr);
+});
+
+export class DistanceField {
+    // Internal ptr reference:
+    #ptr = null;
+
+    // Lifetimes are only to keep dependencies alive.
+    // Since JS won't garbage collect until there are no incoming edges.
+    #selfEdge = [];
+
+    #internalConstructor(symbol, ptr, selfEdge) {
+        if (symbol !== diplomatRuntime.internalConstructor) {
+            console.error("DistanceField is an Opaque type. You cannot call its constructor.");
+            return;
+        }
+        this.#ptr = ptr;
+        this.#selfEdge = selfEdge;
+
+        // Are we being borrowed? If not, we can register.
+        if (this.#selfEdge.length === 0) {
+            DistanceField_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * 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) {
+
+        const result = wasm.DistanceField_from_schematic(schematic.ffiValue);
+
+        try {
+            return new DistanceField(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Blocks below the surface at a voxel: 0 for empty/outside, 1 at the
+     * surface, increasing inward.
+     */
+    depth(x, y, z) {
+
+        const result = wasm.DistanceField_depth(this.ffiValue, x, y, z);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * 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, y, z) {
+
+        const result = wasm.DistanceField_slope(this.ffiValue, x, y, z);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * The full outward surface normal as JSON `[nx, ny, nz]`.
+     */
+    normalJson(x, y, z) {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.DistanceField_normal_json(this.ffiValue, x, y, z, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/RenderConfig.d.ts

@@ -63,6 +63,20 @@ export class RenderConfig {
      */
     clearBackground(): void;
 
+    /**
+     * Configure a one-block world grid. Models are centred on integer
+     * schematic coordinates, so grid lines are placed on half-integer
+     * block boundaries automatically.
+     */
+    setGrid(halfExtent: number, spacing: number, planeY: number, showAxes: boolean, red: number, green: number, blue: number, alpha: number): void;
+
+    /**
+     * Configure a compact grid fitted to half-integer block boundaries.
+     */
+    setFittedGrid(margin: number, spacing: number, planeY: number, showAxes: boolean, red: number, green: number, blue: number, alpha: number): void;
+
+    clearGrid(): void;
+
     /**
      * Enable (`true`) or disable orthographic projection.
      */

package/RenderConfig.mjs

@@ -155,6 +155,44 @@ export class RenderConfig {
         }
     }
 
+    /**
+     * Configure a one-block world grid. Models are centred on integer
+     * schematic coordinates, so grid lines are placed on half-integer
+     * block boundaries automatically.
+     */
+    setGrid(halfExtent, spacing, planeY, showAxes, red, green, blue, alpha) {
+    wasm.RenderConfig_set_grid(this.ffiValue, halfExtent, spacing, planeY, showAxes, red, green, blue, alpha);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Configure a compact grid fitted to half-integer block boundaries.
+     */
+    setFittedGrid(margin, spacing, planeY, showAxes, red, green, blue, alpha) {
+    wasm.RenderConfig_set_fitted_grid(this.ffiValue, margin, spacing, planeY, showAxes, red, green, blue, alpha);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    clearGrid() {
+    wasm.RenderConfig_clear_grid(this.ffiValue);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
     /**
      * Enable (`true`) or disable orthographic projection.
      */

package/Schematic.d.ts

@@ -19,6 +19,12 @@ export class Schematic {
      */
     static create(name: string): Schematic;
 
+    /**
+     * Return an independent deep copy. Subsequent block, region, entity,
+     * metadata, or transform changes do not affect the original.
+     */
+    deepClone(): Schematic;
+
     /**
      * The allocated dimensions (width, height, length) of the schematic's
      * bounding box.
@@ -174,16 +180,46 @@ export class Schematic {
     getBlocksJson(positions: Array<number>): string;
 
     /**
-     * Copy a region from `source` into this schematic. `excluded_blocks_json`
-     * is a JSON array of block strings to skip (empty string or `[]` for none).
+     * Stamp a merged source box into the default region. Excluded blocks
+     * are skipped, preserving destination content. Empty string or `[]`
+     * means no exclusions.
+     */
+    stampBox(source: Schematic, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, targetX: number, targetY: number, targetZ: number, excludedBlocksJson: string): void;
+
+    /**
+     * Stamp one explicitly named source region into the default region.
+     * The region's minimum corner is mapped to the target position.
+     */
+    stampRegion(source: Schematic, sourceRegionName: string, targetX: number, targetY: number, targetZ: number, excludedBlocksJson: string): void;
+
+    /**
+     * Compatibility alias for `stamp_box`.
      */
     copyRegion(source: Schematic, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, targetX: number, targetY: number, targetZ: number, excludedBlocksJson: string): void;
 
+    /**
+     * The full block state at a position. `NotFound` if the position is
+     * outside every region.
+     */
+    getBlock(x: number, y: number, z: number): BlockState;
+
     /**
      * The block at a position with its properties, as a `BlockState`.
+     * Kept as an explicit alias for callers migrating from the older API.
      */
     getBlockWithProperties(x: number, y: number, z: number): BlockState;
 
+    /**
+     * The full block state at a position in one specific region. This
+     * avoids composite lookup ambiguity when regions overlap.
+     */
+    getBlockInRegion(regionName: string, x: number, y: number, z: number): BlockState;
+
+    /**
+     * The block string at a position in one specific region.
+     */
+    getBlockStringInRegion(regionName: string, x: number, y: number, z: number): string;
+
     /**
      * The full block string (name, properties, NBT) at a position.
      */
@@ -195,6 +231,11 @@ export class Schematic {
      */
     getBlockEntityJson(x: number, y: number, z: number): string;
 
+    /**
+     * The block entity at a position in one specific region as JSON.
+     */
+    getBlockEntityJsonInRegion(regionName: string, x: number, y: number, z: number): string;
+
     /**
      * Every block entity as a JSON array of
      * `{"id": ..., "position": [x,y,z], "nbt": {...}}`.
@@ -217,6 +258,14 @@ export class Schematic {
      */
     addEntity(id: string, x: number, y: number, z: number, nbtJson: string): void;
 
+    /**
+     * Add an armor stand without hand-authoring entity NBT.
+     *
+     * `armor_material` accepts `diamond`, `netherite`, `iron`, etc.; an
+     * empty string creates an unarmored stand. `yaw` uses Minecraft degrees.
+     */
+    addArmorStand(x: number, y: number, z: number, yaw: number, armorMaterial: string): void;
+
     /**
      * Remove a mobile entity by index.
      */
@@ -445,87 +494,116 @@ export class Schematic {
 
     /**
      * Mirror the default region along the X axis (in place). Block
-     * orientations (e.g. `facing` properties), block entities, and
-     * entities are mirrored too.
+     * orientations, block entities, and entities are mirrored too.
      */
     flipX(): void;
 
     /**
-     * Mirror the default region along the Y axis (in place). Block
-     * orientations, block entities, and entities are mirrored too.
+     * Mirror the default region along the Y axis (in place).
      */
     flipY(): void;
 
     /**
-     * Mirror the default region along the Z axis (in place). Block
-     * orientations, block entities, and entities are mirrored too.
+     * Mirror the default region along the Z axis (in place).
      */
     flipZ(): void;
 
     /**
-     * Rotate the default region about the X axis. `degrees` must be a
-     * multiple of 90 (anything else is a no-op; negative values wrap).
-     * +90° maps +Z onto +Y (south face rotates up). The region keeps its
-     * minimum corner; block orientations and entities are updated.
+     * Rotate the default region about the X axis. +90° maps south (+Z)
+     * to down (-Y). Only multiples of 90 are accepted; invalid angles
+     * return `InvalidArgument` without changing the schematic. Negative
+     * values wrap.
      */
     rotateX(degrees: number): void;
 
     /**
-     * Rotate the default region about the Y axis (horizontal plane).
-     * `degrees` must be a multiple of 90 (anything else is a no-op;
-     * negative values wrap). +90° maps +X onto -Z (east to north, i.e.
-     * counterclockwise seen from above). The region keeps its minimum
-     * corner; block orientations and entities are updated.
+     * Rotate the default region clockwise about the Y axis when viewed
+     * from above. +90° maps east (+X) to south (+Z).
      */
     rotateY(degrees: number): void;
 
     /**
-     * Rotate the default region about the Z axis. `degrees` must be a
-     * multiple of 90 (anything else is a no-op; negative values wrap).
-     * +90° maps +Y onto +X (up rotates east). The region keeps its
-     * minimum corner; block orientations and entities are updated.
+     * Rotate the default region about the Z axis. +90° maps up (+Y) to
+     * west (-X).
      */
     rotateZ(degrees: number): void;
 
     /**
-     * Mirror a named region along the X axis (like `flip_x`). `NotFound`
-     * if no region has that name.
+     * Move the default region and all attached block entities/entities.
+     */
+    translate(dx: number, dy: number, dz: number): void;
+
+    /**
+     * Mirror a named region along the X axis.
      */
     flipRegionX(regionName: string): void;
 
     /**
-     * Mirror a named region along the Y axis (like `flip_y`). `NotFound`
-     * if no region has that name.
+     * Mirror a named region along the Y axis.
      */
     flipRegionY(regionName: string): void;
 
     /**
-     * Mirror a named region along the Z axis (like `flip_z`). `NotFound`
-     * if no region has that name.
+     * Mirror a named region along the Z axis.
      */
     flipRegionZ(regionName: string): void;
 
     /**
-     * Rotate a named region about the X axis by a multiple of 90 degrees
-     * (same semantics as `rotate_x`). `NotFound` if no region has that
-     * name.
+     * Rotate a named region about the X axis by a multiple of 90 degrees.
      */
     rotateRegionX(regionName: string, degrees: number): void;
 
     /**
-     * Rotate a named region about the Y axis by a multiple of 90 degrees
-     * (same semantics as `rotate_y`). `NotFound` if no region has that
-     * name.
+     * Rotate a named region clockwise about the Y axis by a multiple of
+     * 90 degrees.
      */
     rotateRegionY(regionName: string, degrees: number): void;
 
     /**
-     * Rotate a named region about the Z axis by a multiple of 90 degrees
-     * (same semantics as `rotate_z`). `NotFound` if no region has that
-     * name.
+     * Rotate a named region about the Z axis by a multiple of 90 degrees.
      */
     rotateRegionZ(regionName: string, degrees: number): void;
 
+    /**
+     * Move one named region without affecting its siblings.
+     */
+    translateRegion(regionName: string, dx: number, dy: number, dz: number): void;
+
+    /**
+     * Rotate every region as one rigid schematic around the shared bounds.
+     */
+    rotateSchematicX(degrees: number): void;
+
+    /**
+     * Rotate every region as one rigid schematic around the shared bounds.
+     */
+    rotateSchematicY(degrees: number): void;
+
+    /**
+     * Rotate every region as one rigid schematic around the shared bounds.
+     */
+    rotateSchematicZ(degrees: number): void;
+
+    /**
+     * Mirror every region across the shared schematic X bounds.
+     */
+    flipSchematicX(): void;
+
+    /**
+     * Mirror every region across the shared schematic Y bounds.
+     */
+    flipSchematicY(): void;
+
+    /**
+     * Mirror every region across the shared schematic Z bounds.
+     */
+    flipSchematicZ(): void;
+
+    /**
+     * Move every region by the same delta, preserving their relative layout.
+     */
+    translateSchematic(dx: number, dy: number, dz: number): void;
+
     /**
      * Fill a cuboid with a block.
      */
@@ -565,6 +643,26 @@ export class Schematic {
      */
     setBlockInRegion(regionName: string, x: number, y: number, z: number, blockName: string): void;
 
+    /**
+     * Whether a default or named schematic region exists.
+     */
+    hasRegion(regionName: string): boolean;
+
+    /**
+     * Create an empty named region. Its first block anchors its bounds.
+     */
+    createRegion(regionName: string): void;
+
+    /**
+     * Remove a named region. The default region cannot be removed.
+     */
+    removeRegion(regionName: string): void;
+
+    /**
+     * Rename a named region. The default region cannot be renamed.
+     */
+    renameRegion(oldName: string, newName: string): void;
+
     /**
      * The schematic bounding box as a JSON array
      * `[min_x, min_y, min_z, max_x, max_y, max_z]`.