nucleation 0.10.22 → 0.10.24

package/renderer/PaletteBuilder.d.ts

@@ -0,0 +1,119 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Palette } from "./Palette.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Filter-driven palette construction (wraps
+ * {@link crate::building::PaletteBuilder}, which fronts blockpedia's
+ * `BlockFilter`). Call flag methods, then `build` — the builder is
+ * consumed; further calls error with `AlreadyConsumed`.
+ */
+export class PaletteBuilder {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * A builder matching every colored block (no filters yet).
+     */
+    static create(): PaletteBuilder;
+
+    /**
+     * Exclude gravity-affected blocks (sand, gravel, ...).
+     */
+    excludeFalling(): void;
+
+    /**
+     * Exclude blocks with block entities (chests, furnaces, ...).
+     */
+    excludeTileEntities(): void;
+
+    /**
+     * Keep only full cube blocks (no stairs, slabs, fences, ...).
+     * Metadata-driven: uses the official model geometry extracted from
+     * the vanilla jars, not block-name guessing.
+     */
+    fullBlocksOnly(): void;
+
+    /**
+     * Exclude blocks that need supporting blocks (torches, rails, ...).
+     */
+    excludeNeedsSupport(): void;
+
+    /**
+     * Exclude transparent/translucent blocks (glass, leaves, ...).
+     * Metadata-driven: uses the per-block transparency flag from the
+     * block-data pipeline, not block-name guessing.
+     */
+    excludeTransparent(): void;
+
+    /**
+     * Exclude light-emitting blocks (glowstone, lanterns, ...).
+     */
+    excludeLightSources(): void;
+
+    /**
+     * Keep only blocks obtainable in survival.
+     */
+    survivalOnly(): void;
+
+    /**
+     * Exclude blocks whose id contains `keyword`.
+     */
+    excludeKeyword(keyword: string): void;
+
+    /**
+     * Keep only blocks whose id contains `keyword` (repeatable; matches
+     * any of the included keywords).
+     */
+    includeKeyword(keyword: string): void;
+
+    /**
+     * Require the vanilla block tag `t` (`minecraft:wool` or short
+     * `wool`, nested paths like `mineable/pickaxe` too). Repeatable —
+     * a block must carry ALL required tags (AND semantics).
+     */
+    tag(t: string): void;
+
+    /**
+     * Exclude blocks carrying the vanilla block tag `t` (any listed
+     * tag disqualifies). Repeatable.
+     */
+    excludeTag(t: string): void;
+
+    /**
+     * Keep only blocks of the official definition kind `k`
+     * (`minecraft:stair` or short `stair`; plain full blocks are
+     * `minecraft:block`). Repeatable — a block matching ANY listed
+     * kind passes (OR semantics).
+     */
+    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.
+     */
+    build(): Palette;
+}

package/renderer/PaletteBuilder.mjs

