@jgengine/shell 0.27.0 → 0.29.0

package/dist/render/modelMeshMerge.js

@@ -0,0 +1,269 @@
+import * as THREE from "three";
+import { mergeGeometries } from "three/examples/jsm/utils/BufferGeometryUtils.js";
+const MERGED_NAMES_KEY = "jgMergedMeshNames";
+let mergeEnabled = true;
+/**
+ * Turn load-time sub-mesh merging on or off. On (the default) every loaded model whose meshes share a
+ * material collapses to one mesh per material, which is what a game with many instances of a
+ * multi-mesh prop needs; a game that must keep per-mesh nodes (named material slots, node visibility)
+ * turns it off.
+ * @internal
+ */
+export function setModelSubMeshMerge(enabled) {
+    mergeEnabled = enabled;
+}
+/** The node names a merged mesh absorbed, in the order they were merged. Empty for an unmerged mesh. @internal */
+export function mergedMeshNames(mesh) {
+    const names = mesh.userData[MERGED_NAMES_KEY];
+    return Array.isArray(names) ? names : [];
+}
+/**
+ * Whether a mesh answers to `name`: its own name, or one of the sub-meshes a load-time merge folded
+ * into it. Name-based lookups (material assignment selectors) go through this so a merged model keeps
+ * resolving the names its source meshes had.
+ * @internal
+ */
+export function meshMatchesName(mesh, name) {
+    return mesh.name === name || mergedMeshNames(mesh).includes(name);
+}
+function countMeshes(root) {
+    let count = 0;
+    root.traverse((node) => {
+        if (node.isMesh === true)
+            count += 1;
+    });
+    return count;
+}
+/** Skinning, instancing and bone parents are all driven at runtime, so their transforms cannot be baked. */
+function hasRiggedAncestor(mesh, root) {
+    let node = mesh;
+    while (node !== null && node !== root) {
+        if (node.isBone === true)
+            return true;
+        if (node.isSkinnedMesh === true)
+            return true;
+        node = node.parent;
+    }
+    return false;
+}
+/** Attribute layout two geometries must agree on before their vertices can share a draw. */
+function attributeKey(geometry) {
+    const parts = [geometry.index === null ? "plain" : "indexed"];
+    for (const name of Object.keys(geometry.attributes).sort()) {
+        const attribute = geometry.attributes[name];
+        parts.push(`${name}:${attribute.itemSize}:${attribute.normalized === true ? 1 : 0}`);
+    }
+    return parts.join(",");
+}
+function isMergeable(mesh, root) {
+    if (mesh.isSkinnedMesh === true || mesh.isInstancedMesh === true)
+        return false;
+    // A node with children carries them: removing it would orphan them, and merging the children instead
+    // is handled by their own groups.
+    if (mesh.children.length > 0)
+        return false;
+    if (mesh.visible !== true)
+        return false;
+    if (Array.isArray(mesh.material) || mesh.material === undefined || mesh.material === null)
+        return false;
+    const geometry = mesh.geometry;
+    if (geometry === undefined || geometry.attributes.position === undefined)
+        return false;
+    if (Object.keys(geometry.morphAttributes).length > 0)
+        return false;
+    return !hasRiggedAncestor(mesh, root);
+}
+/**
+ * Collapse a freshly loaded model's meshes that share a material into one mesh per material, baking
+ * each mesh's transform relative to `root` into the merged vertices. Runs once per load, so every
+ * instance cloned from the model inherits the lower draw count.
+ *
+ * Skinned meshes, instanced meshes, meshes with morph targets or rigged ancestors, meshes with
+ * children, hidden meshes, mirrored meshes, and every model carrying an animation clip are left
+ * untouched: a clip can move any node in the file, so baking an animated model's transforms would
+ * freeze it.
+ * @internal
+ */
+export function mergeModelSubMeshes(root, animations = []) {
+    if (!mergeEnabled || animations.length > 0)
+        return { merged: 0, kept: countMeshes(root) };
+    root.updateMatrixWorld(true);
+    const rootInverse = root.matrixWorld.clone().invert();
+    const groups = new Map();
+    let kept = 0;
+    root.traverse((node) => {
+        const mesh = node;
+        if (mesh.isMesh !== true)
+            return;
+        if (!isMergeable(mesh, root)) {
+            kept += 1;
+            return;
+        }
+        // A mirrored node renders with flipped winding, which a baked vertex has no way to express.
+        const relative = new THREE.Matrix4().multiplyMatrices(rootInverse, mesh.matrixWorld);
+        if (relative.determinant() < 0) {
+            kept += 1;
+            return;
+        }
+        const material = mesh.material;
+        const key = `${material.uuid}|${attributeKey(mesh.geometry)}`;
+        const group = groups.get(key);
+        if (group === undefined)
+            groups.set(key, { material, meshes: [{ mesh, relative }] });
+        else
+            group.meshes.push({ mesh, relative });
+    });
+    let merged = 0;
+    for (const group of groups.values()) {
+        if (group.meshes.length < 2) {
+            kept += group.meshes.length;
+            continue;
+        }
+        const parts = group.meshes.map(({ mesh, relative }) => mesh.geometry.clone().applyMatrix4(relative));
+        const geometry = mergeGeometries(parts, false);
+        for (const part of parts)
+            part.dispose();
+        if (geometry === null) {
+            kept += group.meshes.length;
+            continue;
+        }
+        geometry.computeBoundingBox();
+        geometry.computeBoundingSphere();
+        const first = group.meshes[0].mesh;
+        const mesh = new THREE.Mesh(geometry, group.material);
+        mesh.name = first.name;
+        mesh.renderOrder = first.renderOrder;
+        mesh.frustumCulled = first.frustumCulled;
+        mesh.castShadow = first.castShadow;
+        mesh.receiveShadow = first.receiveShadow;
+        const names = [...new Set(group.meshes.map(({ mesh: source }) => source.name).filter((name) => name.length > 0))];
+        if (names.length > 0)
+            mesh.userData[MERGED_NAMES_KEY] = names;
+        for (const { mesh: source } of group.meshes)
+            source.removeFromParent();
+        root.add(mesh);
+        merged += group.meshes.length - 1;
+        kept += 1;
+    }
+    return { merged, kept };
+}
+function boneSlot(slots, bone, inverse) {
+    const found = slots.findIndex((slot) => slot.bone === bone && slot.inverse.equals(inverse));
+    if (found >= 0)
+        return found;
+    slots.push({ bone, inverse: inverse.clone() });
+    return slots.length - 1;
+}
+function isMergeableSkinnedPart(mesh) {
+    if (mesh.isSkinnedMesh !== true)
+        return false;
+    if (mesh.children.length > 0 || mesh.visible !== true)
+        return false;
+    if (Array.isArray(mesh.material) || mesh.material === undefined || mesh.material === null)
+        return false;
+    const geometry = mesh.geometry;
+    if (geometry.attributes.position === undefined)
+        return false;
+    if (Object.keys(geometry.morphAttributes).length > 0)
+        return false;
+    return geometry.getAttribute("skinIndex") !== undefined && geometry.getAttribute("skinWeight") !== undefined;
+}
+/**
+ * Collapse a rigged model's skinned parts that share a skeleton and a material into one skinned mesh,
+ * so one character is one draw and one bone matrix upload instead of one per body part. Vertices move
+ * into bind space (each part's own `bindMatrix` baked in) and skin indices are remapped onto the
+ * union of the parts' bones, which leaves the posed result unchanged. Runs once per load, before any
+ * clone, so every instance inherits the lower part count.
+ *
+ * Parts with a different material, a different attribute layout, morph targets, several materials or
+ * children stay as they are. A model that only has one part is untouched.
+ * @internal
+ */
+export function mergeSkinnedModelParts(root) {
+    if (!mergeEnabled)
+        return { merged: 0, kept: countMeshes(root) };
+    root.updateMatrixWorld(true);
+    const groups = new Map();
+    let kept = 0;
+    root.traverse((node) => {
+        const mesh = node;
+        if (mesh.isMesh !== true)
+            return;
+        if (!isMergeableSkinnedPart(mesh)) {
+            if (mesh.isSkinnedMesh === true)
+                kept += 1;
+            return;
+        }
+        const skinned = mesh;
+        const bones = skinned.skeleton.bones.map((bone) => bone.uuid).join(",");
+        const material = skinned.material;
+        const key = `${material.uuid}|${attributeKey(skinned.geometry)}|${bones}`;
+        const group = groups.get(key);
+        if (group === undefined)
+            groups.set(key, { material, meshes: [skinned] });
+        else
+            group.meshes.push(skinned);
+    });
+    let merged = 0;
+    for (const group of groups.values()) {
+        if (group.meshes.length < 2) {
+            kept += group.meshes.length;
+            continue;
+        }
+        const slots = [];
+        const parts = [];
+        for (const mesh of group.meshes) {
+            const source = mesh.geometry;
+            const part = new THREE.BufferGeometry();
+            for (const [name, attribute] of Object.entries(source.attributes))
+                part.setAttribute(name, attribute.clone());
+            if (source.index !== null)
+                part.setIndex(source.index.clone());
+            part.applyMatrix4(mesh.bindMatrix);
+            const skinIndex = source.getAttribute("skinIndex");
+            const skinWeight = source.getAttribute("skinWeight");
+            const bySkeletonIndex = mesh.skeleton.bones.map((bone, index) => boneSlot(slots, bone, mesh.skeleton.boneInverses[index]));
+            const indices = new Float32Array(skinIndex.count * 4);
+            const weights = new Float32Array(skinWeight.count * 4);
+            for (let vertex = 0; vertex < skinIndex.count; vertex += 1) {
+                for (let channel = 0; channel < 4; channel += 1) {
+                    indices[vertex * 4 + channel] = bySkeletonIndex[skinIndex.getComponent(vertex, channel)] ?? 0;
+                    weights[vertex * 4 + channel] = skinWeight.getComponent(vertex, channel);
+                }
+            }
+            part.setAttribute("skinIndex", new THREE.Float32BufferAttribute(indices, 4));
+            part.setAttribute("skinWeight", new THREE.Float32BufferAttribute(weights, 4));
+            parts.push(part);
+        }
+        const geometry = mergeGeometries(parts, false);
+        for (const part of parts)
+            part.dispose();
+        if (geometry === null) {
+            kept += group.meshes.length;
+            continue;
+        }
+        geometry.computeBoundingBox();
+        geometry.computeBoundingSphere();
+        const first = group.meshes[0];
+        const mesh = new THREE.SkinnedMesh(geometry, group.material);
+        // Bind mode "attached" keeps bindMatrixInverse equal to the mesh's own world matrix, which is what
+        // makes vertices baked out of bind space pose the same wherever the merged node hangs. An explicit
+        // identity bind matrix is required: bind() would otherwise recalculate rest inverses from the
+        // current pose and skin every part against the wrong rest.
+        mesh.bind(new THREE.Skeleton(slots.map((slot) => slot.bone), slots.map((slot) => slot.inverse)), new THREE.Matrix4());
+        mesh.name = first.name;
+        mesh.renderOrder = first.renderOrder;
+        mesh.frustumCulled = first.frustumCulled;
+        mesh.castShadow = first.castShadow;
+        mesh.receiveShadow = first.receiveShadow;
+        const names = [...new Set(group.meshes.map((part) => part.name).filter((name) => name.length > 0))];
+        if (names.length > 0)
+            mesh.userData[MERGED_NAMES_KEY] = names;
+        for (const source of group.meshes)
+            source.removeFromParent();
+        root.add(mesh);
+        merged += group.meshes.length - 1;
+        kept += 1;
+    }
+    return { merged, kept };
+}

package/dist/render/shaderWarmup.d.ts

@@ -0,0 +1,69 @@
+import type { Camera, Object3D } from "three";
+/**
+ * Where the load-time shader warmup is: waiting for the scene to stop growing, compiling a
+ * round, finished, or skipped because the renderer refused. The loading screen renders it.
+ */
+export interface ShaderWarmupState {
+    phase: "waiting" | "compiling" | "ready" | "failed";
+    /** Compile rounds finished. One round covers one burst of streamed models. */
+    rounds: number;
+    /** Shader programs the renderer has initialised, as of the last round. */
+    programs: number;
+    elapsedMs: number;
+}
+/** The renderer surface the warmup needs; a real `WebGLRenderer` satisfies it. */
+export interface ShaderWarmupRenderer {
+    /** Links every mounted material's program; returns the materials it prepared. */
+    compile(scene: Object3D, camera: Camera): unknown;
+    /** Renderer program list; each entry answers `isReady()` once the driver finishes its link. */
+    readonly info?: {
+        readonly programs?: readonly unknown[] | null;
+    };
+}
+/** Defaults sized to cover an initial burst of streamed models without holding the screen. */
+export declare const SHADER_WARMUP_DEFAULTS: {
+    /** Loader quiet time after which a round is the last one. */
+    readonly quietMs: 400;
+    /** Wall-clock cap on the whole warmup. The last round is cut off at it. */
+    readonly budgetMs: 5000;
+    /** Floor for a single round, so a driver that never reports completion cannot stall load. */
+    readonly roundFloorMs: 1500;
+    /** A scene still streaming after this long gets one last round and is revealed anyway. */
+    readonly streamWaitMs: 2000;
+};
+/** Options for {@link createShaderWarmup}; the clock, sleep and loader signal are injectable for tests. */
+export interface ShaderWarmupOptions {
+    renderer: ShaderWarmupRenderer;
+    scene: Object3D;
+    camera: Camera;
+    quietMs?: number;
+    budgetMs?: number;
+    streamWaitMs?: number;
+    /** Called on every state change, so the loading screen can show the phase. */
+    onState?: (state: ShaderWarmupState) => void;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    /** Whether the shared model loader has been quiet long enough. */
+    loaderQuiet?: (quietMs: number) => boolean;
+    /** Changes whenever the shared loader starts a new burst of model loads. */
+    loaderStarts?: () => number;
+}
+/** A warmup in flight: its promise, its latest state, and a way to stop it. */
+export interface ShaderWarmup {
+    /** Resolves when warm, capped or failed; never rejects. */
+    done: Promise<ShaderWarmupState>;
+    state(): ShaderWarmupState;
+    /** Stop after the round in flight and stop waiting; used when the view unmounts. */
+    cancel(): void;
+}
+/**
+ * Warm the scene's shaders through the renderer's async compile, one round per burst of
+ * streamed models, so materials first seen during load never compile on a visible frame.
+ *
+ * A round is `compileAsync` over the mounted scene; the round after it runs only when the
+ * model loader started a new burst or the program count grew, which is what a scene that is
+ * still streaming looks like. Everything is bounded: the last round is raced against the
+ * budget, so a driver that never reports a finished program cannot hold the loading screen.
+ * @internal
+ */
+export declare function createShaderWarmup(options: ShaderWarmupOptions): ShaderWarmup;

package/dist/render/shaderWarmup.js

@@ -0,0 +1,120 @@
+import { modelLoadIdleMs, modelLoadStarts } from "./modelLoad.js";
+function programReady(program) {
+    try {
+        return program.isReady?.() !== false;
+    }
+    catch {
+        return true;
+    }
+}
+/** Defaults sized to cover an initial burst of streamed models without holding the screen. */
+export const SHADER_WARMUP_DEFAULTS = {
+    /** Loader quiet time after which a round is the last one. */
+    quietMs: 400,
+    /** Wall-clock cap on the whole warmup. The last round is cut off at it. */
+    budgetMs: 5_000,
+    /** Floor for a single round, so a driver that never reports completion cannot stall load. */
+    roundFloorMs: 1_500,
+    /** A scene still streaming after this long gets one last round and is revealed anyway. */
+    streamWaitMs: 2_000,
+};
+/**
+ * Warm the scene's shaders through the renderer's async compile, one round per burst of
+ * streamed models, so materials first seen during load never compile on a visible frame.
+ *
+ * A round is `compileAsync` over the mounted scene; the round after it runs only when the
+ * model loader started a new burst or the program count grew, which is what a scene that is
+ * still streaming looks like. Everything is bounded: the last round is raced against the
+ * budget, so a driver that never reports a finished program cannot hold the loading screen.
+ * @internal
+ */
+export function createShaderWarmup(options) {
+    const quietMs = options.quietMs ?? SHADER_WARMUP_DEFAULTS.quietMs;
+    const budgetMs = options.budgetMs ?? SHADER_WARMUP_DEFAULTS.budgetMs;
+    const streamWaitMs = options.streamWaitMs ?? SHADER_WARMUP_DEFAULTS.streamWaitMs;
+    const now = options.now ?? (() => performance.now());
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const loaderQuiet = options.loaderQuiet ?? ((quiet) => modelLoadIdleMs() >= quiet);
+    const loaderStarts = options.loaderStarts ?? modelLoadStarts;
+    const startedAt = now();
+    let state = { phase: "waiting", rounds: 0, programs: 0, elapsedMs: 0 };
+    let cancelled = false;
+    const programs = () => options.renderer.info?.programs?.length ?? 0;
+    const publish = (next) => {
+        state = { ...state, ...next, elapsedMs: Math.round(now() - startedAt) };
+        options.onState?.(state);
+    };
+    const compileRound = async () => {
+        const remaining = budgetMs - (now() - startedAt);
+        const allowance = Math.max(SHADER_WARMUP_DEFAULTS.roundFloorMs, remaining);
+        const deadline = now() + allowance;
+        const before = options.renderer.info?.programs?.length ?? 0;
+        try {
+            // `compileAsync` reports readiness through three's private program property, which throws
+            // when a material regenerated its program mid-poll (ember-command does). Poll the public
+            // program list instead: same wait, no crash path.
+            options.renderer.compile(options.scene, options.camera);
+        }
+        catch {
+            return "error";
+        }
+        for (;;) {
+            if (cancelled)
+                return "timeout";
+            const programs = options.renderer.info?.programs?.slice(before) ?? [];
+            if (programs.every(programReady))
+                return "compiled";
+            if (now() >= deadline)
+                return "timeout";
+            await sleep(10);
+        }
+    };
+    /** Wait (bounded) for the loader to go quiet, so a round is the last one when nothing is left. */
+    const waitLoaderQuiet = async (limitMs) => {
+        const until = startedAt + budgetMs;
+        const limit = Math.min(limitMs, until - now());
+        if (loaderQuiet(quietMs))
+            return true;
+        const deadline = now() + Math.max(0, limit);
+        while (!cancelled && now() < deadline) {
+            await sleep(100);
+            if (loaderQuiet(quietMs))
+                return true;
+        }
+        return loaderQuiet(quietMs);
+    };
+    const done = (async () => {
+        publish({ phase: "compiling" });
+        for (;;) {
+            if (cancelled)
+                break;
+            const starts = loaderStarts();
+            const outcome = await compileRound();
+            if (outcome === "error") {
+                publish({ phase: "failed" });
+                return state;
+            }
+            const settled = programs();
+            publish({ rounds: state.rounds + (outcome === "compiled" ? 1 : 0), programs: settled });
+            if (outcome === "timeout" || cancelled || now() - startedAt >= budgetMs)
+                break;
+            if (!(await waitLoaderQuiet(streamWaitMs)))
+                break;
+            const streamed = loaderStarts() !== starts;
+            const linked = programs() > settled;
+            if (cancelled || (!streamed && !linked))
+                break;
+            if (now() - startedAt >= budgetMs)
+                break;
+        }
+        publish({ phase: "ready" });
+        return state;
+    })();
+    return {
+        done,
+        state: () => state,
+        cancel: () => {
+            cancelled = true;
+        },
+    };
+}

