nucleation 0.5.1 → 0.7.0

package/Schematic.d.ts

@@ -1,8 +1,8 @@
 // generated by diplomat-tool
-import type { BlockPos } from "./BlockPos"
-import type { BlockState } from "./BlockState"
-import type { Dimensions } from "./Dimensions"
-import type { NucleationError } from "./NucleationError"
+import type { BlockPos } from "./BlockPos.mjs"
+import type { BlockState } from "./BlockState.mjs"
+import type { Dimensions } from "./Dimensions.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 

package/SchematicBuilder.d.mts

@@ -0,0 +1,103 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Fluent builder for schematics from character-mapped text layers.
+ *
+ * `build` is consuming (PORTING rule 11): the inner builder is held in an
+ * `Option` and taken on `build`; every method afterwards returns
+ * `AlreadyConsumed`.
+ */
+export class SchematicBuilder {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Create a new builder, pre-loaded with the standard Unicode palette
+     * (override any character via `map` or `palette`).
+     */
+    static create(): SchematicBuilder;
+
+    /**
+     * Parse a builder from the canonical template text format.
+     */
+    static fromTemplate(template: string): SchematicBuilder;
+
+    /**
+     * Set the schematic name.
+     */
+    name(name: string): void;
+
+    /**
+     * Map a palette character to a block string. `ch` must contain exactly
+     * one character (its first char is used).
+     */
+    map(ch: string, block: string): void;
+
+    /**
+     * Append layers. `layers_json` is a JSON array of arrays of row strings,
+     * e.g. `[["ab","cd"],["ef","gh"]]`.
+     */
+    layers(layersJson: string): void;
+
+    /**
+     * Append a single layer of rows. `rows_json` is a JSON array of strings,
+     * e.g. `["abc", "def"]`. Equivalent to a one-element layers array.
+     */
+    layer(rowsJson: string): void;
+
+    /**
+     * Bulk-register palette characters. `pairs_json` is a JSON array of
+     * `[char, block]` two-element arrays, e.g.
+     * `[["c", "minecraft:gray_concrete"], [" ", "minecraft:air"]]`.
+     */
+    palette(pairsJson: string): void;
+
+    /**
+     * Set the build offset applied to every placed block.
+     */
+    offset(x: number, y: number, z: number): void;
+
+    /**
+     * Register the standard Unicode palette (redstone wires, repeaters,
+     * comparators, torches, blocks, air...; the same set `create`
+     * pre-loads), overwriting any clashing character mappings.
+     */
+    useStandardPalette(): void;
+
+    /**
+     * Register the minimal palette (an essentials-only subset of the
+     * standard one), overwriting any clashing character mappings.
+     */
+    useMinimalPalette(): void;
+
+    /**
+     * Register the compact ASCII-only palette, overwriting any clashing
+     * character mappings.
+     */
+    useCompactPalette(): void;
+
+    /**
+     * Run pre-build validation without consuming the builder.
+     */
+    validate(): void;
+
+    /**
+     * Serialize the builder back into the canonical template format.
+     */
+    toTemplate(): string;
+
+    /**
+     * Build the schematic. Consuming: the builder cannot be reused afterwards
+     * (subsequent calls return `AlreadyConsumed`), including after a failed
+     * build.
+     */
+    build(): Schematic;
+}

package/SchematicBuilder.d.ts

@@ -1,6 +1,6 @@
 // generated by diplomat-tool
-import type { NucleationError } from "./NucleationError"
-import type { Schematic } from "./Schematic"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 

package/SchematicRegions.d.mts

