nucleation 0.10.18 → 0.10.19

package/Schematic.d.mts

@@ -418,6 +418,11 @@ export class Schematic {
      * Air cells are materialized too — on a large sparse build this
      * dump is `volume()`-sized and can exhaust wasm memory; renderers
      * and analyzers want `get_non_air_blocks_json`.
+     *
+     * Prefer `get_non_air_blocks_json` for a block list,
+     * `count_blocks_json` for a material tally and
+     * `non_air_blocks_packed_b64` for bulk transfer. This method is
+     * kept for compatibility and is the wrong tool at any real size.
      */
     getAllBlocksJson(): string;
 
@@ -434,6 +439,53 @@ export class Schematic {
      */
     getNonAirBlocksJson(): string;
 
+    /**
+     * Non-air blocks tallied by id: `{"minecraft:stone": 123, ...}`.
+     * One pass, no per block allocation, so a caller that only wants a
+     * material list never has to pull `get_non_air_blocks_json`. "Air"
+     * covers `minecraft:air`, `cave_air` and `void_air` alike.
+     */
+    countBlocksJson(): string;
+
+    /**
+     * Apply a `{"from id": "to id"}` map in place and return how many
+     * blocks changed. Keys match on block id only, ignoring block
+     * states; values may carry states (`minecraft:oak_stairs[facing=north]`),
+     * but not NBT: `parse_block_string` only returns a `BlockState`, so
+     * any `{...}` payload on a `to` value is silently dropped rather
+     * than copied onto the replaced block.
+     * A block whose id is not a key is left alone, and so is one that
+     * already equals its target: the count is the number of blocks
+     * actually changed, so a map that rewrites stone to stone returns 0.
+     * Errors with `Parse` on malformed JSON or an unparseable target id.
+     */
+    replaceBlocksJson(mapJson: string): bigint;
+
+    /**
+     * Every non-air block as a compact binary blob, base64 encoded
+     * (`DiplomatWrite` is UTF-8 only, see `to_litematic_b64`). Little
+     * endian throughout:
+     *
+     * ```text
+     * u32 count
+     * count * { i32 x, i32 y, i32 z, u16 palette_index }
+     * u32 palette_json_len
+     * u8[palette_json_len]   ["minecraft:stone", ...]
+     * ```
+     *
+     * Palette indices are assigned in first-seen order, so the same
+     * schematic always packs identically. About seven times smaller
+     * than `get_non_air_blocks_json` and free of per block JSON
+     * parsing on the far side.
+     *
+     * Palette indices are `u16`, so at most 65,535 distinct non-air
+     * block states can be addressed. A schematic with more than that
+     * writes **an empty string**, not a truncated palette: callers must
+     * treat an empty result as "too many distinct states, fall back to
+     * `get_non_air_blocks_json`". No real build has that many.
+     */
+    nonAirBlocksPackedB64(): string;
+
     /**
      * All blocks within a sub-region (chunk) of the schematic, as the same
      * JSON array shape as `get_all_blocks_json`.

package/Schematic.d.ts

@@ -418,6 +418,11 @@ export class Schematic {
      * Air cells are materialized too — on a large sparse build this
      * dump is `volume()`-sized and can exhaust wasm memory; renderers
      * and analyzers want `get_non_air_blocks_json`.
+     *
+     * Prefer `get_non_air_blocks_json` for a block list,
+     * `count_blocks_json` for a material tally and
+     * `non_air_blocks_packed_b64` for bulk transfer. This method is
+     * kept for compatibility and is the wrong tool at any real size.
      */
     getAllBlocksJson(): string;
 
@@ -434,6 +439,53 @@ export class Schematic {
      */
     getNonAirBlocksJson(): string;
 
+    /**
+     * Non-air blocks tallied by id: `{"minecraft:stone": 123, ...}`.
+     * One pass, no per block allocation, so a caller that only wants a
+     * material list never has to pull `get_non_air_blocks_json`. "Air"
+     * covers `minecraft:air`, `cave_air` and `void_air` alike.
+     */
+    countBlocksJson(): string;
+
+    /**
+     * Apply a `{"from id": "to id"}` map in place and return how many
+     * blocks changed. Keys match on block id only, ignoring block
+     * states; values may carry states (`minecraft:oak_stairs[facing=north]`),
+     * but not NBT: `parse_block_string` only returns a `BlockState`, so
+     * any `{...}` payload on a `to` value is silently dropped rather
+     * than copied onto the replaced block.
+     * A block whose id is not a key is left alone, and so is one that
+     * already equals its target: the count is the number of blocks
+     * actually changed, so a map that rewrites stone to stone returns 0.
+     * Errors with `Parse` on malformed JSON or an unparseable target id.
+     */
+    replaceBlocksJson(mapJson: string): bigint;
+
+    /**
+     * Every non-air block as a compact binary blob, base64 encoded
+     * (`DiplomatWrite` is UTF-8 only, see `to_litematic_b64`). Little
+     * endian throughout:
+     *
+     * ```text
+     * u32 count
+     * count * { i32 x, i32 y, i32 z, u16 palette_index }
+     * u32 palette_json_len
+     * u8[palette_json_len]   ["minecraft:stone", ...]
+     * ```
+     *
+     * Palette indices are assigned in first-seen order, so the same
+     * schematic always packs identically. About seven times smaller
+     * than `get_non_air_blocks_json` and free of per block JSON
+     * parsing on the far side.
+     *
+     * Palette indices are `u16`, so at most 65,535 distinct non-air
+     * block states can be addressed. A schematic with more than that
+     * writes **an empty string**, not a truncated palette: callers must
+     * treat an empty result as "too many distinct states, fall back to
+     * `get_non_air_blocks_json`". No real build has that many.
+     */
+    nonAirBlocksPackedB64(): string;
+
     /**
      * All blocks within a sub-region (chunk) of the schematic, as the same
      * JSON array shape as `get_all_blocks_json`.

package/Schematic.mjs

@@ -1741,6 +1741,11 @@ export class Schematic {
      * Air cells are materialized too — on a large sparse build this
      * dump is `volume()`-sized and can exhaust wasm memory; renderers
      * and analyzers want `get_non_air_blocks_json`.
+     *
+     * Prefer `get_non_air_blocks_json` for a block list,
+     * `count_blocks_json` for a material tally and
+     * `non_air_blocks_packed_b64` for bulk transfer. This method is
+     * kept for compatibility and is the wrong tool at any real size.
      */
     getAllBlocksJson() {
         const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
@@ -1809,6 +1814,102 @@ export class Schematic {
         }
     }
 
+    /**
+     * Non-air blocks tallied by id: `{"minecraft:stone": 123, ...}`.
+     * One pass, no per block allocation, so a caller that only wants a
+     * material list never has to pull `get_non_air_blocks_json`. "Air"
+     * covers `minecraft:air`, `cave_air` and `void_air` alike.
+     */
+    countBlocksJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.Schematic_count_blocks_json(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Apply a `{"from id": "to id"}` map in place and return how many
+     * blocks changed. Keys match on block id only, ignoring block
+     * states; values may carry states (`minecraft:oak_stairs[facing=north]`),
+     * but not NBT: `parse_block_string` only returns a `BlockState`, so
+     * any `{...}` payload on a `to` value is silently dropped rather
+     * than copied onto the replaced block.
+     * A block whose id is not a key is left alone, and so is one that
+     * already equals its target: the count is the number of blocks
+     * actually changed, so a map that rewrites stone to stone returns 0.
+     * Errors with `Parse` on malformed JSON or an unparseable target id.
+     */
+    replaceBlocksJson(mapJson) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const mapJsonSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, mapJson)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 9, 8, true);
+
+
+        const result = wasm.Schematic_replace_blocks_json(diplomatReceive.buffer, this.ffiValue, mapJsonSlice.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 BigUint64Array(wasm.memory.buffer, diplomatReceive.buffer, 1))[0];
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Every non-air block as a compact binary blob, base64 encoded
+     * (`DiplomatWrite` is UTF-8 only, see `to_litematic_b64`). Little
+     * endian throughout:
+     *
+     * ```text
+     * u32 count
+     * count * { i32 x, i32 y, i32 z, u16 palette_index }
+     * u32 palette_json_len
+     * u8[palette_json_len]   ["minecraft:stone", ...]
+     * ```
+     *
+     * Palette indices are assigned in first-seen order, so the same
+     * schematic always packs identically. About seven times smaller
+     * than `get_non_air_blocks_json` and free of per block JSON
+     * parsing on the far side.
+     *
+     * Palette indices are `u16`, so at most 65,535 distinct non-air
+     * block states can be addressed. A schematic with more than that
+     * writes **an empty string**, not a truncated palette: callers must
+     * treat an empty result as "too many distinct states, fall back to
+     * `get_non_air_blocks_json`". No real build has that many.
+     */
+    nonAirBlocksPackedB64() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.Schematic_non_air_blocks_packed_b64(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
     /**
      * All blocks within a sub-region (chunk) of the schematic, as the same
      * JSON array shape as `get_all_blocks_json`.

package/package.json

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