package/dist/render/shadowCasters.d.ts

@@ -0,0 +1,28 @@
+import * as THREE from "three";
+/**
+ * World-space bounding-sphere radius a mesh needs before its shadow is worth a depth
+ * draw. Below this the silhouette is a couple of shadow-map texels wide at every
+ * cascade that reaches it, so the pass spends a draw for a smudge.
+ * @internal
+ */
+export declare const MIN_SHADOW_CASTER_RADIUS = 0.5;
+/** A live caster cull: what it is keeping, and how to put the authored flags back. @internal */
+export interface ShadowCasterCull {
+    /** Meshes still casting in the tree, and how many were cleared for being under the radius. */
+    stats(): {
+        casters: number;
+        skipped: number;
+    };
+    restore(): void;
+}
+/** Bounding-sphere radius of what a mesh draws, in world units; an instance batch counts as its whole spread. @internal */
+export declare function shadowCasterRadius(mesh: THREE.Mesh): number | null;
+/** True when a mesh's shadow is smaller than the map can resolve, so the depth pass should skip it. @internal */
+export declare function isUnderShadowCasterSize(mesh: THREE.Mesh, minRadius?: number): boolean;
+/**
+ * Clear `castShadow` on attached meshes under `minRadius` as nodes stream in, and put the
+ * authored value back when they leave. Only clears: a mesh the game keeps out of the pass
+ * is never turned back on.
+ * @internal
+ */
+export declare function cullSmallShadowCasters(root: THREE.Object3D, minRadius?: number): ShadowCasterCull;

