nucleation 0.10.22 → 0.10.24

package/renderer/Shape.mjs

@@ -0,0 +1,458 @@
+// generated by diplomat-tool
+import { Curve3D } from "./Curve3D.mjs"
+import { NucleationError } from "./NucleationError.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const Shape_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.Shape_destroy(ptr);
+});
+
+/**
+ * A solid region of blocks: primitives (sphere, cuboid, …) and boolean
+ * combinations thereof. Wraps `ShapeEnum`.
+ */
+export class Shape {
+    // 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("Shape 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) {
+            Shape_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Thicken a sampled 3D curve into a parametric tube with the given radius.
+     * Inputs outside voxel-coordinate or bounded-work limits are rejected.
+     */
+    static tubeAlong(curve, radius) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Shape_tube_along(diplomatReceive.buffer, curve.ffiValue, radius);
+
+        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 Shape(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Sphere centered at (`cx`, `cy`, `cz`) (truncated to block coordinates,
+     * matching the old `shape_sphere`).
+     */
+    static sphere(cx, cy, cz, radius) {
+
+        const result = wasm.Shape_sphere(cx, cy, cz, radius);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Axis-aligned box spanning the two corners (inclusive).
+     */
+    static cuboid(minX, minY, minZ, maxX, maxY, maxZ) {
+
+        const result = wasm.Shape_cuboid(minX, minY, minZ, maxX, maxY, maxZ);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * A closed 2D polygon extruded between two Y levels (inclusive). The
+     * footprint is `polygon_json`, a JSON array of `[x, z]` world-coordinate
+     * pairs in order (winding does not matter; the ring closes implicitly);
+     * any simple polygon works, concave ones included. This is the shape
+     * behind extruded building footprints, lake outlines, and plot fills.
+     * Errors with `Parse` on invalid JSON and `InvalidArgument` on non-UTF-8
+     * or fewer than three vertices.
+     */
+    static polygonPrism(polygonJson, yMin, yMax) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const polygonJsonSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, polygonJson)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Shape_polygon_prism(diplomatReceive.buffer, polygonJsonSlice.ptr, yMin, yMax);
+
+        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 Shape(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Ellipsoid centered at (`cx`, `cy`, `cz`) with per-axis radii.
+     */
+    static ellipsoid(cx, cy, cz, rx, ry, rz) {
+
+        const result = wasm.Shape_ellipsoid(cx, cy, cz, rx, ry, rz);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Cylinder from base point along an axis vector.
+     */
+    static cylinder(bx, by, bz, ax, ay, az, radius, height) {
+
+        const result = wasm.Shape_cylinder(bx, by, bz, ax, ay, az, radius, height);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Cylinder spanning the segment between two points.
+     */
+    static cylinderBetween(x1, y1, z1, x2, y2, z2, radius) {
+
+        const result = wasm.Shape_cylinder_between(x1, y1, z1, x2, y2, z2, radius);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Cone with apex at (`ax`, `ay`, `az`) opening along direction (`dx`, `dy`, `dz`).
+     */
+    static cone(ax, ay, az, dx, dy, dz, radius, height) {
+
+        const result = wasm.Shape_cone(ax, ay, az, dx, dy, dz, radius, height);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Torus centered at (`cx`, `cy`, `cz`) with the given major/minor radii and
+     * axis (`ax`, `ay`, `az`).
+     */
+    static torus(cx, cy, cz, majorR, minorR, ax, ay, az) {
+
+        const result = wasm.Shape_torus(cx, cy, cz, majorR, minorR, ax, ay, az);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Rectangular pyramid: base center, half-extents, height, up-axis.
+     */
+    static pyramid(bx, by, bz, halfW, halfD, height, ax, ay, az) {
+
+        const result = wasm.Shape_pyramid(bx, by, bz, halfW, halfD, height, ax, ay, az);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Flat disk: center, radius, plane normal, thickness.
+     */
+    static disk(cx, cy, cz, radius, nx, ny, nz, thickness) {
+
+        const result = wasm.Shape_disk(cx, cy, cz, radius, nx, ny, nz, thickness);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Finite plane patch: origin, two spanning vectors `u`/`v`, extents along
+     * each, thickness.
+     */
+    static plane(ox, oy, oz, ux, uy, uz, vx, vy, vz, uExt, vExt, thickness) {
+
+        const result = wasm.Shape_plane(ox, oy, oz, ux, uy, uz, vx, vy, vz, uExt, vExt, thickness);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Filled triangle between three vertices, thickened by `thickness`.
+     */
+    static triangle(ax, ay, az, bx, by, bz, cx, cy, cz, thickness) {
+
+        const result = wasm.Shape_triangle(ax, ay, az, bx, by, bz, cx, cy, cz, thickness);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Line segment between two points, thickened by `thickness`.
+     */
+    static line(x1, y1, z1, x2, y2, z2, thickness) {
+
+        const result = wasm.Shape_line(x1, y1, z1, x2, y2, z2, thickness);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Bézier curve through `control_points` (flat `[x0, y0, z0, x1, y1, z1, …]`,
+     * so the length must be a non-zero multiple of 3), thickened by `thickness`
+     * and sampled at `resolution` steps.
+     */
+    static bezier(controlPoints, thickness, resolution) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const controlPointsSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.slice(wasm, controlPoints, "f32")));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Shape_bezier(diplomatReceive.buffer, controlPointsSlice.ptr, thickness, resolution);
+
+        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 Shape(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Any SDF tree as a Shape: the same JSON the terrain sampler takes
+     * (primitives, smooth booleans, noise — see the SDF guide) becomes
+     * fillable with every brush, combinable with other shapes, and
+     * usable in masked fills. Normals come from the field gradient, so
+     * the shaded brush shades smooth blends smoothly. Errors with
+     * `Parse` on invalid JSON and `InvalidArgument` for unbounded trees
+     * (use `sdf_bounded`).
+     */
+    static sdf(sdfJson) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const sdfJsonSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, sdfJson)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Shape_sdf(diplomatReceive.buffer, sdfJsonSlice.ptr);
+
+        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 Shape(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Like `sdf`, with explicit sampling bounds (inclusive block
+     * coordinates) for unbounded trees such as planes.
+     */
+    static sdfBounded(sdfJson, minX, minY, minZ, maxX, maxY, maxZ) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const sdfJsonSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, sdfJson)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Shape_sdf_bounded(diplomatReceive.buffer, sdfJsonSlice.ptr, minX, minY, minZ, maxX, maxY, maxZ);
+
+        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 Shape(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Hollowed-out copy of this shape with the given wall thickness (clones the
+     * input, like the old `shape_hollow`).
+     */
+    hollow(thickness) {
+
+        const result = wasm.Shape_hollow(this.ffiValue, thickness);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Boolean union of this shape and `other` (clones both inputs).
+     */
+    unionWith(other) {
+
+        const result = wasm.Shape_union_with(this.ffiValue, other.ffiValue);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Boolean intersection of this shape and `other` (clones both inputs).
+     */
+    intersectionWith(other) {
+
+        const result = wasm.Shape_intersection_with(this.ffiValue, other.ffiValue);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Boolean difference: this shape minus `other` (clones both inputs).
+     */
+    differenceWith(other) {
+
+        const result = wasm.Shape_difference_with(this.ffiValue, other.ffiValue);
+
+        try {
+            return new Shape(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/renderer/SortStrategy.d.mts

@@ -0,0 +1,86 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Ordering applied to region positions before bit assignment
+ * (PORTING rule 10).
+ */
+export class SortStrategy {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Sort by Y ascending, then X, then Z (default Minecraft layer
+     * order). The first position after sorting is bit 0 (LSB).
+     */
+    static yxz(): SortStrategy;
+
+    /**
+     * Sort by X ascending, then Y, then Z.
+     */
+    static xyz(): SortStrategy;
+
+    /**
+     * Sort by Z ascending, then Y, then X.
+     */
+    static zyx(): SortStrategy;
+
+    /**
+     * Sort by Y descending, then X ascending, then Z ascending.
+     */
+    static yDescXz(): SortStrategy;
+
+    /**
+     * Sort by X descending, then Y ascending, then Z ascending.
+     */
+    static xDescYz(): SortStrategy;
+
+    /**
+     * Sort by Z descending, then Y ascending, then X ascending.
+     */
+    static zDescYx(): SortStrategy;
+
+    /**
+     * Old ABI name: `sort_strategy_descending`.
+     */
+    static descending(): SortStrategy;
+
+    /**
+     * Sort by Euclidean distance from the reference point, closest
+     * first (ties broken by Y, X, Z ascending).
+     */
+    static distanceFrom(x: number, y: number, z: number): SortStrategy;
+
+    /**
+     * Sort by Euclidean distance from the reference point, farthest
+     * first (ties broken by Y, X, Z descending).
+     */
+    static distanceFromDesc(x: number, y: number, z: number): SortStrategy;
+
+    /**
+     * Keep positions in the order they were added (no sorting). Useful
+     * when positions were ordered manually or box order matters.
+     */
+    static preserve(): SortStrategy;
+
+    /**
+     * Reverse of the order positions were added.
+     */
+    static reverse(): SortStrategy;
+
+    /**
+     * Parse from a name (e.g. "yxz", "descending", "preserve").
+     */
+    static fromString(s: string): SortStrategy;
+
+    /**
+     * The strategy name.
+     */
+    name(): string;
+}

package/renderer/SortStrategy.d.ts

@@ -0,0 +1,86 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Ordering applied to region positions before bit assignment
+ * (PORTING rule 10).
+ */
+export class SortStrategy {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Sort by Y ascending, then X, then Z (default Minecraft layer
+     * order). The first position after sorting is bit 0 (LSB).
+     */
+    static yxz(): SortStrategy;
+
+    /**
+     * Sort by X ascending, then Y, then Z.
+     */
+    static xyz(): SortStrategy;
+
+    /**
+     * Sort by Z ascending, then Y, then X.
+     */
+    static zyx(): SortStrategy;
+
+    /**
+     * Sort by Y descending, then X ascending, then Z ascending.
+     */
+    static yDescXz(): SortStrategy;
+
+    /**
+     * Sort by X descending, then Y ascending, then Z ascending.
+     */
+    static xDescYz(): SortStrategy;
+
+    /**
+     * Sort by Z descending, then Y ascending, then X ascending.
+     */
+    static zDescYx(): SortStrategy;
+
+    /**
+     * Old ABI name: `sort_strategy_descending`.
+     */
+    static descending(): SortStrategy;
+
+    /**
+     * Sort by Euclidean distance from the reference point, closest
+     * first (ties broken by Y, X, Z ascending).
+     */
+    static distanceFrom(x: number, y: number, z: number): SortStrategy;
+
+    /**
+     * Sort by Euclidean distance from the reference point, farthest
+     * first (ties broken by Y, X, Z descending).
+     */
+    static distanceFromDesc(x: number, y: number, z: number): SortStrategy;
+
+    /**
+     * Keep positions in the order they were added (no sorting). Useful
+     * when positions were ordered manually or box order matters.
+     */
+    static preserve(): SortStrategy;
+
+    /**
+     * Reverse of the order positions were added.
+     */
+    static reverse(): SortStrategy;
+
+    /**
+     * Parse from a name (e.g. "yxz", "descending", "preserve").
+     */
+    static fromString(s: string): SortStrategy;
+
+    /**
+     * The strategy name.
+     */
+    name(): string;
+}