nucleation 0.3.7 → 0.3.9

package/Blocks.d.ts

@@ -38,6 +38,14 @@ export class Blocks {
 
     /**
      * Ids of every block carrying the vanilla block tag, as a sorted
+     * Blocks whose measured texture color is within `max_distance`
+     * (Oklab; ~0.05 = same color family, ~0.15 = generous) of the given
+     * RGB, as a JSON array of `{"id", "color": [r,g,b], "distance"}`
+     * sorted nearest-first. Blocks without color data never match.
+     */
+    static byColorJson(r: number, g: number, b: number, maxDistance: number): string;
+
+    /**
      * JSON array string (`[]` for unknown tags). Accepts
      * `minecraft:wool` and short `wool` forms, including nested paths
      * like `mineable/pickaxe`.

package/Blocks.mjs

@@ -102,6 +102,35 @@ export class Blocks {
 
     /**
      * Ids of every block carrying the vanilla block tag, as a sorted
+     * Blocks whose measured texture color is within `max_distance`
+     * (Oklab; ~0.05 = same color family, ~0.15 = generous) of the given
+     * RGB, as a JSON array of `{"id", "color": [r,g,b], "distance"}`
+     * sorted nearest-first. Blocks without color data never match.
+     */
+    static byColorJson(r, g, b, maxDistance) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Blocks_by_color_json(diplomatReceive.buffer, r, g, b, maxDistance, write.buffer);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
      * JSON array string (`[]` for unknown tags). Accepts
      * `minecraft:wool` and short `wool` forms, including nested paths
      * like `mineable/pickaxe`.

package/Brush.d.ts

@@ -51,6 +51,15 @@ export class Brush {
      */
     static pointGradient(positions: Array<number>, colors: Array<number>, falloff: number, space: InterpolationSpace): Brush;
 
+    /**
+     * Spotlight-lit base color (`r`, `g`, `b`): Lambert shading toward a
+     * cone light at (`px`, `py`, `pz`) aimed along (`dx`, `dy`, `dz`).
+     * Full intensity inside 0.7 × `cone_angle_deg`, smoothstep falloff
+     * to zero at the cone edge; surfaces facing away or outside the cone
+     * drop to a 4% ambient floor.
+     */
+    static spotlight(px: number, py: number, pz: number, dx: number, dy: number, dz: number, coneAngleDeg: number, r: number, g: number, b: number): Brush;
+
     /**
      * Use `palette` for this brush's color→block snapping instead of the
      * default all-blocks palette. No-op for `solid` brushes, which place

package/Brush.mjs

@@ -167,6 +167,26 @@ export class Brush {
         }
     }
 
+    /**
+     * Spotlight-lit base color (`r`, `g`, `b`): Lambert shading toward a
+     * cone light at (`px`, `py`, `pz`) aimed along (`dx`, `dy`, `dz`).
+     * Full intensity inside 0.7 × `cone_angle_deg`, smoothstep falloff
+     * to zero at the cone edge; surfaces facing away or outside the cone
+     * drop to a 4% ambient floor.
+     */
+    static spotlight(px, py, pz, dx, dy, dz, coneAngleDeg, r, g, b) {
+
+        const result = wasm.Brush_spotlight(px, py, pz, dx, dy, dz, coneAngleDeg, r, g, b);
+
+        try {
+            return new Brush(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
     /**
      * Use `palette` for this brush's color→block snapping instead of the
      * default all-blocks palette. No-op for `solid` brushes, which place

package/PaletteBuilder.d.ts

@@ -94,6 +94,24 @@ export class PaletteBuilder {
      */
     kind(k: string): void;
 
+    /**
+     * Keep only blocks whose measured Oklab lightness L is within
+     * `[min, max]` (0.0 = black, 1.0 = white).
+     */
+    lightnessBetween(min: number, max: number): void;
+
+    /**
+     * Keep only near-neutral blocks: measured Oklab chroma at most
+     * `max` (the grayscale preset uses 0.022).
+     */
+    chromaBelow(max: number): void;
+
+    /**
+     * Keep only blocks whose measured color is within `max_distance`
+     * (Oklab; ~0.05 = same family, ~0.15 = generous) of the RGB color.
+     */
+    colorNear(r: number, g: number, b: number, maxDistance: number): void;
+
     /**
      * Build the palette; consumes the builder.
      */

package/PaletteBuilder.mjs

@@ -359,6 +359,75 @@ export class PaletteBuilder {
         }
     }
 
+    /**
+     * Keep only blocks whose measured Oklab lightness L is within
+     * `[min, max]` (0.0 = black, 1.0 = white).
+     */
+    lightnessBetween(min, max) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_lightness_between(diplomatReceive.buffer, this.ffiValue, min, max);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Keep only near-neutral blocks: measured Oklab chroma at most
+     * `max` (the grayscale preset uses 0.022).
+     */
+    chromaBelow(max) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_chroma_below(diplomatReceive.buffer, this.ffiValue, max);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Keep only blocks whose measured color is within `max_distance`
+     * (Oklab; ~0.05 = same family, ~0.15 = generous) of the RGB color.
+     */
+    colorNear(r, g, b, maxDistance) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_color_near(diplomatReceive.buffer, this.ffiValue, r, g, b, maxDistance);
+
+        try {
+            if (!diplomatReceive.resultFlag) {
+                const cause = new NucleationError(diplomatRuntime.internalConstructor, diplomatRuntime.enumDiscriminant(wasm, diplomatReceive.buffer));
+                throw new globalThis.Error('NucleationError.' + cause.value, { cause });
+            }
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
     /**
      * Build the palette; consumes the builder.
      */

package/Shape.d.ts

@@ -85,6 +85,23 @@ export class Shape {
      */
     static bezier(controlPoints: Array<number>, thickness: number, resolution: number): Shape;
 
+    /**
+     * 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: string): Shape;
+
+    /**
+     * Like `sdf`, with explicit sampling bounds (inclusive block
+     * coordinates) for unbounded trees such as planes.
+     */
+    static sdfBounded(sdfJson: string, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): Shape;
+
     /**
      * Hollowed-out copy of this shape with the given wall thickness (clones the
      * input, like the old `shape_hollow`).

package/Shape.mjs

@@ -265,6 +265,69 @@ export class Shape {
         }
     }
 
+    /**
+     * 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`).

package/Voxelizer.d.ts

@@ -0,0 +1,56 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError"
+import type { Palette } from "./Palette"
+import type { Schematic } from "./Schematic"
+import type { Shape } from "./Shape"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Namespace for the mesh-voxelization entry points (GLB/OBJ → shapes
+ * and textured schematics).
+ */
+export class Voxelizer {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Load a binary glTF (`.glb`, embedded buffers/images) and voxelize
+     * it into a fillable Shape: the model is uniformly scaled so its
+     * largest dimension equals `target_size` voxels, centered on x/z
+     * with its base resting at y = 0. Solidity is a parity test at each
+     * voxel center (robust on closed meshes), plus — when `shell` > 0 —
+     * every voxel whose center is within `shell` blocks of the surface,
+     * which rescues thin walls and hollow vessels (0.7–1.0 closes
+     * single-voxel shells; 0 = pure parity). Errors with `Parse` on
+     * malformed/triangle-less GLB and `InvalidArgument` on a
+     * non-positive `target_size`.
+     */
+    static shapeFromGlb(data: Array<number>, targetSize: number, shell: number): Shape;
+
+    /**
+     * Load a Wavefront OBJ (`v`/`vt`/`f` lines; polygon faces are
+     * fan-triangulated, negative indices supported, materials ignored)
+     * and voxelize it into a fillable Shape, fitted and shelled exactly
+     * like `shape_from_glb`. Errors with `Parse` on malformed/triangle-less
+     * OBJ and `InvalidArgument` on invalid UTF-8 or a non-positive
+     * `target_size`.
+     */
+    static shapeFromObj(text: string, targetSize: number, shell: number): Shape;
+
+    /**
+     * Load a binary glTF and voxelize it directly into a textured
+     * schematic named `name`: every solid voxel becomes the `palette`
+     * block closest to its nearest-surface texture color (interior
+     * voxels inherit the nearest surface color; voxels without texture
+     * info snap to mid-gray). `shell` behaves as in `shape_from_glb` —
+     * use ~0.7 for thin-walled models. Errors with `Parse` on malformed GLB and
+     * `InvalidArgument` on invalid UTF-8 or a non-positive
+     * `target_size`.
+     */
+    static schematicFromGlbTextured(data: Array<number>, targetSize: number, shell: number, palette: Palette, name: string): Schematic;
+}

package/Voxelizer.mjs

@@ -0,0 +1,155 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import { Palette } from "./Palette.mjs"
+import { Schematic } from "./Schematic.mjs"
+import { Shape } from "./Shape.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const Voxelizer_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.Voxelizer_destroy(ptr);
+});
+
+/**
+ * Namespace for the mesh-voxelization entry points (GLB/OBJ → shapes
+ * and textured schematics).
+ */
+export class Voxelizer {
+    // 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("Voxelizer 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) {
+            Voxelizer_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Load a binary glTF (`.glb`, embedded buffers/images) and voxelize
+     * it into a fillable Shape: the model is uniformly scaled so its
+     * largest dimension equals `target_size` voxels, centered on x/z
+     * with its base resting at y = 0. Solidity is a parity test at each
+     * voxel center (robust on closed meshes), plus — when `shell` > 0 —
+     * every voxel whose center is within `shell` blocks of the surface,
+     * which rescues thin walls and hollow vessels (0.7–1.0 closes
+     * single-voxel shells; 0 = pure parity). Errors with `Parse` on
+     * malformed/triangle-less GLB and `InvalidArgument` on a
+     * non-positive `target_size`.
+     */
+    static shapeFromGlb(data, targetSize, shell) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const dataSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.slice(wasm, data, "u8")));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Voxelizer_shape_from_glb(diplomatReceive.buffer, dataSlice.ptr, targetSize, shell);
+
+        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();
+        }
+    }
+
+    /**
+     * Load a Wavefront OBJ (`v`/`vt`/`f` lines; polygon faces are
+     * fan-triangulated, negative indices supported, materials ignored)
+     * and voxelize it into a fillable Shape, fitted and shelled exactly
+     * like `shape_from_glb`. Errors with `Parse` on malformed/triangle-less
+     * OBJ and `InvalidArgument` on invalid UTF-8 or a non-positive
+     * `target_size`.
+     */
+    static shapeFromObj(text, targetSize, shell) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const textSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, text)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Voxelizer_shape_from_obj(diplomatReceive.buffer, textSlice.ptr, targetSize, shell);
+
+        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();
+        }
+    }
+
+    /**
+     * Load a binary glTF and voxelize it directly into a textured
+     * schematic named `name`: every solid voxel becomes the `palette`
+     * block closest to its nearest-surface texture color (interior
+     * voxels inherit the nearest surface color; voxels without texture
+     * info snap to mid-gray). `shell` behaves as in `shape_from_glb` —
+     * use ~0.7 for thin-walled models. Errors with `Parse` on malformed GLB and
+     * `InvalidArgument` on invalid UTF-8 or a non-positive
+     * `target_size`.
+     */
+    static schematicFromGlbTextured(data, targetSize, shell, palette, name) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const dataSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.slice(wasm, data, "u8")));
+        const nameSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, name)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Voxelizer_schematic_from_glb_textured(diplomatReceive.buffer, dataSlice.ptr, targetSize, shell, palette.ffiValue, nameSlice.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 Schematic(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/index.d.ts

@@ -106,6 +106,8 @@ export { Store } from "./Store"
 
 export { StoreIo } from "./StoreIo"
 
+export { Voxelizer } from "./Voxelizer"
+
 export { WorldChunkView } from "./WorldChunkView"
 
 export { WorldSink } from "./WorldSink"

package/index.mjs

@@ -104,6 +104,8 @@ export { Store } from "./Store.mjs"
 
 export { StoreIo } from "./StoreIo.mjs"
 
+export { Voxelizer } from "./Voxelizer.mjs"
+
 export { WorldChunkView } from "./WorldChunkView.mjs"
 
 export { WorldSink } from "./WorldSink.mjs"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nucleation",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "A high-performance Minecraft schematic parser and utility library",
   "type": "module",
   "main": "index.mjs",