@adatechnology/game-shapes 0.0.0-stage → 0.2.0

package/dist/worker-BZ7plgyI.d.ts

@@ -0,0 +1,394 @@
+/** `[x, y, z]` in metres (or a direction). */
+type Vec3 = readonly [number, number, number];
+/** `[x, y]`. */
+type Vec2 = readonly [number, number];
+/** A column-major 4 x 4 matrix (the layout of three's `Matrix4.elements`). */
+type Mat4 = readonly number[];
+/** `0xRRGGBB` or `'#rrggbb'`. */
+type Color = number | string;
+/** Euler order, as three names it. */
+type RotationOrder = 'XYZ' | 'YXZ' | 'ZXY' | 'ZYX' | 'YZX' | 'XZY';
+/** An atlas cell: the primitive's uvs are remapped into it (`u0 + u x (u1 - u0)`). */
+interface UvRect {
+    readonly u0: number;
+    readonly v0: number;
+    readonly u1: number;
+    readonly v1: number;
+}
+/**
+ * A local transform. Either `position` / `rotation` / `rotationOrder` / `scale` (composed as three's `Object3D` does: Euler, quaternion, matrix),
+ * or `heading` with `position` (a pure rotation about +y built as a rotation matrix, the turn of an item on the floor), or a whole `matrix`.
+ */
+interface Transform {
+    readonly position?: Vec3;
+    readonly rotation?: Vec3;
+    readonly rotationOrder?: RotationOrder;
+    readonly scale?: number | Vec3;
+    readonly heading?: number;
+    readonly matrix?: Mat4;
+}
+/** One copy of an instanced node: where it goes (between the parent and the node) and, optionally, its own colour. */
+interface InstanceSpec extends Transform {
+    readonly color?: Color;
+}
+/** Fields every node may carry. */
+interface NodeCommon extends Transform {
+    /** Named range: the vertices and indices this node adds are listed per batch in `ranges`. */
+    readonly name?: string;
+    /** Starts a movable part (see the README): the node's transform is the part's pivot, relative to the root; its children are baked in the part's space. */
+    readonly part?: string;
+    /** Material id, inherited by the children. */
+    readonly material?: string;
+    /** Vertex colour, inherited by the children. */
+    readonly color?: Color;
+    /** Atlas cell of the uvs, inherited by the children. */
+    readonly uv?: UvRect;
+    /** Instancing hint: draw this node once per entry instead of merging it. */
+    readonly instances?: readonly InstanceSpec[];
+    /** Left out of the LOD levels whose `detail` is below this. */
+    readonly minDetail?: number;
+    /** Free strings carried to the node's `ranges`. */
+    readonly tags?: readonly string[];
+}
+interface GroupNode extends NodeCommon {
+    readonly kind: 'group';
+    readonly children?: readonly ShapeNode[];
+}
+interface BoxNode extends NodeCommon {
+    readonly kind: 'box';
+    /** `[width, height, depth]`, default `[1, 1, 1]`. */
+    readonly size?: Vec3;
+    /** `[widthSegments, heightSegments, depthSegments]`, default `[1, 1, 1]`. */
+    readonly segments?: readonly [number, number, number];
+}
+interface CylinderNode extends NodeCommon {
+    readonly kind: 'cylinder';
+    readonly radiusTop?: number;
+    readonly radiusBottom?: number;
+    readonly height?: number;
+    readonly radialSegments?: number;
+    readonly heightSegments?: number;
+    readonly openEnded?: boolean;
+    readonly thetaStart?: number;
+    readonly thetaLength?: number;
+}
+interface ConeNode extends NodeCommon {
+    readonly kind: 'cone';
+    readonly radius?: number;
+    readonly height?: number;
+    readonly radialSegments?: number;
+    readonly heightSegments?: number;
+    readonly openEnded?: boolean;
+    readonly thetaStart?: number;
+    readonly thetaLength?: number;
+}
+interface SphereNode extends NodeCommon {
+    readonly kind: 'sphere';
+    readonly radius?: number;
+    readonly widthSegments?: number;
+    readonly heightSegments?: number;
+    readonly phiStart?: number;
+    readonly phiLength?: number;
+    readonly thetaStart?: number;
+    readonly thetaLength?: number;
+}
+interface PlaneNode extends NodeCommon {
+    readonly kind: 'plane';
+    readonly width?: number;
+    readonly height?: number;
+    readonly widthSegments?: number;
+    readonly heightSegments?: number;
+}
+interface CircleNode extends NodeCommon {
+    readonly kind: 'circle';
+    readonly radius?: number;
+    readonly segments?: number;
+    readonly thetaStart?: number;
+    readonly thetaLength?: number;
+}
+interface RingNode extends NodeCommon {
+    readonly kind: 'ring';
+    readonly innerRadius?: number;
+    readonly outerRadius?: number;
+    readonly thetaSegments?: number;
+    readonly phiSegments?: number;
+    readonly thetaStart?: number;
+    readonly thetaLength?: number;
+}
+interface LatheNode extends NodeCommon {
+    readonly kind: 'lathe';
+    /** The profile, `[x, y]` with x the distance from the axis. */
+    readonly points: readonly Vec2[];
+    readonly segments?: number;
+    readonly phiStart?: number;
+    readonly phiLength?: number;
+}
+interface TorusNode extends NodeCommon {
+    readonly kind: 'torus';
+    readonly radius?: number;
+    readonly tube?: number;
+    readonly radialSegments?: number;
+    readonly tubularSegments?: number;
+    readonly arc?: number;
+}
+/** A straight-edged outline (curves are sampled by the caller), with optional holes. */
+interface ShapeOutline {
+    readonly outer: readonly Vec2[];
+    readonly holes?: readonly (readonly Vec2[])[];
+}
+interface BevelSpec {
+    readonly thickness?: number;
+    readonly size?: number;
+    readonly offset?: number;
+    readonly segments?: number;
+}
+interface ExtrudeNode extends NodeCommon {
+    readonly kind: 'extrude';
+    readonly shape: ShapeOutline;
+    /** Default 1, as three. */
+    readonly depth?: number;
+    readonly steps?: number;
+    /** `false` for no bevel; default three's (`thickness 0.2`, `size thickness - 0.1`, `offset 0`, `segments 3`). */
+    readonly bevel?: false | BevelSpec;
+}
+/** A rectangle `min`..`max` in the box's xy plane (centred coordinates) cut through the whole depth. */
+interface HoleSpec {
+    readonly min: Vec2;
+    readonly max: Vec2;
+}
+/** A box minus rectangular prisms that go all the way through it along z: walls with windows and doors. */
+interface DifferenceNode extends NodeCommon {
+    readonly kind: 'difference';
+    readonly size: Vec3;
+    readonly subtract: readonly HoleSpec[];
+}
+/** Raw triangles. Normals are computed as three's `computeVertexNormals` when missing; uvs default to zero. */
+interface MeshNode extends NodeCommon {
+    readonly kind: 'mesh';
+    readonly positions: readonly number[];
+    readonly normals?: readonly number[];
+    readonly uvs?: readonly number[];
+    readonly indices?: readonly number[];
+}
+/** An anchor (a light, a muzzle, a seat): reported in `points`, at `position` in its parent's space. */
+interface PointNode extends NodeCommon {
+    readonly kind: 'point';
+    readonly data?: unknown;
+}
+/** A node made by a generator the host registered (`registerGenerator`). */
+interface CustomNode extends NodeCommon {
+    readonly kind: 'custom';
+    readonly generator: string;
+    readonly params?: unknown;
+}
+type PrimitiveNode = BoxNode | CylinderNode | ConeNode | SphereNode | PlaneNode | CircleNode | RingNode | LatheNode | TorusNode | ExtrudeNode | DifferenceNode | MeshNode;
+type ShapeNode = GroupNode | PrimitiveNode | PointNode | CustomNode;
+type ShapeKind = ShapeNode['kind'];
+/** Renderer-agnostic hints for a material id; `game-shapes-three` turns them into a material when the host gives none. */
+interface MaterialHint {
+    readonly color?: Color;
+    readonly roughness?: number;
+    readonly metalness?: number;
+    readonly opacity?: number;
+    readonly transparent?: boolean;
+    readonly emissive?: Color;
+    readonly emissiveIntensity?: number;
+    readonly side?: 'front' | 'back' | 'double';
+    readonly flatShading?: boolean;
+    readonly vertexColors?: boolean;
+    readonly depthWrite?: boolean;
+}
+/** A level after the base one. */
+interface LodLevel {
+    /** Camera distance from which this level is drawn. */
+    readonly distance: number;
+    /** Multiplies the segment counts of round primitives (0 < detail <= 1). */
+    readonly detail: number;
+    /** Leaf nodes whose bounding radius is below this are left out. */
+    readonly minSize?: number;
+    /** Segment counts never go below this (default 3). */
+    readonly minSegments?: number;
+}
+/** The document: a node tree and how to draw it. */
+interface ShapeSchema {
+    readonly version: 1;
+    readonly name?: string;
+    readonly materials?: Readonly<Record<string, MaterialHint>>;
+    readonly root: ShapeNode;
+    readonly lod?: readonly LodLevel[];
+    readonly cullDistance?: number;
+}
+/** A group of the index of a primitive, as three's `BufferGeometry.groups`. */
+interface GeometryGroup {
+    readonly start: number;
+    readonly count: number;
+    readonly materialIndex: number;
+}
+/** One primitive on its own, not baked: exactly the arrays the three generator of `type` builds. */
+interface PrimitiveBuffers {
+    /** The three geometry this reproduces (`'BoxGeometry'`...), or `'BufferGeometry'`. */
+    readonly type: string;
+    /** The parameters, as three's `geometry.parameters` would hold them. */
+    readonly parameters: Readonly<Record<string, unknown>>;
+    readonly positions: Float32Array;
+    readonly normals: Float32Array;
+    readonly uvs: Float32Array;
+    /** Absent for non-indexed geometry (extrusions). */
+    readonly indices?: Uint16Array | Uint32Array;
+    readonly groups: readonly GeometryGroup[];
+}
+/** The vertices and indices a named node added to a batch. */
+interface NamedRange {
+    readonly name: string;
+    readonly tags?: readonly string[];
+    readonly vertexStart: number;
+    readonly vertexCount: number;
+    readonly indexStart: number;
+    readonly indexCount: number;
+}
+interface Bounds {
+    readonly min: [number, number, number];
+    readonly max: [number, number, number];
+}
+/** Everything of one (part, material): baked, ready for one draw call. */
+interface ShapeBatch {
+    readonly material: string;
+    /** `null` for the static body. */
+    readonly part: string | null;
+    readonly positions: Float32Array;
+    readonly normals: Float32Array;
+    readonly uvs: Float32Array;
+    readonly colors?: Float32Array;
+    readonly indices?: Uint16Array | Uint32Array;
+    readonly ranges: readonly NamedRange[];
+    readonly bounds: Bounds;
+}
+/** A node drawn many times: its geometry once (in the node's space) and one matrix per copy (in the part's space). */
+interface InstancedBatch {
+    readonly material: string;
+    readonly part: string | null;
+    readonly name?: string;
+    readonly geometry: PrimitiveBuffers;
+    /** 16 floats per instance, column-major. */
+    readonly matrices: Float32Array;
+    /** rgb per instance, when the instances have colours. */
+    readonly colors?: Float32Array;
+    readonly count: number;
+}
+interface ShapeLevel {
+    readonly distance: number;
+    readonly detail: number;
+    readonly batches: readonly ShapeBatch[];
+    readonly instanced: readonly InstancedBatch[];
+}
+/** A movable part: its pivot transform, relative to the root, as given in the schema, and as a matrix. */
+interface ShapePart extends Transform {
+    readonly id: string;
+    readonly matrix: Mat4;
+}
+interface ShapePoint {
+    readonly name?: string;
+    readonly part: string | null;
+    readonly position: [number, number, number];
+    readonly data?: unknown;
+    readonly tags?: readonly string[];
+}
+interface ShapeStats {
+    readonly vertices: number;
+    readonly triangles: number;
+    readonly batches: number;
+    readonly instances: number;
+    readonly primitives: number;
+}
+/** What `generate` returns. Every array owns its buffer (transferable). */
+interface ShapeBuffers {
+    readonly key: string;
+    readonly name?: string;
+    readonly levels: readonly ShapeLevel[];
+    readonly parts: readonly ShapePart[];
+    readonly points: readonly ShapePoint[];
+    readonly materials?: Readonly<Record<string, MaterialHint>>;
+    readonly cullDistance?: number;
+    /** Of level 0. */
+    readonly stats: ShapeStats;
+}
+/** What a custom generator receives besides its params. */
+interface GeneratorContext {
+    /** Seeded stream in [0, 1), its own per (seed, generator, node path). */
+    readonly random: () => number;
+    readonly seed: number | string;
+    readonly detail: number;
+    readonly path: string;
+}
+type ShapeGenerator = (params: any, context: GeneratorContext) => ShapeNode;
+interface GenerateOptions {
+    /** Seed of the custom generators. Default 0. */
+    readonly seed?: number | string;
+    /** Vertex colours: `'linear'` (three's working space, default), `'srgb'` (the channels over 255) or `'none'`. */
+    readonly colors?: 'linear' | 'srgb' | 'none';
+    /** Index the batches (default true). */
+    readonly indexed?: boolean;
+    /** Material ids the host draws; any other id becomes `fallbackMaterial`. Default: every id is kept. */
+    readonly materials?: readonly string[];
+    readonly fallbackMaterial?: string;
+    /** Ids that share a draw: `{ metal: 'plain' }` puts metal into the plain batches (after `materials`). */
+    readonly materialAlias?: Readonly<Record<string, string>>;
+    /** Instance identical leaf primitives repeated at least `minCount` times. Off by default. */
+    readonly instancing?: {
+        readonly minCount: number;
+    };
+    /** Only these level indices (0 is the base). Default all. */
+    readonly levels?: readonly number[];
+    /** Generators besides the registered ones. */
+    readonly generators?: Readonly<Record<string, ShapeGenerator>>;
+    /** Look custom nodes up only in `generators`, never in the global registry (what a `createShapes` set does). */
+    readonly isolatedGenerators?: boolean;
+    /** Validate the schema first (default true). */
+    readonly validate?: boolean;
+    /**
+     * The result's `key`: computed by default (`shapeKey`, a hash of the whole schema text), taken as given when a string, or `''` with `false`
+     * (a schema built in code, used once and never cached: the hash would cost more than a small shape).
+     */
+    readonly key?: string | false;
+}
+
+/** A job the pool posts: `options` without `generators` (functions do not cross threads; register them in the worker script). */
+interface ShapeJob {
+    readonly id: number;
+    readonly schema: ShapeSchema;
+    readonly options?: Omit<GenerateOptions, 'generators'>;
+}
+type ShapeReply = {
+    readonly id: number;
+    readonly ok: true;
+    readonly buffers: ShapeBuffers;
+} | {
+    readonly id: number;
+    readonly ok: false;
+    readonly error: string;
+};
+/** What a worker scope looks like: `self` in a browser worker, a `worker_threads` `parentPort` wrapper in Node, or an in-thread fake. */
+interface WorkerScopeLike {
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    postMessage(message: unknown, transfer?: ArrayBuffer[]): void;
+}
+interface ShapeWorkerOptions {
+    /** Generators of the `custom` nodes, the same ones the main thread registers. */
+    readonly generators?: Readonly<Record<string, ShapeGenerator>>;
+    /** Transfer the arrays back (default true: zero copy, the worker keeps nothing). */
+    readonly transfer?: boolean;
+}
+/**
+ * The worker side of `createShapePool`: answers each job with `generate(schema, options)`, transferring every array.
+ *
+ * ```ts
+ * // shape-worker.ts
+ * import { installShapeWorker } from '@adatechnology/game-shapes/worker'
+ * installShapeWorker(self as never, { generators: myGenerators })
+ * ```
+ */
+declare function installShapeWorker(scope: WorkerScopeLike, options?: ShapeWorkerOptions): void;
+
+export { type ShapePart as A, type BevelSpec as B, type Color as C, type DifferenceNode as D, type ExtrudeNode as E, type ShapePoint as F, type GenerateOptions as G, type HoleSpec as H, type InstanceSpec as I, type ShapeReply as J, type ShapeStats as K, type LatheNode as L, type Mat4 as M, type NamedRange as N, type ShapeWorkerOptions as O, type PrimitiveNode as P, type SphereNode as Q, type RotationOrder as R, type ShapeSchema as S, type Transform as T, type TorusNode as U, type Vec3 as V, type UvRect as W, type Vec2 as X, type WorkerScopeLike as Y, installShapeWorker as Z, type ShapeBuffers as a, type ShapeNode as b, type PrimitiveBuffers as c, type ShapeOutline as d, type ShapeGenerator as e, type Bounds as f, type BoxNode as g, type CircleNode as h, type ConeNode as i, type CustomNode as j, type CylinderNode as k, type GeneratorContext as l, type GeometryGroup as m, type GroupNode as n, type InstancedBatch as o, type LodLevel as p, type MaterialHint as q, type MeshNode as r, type NodeCommon as s, type PlaneNode as t, type PointNode as u, type RingNode as v, type ShapeBatch as w, type ShapeJob as x, type ShapeKind as y, type ShapeLevel as z };

