@adatechnology/game-shapes 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,253 @@
+import { S as ShapeSchema, G as GenerateOptions, a as ShapeBuffers, b as ShapeNode, P as PrimitiveNode, c as PrimitiveBuffers, d as ShapeOutline, B as BevelSpec, V as Vec3, H as HoleSpec, e as ShapeGenerator, C as Color, T as Transform, R as RotationOrder } from './worker-BZ7plgyI.js';
+export { f as Bounds, g as BoxNode, h as CircleNode, i as ConeNode, j as CustomNode, k as CylinderNode, D as DifferenceNode, E as ExtrudeNode, l as GeneratorContext, m as GeometryGroup, n as GroupNode, I as InstanceSpec, o as InstancedBatch, L as LatheNode, p as LodLevel, M as Mat4, q as MaterialHint, r as MeshNode, N as NamedRange, s as NodeCommon, t as PlaneNode, u as PointNode, v as RingNode, w as ShapeBatch, x as ShapeJob, y as ShapeKind, z as ShapeLevel, A as ShapePart, F as ShapePoint, J as ShapeReply, K as ShapeStats, O as ShapeWorkerOptions, Q as SphereNode, U as TorusNode, W as UvRect, X as Vec2, Y as WorkerScopeLike, Z as installShapeWorker } from './worker-BZ7plgyI.js';
+
+declare const isPrimitiveNode: (node: ShapeNode) => node is PrimitiveNode;
+/** The options that change the output, as they enter the cache key. */
+declare function keyOptions(options?: GenerateOptions): Record<string, unknown>;
+/** The cache key of a shape under some options: 64-bit FNV-1a of the canonical schema text and the options that change the output. */
+declare const shapeKey: (schema: ShapeSchema, options?: GenerateOptions) => string;
+/**
+ * Turns a shape into buffers: one batch per (part, material) per level, baked; instanced nodes as instance batches; parts with their pivots;
+ * points. Pure: the same schema and options give the same bytes, here or in a worker.
+ */
+declare function generate(schema: ShapeSchema, options?: GenerateOptions): ShapeBuffers;
+
+declare function box(width?: number, height?: number, depth?: number, widthSegments?: number, heightSegments?: number, depthSegments?: number): PrimitiveBuffers;
+declare function cylinder(radiusTop?: number, radiusBottom?: number, height?: number, radialSegments?: number, heightSegments?: number, openEnded?: boolean, thetaStart?: number, thetaLength?: number): PrimitiveBuffers;
+declare function cone(radius?: number, height?: number, radialSegments?: number, heightSegments?: number, openEnded?: boolean, thetaStart?: number, thetaLength?: number): PrimitiveBuffers;
+declare function sphere(radius?: number, widthSegments?: number, heightSegments?: number, phiStart?: number, phiLength?: number, thetaStart?: number, thetaLength?: number): PrimitiveBuffers;
+declare function plane(width?: number, height?: number, widthSegments?: number, heightSegments?: number): PrimitiveBuffers;
+declare function circle(radius?: number, segments?: number, thetaStart?: number, thetaLength?: number): PrimitiveBuffers;
+declare function ring(innerRadius?: number, outerRadius?: number, thetaSegments?: number, phiSegments?: number, thetaStart?: number, thetaLength?: number): PrimitiveBuffers;
+declare function lathe(points: ReadonlyArray<readonly [number, number]>, segments?: number, phiStart?: number, phiLength?: number): PrimitiveBuffers;
+declare function torus(radius?: number, tube?: number, radialSegments?: number, tubularSegments?: number, arc?: number): PrimitiveBuffers;
+
+/** `BufferGeometry.computeVertexNormals` for non-indexed Float32 positions, then `normalizeNormals`, both stored as Float32. */
+declare function computeVertexNormals(positions: Float32Array, indices?: ArrayLike<number>): Float32Array;
+declare function extrude(outline: ShapeOutline, depth?: number, steps?: number, bevel?: false | BevelSpec | undefined): PrimitiveBuffers;
+
+/**
+ * A box (centred, `size = [w, h, d]`) minus rectangular prisms that go all the way through it along z: the cheap, exact boolean (walls with
+ * windows and doors). The face is cut into a grid at every hole edge; each solid cell gets its front and back quads, and every cell edge between
+ * solid and empty (a hole or the outside) gets a quad over the depth facing the empty side, so the outer sides and the reveals come out of the
+ * same rule. Front uvs map the face to [0, 1]; side uvs run along the edge and the depth.
+ */
+declare function difference(size: Vec3, subtract: readonly HoleSpec[]): PrimitiveBuffers;
+
+/** How a level of detail changes a primitive. */
+interface DetailOptions {
+    /** Multiplies the segment counts of round primitives (1 leaves them as given). */
+    readonly detail?: number;
+    /** Floor of the scaled segment counts (default 3). */
+    readonly minSegments?: number;
+}
+/** The parameters of a primitive node (no transform, colour or name), with the level of detail applied: what its geometry depends on. */
+declare function primitiveParameters(node: PrimitiveNode, options?: DetailOptions): Record<string, unknown>;
+/** Sets how many primitive templates are kept (least recently used out; 0 turns the cache off). */
+declare function setTemplateCacheSize(size: number): void;
+declare function clearTemplateCache(): void;
+declare const templateCacheStats: () => {
+    size: number;
+    hits: number;
+    misses: number;
+};
+/**
+ * The geometry of one primitive on its own, not baked: the arrays three's generator of the same kind builds, bit for bit (meshes and differences
+ * are `BufferGeometry`). The result comes from a shared template cache and must not be written to (copy it with `clonePrimitive`).
+ */
+declare function buildPrimitive(node: PrimitiveNode, options?: DetailOptions): PrimitiveBuffers;
+/** A copy that owns its arrays. */
+declare function clonePrimitive(p: PrimitiveBuffers): PrimitiveBuffers;
+
+/** One piece for `mergeTransformed`: arrays (any may be missing) and the matrix that takes them into the merged space. */
+interface TransformedPiece {
+    readonly positions: ArrayLike<number>;
+    readonly normals?: ArrayLike<number>;
+    readonly uvs?: ArrayLike<number>;
+    readonly indices?: ArrayLike<number> | null;
+    /** Column-major 4 x 4. */
+    readonly matrix: readonly number[];
+}
+interface MergedArrays {
+    readonly positions: Float32Array;
+    readonly normals: Float32Array;
+    readonly uvs: Float32Array;
+}
+/**
+ * Joins pieces into one non-indexed set of arrays, each piece de-indexed, its missing normals and uvs zero-filled, its positions by
+ * `Vector3.applyMatrix4` and its normals by the normal matrix and normalised: what three's `toNonIndexed` + `applyMatrix4` + a join do,
+ * bit for bit (the port of `mergeByMaterial`).
+ */
+declare function mergeTransformed(pieces: readonly TransformedPiece[]): MergedArrays;
+/** Every `ArrayBuffer` of a result, for `postMessage(buffers, transferablesOf(buffers))`. */
+declare function transferablesOf(buffers: ShapeBuffers): ArrayBuffer[];
+/** A deep copy whose arrays are its own (cached results are shared and read-only; copy before deforming). */
+declare function cloneBuffers(buffers: ShapeBuffers): ShapeBuffers;
+/** Bytes held by the arrays of a result (what the cache counts). */
+declare function byteSizeOf(buffers: ShapeBuffers): number;
+
+/** The JSON Schema (draft 2020-12) of a shape document; the same file ships as `@adatechnology/game-shapes/schema.json`. */
+declare const SHAPE_SCHEMA: Readonly<Record<string, unknown>>;
+/** Every rule of the JSON Schema, checked without a schema engine: one message per problem, with its path (`root.children[3].radialSegments: ...`). */
+declare function validateShape(schema: unknown): string[];
+/** Throws with every problem when the schema is not valid. */
+declare function assertValidShape(schema: unknown): asserts schema is ShapeSchema;
+
+/** The generators of one set: what `{ kind: 'custom', generator: name, params }` nodes look up. */
+interface ShapeGenerators {
+    /**
+     * Registers a generator: a pure function of its params and a seeded stream that returns a node. A worker that generates shapes with custom nodes must
+     * register the same generators (import the same module in the worker script).
+     */
+    register(name: string, generator: ShapeGenerator): void;
+    unregister(name: string): boolean;
+    get(name: string): ShapeGenerator | undefined;
+    list(): string[];
+    /** The generators by name, as `GenerateOptions.generators` takes them. */
+    record(): Readonly<Record<string, ShapeGenerator>>;
+}
+/** The set behind `registerGenerator`, `getGenerator` and the rest of the global functions, created on first use. */
+declare const defaultShapeGenerators: () => ShapeGenerators;
+/** @deprecated use `createShapes(...).register`. */
+declare const registerGenerator: (name: string, generator: ShapeGenerator) => void;
+/** @deprecated use `createShapes(...).unregister`. */
+declare const unregisterGenerator: (name: string) => boolean;
+/** @deprecated use `createShapes(...).get`. */
+declare const getGenerator: (name: string) => ShapeGenerator | undefined;
+/** @deprecated use `createShapes(...).list`. */
+declare const listGenerators: () => string[];
+
+interface ShapesOptions {
+    /** Generators by name, added to the set; later packs replace earlier ones with the same name. */
+    readonly packs?: readonly Readonly<Record<string, ShapeGenerator>>[];
+    /** A generator replaced by name (a function is replaced as a whole). */
+    readonly patch?: Readonly<Record<string, ShapeGenerator>>;
+    /** Names taken out. */
+    readonly remove?: readonly string[];
+}
+interface Shapes extends ShapeGenerators {
+    /** `generate` that looks custom nodes up in this set only (a name only the global registry has throws). */
+    generate(schema: ShapeSchema, options?: Omit<GenerateOptions, 'isolatedGenerators'>): ShapeBuffers;
+}
+/** A set of shape generators of its own. Nothing is shared with any other set or with the global registry. */
+declare function createShapes(options?: ShapesOptions): Shapes;
+
+/**
+ * Canonical JSON (keys sorted, `undefined` left out, `-0` kept as `-0`, typed arrays as plain lists) and a 64-bit FNV-1a of it in two 32-bit
+ * lanes: the key a shape is cached and shared by.
+ */
+declare function canonicalJson(value: unknown): string;
+/** 64-bit FNV-1a of a text as 16 hex digits (two independent 32-bit lanes). */
+declare const hash64: (text: string) => string;
+/** `hash64(canonicalJson(value))`. */
+declare const hashValue: (value: unknown) => string;
+
+/** mulberry32: a small, fast 32-bit seeded stream in [0, 1). */
+declare function mulberry32(seed: number): () => number;
+/** The stream of one node: its own per (seed, generator, path), so adding a node never shifts another node's draws. */
+declare const streamFor: (seed: number | string, generator: string, path: string) => (() => number);
+
+/** A colour as `0xRRGGBB`: numbers as given (floored, as three's `setHex`), `'#rrggbb'` strings parsed. */
+declare function colorHex(color: Color | undefined, fallback?: number): number;
+/** three's `SRGBToLinear` (r160 `ColorManagement`), the same constants. */
+declare const srgbToLinear: (c: number) => number;
+/**
+ * The rgb floats of a hex colour as three's `Color.setHex` stores them: the channels over 255 (`'srgb'`), converted to the linear working space
+ * when colour management is on (`'linear'`).
+ */
+declare function colorChannels(hex: number, space: 'linear' | 'srgb'): [number, number, number];
+
+type Matrix4 = number[];
+type Matrix3 = number[];
+declare const identity4: () => Matrix4;
+/** `Quaternion.setFromEuler` (x, y, z, w). */
+declare function quaternionFromEuler(x: number, y: number, z: number, order?: RotationOrder): [number, number, number, number];
+/** `Matrix4.compose(position, quaternion, scale)`. */
+declare function compose(px: number, py: number, pz: number, q: readonly [number, number, number, number], sx: number, sy: number, sz: number): Matrix4;
+/** `Matrix4.makeRotationY(theta)` followed by `setPosition(x, y, z)`. */
+declare function headingMatrix(theta: number, x?: number, y?: number, z?: number): Matrix4;
+/** `Matrix4.multiplyMatrices(a, b)`: a x b. */
+declare function multiply(ae: readonly number[], be: readonly number[]): Matrix4;
+/** `Matrix3.getNormalMatrix(m)`: the inverse transpose of the upper 3 x 3 (all zeros when singular, as three). */
+declare function normalMatrix(me: readonly number[]): Matrix3;
+/** True when the last row is (0, 0, 0, 1): `applyMatrix4`'s divide by w is then a multiply by exactly 1. */
+declare const isAffine: (e: readonly number[]) => boolean;
+/** `Vector3.applyMatrix4`. */
+declare function transformPoint(e: readonly number[], x: number, y: number, z: number): [number, number, number];
+/** The local matrix of a transform, or `null` when it has none. */
+declare function matrixOf(t: Transform): Matrix4 | null;
+
+interface ShapeCacheOptions {
+    /** Most results kept (default 256). */
+    readonly maxEntries?: number;
+    /** Most bytes of arrays kept (default 64 MiB). A result larger than this alone is not kept. */
+    readonly maxBytes?: number;
+}
+interface ShapeCacheStats {
+    readonly entries: number;
+    readonly bytes: number;
+    readonly hits: number;
+    readonly misses: number;
+    readonly evictions: number;
+}
+/** An LRU of results by `shapeKey`. What it returns is shared: read-only (copy with `cloneBuffers` before deforming). */
+interface ShapeCache {
+    get(key: string): ShapeBuffers | undefined;
+    set(key: string, buffers: ShapeBuffers): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    stats(): ShapeCacheStats;
+}
+/** An LRU of `ShapeBuffers` by key, bounded by entries and by bytes of the arrays. Pure memoisation: a hit gives the bytes a miss would. */
+declare function createShapeCache(options?: ShapeCacheOptions): ShapeCache;
+
+/** Anything with `postMessage` / `onmessage` / `terminate`: a browser `Worker`, a `worker_threads` wrapper, an in-thread fake. */
+interface WorkerLike {
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    onerror?: ((event: unknown) => void) | null;
+    postMessage(message: unknown, transfer?: ArrayBuffer[]): void;
+    terminate(): unknown;
+}
+interface ShapePoolOptions {
+    /** Workers (default 0: generate in the calling thread). */
+    readonly size?: number;
+    /** Makes one worker that runs `installShapeWorker`. Without it the pool generates in the calling thread. */
+    readonly spawn?: () => WorkerLike;
+    /** Results by `shapeKey`: a hit resolves at once and never reaches a worker. */
+    readonly cache?: ShapeCache;
+    /** Generators of the `custom` nodes for the jobs made in the calling thread (the workers register their own). */
+    readonly generators?: Readonly<Record<string, ShapeGenerator>>;
+    /** Look custom nodes up in `generators` only (for example `shapes.record()` of `createShapes`), never in the global registry; the jobs then run in the calling thread, since a worker cannot receive functions. */
+    readonly isolatedGenerators?: boolean;
+}
+interface ShapeRequest {
+    readonly schema: ShapeSchema;
+    readonly options?: GenerateOptions;
+}
+interface ShapePoolStats {
+    readonly workers: number;
+    readonly jobs: number;
+    readonly cacheHits: number;
+    readonly shared: number;
+    readonly inThread: number;
+    readonly busy: number;
+}
+interface ShapePool {
+    /** `generate(schema, options)` off the main thread. Same key, same promise while in flight; the result is shared (read-only). */
+    generate(schema: ShapeSchema, options?: GenerateOptions): Promise<ShapeBuffers>;
+    /** A list spread over the workers, resolved in input order. */
+    generateMany(list: readonly (ShapeSchema | ShapeRequest)[]): Promise<ShapeBuffers[]>;
+    stats(): ShapePoolStats;
+    /** Stops the workers; pending jobs reject. */
+    terminate(): void;
+}
+/**
+ * A pool of shape workers. The schema is cheap (plain data) and is built on the main thread; the buffers are generated in a worker and
+ * transferred back. With `size: 0` or no `spawn` it generates in the calling thread, with the same cache and in-flight sharing.
+ */
+declare function createShapePool(options?: ShapePoolOptions): ShapePool;
+
+export { BevelSpec, Color, type DetailOptions, GenerateOptions, HoleSpec, type Matrix3, type Matrix4, type MergedArrays, PrimitiveBuffers, PrimitiveNode, RotationOrder, SHAPE_SCHEMA, ShapeBuffers, type ShapeCache, type ShapeCacheOptions, type ShapeCacheStats, ShapeGenerator, type ShapeGenerators, ShapeNode, ShapeOutline, type ShapePool, type ShapePoolOptions, type ShapePoolStats, type ShapeRequest, ShapeSchema, type Shapes, type ShapesOptions, Transform, type TransformedPiece, Vec3, type WorkerLike, assertValidShape, box, buildPrimitive, byteSizeOf, canonicalJson, circle, clearTemplateCache, cloneBuffers, clonePrimitive, colorChannels, colorHex, compose, computeVertexNormals, cone, createShapeCache, createShapePool, createShapes, cylinder, defaultShapeGenerators, difference, extrude, generate, getGenerator, hash64, hashValue, headingMatrix, identity4, isAffine, isPrimitiveNode, keyOptions, lathe, listGenerators, matrixOf, mergeTransformed, mulberry32, multiply, normalMatrix, plane, primitiveParameters, quaternionFromEuler, registerGenerator, ring, setTemplateCacheSize, shapeKey, sphere, srgbToLinear, streamFor, templateCacheStats, torus, transferablesOf, transformPoint, unregisterGenerator, validateShape };