package/dist/render/shadowCasters.js

@@ -0,0 +1,95 @@
+import * as THREE from "three";
+/**
+ * World-space bounding-sphere radius a mesh needs before its shadow is worth a depth
+ * draw. Below this the silhouette is a couple of shadow-map texels wide at every
+ * cascade that reaches it, so the pass spends a draw for a smudge.
+ * @internal
+ */
+export const MIN_SHADOW_CASTER_RADIUS = 0.5;
+function maxAxisScale(node) {
+    const e = node.matrixWorld.elements;
+    return Math.max(Math.hypot(e[0], e[1], e[2]), Math.hypot(e[4], e[5], e[6]), Math.hypot(e[8], e[9], e[10]));
+}
+/** Bounding-sphere radius of what a mesh draws, in world units; an instance batch counts as its whole spread. @internal */
+export function shadowCasterRadius(mesh) {
+    if (mesh.isInstancedMesh === true) {
+        const batch = mesh;
+        if (batch.boundingSphere === null)
+            batch.computeBoundingSphere();
+        return batch.boundingSphere === null ? null : batch.boundingSphere.radius * maxAxisScale(batch);
+    }
+    const geometry = mesh.geometry;
+    if (geometry === undefined || geometry === null)
+        return null;
+    if (geometry.boundingSphere === null)
+        geometry.computeBoundingSphere();
+    const sphere = geometry.boundingSphere;
+    return sphere === null ? null : sphere.radius * maxAxisScale(mesh);
+}
+/** True when a mesh's shadow is smaller than the map can resolve, so the depth pass should skip it. @internal */
+export function isUnderShadowCasterSize(mesh, minRadius = MIN_SHADOW_CASTER_RADIUS) {
+    const radius = shadowCasterRadius(mesh);
+    return radius !== null && radius < minRadius;
+}
+/**
+ * Clear `castShadow` on attached meshes under `minRadius` as nodes stream in, and put the
+ * authored value back when they leave. Only clears: a mesh the game keeps out of the pass
+ * is never turned back on.
+ * @internal
+ */
+export function cullSmallShadowCasters(root, minRadius = MIN_SHADOW_CASTER_RADIUS) {
+    const cleared = new Map();
+    const listeners = new Map();
+    const apply = (node) => {
+        const mesh = node;
+        if (mesh.isMesh !== true || cleared.has(mesh) || mesh.castShadow !== true)
+            return;
+        node.updateWorldMatrix(true, false);
+        if (!isUnderShadowCasterSize(mesh, minRadius))
+            return;
+        cleared.set(mesh, mesh.castShadow);
+        mesh.castShadow = false;
+    };
+    const restoreTree = (node) => {
+        const mesh = node;
+        const authored = cleared.get(mesh);
+        if (authored !== undefined) {
+            mesh.castShadow = authored;
+            cleared.delete(mesh);
+        }
+        for (const child of node.children)
+            restoreTree(child);
+    };
+    const attach = (node) => {
+        if (listeners.has(node))
+            return;
+        apply(node);
+        const added = ({ child }) => attach(child);
+        const removed = ({ child }) => restoreTree(child);
+        node.addEventListener("childadded", added);
+        node.addEventListener("childremoved", removed);
+        listeners.set(node, () => {
+            node.removeEventListener("childadded", added);
+            node.removeEventListener("childremoved", removed);
+        });
+        for (const child of node.children)
+            attach(child);
+    };
+    attach(root);
+    return {
+        stats() {
+            let casters = 0;
+            root.traverse((node) => {
+                if (node.isMesh === true && node.castShadow)
+                    casters += 1;
+            });
+            return { casters, skipped: cleared.size };
+        },
+        restore() {
+            for (const off of listeners.values())
+                off();
+            listeners.clear();
+            restoreTree(root);
+        },
+    };
+}

