nucleation 0.10.21 → 0.10.23

package/renderer/Palette.mjs

@@ -0,0 +1,487 @@
+// generated by diplomat-tool
+import { NucleationError } from "./NucleationError.mjs"
+import wasm from "./diplomat-wasm.mjs";
+import * as diplomatRuntime from "./diplomat-runtime.mjs";
+
+const Palette_box_destroy_registry = new FinalizationRegistry((ptr) => {
+    wasm.Palette_destroy(ptr);
+});
+
+/**
+ * A set of colored blocks that color/gradient brushes snap their computed
+ * colors to (nearest neighbor in Oklab space). Wraps an Arc'd
+ * {@link crate::building::BlockPalette}; sharing one palette across many
+ * brushes is cheap.
+ */
+export class Palette {
+    // 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("Palette 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) {
+            Palette_box_destroy_registry.register(this, this.#ptr);
+        }
+
+        return this;
+    }
+    /** @internal */
+    get ffiValue() {
+        return this.#ptr;
+    }
+
+
+    /**
+     * Opaque building blocks and full glass blocks, for material-aware imports.
+     */
+    static materials() {
+
+        const result = wasm.Palette_materials();
+
+        try {
+            return new Palette(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Keep only opaque blocks (`false`) or full glass blocks (`true`).
+     * Includes/excludes remain respected. Returns an empty palette when
+     * no suitable block exists; check `len()` before matching colours.
+     */
+    forMaterial(translucent) {
+
+        const result = wasm.Palette_for_material(this.ffiValue, translucent);
+
+        try {
+            return new Palette(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Every block blockpedia knows a color for (the default palette
+     * brushes use when none is set).
+     */
+    static all() {
+
+        const result = wasm.Palette_all();
+
+        try {
+            return new Palette(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Only solid blocks: no transparency, gravity, tile entities, or
+     * support requirements.
+     */
+    static solid() {
+
+        const result = wasm.Palette_solid();
+
+        try {
+            return new Palette(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Conservative structural set (full building blocks).
+     */
+    static structural() {
+
+        const result = wasm.Palette_structural();
+
+        try {
+            return new Palette(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Decorative set: allows stairs/slabs but no tile entities.
+     */
+    static decorative() {
+
+        const result = wasm.Palette_decorative();
+
+        try {
+            return new Palette(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * The 16 concrete colors (excludes concrete powder).
+     */
+    static concrete() {
+
+        const result = wasm.Palette_concrete();
+
+        try {
+            return new Palette(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * The 16 wool colors.
+     */
+    static wool() {
+
+        const result = wasm.Palette_wool();
+
+        try {
+            return new Palette(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Terracotta colors (excludes glazed variants).
+     */
+    static terracotta() {
+
+        const result = wasm.Palette_terracotta();
+
+        try {
+            return new Palette(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * Genuinely gray blocks: opaque full cubes whose measured color
+     * is near-neutral (low Oklab chroma) — judged from color data,
+     * not names.
+     */
+    static grayscale() {
+
+        const result = wasm.Palette_grayscale();
+
+        try {
+            return new Palette(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * The planks family — a natural light→dark wood ramp.
+     */
+    static wood() {
+
+        const result = wasm.Palette_wood();
+
+        try {
+            return new Palette(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * A copy of this palette with ordered dithering enabled: brushes
+     * snapping through it alternate between the two nearest blocks per
+     * voxel (4x4 Bayer threshold, deterministic in position), which
+     * reads as intermediate shades at a distance — the classic map-art
+     * trick. Ramp and list queries are unaffected.
+     */
+    dithered() {
+
+        const result = wasm.Palette_dithered(this.ffiValue);
+
+        try {
+            return new Palette(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * A copy of this palette ordered by perceptual lightness (Oklab L,
+     * dark → light). Combined with `block_ids_json`, gives a
+     * ready-to-index ramp: `ids[i]` for intensity `i / (len - 1)`.
+     */
+    sortedByLightness() {
+
+        const result = wasm.Palette_sorted_by_lightness(this.ffiValue);
+
+        try {
+            return new Palette(diplomatRuntime.internalConstructor, result, []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * JSON array of exactly `steps` DISTINCT block ids forming the
+     * smoothest ramp this palette can make from (`r1`,`g1`,`b1`) to
+     * (`r2`,`g2`,`b2`): targets are evenly spaced along the Oklab line
+     * and blocks are chosen by a minimum-cost monotonic matching, so
+     * off-hue blocks are penalized and no block repeats. Errors with
+     * `InvalidArgument` when the palette has fewer than `steps` blocks,
+     * `steps` is 0, or start equals end.
+     */
+    rampIdsJson(r1, g1, b1, r2, g2, b2, steps) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Palette_ramp_ids_json(diplomatReceive.buffer, this.ffiValue, r1, g1, b1, r2, g2, b2, steps, 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 of exactly `steps` block ids sampling the color
+     * gradient from (`r1`,`g1`,`b1`) to (`r2`,`g2`,`b2`) in Oklab
+     * space, each step snapped to this palette's closest block. Built
+     * for value→block lookups (heatmaps, fractals): index the returned
+     * list by `intensity * (steps - 1)`. Entries may repeat on coarse
+     * palettes; errors with `NotFound` on an empty palette.
+     */
+    gradientIdsJson(r1, g1, b1, r2, g2, b2, steps) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Palette_gradient_ids_json(diplomatReceive.buffer, this.ffiValue, r1, g1, b1, r2, g2, b2, steps, 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 of exactly `steps` block ids sampling an Oklab gradient
+     * whose endpoints are the measured texture colors of `start_block`
+     * and `end_block`. Errors with `NotFound` when either id is unknown
+     * or has no measured color, or when this palette is empty.
+     */
+    gradientIdsBetweenBlocksJson(startBlock, endBlock, steps) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const startBlockSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, startBlock)));
+        const endBlockSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, endBlock)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Palette_gradient_ids_between_blocks_json(diplomatReceive.buffer, this.ffiValue, startBlockSlice.ptr, endBlockSlice.ptr, steps, 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();
+        }
+    }
+
+    /**
+     * Custom palette from a JSON array of block ids, e.g.
+     * `["minecraft:stone", "minecraft:oak_planks"]`. Ids blockpedia has
+     * no color for are silently skipped — check `len` afterwards.
+     */
+    static fromBlockIds(idsJson) {
+        let functionCleanupArena = new diplomatRuntime.CleanupArena();
+
+        const idsJsonSlice = functionCleanupArena.alloc(diplomatRuntime.DiplomatBuf.sliceWrapper(wasm, diplomatRuntime.DiplomatBuf.str8(wasm, idsJson)));
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+
+        const result = wasm.Palette_from_block_ids(diplomatReceive.buffer, idsJsonSlice.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 Palette(diplomatRuntime.internalConstructor, diplomatRuntime.ptrRead(wasm, diplomatReceive.buffer), []);
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            functionCleanupArena.free();
+
+            diplomatReceive.free();
+        }
+    }
+
+    /**
+     * Number of blocks in the palette.
+     */
+    len() {
+
+        const result = wasm.Palette_len(this.ffiValue);
+
+        try {
+            return result;
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+        }
+    }
+
+    /**
+     * The palette's block ids as a JSON array string.
+     */
+    blockIdsJson() {
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+    wasm.Palette_block_ids_json(this.ffiValue, write.buffer);
+
+        try {
+            return write.readString8();
+        }
+
+        finally {
+            diplomatRuntime.FUNCTION_PARAM_ALLOC.clean();
+            write.free();
+        }
+    }
+
+    /**
+     * Position-aware dithered snap: the block for the given RGB at
+     * voxel (x, y, z), alternating between the two nearest palette
+     * blocks per position (4x4 Bayer) — the per-pixel entry point for
+     * pixel art and image mapping. Deterministic. Errors with
+     * `NotFound` on an empty palette.
+     */
+    closestBlockDithered(r, g, b, x, y, z) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Palette_closest_block_dithered(diplomatReceive.buffer, this.ffiValue, r, g, b, x, y, z, 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();
+        }
+    }
+
+    /**
+     * The palette block whose color is closest (Oklab distance) to the
+     * given RGB. Errors with `NotFound` on an empty palette.
+     */
+    closestBlock(r, g, b) {
+        const diplomatReceive = new diplomatRuntime.DiplomatReceiveBuf(wasm, 5, 4, true);
+
+        const write = new diplomatRuntime.DiplomatWriteBuf(wasm);
+
+
+        const result = wasm.Palette_closest_block(diplomatReceive.buffer, this.ffiValue, r, g, b, 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();
+        }
+    }
+
+    constructor(symbol, ptr, selfEdge) {
+        return this.#internalConstructor(...arguments)
+    }
+}

package/renderer/PaletteBuilder.d.mts

@@ -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;
+}