@@ -0,0 +1,457 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import { Palette } from "./Palette.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const PaletteBuilder_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.PaletteBuilder_destroy(ptr);
+});
+
+/**
+ * Filter-driven palette construction (wraps
+ * {@link crate::building::PaletteBuilder}, which fronts blockpedia's
+ * `BlockFilter`). Call flag methods, then `build` — the builder is
+ * consumed; further calls error with `AlreadyConsumed`.
+ */
+export class PaletteBuilder {
+    // 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("PaletteBuilder 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) {
+            PaletteBuilder_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * A builder matching every colored block (no filters yet).
+     */
+    static create() {
+
+        const result = wasm.PaletteBuilder_create();
+
+        try {
+            return new PaletteBuilder(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Exclude gravity-affected blocks (sand, gravel, ...).
+     */
+    excludeFalling() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_exclude_falling(diplomatReceive.buffer, this.ffiValue);
+
+        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();
+        }
+    }
+
+    /**
+     * Exclude blocks with block entities (chests, furnaces, ...).
+     */
+    excludeTileEntities() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_exclude_tile_entities(diplomatReceive.buffer, this.ffiValue);
+
+        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 full cube blocks (no stairs, slabs, fences, ...).
+     * Metadata-driven: uses the official model geometry extracted from
+     * the vanilla jars, not block-name guessing.
+     */
+    fullBlocksOnly() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_full_blocks_only(diplomatReceive.buffer, this.ffiValue);
+
+        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();
+        }
+    }
+
+    /**
+     * Exclude blocks that need supporting blocks (torches, rails, ...).
+     */
+    excludeNeedsSupport() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_exclude_needs_support(diplomatReceive.buffer, this.ffiValue);
+
+        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();
+        }
+    }
+
+    /**
+     * Exclude transparent/translucent blocks (glass, leaves, ...).
+     * Metadata-driven: uses the per-block transparency flag from the
+     * block-data pipeline, not block-name guessing.
+     */
+    excludeTransparent() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_exclude_transparent(diplomatReceive.buffer, this.ffiValue);
+
+        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();
+        }
+    }
+
+    /**
+     * Exclude light-emitting blocks (glowstone, lanterns, ...).
+     */
+    excludeLightSources() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_exclude_light_sources(diplomatReceive.buffer, this.ffiValue);
+
+        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 obtainable in survival.
+     */
+    survivalOnly() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_survival_only(diplomatReceive.buffer, this.ffiValue);
+
+        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();
+        }
+    }
+
+    /**
+     * Exclude blocks whose id contains `keyword`.
+     */
+    excludeKeyword(keyword) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const keywordSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, keyword)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_exclude_keyword(diplomatReceive.buffer, this.ffiValue, keywordSlice.ptr);
+
+        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();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Keep only blocks whose id contains `keyword` (repeatable; matches
+     * any of the included keywords).
+     */
+    includeKeyword(keyword) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const keywordSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, keyword)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_include_keyword(diplomatReceive.buffer, this.ffiValue, keywordSlice.ptr);
+
+        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();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Require the vanilla block tag `t` (`minecraft:wool` or short
+     * `wool`, nested paths like `mineable/pickaxe` too). Repeatable —
+     * a block must carry ALL required tags (AND semantics).
+     */
+    tag(t) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const tSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, t)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_tag(diplomatReceive.buffer, this.ffiValue, tSlice.ptr);
+
+        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();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Exclude blocks carrying the vanilla block tag `t` (any listed
+     * tag disqualifies). Repeatable.
+     */
+    excludeTag(t) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const tSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, t)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_exclude_tag(diplomatReceive.buffer, this.ffiValue, tSlice.ptr);
+
+        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();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Keep only blocks of the official definition kind `k`
+     * (`minecraft:stair` or short `stair`; plain full blocks are
+     * `minecraft:block`). Repeatable — a block matching ANY listed
+     * kind passes (OR semantics).
+     */
+    kind(k) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const kSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, k)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_kind(diplomatReceive.buffer, this.ffiValue, kSlice.ptr);
+
+        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();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * 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.
+     */
+    build() {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.PaletteBuilder_build(diplomatReceive.buffer, this.ffiValue);
+
+        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 Palette(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/renderer/README.md

@@ -0,0 +1,67 @@
+# nucleation
+
+A high-performance Minecraft schematic engine, compiled to WebAssembly from Rust. Parse, edit,
+diff, fingerprint, and generate schematics in Node or the browser.
+
+This package ships generated ESM bindings (with TypeScript typings) plus the WASM binary. It
+requires Node 18+ or a bundler; no native dependencies.
+
+## Install
+
+```bash
+npm install nucleation
+```
+
+## Quick start
+
+```javascript
+import { Schematic } from "nucleation";
+
+const schematic = Schematic.create("demo");
+schematic.setBlock(1, 2, 3, "minecraft:stone");
+console.log(schematic.getBlockName(1, 2, 3)); // "minecraft:stone"
+
+// Binary payloads cross the WASM boundary base64-encoded
+const b64 = schematic.toLitematicB64();
+const bytes = Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+const loaded = Schematic.fromLitematic(bytes);
+```
+
+## What is included
+
+The published WASM contains the core feature set: schematic editing, all schematic formats,
+world import (from zip) and export, the schematic builder, the procedural building tool,
+definition regions, diff and fingerprinting, autostack, NBT helpers, SDF sampling, and the
+in-memory store.
+
+Redstone simulation and mesh generation also work on WASM but are not compiled into the
+published binary. To use them, build a custom WASM from the
+[repository](https://github.com/Schem-at/Nucleation):
+
+```bash
+cargo build --release --target wasm32-unknown-unknown --lib --features bridge,simulation,meshing
+```
+
+and point the package's `diplomat.config.mjs` at your `nucleation.wasm`. GPU rendering and
+embedded scripting are native-only.
+
+## Documentation
+
+- [JavaScript API reference](https://github.com/Schem-at/Nucleation/blob/master/docs/javascript/README.md)
+- [Feature guides](https://github.com/Schem-at/Nucleation/tree/master/docs/guides)
+
+## License
+
+MIT
+
+### Renderer-only WebAssembly
+
+`import { Schematic } from "nucleation/renderer"` loads the bridge-only WASM build
+for schematic viewing and editing. Simulation, meshing and voxelization remain
+available from the main `nucleation` entry point. Each entry owns a separate WASM
+instance; import only the entry needed by a worker.
+
+Use `renderRegionsJson()` for region bounds and palettes, then
+`regionBlockIndices(name, start, count)` for owned `Uint32Array` windows of at most
+65,536 cells. Indices use x-fastest, then z, then y order. Call `clearContents()`
+when done to release schematic storage immediately.