package/dist/render/staticTransforms.d.ts

@@ -0,0 +1,20 @@
+import * as THREE from "three";
+/**
+ * Bake a subtree's world matrices from its current pose and take it out of three's per-frame
+ * `updateMatrixWorld` pass. Three recomposes every node that keeps `matrixAutoUpdate` and then forces
+ * its whole subtree to rebuild the world matrix, so authored scenery — terrain, batched props,
+ * scatter, instanced ground — pays that cost every frame for a pose it never changes (#2038).
+ *
+ * Freeze a subtree only when its pose is final and its ancestors stay put: a frozen node ignores a
+ * moving parent, and a frozen light or camera stops following the scene. Actors, their bones and
+ * anything a game writes per frame keep auto-updating; a frozen seam that moves on a rare event
+ * (a door, a lift) thaws, moves, then freezes again.
+ * @capability static-transforms
+ */
+export declare function freezeStaticTransforms(root: THREE.Object3D): void;
+/**
+ * Put a subtree back on the per-frame matrix pass after {@link freezeStaticTransforms} — for the
+ * authored seam that moves on an event rather than every frame.
+ * @capability static-transforms
+ */
+export declare function thawStaticTransforms(root: THREE.Object3D): void;

package/dist/render/staticTransforms.js

@@ -0,0 +1,32 @@
+import * as THREE from "three";
+/**
+ * Bake a subtree's world matrices from its current pose and take it out of three's per-frame
+ * `updateMatrixWorld` pass. Three recomposes every node that keeps `matrixAutoUpdate` and then forces
+ * its whole subtree to rebuild the world matrix, so authored scenery — terrain, batched props,
+ * scatter, instanced ground — pays that cost every frame for a pose it never changes (#2038).
+ *
+ * Freeze a subtree only when its pose is final and its ancestors stay put: a frozen node ignores a
+ * moving parent, and a frozen light or camera stops following the scene. Actors, their bones and
+ * anything a game writes per frame keep auto-updating; a frozen seam that moves on a rare event
+ * (a door, a lift) thaws, moves, then freezes again.
+ * @capability static-transforms
+ */
+export function freezeStaticTransforms(root) {
+    root.updateMatrixWorld(true);
+    root.traverse((node) => {
+        node.matrixAutoUpdate = false;
+        node.matrixWorldAutoUpdate = false;
+    });
+}
+/**
+ * Put a subtree back on the per-frame matrix pass after {@link freezeStaticTransforms} — for the
+ * authored seam that moves on an event rather than every frame.
+ * @capability static-transforms
+ */
+export function thawStaticTransforms(root) {
+    root.traverse((node) => {
+        node.matrixAutoUpdate = true;
+        node.matrixWorldAutoUpdate = true;
+        node.matrixWorldNeedsUpdate = true;
+    });
+}

