@aethervtt/shard-mesh 0.1.0 → 0.2.1

package/dist/builder.d.ts

@@ -0,0 +1,146 @@
+import type { MeshData } from './mesh.js';
+/**
+ * A procedural modelling toolkit (spec 0045): append shapes, deform them, and finish into
+ * `MeshData`. Data lives in growable TypedArrays (no per-vertex objects), in f64 until `finish`.
+ *
+ * Deterministic: only +, −, ×, ÷, and sqrt (trig through `sinCos`), so the same calls give the same
+ * bytes in every JavaScript engine. That's what generators (0042) need.
+ */
+export declare class MeshBuilder {
+    /** xyz per vertex. */
+    positions: Float64Array;
+    /** xyz per vertex (zero until normals are computed or a shape writes them). */
+    normalData: Float64Array;
+    /** uv per vertex. */
+    uvData: Float64Array;
+    /** rgba per vertex, or undefined until something sets a color. */
+    colorData: Float64Array | undefined;
+    /** Second uv set per vertex, or undefined until something sets one. */
+    uv1Data: Float64Array | undefined;
+    /** xyzw per vertex, after `tangents()`. */
+    tangentData: Float64Array | undefined;
+    indices: Uint32Array;
+    vertexCount: number;
+    /** Index count (three per triangle). */
+    indexCount: number;
+    /** Whether `normals` hold real normals for every vertex. */
+    private hasNormals;
+    static create(): MeshBuilder;
+    /** A builder holding a copy of `mesh`. */
+    static from(mesh: MeshData): MeshBuilder;
+    get triangleCount(): number;
+    private reserve;
+    /** Appends a vertex and returns its index. A zero normal means "compute it in `finish`". */
+    vertex(x: number, y: number, z: number, nx?: number, ny?: number, nz?: number, u?: number, v?: number): number;
+    triangle(a: number, b: number, c: number): this;
+    /** Two triangles, a-b-c and a-c-d (counter-clockwise front faces). */
+    quad(a: number, b: number, c: number, d: number): this;
+    /** Sets one vertex's color (linear rgba). Other vertices default to white. */
+    color(vertex: number, r: number, g: number, b: number, a?: number): this;
+    private ensureColors;
+    /**
+     * Sets one vertex's second uv set. Engine generators (0045) put a part code and a shade there
+     * (0 bark or base, 1 leaf or tip; a per-vertex variation), which vegetation materials tint by.
+     */
+    uv1(vertex: number, u: number, v: number): this;
+    /** Sets the second uv set of every vertex from `first` on. */
+    uv1All(u: number, v: number, first?: number): this;
+    /** Colors every vertex from `first` on (default: all of them). */
+    colorAll(r: number, g: number, b: number, a?: number, first?: number): this;
+    /** A sphere of `radius` subdivided `detail` times from an icosahedron (10 · 4^detail + 2 vertices). */
+    icosphere(detail: number, radius?: number): this;
+    /** An axis-aligned box centered on the origin, with flat faces. */
+    box(options?: {
+        x?: number;
+        y?: number;
+        z?: number;
+    }): this;
+    /**
+     * A surface of revolution around +Y: `profile` is [radius, y] pairs from bottom to top, swept
+     * through `sides` steps. A radius of 0 closes that end to a point.
+     */
+    lathe(profile: ArrayLike<number>, options?: {
+        sides?: number;
+        caps?: boolean;
+    }): this;
+    private cap;
+    /** A cylinder (or a cone, with `radiusTop` 0) on +Y, centered on the origin. */
+    cylinder(options?: {
+        radius?: number;
+        radiusTop?: number;
+        height?: number;
+        sides?: number;
+        caps?: boolean;
+    }): this;
+    /**
+     * A tube along a curve (xyz points): rings of `sides` vertices, oriented by parallel transport
+     * so they don't twist. `radius` is one number or one per point (0 at an end makes a point).
+     */
+    tube(curve: ArrayLike<number>, radius: number | ArrayLike<number>, options?: {
+        sides?: number;
+        caps?: boolean;
+        v0?: number;
+        vScale?: number;
+    }): this;
+    /**
+     * Moves every vertex along its normal by `fn(position, normal, index)` metres (normals are
+     * computed first where missing). Synchronous: for generator code, which runs off the main thread.
+     */
+    displace(fn: (position: Float64Array, normal: Float64Array, index: number) => number, first?: number): this;
+    /**
+     * Moves every vertex along its normal by `amount × noise(position)`, sampling all positions in one
+     * batch: `sample(points, out)` is a batch noise call, such as a generator's
+     * `(p, out) => ctx.noise.sample(graph, seed, p, out)`.
+     */
+    displaceNoise(sample: (points: Float32Array, out: Float32Array) => void, amount: number, first?: number): this;
+    /** Scales positions per axis about the origin (normals follow the inverse transpose). */
+    scale(x: number, y?: number, z?: number, first?: number): this;
+    /** Moves vertices from `first` on. */
+    translate(x: number, y: number, z: number, first?: number): this;
+    /**
+     * Transforms vertices from `first` on by a column-major 4×4 affine matrix (normals by its
+     * inverse transpose, renormalized).
+     */
+    transform(m: ArrayLike<number>, first?: number): this;
+    /**
+     * Extrudes a set of triangles (indices of triangles, i.e. index / 3) by `distance` along their
+     * average normal per vertex: the set moves out, and its boundary gets side walls.
+     */
+    extrude(faceSet: ArrayLike<number>, distance: number): this;
+    private copyVertex;
+    /**
+     * Appends another mesh (a builder or MeshData), optionally transformed by a column-major 4×4
+     * affine matrix.
+     */
+    merge(other: MeshBuilder | MeshData, transform?: ArrayLike<number>): this;
+    /**
+     * Merges vertices closer than `epsilon` (positions only; the first vertex's attributes win) and
+     * drops triangles that collapse.
+     */
+    weld(epsilon?: number): this;
+    /** Keeps vertices `keep[0..count)` (in that order) and rewrites indices through `remap`. */
+    private compact;
+    /**
+     * Recomputes normals from the triangles (area-weighted). Faces meeting at more than `angle`
+     * degrees keep a hard edge (their shared vertices are split); `angle: 180` smooths everything.
+     */
+    normals(options?: {
+        angle?: number;
+    }): this;
+    private computeNormals;
+    private ensureNormals;
+    /**
+     * Per-vertex tangents (xyzw, w the handedness) from the UV gradient (Lengyel's method, averaged
+     * per vertex), or any direction perpendicular to the normal where there's no gradient.
+     */
+    tangents(): this;
+    /**
+     * UVs projected along each vertex's dominant normal axis, `scale` metres per repeat: cheap
+     * texturing for rocks and crystals, with seams where the axis changes.
+     */
+    uvsTriplanar(scale?: number): this;
+    /** The mesh as `MeshData` (f32 attributes; u16 indices when they fit). Normals are filled in. */
+    finish(): MeshData;
+}
+/** Any unit vector perpendicular to (x, y, z) (a unit vector), written into `out`. */
+export declare function perpendicular(x: number, y: number, z: number, out: Float64Array): Float64Array;