package/dist/worker.d.ts

@@ -0,0 +1 @@
+export { x as ShapeJob, J as ShapeReply, O as ShapeWorkerOptions, Y as WorkerScopeLike, Z as installShapeWorker } from './worker-BZ7plgyI.js';

package/dist/worker.js

@@ -0,0 +1,7 @@
+import {
+  installShapeWorker
+} from "./chunk-IFXQIDSA.js";
+export {
+  installShapeWorker
+};
+//# sourceMappingURL=worker.js.map

package/dist/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@adatechnology/game-shapes",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "license": "MIT",
+  "description": "Renderer-agnostic 3D shape generator: a JSON shape schema (primitives, extrusions, lathes, cheap booleans, transforms, groups, named parts, materials by id, LOD rules, instancing hints) in, typed-array buffers per material out. Pure, deterministic by seed, worker friendly and cacheable; the generators are bit-exact ports of three.js r160.",
+  "keywords": [
+    "3d",
+    "geometry",
+    "procedural",
+    "low-poly",
+    "game",
+    "json",
+    "worker"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Andersonfrfilho/adatechnology-game-kit.git",
+    "directory": "packages/game-shapes"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "unpkg": "dist/index.global.js",
+  "jsdelivr": "dist/index.global.js",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./worker": {
+      "types": "./dist/worker.d.ts",
+      "import": "./dist/worker.js"
+    },
+    "./schema.json": "./schema/shape.schema.json",
+    "./global": "./dist/index.global.js"
+  },
+  "files": [
+    "dist",
+    "schema"
+  ],
+  "dependencies": {
+    "@adatechnology/game-contracts": "^0.22.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "@types/three": "^0.160.0",
+    "three": "^0.160.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }