@thunderclap-engine/engine 0.0.0-stage → 1.1.0

package/dist/assets/cache.js

@@ -0,0 +1,123 @@
+/**
+ * The asset cache: one place that knows what a game has loaded and what it costs. Entries are
+ * keyed (a uri, usually), loaded once however many callers ask at the same time, refcounted,
+ * and sized by the caller (`size(value)`: bytes of GPU memory, of decoded data, whatever the
+ * budget counts). Once the total passes `budgetBytes`, unreferenced, unpinned entries go,
+ * least recently used first, through `onEvict` so the game frees what the value holds
+ * (`scene.destroy()`, `texture.destroy()`).
+ *
+ * The cache never fetches: `load` is the caller's, typically over the bundle's `read`
+ * (`() => read(uri).then(decode)`).
+ */
+/** Make an asset cache (`AssetCache`); see the module comment. */
+export function createAssetCache(opts) {
+    if (!(opts.budgetBytes >= 0))
+        throw new Error(`asset cache: budgetBytes ${opts.budgetBytes} must be >= 0`);
+    // Map order is recency: a touched entry is moved to the end, eviction walks from the start.
+    const entries = new Map();
+    let bytes = 0;
+    let hits = 0;
+    let misses = 0;
+    let evictions = 0;
+    const touch = (key, e) => {
+        entries.delete(key);
+        entries.set(key, e);
+    };
+    const remove = (key, e) => {
+        entries.delete(key);
+        bytes -= e.size;
+        opts.onEvict?.(key, e.value);
+    };
+    const trim = () => {
+        if (bytes <= opts.budgetBytes)
+            return;
+        for (const [key, e] of entries) {
+            if (bytes <= opts.budgetBytes)
+                break;
+            if (e.refs > 0 || e.pinned || !e.loaded)
+                continue;
+            evictions++;
+            remove(key, e);
+        }
+    };
+    const entry = (key, op) => {
+        const e = entries.get(key);
+        if (!e)
+            throw new Error(`asset cache: ${op}("${key}"): key not in the cache`);
+        return e;
+    };
+    return {
+        acquire(key, load, size) {
+            const found = entries.get(key);
+            if (found) {
+                hits++;
+                found.refs++;
+                touch(key, found);
+                return found.promise;
+            }
+            misses++;
+            const e = {
+                promise: undefined,
+                value: undefined,
+                loaded: false,
+                size: 0,
+                refs: 1,
+                pinned: false,
+            };
+            e.promise = Promise.resolve()
+                .then(load)
+                .then((value) => {
+                e.value = value;
+                e.size = Math.max(0, size(value));
+                e.loaded = true;
+                if (entries.get(key) === e) {
+                    bytes += e.size;
+                    trim();
+                }
+                return value;
+            }, (err) => {
+                if (entries.get(key) === e)
+                    entries.delete(key);
+                throw err;
+            });
+            entries.set(key, e);
+            return e.promise;
+        },
+        release(key) {
+            const e = entry(key, 'release');
+            if (e.refs === 0)
+                throw new Error(`asset cache: release("${key}"): no reference held`);
+            e.refs--;
+            if (e.refs === 0) {
+                touch(key, e);
+                trim();
+            }
+        },
+        pin(key) {
+            entry(key, 'pin').pinned = true;
+        },
+        unpin(key) {
+            entry(key, 'unpin').pinned = false;
+            trim();
+        },
+        has(key) {
+            return entries.has(key);
+        },
+        refs(key) {
+            return entries.get(key)?.refs ?? 0;
+        },
+        dispose(key) {
+            const e = entries.get(key);
+            if (!e?.loaded)
+                return false;
+            if (e.refs > 0) {
+                throw new Error(`asset cache: dispose("${key}"): ${e.refs} reference(s) still held`);
+            }
+            remove(key, e);
+            return true;
+        },
+        get stats() {
+            return { bytes, entries: entries.size, hits, misses, evictions };
+        },
+    };
+}

package/dist/assets/gltf-load.d.ts