package/dist/render/useFootIk.d.ts

@@ -27,6 +27,13 @@ export interface FootIkRig {
     legs: IkLeg[];
     pelvis: THREE.Object3D | null;
     head: THREE.Object3D | null;
+    /** Yaw and pitch limits of the look-at solve, in radians; absent means unconstrained. */
+    lookAtLimits: {
+        maxYaw?: number;
+        maxPitch?: number;
+    };
+    /** How much of the solved look-at turn reaches the bone, `0..1`. */
+    lookAtWeight: number;
     maxAdjust: number;
     alignToGround: number;
     /** Pose before and after last frame's correction, so a bone no clip animates never accumulates it. */
@@ -45,10 +52,11 @@ export declare function resolveFootIkRig(scene: THREE.Object3D, config: FootIkCo
 /**
  * Applies one frame of foot IK after the animation mixer: probes the ground under each foot,
  * resolves targets with `placeFeet`, lowers the pelvis, solves each leg with `solveTwoBone` bending
- * toward the animated knee, and tilts planted feet to the ground. Returns whether the feet are
- * grounded; `state` carries the faded weight between frames. Exported for tests and custom hosts.
+ * toward the animated knee, and tilts planted feet to the ground. Turns the look-at bone toward
+ * `lookAtTarget` when the rig has one. Returns whether the feet are grounded; `state` carries the
+ * faded weight between frames. Exported for tests and custom hosts.
  */
-export declare function applyFootIk(rig: FootIkRig, originY: number, probe: GroundProbe, state: FootIkState, delta: number, cameraTarget?: readonly [number, number, number]): boolean;
+export declare function applyFootIk(rig: FootIkRig, originY: number, probe: GroundProbe, state: FootIkState, delta: number, lookAtTarget?: readonly [number, number, number]): boolean;
 /**
  * Runs foot IK after the model's animation mixer for `ModelConfig.ik`. Ground probes hit terrain and
  * blocking physical objects, never the model's own entity. `groundOffset` is the model-space height