@@ -0,0 +1,93 @@
+// generated by diplomat-tool
+import type { DefinitionRegion } from "./DefinitionRegion.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Namespace type for the schematic-attached definition-region operations
+ * (PORTING rule 12; the `Schematic` opaque lives in another module, so
+ * these are statics taking it explicitly, like `Autostack`).
+ */
+export class SchematicRegions {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Insert (or overwrite) `region` under `name`.
+     */
+    static add(schematic: Schematic, name: string, region: DefinitionRegion): void;
+
+    /**
+     * Overwrite the region stored under `name` (identical to `add` in the
+     * old ABI too; kept as a separate method for 1:1 coverage of
+     * `schematic_update_region`).
+     */
+    static update(schematic: Schematic, name: string, region: DefinitionRegion): void;
+
+    /**
+     * A copy of the region stored under `name`. Errors with `NotFound` when
+     * absent.
+     */
+    static get(schematic: Schematic, name: string): DefinitionRegion;
+
+    /**
+     * Remove the region stored under `name`. Errors with `NotFound` when
+     * absent.
+     */
+    static remove(schematic: Schematic, name: string): void;
+
+    /**
+     * The names of every definition region, written as a JSON array string.
+     */
+    static namesJson(schematic: Schematic): string;
+
+    /**
+     * Create an empty region under `name`.
+     */
+    static create(schematic: Schematic, name: string): void;
+
+    /**
+     * Create a single-point region under `name`.
+     */
+    static createFromPoint(schematic: Schematic, name: string, x: number, y: number, z: number): void;
+
+    /**
+     * Create a single-box region under `name`.
+     */
+    static createFromBounds(schematic: Schematic, name: string, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): void;
+
+    /**
+     * Create a single-box region under `name` and return a copy of it.
+     */
+    static createRegion(schematic: Schematic, name: string, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): DefinitionRegion;
+
+    /**
+     * Add a box to the region stored under `name`. Errors with `NotFound`
+     * when absent.
+     */
+    static addBoundsTo(schematic: Schematic, name: string, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): void;
+
+    /**
+     * Add a point to the region stored under `name`. Errors with `NotFound`
+     * when absent.
+     */
+    static addPointTo(schematic: Schematic, name: string, x: number, y: number, z: number): void;
+
+    /**
+     * Set a metadata entry on the region stored under `name`. Errors with
+     * `NotFound` when absent.
+     */
+    static setMetadataOn(schematic: Schematic, name: string, key: string, value: string): void;
+
+    /**
+     * Shift the region stored under `name` by (`dx`, `dy`, `dz`). Errors
+     * with `NotFound` when absent.
+     */
+    static shiftRegion(schematic: Schematic, name: string, dx: number, dy: number, dz: number): void;
+}

package/SchematicRegions.d.ts

@@ -1,7 +1,7 @@
 // generated by diplomat-tool
-import type { DefinitionRegion } from "./DefinitionRegion"
-import type { NucleationError } from "./NucleationError"
-import type { Schematic } from "./Schematic"
+import type { DefinitionRegion } from "./DefinitionRegion.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 

package/Scripting.d.mts

@@ -0,0 +1,40 @@
+// generated by diplomat-tool
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * Namespace for the script-runner free functions of the old ABI
+ * (`run_lua_script`, `run_js_script`, `run_script`).
+ */
+export class Scripting {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    /**
+     * Run a Lua script file. Returns the schematic the script assigns to
+     * `result`; `NotFound` if it produced none, `Parse` if it failed, and
+     * `InvalidArgument` when built without the `scripting-lua` feature.
+     */
+    static runLuaScript(path: string): Schematic;
+
+    /**
+     * Run a JS script file. Returns the schematic the script assigns to
+     * `result`; `NotFound` if it produced none, `Parse` if it failed, and
+     * `InvalidArgument` when built without the `scripting-js` feature.
+     */
+    static runJsScript(path: string): Schematic;
+
+    /**
+     * Run a script file, auto-detecting the engine by extension (`.lua` or
+     * `.js`). Returns the schematic the script assigns to `result`; `NotFound`
+     * if it produced none, `Parse` if it failed (including unsupported
+     * extensions).
+     */
+    static runScript(path: string): Schematic;
+}

package/Scripting.d.ts

@@ -1,6 +1,6 @@
 // generated by diplomat-tool
-import type { NucleationError } from "./NucleationError"
-import type { Schematic } from "./Schematic"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 

package/Sdf.d.mts

@@ -0,0 +1,234 @@
+// generated by diplomat-tool
+import type { Field3 } from "./Field3.mjs"
+import type { FieldProgram } from "./FieldProgram.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
+import type { SdfAxis } from "./SdfAxis.mjs"
+import type { SdfBounds } from "./SdfBounds.mjs"
+import type { SdfCellMode } from "./SdfCellMode.mjs"
+import type { SdfNormal } from "./SdfNormal.mjs"
+import type { Shape } from "./Shape.mjs"
+import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
+
+
+
+/**
+ * An immutable, composable signed-distance-field expression graph.
+ *
+ * Primitive constructors and every combinator return a new graph, so values
+ * can be shared safely between Flow nodes and across Kotlin/Java, JavaScript,
+ * and Python bindings. JSON is retained only for explicit import/export and
+ * the legacy sampling helpers.
+ */
+export class Sdf {
+    /** @internal */
+    get ffiValue(): pointer;
+    /** @internal */
+    constructor();
+
+
+    static sphere(radius: number): Sdf;
+
+    /**
+     * Axis-aligned rounded box, centered at the origin.
+     */
+    static boxShape(halfX: number, halfY: number, halfZ: number, rounding: number): Sdf;
+
+    static ellipsoid(radiusX: number, radiusY: number, radiusZ: number): Sdf;
+
+    static torus(majorRadius: number, minorRadius: number): Sdf;
+
+    /**
+     * Torus ring cut down to an arc. `cap_angle_degrees` is the half-aperture
+     * in `(0, 180]`, measured from +X and mirrored across X; `180` is a full
+     * torus.
+     */
+    static cappedTorus(majorRadius: number, minorRadius: number, capAngleDegrees: number): Sdf;
+
+    /**
+     * Chain-link shape: a torus stretched along Z by `half_length` and
+     * capped by two half-tori. `half_length: 0` is a plain torus.
+     */
+    static link(majorRadius: number, minorRadius: number, halfLength: number): Sdf;
+
+    static capsule(ax: number, ay: number, az: number, bx: number, by: number, bz: number, radius: number): Sdf;
+
+    /**
+     * Convex hull of two spheres: a capsule with a linear taper between
+     * `r1` (at `a`) and `r2` (at `b`) instead of one constant radius.
+     */
+    static roundCone(ax: number, ay: number, az: number, bx: number, by: number, bz: number, r1: number, r2: number): Sdf;
+
+    /**
+     * Sphere of `radius` intersected with an infinite cone of
+     * half-aperture `angle_degrees` (in `(0, 180)`) from the +Y axis,
+     * apex at the origin.
+     */
+    static solidAngle(radius: number, angleDegrees: number): Sdf;
+
+    /**
+     * Sphere cut by the plane `y = height`, keeping the cap above it
+     * (a dome). `height` must be strictly between `-radius` and
+     * `radius`.
+     */
+    static cutSphere(radius: number, height: number): Sdf;
+
+    /**
+     * Open (hollow) shell of `cut_sphere`'s dome: just the spherical
+     * cap surface, offset by `thickness`, with no flat floor.
+     */
+    static cutHollowSphere(radius: number, height: number, thickness: number): Sdf;
+
+    static cappedCylinder(radius: number, halfHeight: number): Sdf;
+
+    /**
+     * Exact Y-axis cylinder with infinite extent. Sampling requires explicit bounds.
+     */
+    static infiniteCylinder(radius: number): Sdf;
+
+    static cappedCone(halfHeight: number, bottomRadius: number, topRadius: number): Sdf;
+
+    static plane(normalX: number, normalY: number, normalZ: number, offset: number): Sdf;
+
+    static octahedron(size: number): Sdf;
+
+    static hexPrism(radius: number, halfHeight: number): Sdf;
+
+    static superPrism(halfX: number, halfY: number, halfZ: number, exponent: number): Sdf;
+
+    /**
+     * Hollow wireframe box: only the 12 edge beams are solid.
+     */
+    static boxFrame(halfX: number, halfY: number, halfZ: number, thickness: number): Sdf;
+
+    /**
+     * Exact but unbounded Y-axis infinite cone: apex at the origin,
+     * single nappe opening along +Y, half-aperture `angle_degrees`
+     * strictly in `(0, 90)`.
+     */
+    static infiniteCone(angleDegrees: number): Sdf;
+
+    /**
+     * Square-base pyramid, vertically centered: base (half-extent
+     * `half_base`) at `y = -height/2`, apex at `y = height/2`. `height`
+     * must be at least the smallest positive normal `f32`.
+     */
+    static squarePyramid(halfBase: number, height: number): Sdf;
+
+    static cells(frequency: number, seed: number, jitter: number, mode: SdfCellMode, threshold: number): Sdf;
+
+    unionWith(other: Sdf): Sdf;
+
+    intersectionWith(other: Sdf): Sdf;
+
+    subtract(other: Sdf): Sdf;
+
+    smoothUnion(other: Sdf, radius: number): Sdf;
+
+    smoothSubtract(other: Sdf, radius: number): Sdf;
+
+    smoothIntersection(other: Sdf, radius: number): Sdf;
+
+    rounded(radius: number): Sdf;
+
+    shell(thickness: number): Sdf;
+
+    /**
+     * Symmetric difference (XOR): solid where exactly one of `self`/
+     * `other` is solid.
+     */
+    xorWith(other: Sdf): Sdf;
+
+    /**
+     * Stretches this graph with IQ's origin-centered `opElongate` fold.
+     * Exactness requires a suitable origin-centered, reflection-symmetric
+     * child; off-center/asymmetric children are mirrored and produce only
+     * an estimate. Half-lengths must be finite and non-negative, with at
+     * least one strictly positive.
+     */
+    elongate(halfX: number, halfY: number, halfZ: number): Sdf;
+
+    translate(x: number, y: number, z: number): Sdf;
+
+    rotate(xDegrees: number, yDegrees: number, zDegrees: number): Sdf;
+
+    scale(factor: number): Sdf;
+
+    mirror(axis: SdfAxis): Sdf;
+
+    /**
+     * Twists this graph about the Y axis by `amount` radians per unit
+     * Y (IQ's `opTwist`). *Distorted*: not guaranteed exact even when
+     * `self` is.
+     */
+    twist(amount: number): Sdf;
+
+    /**
+     * Cheaply bends this graph by `amount` radians per unit X (IQ's
+     * `opCheapBend`). *Distorted*: not guaranteed exact even when
+     * `self` is.
+     */
+    bend(amount: number): Sdf;
+
+    repeatInfinite(spacingX: number, spacingY: number, spacingZ: number): Sdf;
+
+    repeatCounted(spacingX: number, spacingY: number, spacingZ: number, countX: number, countY: number, countZ: number): Sdf;
+
+    /**
+     * Finite rigid instances of this graph at arbitrary XYZ offsets.
+     * `offsets` is flat `[x0, y0, z0, x1, y1, z1, ...]` and may contain
+     * at most 4096 points.
+     */
+    repeatPoints(offsets: Array<number>): Sdf;
+
+    displace(amplitude: number, frequency: number, seed: number, octaves: number): Sdf;
+
+    /**
+     * Offset this surface by a reusable scalar field. The resulting zero
+     * set is generally an approximate field, not an exact distance field.
+     */
+    offsetByField(field: Field3, amplitude: number): Sdf;
+
+    warp(amplitude: number, frequency: number, seed: number): Sdf;
+
+    evalAt(x: number, y: number, z: number): number;
+
+    normal(x: number, y: number, z: number, epsilon: number): SdfNormal;
+
+    /**
+     * Conservative finite bounds, or `NotFound` for an unbounded graph
+     * (a bare `plane` or `infinite_cylinder` has no finite extent).
+     */
+    bounds(): SdfBounds;
+
+    toShape(): Shape;
+
+    toShapeBounded(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): Shape;
+
+    static fromJsonString(json: string): Sdf;
+
+    toJson(): string;
+
+    /**
+     * Wrap a validated {@link FieldProgram} as an `Sdf` graph (cloning it,
+     * with its own explicit bounds and distance-kind metadata), so it
+     * composes with every other combinator.
+     */
+    static fromProgram(program: FieldProgram): Sdf;
+
+    /**
+     * Legacy JSON-first terrain helper. Prefer typed constructors and
+     * `to_shape()` with `BuildingTool.fill()` for new code.
+     */
+    static schematicFromSdfAuto(sdfJson: string, rulesJson: string): Schematic;
+
+    /**
+     * Legacy JSON-first terrain helper with optional explicit bounds.
+     */
+    static schematicFromSdf(sdfJson: string, rulesJson: string, hasBounds: boolean, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): Schematic;
+
+    /**
+     * Legacy JSON-first evaluator. Prefer `Sdf.from_json_string(...).eval_at(...)`.
+     */
+    static eval(sdfJson: string, x: number, y: number, z: number): number;
+}