@@ -0,0 +1,252 @@
+/**
+ * `loadGltf`: a parsed `GltfDocument` → engine meshes (`VERTEX_LAYOUT_3D`, the tangent layout
+ * for primitives with `TANGENT`, the skinned layout for skinned ones when a palette is given),
+ * one `Transform` per node, one `Texture` per (image, colour space) a material reads, one
+ * standard PBR `Material` per glTF material (every map, factor, sampler, alpha mode and
+ * `KHR_texture_transform` carried over; `opts.lit: 'lit'` keeps the older base-colour-only
+ * material), and a `GltfScene` whose `draw(frame)` pushes one instance per (node, primitive)
+ * with no allocation. Images decode through `createImageBitmap` (or `opts.decodeImage`);
+ * external URIs come from `opts.resources`, fetched by the game. The engine fetches nothing.
+ *
+ * Morph targets: a mesh with targets keeps its primitives' base vertex buffers on the CPU and
+ * blends them through `anim`'s `createMorphBlender` into a second buffer `draw` uploads with
+ * `Mesh.update` when `scene.morph(node).apply()` reported a change. Meshes without targets keep
+ * nothing on the CPU.
+ *
+ * Lights and cameras: `scene.lights` holds the file's `KHR_lights_punctual` lights as the
+ * render module's `SunLight` / `PointLight` / `SpotLight` records (push them into
+ * `frame.lights`); `scene.cameras` the file's cameras, which `applyGltfCamera` sets on a
+ * `Camera`. Material variants (`KHR_materials_variants`): every material is created at load;
+ * `scene.setVariant(name)` swaps the material of each mapped draw in place.
+ */
+import { type MorphBlender } from '../anim/morph.js';
+import type { Camera } from '../render/camera.js';
+import type { Frame, InstanceParams } from '../render/frame.js';
+import type { PointLight, SpotLight, SunLight } from '../render/lights.js';
+import type { Material } from '../render/material.js';
+import { Mesh, type MeshUpdate } from '../render/mesh.js';
+import type { Renderer } from '../render/renderer.js';
+import type { SkinPalette } from '../render/skin.js';
+import type { SamplerKind, Texture } from '../render/texture.js';
+import { Transform } from '../render/transform.js';
+import { type GltfAnimation, type GltfCamera, type GltfDocument, type GltfPrimitive, type GltfSampler, type GltfSkin, type GltfVariantMapping } from './gltf.js';
+/** Which material the loader builds per glTF material. */
+export type GltfLitMode = 'standard' | 'lit';
+/** A decoded image the loader can upload: an `ImageBitmap` or anything `copyExternalImageToTexture` takes. */
+export type GltfImageSource = ImageBitmap | HTMLCanvasElement | OffscreenCanvas;
+export interface LoadGltfOptions {
+    /**
+     * External resources by the URI the file names (`GltfDocument.externalUris`): encoded image
+     * bytes, or an already decoded image. A URI the document needs and this lacks throws.
+     */
+    resources?: Record<string, ArrayBuffer | GltfImageSource>;
+    /**
+     * Draw every primitive with this material instead of the built-in ones. The scene's
+     * textures are still created (`scene.textures`) for the game to bind as it likes; `lit`
+     * and `palette` only pick the mesh layouts.
+     */
+    material?: Material;
+    /**
+     * `'standard'` (default): one `createStandardMaterial` per glTF material with every map,
+     * factor, sampler, alpha mode and texture transform the file gives (`scene.materials[i]`
+     * for `doc.materials[i]`, `scene.materialNames[i]` its name). `'lit'`: the older
+     * base-colour-only `GLTF_LIT_WGSL` material (base colour factor as `tint`, mask cutoff as
+     * `params.x`).
+     */
+    lit?: GltfLitMode;
+    /**
+     * Skinned primitives (`JOINTS_0`) become `VERTEX_LAYOUT_SKINNED` meshes bound to this
+     * palette: the standard materials are created with `skin: palette`, and a skinned draw's
+     * `params.params[3]` picks its palette slot (`SKIN_PARAM`). Without one, skinned primitives
+     * are built in the 3D layout at their bind pose (their joints and weights stay on the
+     * document); a material cannot take a palette later, so give it here.
+     */
+    palette?: SkinPalette;
+    /** Label prefix for GPU objects (default `'gltf'`). */
+    label?: string;
+    /** Build mip chains for the textures (default true; `generateMipmaps` on the GPU). */
+    mips?: boolean;
+    /**
+     * How encoded image bytes become an image (default: `createImageBitmap` on a `Blob`). Tests
+     * and Workers without image decoding pass their own.
+     */
+    decodeImage?: (bytes: Uint8Array, mimeType: string | null) => Promise<GltfImageSource>;
+    /**
+     * Multiplies glTF light intensity on its way into `scene.lights` (default 1). The engine's
+     * light colours are unitless linear RGB; a file's candela (point, spot) and lux
+     * (directional) usually want a scale well below 1.
+     */
+    lightScale?: number;
+}
+/**
+ * The file's `KHR_lights_punctual` lights as the render module's records, in scene order
+ * (`GltfDocument.lights` keeps glTF's units). `color` is glTF `color × intensity × lightScale`;
+ * `radius` is `range`, or `16·√(intensity × lightScale)` without one (where an inverse-square
+ * light has fallen to 1/256); spot `innerAngle` / `outerAngle` are the cone half-angles.
+ * A directional light is a `SunLight` (ws/assets-4): `direction` is the node's world -Z,
+ * normalised, the way the light travels (the engine's convention, as `SpotLight.direction`),
+ * and the deprecated `dir` reads and replaces the same array. Push the points and spots into
+ * `frame.lights.points` / `.spots`, or copy a sun's `direction` and `color` into
+ * `frame.lights.sun`.
+ */
+export interface GltfSceneLights {
+    directional: SunLight[];
+    points: PointLight[];
+    spots: SpotLight[];
+}
+/** One draw of the scene: a primitive's mesh placed by its node's transform. */
+export interface GltfSceneNode {
+    /** Index into `GltfDocument.nodes` / `GltfScene.transforms`. */
+    node: number;
+    transform: Transform;
+    mesh: Mesh;
+    material: Material;
+    /**
+     * Mutate to recolour the draw. `lit: 'standard'`: `tint` white, `params` zero (the factors
+     * live in the material); a skinned draw sets `params[3]` to its palette slot. `lit: 'lit'`:
+     * base colour factor as `tint`, alpha cutoff as `params.x`.
+     */
+    params: InstanceParams;
+    /** The node's skin (index into `GltfScene.skins`), or null for a static draw. */
+    skin: number | null;
+    /**
+     * The glTF material the draw uses (index into `GltfDocument.materials` and
+     * `GltfScene.materials`), or null for the default; `setVariant` changes it.
+     */
+    materialIndex: number | null;
+}
+/** One draw whose primitive has `KHR_materials_variants` mappings. */
+interface VariantDraw {
+    draw: GltfSceneNode;
+    /** The primitive's own material (no variant, or a variant no mapping names). */
+    base: number | null;
+    mappings: readonly GltfVariantMapping[];
+}
+/**
+ * The morph state of one glTF mesh (shared by every node drawing it): one `weights` array for
+ * all its primitives, blended by one `MorphBlender` per primitive. Write `weights` (by hand or
+ * with `anim`'s `sampleWeights`), call `apply()`; the scene uploads changed primitives on its
+ * next `draw`.
+ */
+export interface GltfMorph {
+    /** Index into `GltfDocument.meshes`. */
+    readonly mesh: number;
+    /** One weight per target, starting at the file's `mesh.weights` (or zeros). */
+    readonly weights: Float32Array;
+    readonly targetCount: number;
+    /** One per primitive of the mesh, all reading `weights`. */
+    readonly blenders: readonly MorphBlender[];
+    /** Blend every primitive; true when any vertex buffer changed (and so will be uploaded). */
+    apply(): boolean;
+}
+/** One morphed primitive: its blender, the buffer it writes and the mesh that uploads it. */
+interface MorphEntry {
+    blender: MorphBlender;
+    mesh: Mesh;
+    update: MeshUpdate;
+    dirty: boolean;
+}
+/**
+ * Built-in material: base colour texture × factor × vertex colour, lit by the engine's lighting
+ * block (`engine_lambert`) plus a faint sky term from above. `params.x` > 0 is a `MASK` cutoff.
+ */
+export declare const GLTF_LIT_WGSL = "\n@group(1) @binding(1) var baseSampler: sampler;\n@group(1) @binding(2) var baseTex: texture_2d<f32>;\n\n@fragment fn fs_main(in: VSOut) -> FragOut {\n  let c = textureSample(baseTex, baseSampler, in.uv) * in.color;\n  if (in.params.x > 0.0 && c.a < in.params.x) { discard; }\n  let n = normalize(in.normal);\n  let sky = 0.5 + 0.5 * n.y;\n  var o: FragOut;\n  o.color = vec4f(c.rgb * (engine_lambert(n, in.worldPos) + 0.12 * sky), c.a);\n  o.emissive = vec4f(0.0);\n  return o;\n}\n";
+/** The GPU side of one glTF document. Owns what it created; `destroy()` frees it. */
+export declare class GltfScene {
+    /** One per primitive, in document order (mesh 0's primitives, then mesh 1's, …). */
+    readonly meshes: Mesh[];
+    /**
+     * One per (image, colour space) a material reads, in first-use order: base colour and
+     * emissive maps are sRGB, the rest linear, so an image used both ways is uploaded twice.
+     */
+    readonly textures: Texture[];
+    /** One per glTF material, built by the loader (empty when `opts.material` was given). */
+    readonly materials: Material[];
+    /** The file's `material.name` per glTF material (null when unnamed). */
+    readonly materialNames: (string | null)[];
+    /** The palette skinned meshes are bound to (`opts.palette`), or null. */
+    readonly palette: SkinPalette | null;
+    /** One per document node, parented like the file (`doc.nodes[i]` → `transforms[i]`). */
+    readonly transforms: Transform[];
+    /** Every draw: one per (node in the default scene, primitive of its mesh). */
+    readonly nodes: GltfSceneNode[];
+    /** World-space bounds of the default scene (from the document). */
+    readonly bounds: {
+        center: [number, number, number];
+        radius: number;
+    };
+    /** The document's skins (`skeletonFromSkin(doc, i)` builds the animation module's skeleton). */
+    readonly skins: readonly GltfSkin[];
+    /** The document's clips, in the animation module's `AnimationClip` shape. */
+    readonly animations: readonly GltfAnimation[];
+    /** One per mesh that carries morph targets, in mesh order. */
+    readonly morphs: readonly GltfMorph[];
+    /** The file's lights as render records (`GltfSceneLights`; empty lists when it has none). */
+    readonly lights: GltfSceneLights;
+    /** The file's cameras placed by their nodes (`applyGltfCamera` sets one on a `Camera`). */
+    readonly cameras: readonly GltfCamera[];
+    /** The file's `KHR_materials_variants` names (`setVariant` takes one). */
+    readonly variants: readonly string[];
+    /** Whether the default material or textures were created here (and so destroyed here). */
+    private readonly ownsMaterials;
+    private readonly morphByMesh;
+    private readonly morphEntries;
+    private readonly doc;
+    private readonly variantDraws;
+    private resolveMaterial;
+    private litParams;
+    private activeVariant;
+    constructor(doc: GltfDocument, ownsMaterials: boolean, palette?: SkinPalette | null);
+    /** The active material variant, or null for each primitive's own material. */
+    get variant(): string | null;
+    /**
+     * Switch every draw with `KHR_materials_variants` mappings to the material `name` binds (a
+     * draw no mapping of `name` covers goes back to its own material); null restores every
+     * draw's own material. Swaps `material` (and `materialIndex`) in place: no material is
+     * created. Throws `GltfError` listing the file's variants for an unknown name.
+     */
+    setVariant(name: string | null): this;
+    /** @internal The loader: how `setVariant` finds a material, and which draws it touches. */
+    bindVariants(resolve: ((index: number | null) => Material) | null, litParams: boolean, draws: VariantDraw[]): void;
+    /**
+     * The morph state of the mesh `nodeIndex` (into `GltfDocument.nodes`) draws, or null when the
+     * node has no mesh or the mesh no targets. Nodes sharing a mesh share the object.
+     */
+    morph(nodeIndex: number): GltfMorph | null;
+    /** @internal Register a mesh's morph state (the loader). */
+    addMorph(morph: GltfMorph, entries: MorphEntry[]): void;
+    /**
+     * Upload every morphed primitive whose `apply()` changed it, then record every draw into
+     * `frame`. Allocation-free.
+     */
+    draw(frame: Frame): void;
+    destroy(): void;
+}
+/**
+ * Upload a document to the GPU. Resolves once every image is decoded; everything else is
+ * synchronous. Throws `GltfError` for a missing external resource or an undecodable image.
+ */
+export declare function loadGltf(renderer: Renderer, doc: GltfDocument, opts?: LoadGltfOptions): Promise<GltfScene>;
+/**
+ * Set `camera` to a glTF camera: its projection (perspective `yfov`, the file's `aspectRatio`
+ * or `aspect`, `znear`, `zfar` or an infinite far plane; orthographic `xmag` / `ymag` half
+ * extents and its depth range) and its node's view (`GltfCamera.view`). Turns depth test,
+ * depth write and culling on. Allocation-free; returns `camera`.
+ */
+export declare function applyGltfCamera(camera: Camera, c: GltfCamera, aspect: number): Camera;
+/**
+ * The engine sampler nearest a glTF one: nearest magnification → `nearest-mip-clamp` (or
+ * `nearest-clamp` without mips; the engine has no nearest-repeat), linear → `linear-clamp`
+ * when both wraps clamp, else `linear-mip-repeat` (`linear-repeat` without mips; mirrored
+ * repeat is treated as repeat). `mips` false, or a glTF `minFilter` without a mipmap mode,
+ * picks the level-0 sampler.
+ */
+export declare function gltfSamplerKind(sampler: GltfSampler, mips: boolean): SamplerKind;
+/** `x, y, z, nx, ny, nz, u, v, r, g, b, a` per vertex (the `VERTEX_LAYOUT_3D` float order). */
+export declare function interleave3d(p: GltfPrimitive): Float32Array;
+/**
+ * `VERTEX_LAYOUT_3D_TANGENT`: the 12 floats of `interleave3d` then `tangent.xyzw` per vertex.
+ * A primitive without `TANGENT` gets `(1, 0, 0, 1)`.
+ */
+export declare function interleave3dTangent(p: GltfPrimitive): Float32Array;
+export {};