nucleation 0.2.17 → 0.3.0

package/README.md

@@ -1,16 +1,10 @@
-# Nucleation for JavaScript / TypeScript
+# nucleation
 
-[![npm](https://img.shields.io/npm/v/nucleation.svg)](https://www.npmjs.com/package/nucleation)
+A high-performance Minecraft schematic engine, compiled to WebAssembly from Rust. Parse, edit,
+diff, fingerprint, and generate schematics in Node or the browser.
 
-JavaScript / TypeScript bindings for **Nucleation**, a high-performance
-Minecraft schematic engine. Read, edit, build, simulate, and mesh
-`.schematic`, `.litematic`, `.nbt`, and `.mcstructure` files — in the
-browser or in Node.
-
-The core is written in Rust and compiled to WebAssembly via wasm-bindgen.
-A single package works in modern browsers, bundlers, and Node 18+.
-
----
+This package ships generated ESM bindings (with TypeScript typings) plus the WASM binary. It
+requires Node 18+ or a bundler; no native dependencies.
 
 ## Install
 
@@ -18,206 +12,44 @@ A single package works in modern browsers, bundlers, and Node 18+.
 npm install nucleation
 ```
 
-```bash
-pnpm add nucleation
-```
-
-```bash
-bun add nucleation
-```
-
----
-
 ## Quick start
 
-```ts
-import init from "nucleation";
-import { Schematic } from "nucleation/api";
-
-await init(); // load the wasm module
+```javascript
+import { Schematic } from "nucleation";
 
-const bytes = await fetch("example.litematic").then((r) => r.arrayBuffer());
-const schem = Schematic.open(new Uint8Array(bytes), {
-  hint: "example.litematic",
-});
+const schematic = Schematic.create("demo");
+schematic.setBlock(1, 2, 3, "minecraft:stone");
+console.log(schematic.getBlockName(1, 2, 3)); // "minecraft:stone"
 
-schem.setBlock([0, 0, 0], "minecraft:gold_block");
-schem.setBlock([0, 1, 0], "minecraft:repeater", {
-  state: { delay: 4, facing: "east" },
-});
-
-const out = await schem.save("out.schem"); // Uint8Array
+// 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);
 ```
 
-### Hot loops
-
-```ts
-// One call into wasm — millions of placements/sec.
-const positions = Array.from({ length: 1_000_000 }, (_, x) => [x, 0, 0]);
-schem.setBlocks(positions, "minecraft:stone");
+## What is included
 
-// Pre-resolve once, place by index.
-const stone = schem.prepareBlock("minecraft:stone");
-for (const [x, y, z] of positions) {
-  schem.place(x, y, z, stone);
-}
-```
+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.
 
-### Tile-entity helpers
-
-```ts
-import { chest, sign, text, Item } from "nucleation/api";
-
-schem.setBlock([0, 0, 0], "minecraft:chest", {
-  state: { facing: "north" },
-  nbt: chest([
-    Item("minecraft:diamond", { count: 64 }),
-    Item("minecraft:elytra"),
-  ]),
-});
-
-schem.setBlock([0, 1, 0], "minecraft:oak_sign", {
-  nbt: sign([text("Loot", { color: "gold" }), "this way →"]),
-});
-```
-
-For lossless, fully-typed reads/writes (64-bit NBT, item components), use the
-SNBT accessors: `getBlockEntitySnbt(x, y, z)` / `setBlockEntity(x, y, z, id, snbt)`
-and `getEntitiesSnbt()` / `addEntityFromSnbt(snbt)`.
-
-### Version conversion (datafixers)
-
-Convert block / block-entity / item / entity data **between Minecraft data
-versions** — a Rust port of PaperMC's DataConverter. Forward conversion is
-lossless; down-converting to an older version returns a JSON **loss report** so
-you can warn before saving. Importers capture the source data version (set it
-manually for versionless formats; classic `.schematic` ≈ `1343`).
-
-```ts
-schem.fromLitematic(bytes);
-console.log(schem.getSourceDataVersion());          // e.g. 3953 (1.21)
-console.log(SchematicWrapper.canonicalDataVersion()); // 4790 (in-memory target)
-
-// Save a copy for 1.16.5 (data version 2586); schem itself is untouched.
-const { bytes: out, loss } = schem.toLitematicForVersion(2586);
-const report = JSON.parse(loss);                     // [] when lossless
-for (const e of report) {                            // {version, kind, severity, path, detail}
-  console.warn(`[${e.severity}] ${e.path}: ${e.detail}`);
-}
-```
-
-### Storage
-
-The `Store` class is pluggable byte storage — it decides *where bytes live*,
-independent of the schematic format. Keys are `/`-delimited UTF-8 paths.
-
-```ts
-import { Store } from "nucleation";
-
-const store = new Store("mem://"); // throws on error
-
-store.put("schems/base.litematic", out); // (key, data: Uint8Array) -> void
-const data = store.get("schems/base.litematic"); // -> Uint8Array | undefined
-store.has("schems/base.litematic"); // -> boolean
-store.list("schems/"); // -> string[] (keys with this prefix)
-store.delete("schems/base.litematic"); // -> void (idempotent)
-```
+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):
 
-A schematic can read/write a `Store` directly — the format is inferred from the
-key's extension. This is the way to use remote/host storage on the web; it works
-with `mem://` and with `Store.fromCallbacks({ get, put, has, delete, list, health })`.
-
-```ts
-const schem = SchematicWrapper.openFromStore(store, "schems/base.litematic");
-schem.saveToStore(store, "schems/copy.schem"); // format from extension
-```
-
-> **Web = `mem://` only.** On `wasm32` the in-memory backend is the only one
-> available — the filesystem, S3, Redis, and Postgres backends are native-only
-> and compiled out of the WASM build. Errors surface as thrown JS exceptions.
-
----
-
-## Diff & Fingerprint
-
-Canonically fingerprint a build, dedup near-duplicates, and structurally diff two
-builds — all under an equivalence ruleset chosen by **preset name**:
-
-- `"exact"` — material- and orientation-sensitive (identical blockstates only).
-- `"shape"` — occupancy only; palette and orientation ignored.
-- `"structural"` — functional shape, rotation- and material-agnostic.
-- `"redstone_computational"` (alias `"redstone"`) — redstone-logic equivalence,
-  rotation- and cosmetic-material-agnostic.
-- `"redstone_survival"` — like `"redstone"`, keeping survival material constraints.
-
-`diff()` also takes an optional overrides object with per-edit cost weights and a
-symmetry group: `{ cost_add?, cost_delete?, cost_change?, cost_swap?, symmetry? }`.
-
-```ts
-import { SchematicWrapper } from "nucleation";
-
-const a = new SchematicWrapper();
-a.from_litematic(aBytes);
-const b = new SchematicWrapper();
-b.from_litematic(bBytes);
-
-// 32-hex canonical hash (rotation/translation/palette-agnostic per preset).
-console.log(a.fingerprint("structural"));
-
-// Cheap exact dedup + fuzzy FFT shape distance (0.0 == same shape).
-if (a.isDuplicateOf(b, "structural")) console.log("duplicate build");
-console.log("footprint distance:", a.footprintDistance(b, "structural"));
-
-// Dims + token histogram as JSON.
-console.log(a.signature("structural"));
-
-// Structural diff -> DiffWrapper. `preset` defaults to "exact".
-const d = a.diff(b, "redstone");
-console.log("distance:", d.distance);
-// support = fraction of the larger build's cells that aligned (confidence,
-// NOT a similarity %).
-console.log("support:", d.support);
-
-// Each delta as its own SchematicWrapper.
-d.added(); d.removed(); d.changed(); d.swapped(); d.markers();
-
-// Lossless JSON round-trips via DiffWrapper.fromJson; summaryJson() is compact.
-import { DiffWrapper } from "nucleation";
-const full = d.toJson();
-const restored = DiffWrapper.fromJson(full);
-console.log(d.summaryJson());
-```
-
-The glowing-overlay GLB requires a build compiled with the `meshing` feature
-(the published WASM bundle includes it):
-
-```ts
-// `afterGlb` is the meshed "after" build (Uint8Array); returns a new GLB.
-const glb = d.toOverlayGlb(afterGlb); // -> Uint8Array
+```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
 
-Full reference, including simulation, meshing, and resource-pack rendering,
-lives in the main repository:
-
-- [Nucleation on GitHub](https://github.com/Schem-at/Nucleation)
 - [JavaScript API reference](https://github.com/Schem-at/Nucleation/blob/master/docs/javascript/README.md)
-- [Schematic Builder guide](https://github.com/Schem-at/Nucleation/blob/master/docs/guide/schematic-builder.md)
-
----
-
-## Why Rust + WASM?
-
-Nucleation's core is shared across Rust, WebAssembly/JS, Python, and C/PHP —
-one engine, one set of behaviour, one set of tests. The npm package you
-install is the same engine that powers the Python and Rust libraries; the
-wasm boundary is the only thing between your JS and native-speed parsing
-and meshing.
+- [Feature guides](https://github.com/Schem-at/Nucleation/tree/master/docs/guides)
 
 ## License
 
-MIT. See the [main repository](https://github.com/Schem-at/Nucleation)
-for details.
+MIT

package/RawMeshExport.d.ts

@@ -0,0 +1,74 @@
+// generated by diplomat-tool
+import type { MeshConfig } from "./MeshConfig"
+import type { NucleationError } from "./NucleationError"
+import type { ResourcePack } from "./ResourcePack"
+import type { Schematic } from "./Schematic"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Raw vertex streams for custom rendering. Wraps {@link crate::meshing::RawMeshExport}.
+ */
+export class RawMeshExport {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Export raw mesh data (old ABI: `schematic_to_raw_mesh`).
+     */
+    static create(schematic: Schematic, pack: ResourcePack, config: MeshConfig): RawMeshExport;
+
+    /**
+     * Number of vertices in the exported mesh.
+     */
+    vertexCount(): number;
+
+    /**
+     * Number of triangles in the exported mesh.
+     */
+    triangleCount(): number;
+
+    /**
+     * Flat `[x,y,z,...]` positions as little-endian `f32` bytes, base64-encoded.
+     */
+    positionsB64(): string;
+
+    /**
+     * Flat normals as little-endian `f32` bytes, base64-encoded.
+     */
+    normalsB64(): string;
+
+    /**
+     * Flat UVs as little-endian `f32` bytes, base64-encoded.
+     */
+    uvsB64(): string;
+
+    /**
+     * Flat vertex colors as little-endian `f32` bytes, base64-encoded.
+     */
+    colorsB64(): string;
+
+    /**
+     * Triangle indices as little-endian `u32` bytes, base64-encoded.
+     */
+    indicesB64(): string;
+
+    /**
+     * Raw RGBA texture pixels, base64-encoded.
+     */
+    textureRgbaB64(): string;
+
+    /**
+     * Width of the baked texture in pixels.
+     */
+    textureWidth(): number;
+
+    /**
+     * Height of the baked texture in pixels.
+     */
+    textureHeight(): number;
+}

package/RawMeshExport.mjs

@@ -0,0 +1,243 @@
+// generated by diplomat-tool
+import { MeshConfig } from "./MeshConfig.mjs"
+import { NucleationError } from "./NucleationError.mjs"
+import { ResourcePack } from "./ResourcePack.mjs"
+import { Schematic } from "./Schematic.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const RawMeshExport_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.RawMeshExport_destroy(ptr);
+});
+
+/**
+ * Raw vertex streams for custom rendering. Wraps {@link crate::meshing::RawMeshExport}.
+ */
+export class RawMeshExport {
+    // 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("RawMeshExport 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) {
+            RawMeshExport_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Export raw mesh data (old ABI: `schematic_to_raw_mesh`).
+     */
+    static create(schematic, pack, config) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.RawMeshExport_create(diplomatReceive.buffer, schematic.ffiValue, pack.ffiValue, config.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 RawMeshExport(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Number of vertices in the exported mesh.
+     */
+    vertexCount() {
+
+        const result = wasm.RawMeshExport_vertex_count(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Number of triangles in the exported mesh.
+     */
+    triangleCount() {
+
+        const result = wasm.RawMeshExport_triangle_count(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Flat `[x,y,z,...]` positions as little-endian `f32` bytes, base64-encoded.
+     */
+    positionsB64() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.RawMeshExport_positions_b64(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Flat normals as little-endian `f32` bytes, base64-encoded.
+     */
+    normalsB64() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.RawMeshExport_normals_b64(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Flat UVs as little-endian `f32` bytes, base64-encoded.
+     */
+    uvsB64() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.RawMeshExport_uvs_b64(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Flat vertex colors as little-endian `f32` bytes, base64-encoded.
+     */
+    colorsB64() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.RawMeshExport_colors_b64(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Triangle indices as little-endian `u32` bytes, base64-encoded.
+     */
+    indicesB64() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.RawMeshExport_indices_b64(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Raw RGBA texture pixels, base64-encoded.
+     */
+    textureRgbaB64() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.RawMeshExport_texture_rgba_b64(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Width of the baked texture in pixels.
+     */
+    textureWidth() {
+
+        const result = wasm.RawMeshExport_texture_width(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Height of the baked texture in pixels.
+     */
+    textureHeight() {
+
+        const result = wasm.RawMeshExport_texture_height(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/RedstoneGraph.d.ts

@@ -0,0 +1,58 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * An extracted redstone logic graph. Wraps
+ * {@link crate::simulation::graph::RedstoneGraph}.
+ */
+export class RedstoneGraph {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Number of nodes in the graph.
+     */
+    nodeCount(): number;
+
+    /**
+     * Total number of directed edges in the graph.
+     */
+    edgeCount(): number;
+
+    /**
+     * The nodes as a JSON array string.
+     */
+    nodesJson(): string;
+
+    /**
+     * The directed edges as a JSON array string.
+     */
+    edgesJson(): string;
+
+    /**
+     * Computed graph features as a JSON object string.
+     */
+    featuresJson(): string;
+
+    /**
+     * Fingerprint (hex string) for `preset` ("structural" | "functional" |
+     * "exact"; empty defaults to "structural").
+     */
+    fingerprint(preset: string): string;
+
+    /**
+     * Serialize the whole graph to JSON.
+     */
+    toJson(): string;
+
+    /**
+     * Deserialize a graph from a JSON string.
+     */
+    static fromJson(json: string): RedstoneGraph;
+}