nucleation 0.3.2 → 0.3.4

package/Blocks.d.ts

@@ -0,0 +1,83 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Namespace for read-only queries over the built-in block table
+ * (Java 26.2 blocks + official semantics extracted from the vanilla
+ * jars: definition kinds, base-block links, block tags, model
+ * geometry). All list results are JSON array strings sorted by id;
+ * block/tag/kind arguments accept both `minecraft:`-prefixed and
+ * short forms (`minecraft:oak_stairs` / `oak_stairs`).
+ */
+export class Blocks {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Full facts for one block as a JSON object:
+     * `{id, kind, base_block, tags: [...], full_cube, transparent,
+     * color: [r, g, b] | null, properties: {name: [values...]},
+     * default_state: {name: value}}`. `kind` is the official
+     * definition kind (`minecraft:stair`, plain full blocks are
+     * `minecraft:block`); `base_block` is the block this one is a
+     * shape variant of (or `null`); `color` is the texture-derived
+     * average RGB. Errors with `NotFound` for unknown ids.
+     */
+    static getJson(id: string): string;
+
+    /**
+     * All known block ids as a sorted JSON array string.
+     */
+    static idsJson(): string;
+
+    /**
+     * Ids of every block carrying the vanilla block tag, as a sorted
+     * JSON array string (`[]` for unknown tags). Accepts
+     * `minecraft:wool` and short `wool` forms, including nested paths
+     * like `mineable/pickaxe`.
+     */
+    static byTagJson(tag: string): string;
+
+    /**
+     * Ids of every block of the given official definition kind
+     * (`minecraft:stair`, `minecraft:slab`, `minecraft:door`, ...), as
+     * a sorted JSON array string (`[]` for unknown kinds).
+     */
+    static byKindJson(kind: string): string;
+
+    /**
+     * The base block followed by all its shape variants — blocks whose
+     * `base_block` is `base_id` (stairs, slabs, walls, fences of the
+     * base) — as a JSON array string. The base itself is always first;
+     * variants follow sorted by id. Errors with `NotFound` for unknown
+     * base ids.
+     */
+    static variantsOfJson(baseId: string): string;
+
+    /**
+     * All known vanilla block tag names as a sorted JSON array string
+     * (`minecraft:`-prefixed, e.g. `minecraft:wool`).
+     */
+    static tagsJson(): string;
+
+    /**
+     * Every property-value combination of the block as a JSON array of
+     * `{prop: value}` objects (a single `{}` entry for property-less
+     * blocks). Errors with `NotFound` for unknown ids and with
+     * `InvalidArgument` if the combination count exceeds 4096 (guard
+     * against pathological output; the current data tops out at 1350
+     * for `minecraft:note_block`).
+     */
+    static statesJson(id: string): string;
+
+    /**
+     * Total number of blocks in the table.
+     */
+    static count(): number;
+}

package/Blocks.mjs

@@ -0,0 +1,279 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const Blocks_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.Blocks_destroy(ptr);
+});
+
+/**
+ * Namespace for read-only queries over the built-in block table
+ * (Java 26.2 blocks + official semantics extracted from the vanilla
+ * jars: definition kinds, base-block links, block tags, model
+ * geometry). All list results are JSON array strings sorted by id;
+ * block/tag/kind arguments accept both `minecraft:`-prefixed and
+ * short forms (`minecraft:oak_stairs` / `oak_stairs`).
+ */
+export class Blocks {
+    // 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("Blocks 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) {
+            Blocks_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Full facts for one block as a JSON object:
+     * `{id, kind, base_block, tags: [...], full_cube, transparent,
+     * color: [r, g, b] | null, properties: {name: [values...]},
+     * default_state: {name: value}}`. `kind` is the official
+     * definition kind (`minecraft:stair`, plain full blocks are
+     * `minecraft:block`); `base_block` is the block this one is a
+     * shape variant of (or `null`); `color` is the texture-derived
+     * average RGB. Errors with `NotFound` for unknown ids.
+     */
+    static getJson(id) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const idSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, id)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Blocks_get_json(diplomatReceive.buffer, idSlice.ptr, 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();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * All known block ids as a sorted JSON array string.
+     */
+    static idsJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.Blocks_ids_json(write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Ids of every block carrying the vanilla block tag, as a sorted
+     * JSON array string (`[]` for unknown tags). Accepts
+     * `minecraft:wool` and short `wool` forms, including nested paths
+     * like `mineable/pickaxe`.
+     */
+    static byTagJson(tag) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const tagSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, tag)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Blocks_by_tag_json(diplomatReceive.buffer, tagSlice.ptr, 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();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * Ids of every block of the given official definition kind
+     * (`minecraft:stair`, `minecraft:slab`, `minecraft:door`, ...), as
+     * a sorted JSON array string (`[]` for unknown kinds).
+     */
+    static byKindJson(kind) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const kindSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, kind)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Blocks_by_kind_json(diplomatReceive.buffer, kindSlice.ptr, 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();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * The base block followed by all its shape variants — blocks whose
+     * `base_block` is `base_id` (stairs, slabs, walls, fences of the
+     * base) — as a JSON array string. The base itself is always first;
+     * variants follow sorted by id. Errors with `NotFound` for unknown
+     * base ids.
+     */
+    static variantsOfJson(baseId) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const baseIdSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, baseId)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Blocks_variants_of_json(diplomatReceive.buffer, baseIdSlice.ptr, 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();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * All known vanilla block tag names as a sorted JSON array string
+     * (`minecraft:`-prefixed, e.g. `minecraft:wool`).
+     */
+    static tagsJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.Blocks_tags_json(write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Every property-value combination of the block as a JSON array of
+     * `{prop: value}` objects (a single `{}` entry for property-less
+     * blocks). Errors with `NotFound` for unknown ids and with
+     * `InvalidArgument` if the combination count exceeds 4096 (guard
+     * against pathological output; the current data tops out at 1350
+     * for `minecraft:note_block`).
+     */
+    static statesJson(id) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const idSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, id)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Blocks_states_json(diplomatReceive.buffer, idSlice.ptr, 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();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+            write.free();
+        }
+    }
+
+    /**
+     * Total number of blocks in the table.
+     */
+    static count() {
+
+        const result = wasm.Blocks_count();
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/BuildingTool.d.ts

@@ -1,5 +1,6 @@
 // generated by diplomat-tool
 import type { Brush } from "./Brush"
+import type { NucleationError } from "./NucleationError"
 import type { Schematic } from "./Schematic"
 import type { Shape } from "./Shape"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
@@ -26,4 +27,20 @@ export class BuildingTool {
      * Fill `count` copies of `shape`, each offset by `offset * i`.
      */
     static rstack(schematic: Schematic, shape: Shape, brush: Brush, count: number, offsetX: number, offsetY: number, offsetZ: number): void;
+
+    /**
+     * Masked fill that preserves everything already placed: `brush` is
+     * only written where `schematic` currently has air (or nothing at
+     * all), so existing structures inside `shape` survive untouched.
+     */
+    static fillOnlyAir(schematic: Schematic, shape: Shape, brush: Brush): void;
+
+    /**
+     * Masked fill that only overwrites the listed blocks: `targets_json`
+     * is a JSON array of block ids (e.g. `["minecraft:stone"]`, state
+     * properties ignored) and every cell of `shape` whose current block
+     * id is in the list is replaced by `brush` — everything else,
+     * including air, is left alone.
+     */
+    static fillReplacing(schematic: Schematic, shape: Shape, brush: Brush, targetsJson: string): void;
 }

package/BuildingTool.mjs

@@ -1,5 +1,6 @@
 // generated by diplomat-tool
 import { Brush } from "./Brush.mjs"
+import { NucleationError } from "./NucleationError.mjs"
 import { Schematic } from "./Schematic.mjs"
 import { Shape } from "./Shape.mjs"
 import wasm from "./diplomat-wasm.mjs";
@@ -68,6 +69,52 @@ export class BuildingTool {
         }
     }
 
+    /**
+     * Masked fill that preserves everything already placed: `brush` is
+     * only written where `schematic` currently has air (or nothing at
+     * all), so existing structures inside `shape` survive untouched.
+     */
+    static fillOnlyAir(schematic, shape, brush) {
+    wasm.BuildingTool_fill_only_air(schematic.ffiValue, shape.ffiValue, brush.ffiValue);
+
+        try {}
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Masked fill that only overwrites the listed blocks: `targets_json`
+     * is a JSON array of block ids (e.g. `["minecraft:stone"]`, state
+     * properties ignored) and every cell of `shape` whose current block
+     * id is in the list is replaced by `brush` — everything else,
+     * including air, is left alone.
+     */
+    static fillReplacing(schematic, shape, brush, targetsJson) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const targetsJsonSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, targetsJson)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.BuildingTool_fill_replacing(diplomatReceive.buffer, schematic.ffiValue, shape.ffiValue, brush.ffiValue, targetsJsonSlice.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();
+        }
+    }
+
     constructor(symbol, ptr, selfEdge) {
         return this.#internalConstructor(...arguments)
     }

package/PaletteBuilder.d.ts

@@ -35,6 +35,8 @@ export class PaletteBuilder {
 
     /**
      * 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;
 
@@ -45,6 +47,8 @@ export class PaletteBuilder {
 
     /**
      * 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;
 
@@ -69,6 +73,27 @@ export class PaletteBuilder {
      */
     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;
+
     /**
      * Build the palette; consumes the builder.
      */

package/PaletteBuilder.mjs

@@ -105,6 +105,8 @@ export class PaletteBuilder {
 
     /**
      * 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);
@@ -149,6 +151,8 @@ export class PaletteBuilder {
 
     /**
      * 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);
@@ -268,6 +272,93 @@ export class PaletteBuilder {
         }
     }
 
+    /**
+     * 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();
+        }
+    }
+
     /**
      * Build the palette; consumes the builder.
      */

package/index.d.ts

@@ -18,6 +18,8 @@ export { Dimensions, Dimensions_obj } from "./Dimensions"
 
 export { Autostack } from "./Autostack"
 
+export { Blocks } from "./Blocks"
+
 export { Brush } from "./Brush"
 
 export { BuildingTool } from "./BuildingTool"

package/index.mjs

@@ -16,6 +16,8 @@ export { Dimensions } from "./Dimensions.mjs"
 
 export { Autostack } from "./Autostack.mjs"
 
+export { Blocks } from "./Blocks.mjs"
+
 export { Brush } from "./Brush.mjs"
 
 export { BuildingTool } from "./BuildingTool.mjs"

package/package.json

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