@jgengine/shell 0.26.0 → 0.28.0

package/dist/render/modelWind.js

@@ -0,0 +1,103 @@
+import * as THREE from "three";
+import { useFrame } from "@react-three/fiber";
+/** Shared gust clock every foliage material reads; advanced once per frame by `WindClock`. */
+export const windClock = { value: 0 };
+/** Shared gust direction (XZ); a model may override it with its own authored direction. */
+export const windDirection = new THREE.Vector2(1, 0.35).normalize();
+const WIND_KEY = "jgWind";
+/** Fully-defaulted sway settings for a model. @internal */
+export function resolveModelWind(wind, fallbackHeight) {
+    if (wind === false || wind === undefined)
+        return null;
+    const strength = wind.strength ?? 0.35;
+    if (!Number.isFinite(strength) || strength < 0)
+        throw new Error("Model wind strength must be finite and non-negative");
+    const speed = wind.speed ?? 1;
+    if (!Number.isFinite(speed) || speed <= 0)
+        throw new Error("Model wind speed must be finite and positive");
+    const height = wind.height ?? fallbackHeight;
+    if (!Number.isFinite(height) || height <= 0)
+        throw new Error("Model wind height must be finite and positive");
+    const direction = new THREE.Vector2(wind.direction?.[0] ?? windDirection.x, wind.direction?.[1] ?? windDirection.y);
+    if (direction.lengthSq() === 0)
+        direction.set(1, 0);
+    direction.normalize();
+    return { strength, speed, height, direction };
+}
+const VERTEX_PARS = /* glsl */ `
+uniform float uJgWindTime;
+uniform vec2 uJgWindDir;
+uniform float uJgWindStrength;
+uniform float uJgWindSpeed;
+uniform float uJgWindHeight;`;
+// Height-ramped sway in object space, phased by the instance's world position so neighbouring
+// plants move on different gusts. Trunks (low vertices) barely move; fronds ride the full travel.
+const VERTEX_SWAY = /* glsl */ `#include <begin_vertex>
+{
+  float jgWindT = clamp(position.y / max(uJgWindHeight, 0.001), 0.0, 1.0);
+  float jgWindRamp = jgWindT * jgWindT;
+  #ifdef USE_INSTANCING
+    vec3 jgWindWorld = (instanceMatrix * vec4(transformed, 1.0)).xyz;
+  #else
+    vec3 jgWindWorld = (modelMatrix * vec4(transformed, 1.0)).xyz;
+  #endif
+  float jgWindPhase = dot(jgWindWorld.xz, vec2(0.17, 0.13)) + uJgWindTime * uJgWindSpeed;
+  float jgWindGust = sin(jgWindPhase) * 0.6 + sin(jgWindPhase * 0.47 + 2.3) * 0.4;
+  float jgWindFlutter = sin(uJgWindTime * 6.3 + jgWindWorld.x * 0.9 + jgWindWorld.z * 1.3) * 0.18;
+  vec2 jgWindPush = uJgWindDir * (jgWindGust + jgWindFlutter) * uJgWindStrength * jgWindRamp;
+  transformed.x += jgWindPush.x;
+  transformed.z += jgWindPush.y;
+}`;
+/**
+ * Compiles height-ramped wind sway into a standard material's vertex shader. Idempotent per
+ * material; the clock and direction are shared module uniforms, so the whole scene advances with
+ * one write per frame and no per-material bookkeeping.
+ * @capability model-wind sway a foliage model in the shared gust field
+ */
+export function applyModelWind(material, wind) {
+    if (material.userData[WIND_KEY] !== undefined)
+        return material;
+    const uniforms = {
+        uJgWindTime: windClock,
+        uJgWindDir: { value: wind.direction.clone() },
+        uJgWindStrength: { value: wind.strength },
+        uJgWindSpeed: { value: wind.speed },
+        uJgWindHeight: { value: wind.height },
+    };
+    material.userData[WIND_KEY] = uniforms;
+    const previousCompile = material.onBeforeCompile;
+    const previousKey = material.customProgramCacheKey;
+    material.onBeforeCompile = (shader, renderer) => {
+        previousCompile.call(material, shader, renderer);
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `#include <common>\n${VERTEX_PARS}`)
+            .replace("#include <begin_vertex>", VERTEX_SWAY);
+    };
+    material.customProgramCacheKey = () => `${previousKey.call(material)}|jg-wind:v1`;
+    material.needsUpdate = true;
+    return material;
+}
+/** Applies wind to every standard material under a cloned model. @internal */
+export function applyModelWindToScene(root, wind, fallbackHeight = 4) {
+    const resolved = resolveModelWind(wind, fallbackHeight);
+    if (resolved === null)
+        return;
+    root.traverse((node) => {
+        const mesh = node;
+        if (!mesh.isMesh)
+            return;
+        const list = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+        for (const material of list) {
+            if (material.isMeshStandardMaterial === true)
+                applyModelWind(material, resolved);
+        }
+    });
+}
+/** Advances the shared gust clock once per frame; mount one per 3D world. */
+export function WindClock() {
+    useFrame(({ clock }) => {
+        windClock.value = clock.getElapsedTime();
+    });
+    return null;
+}

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

package/dist/render/useFootIk.js

@@ -134,6 +134,8 @@ export function resolveFootIkRig(scene, config) {
         legs,
         pelvis,
         head,
+        lookAtLimits: { ...(options.lookAt?.maxYaw === undefined ? {} : { maxYaw: options.lookAt.maxYaw }), ...(options.lookAt?.maxPitch === undefined ? {} : { maxPitch: options.lookAt.maxPitch }) },
+        lookAtWeight: Math.max(0, Math.min(1, options.lookAt?.weight ?? 1)),
         maxAdjust: options.maxAdjust ?? DEFAULT_MAX_ADJUST,
         alignToGround: Math.max(0, Math.min(1, options.alignToGround ?? 1)),
         poses: [...bones].map((bone) => ({
@@ -175,10 +177,11 @@ function restoreFootIkPose(rig) {
 /**
  * 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 function applyFootIk(rig, originY, probe, state, delta, cameraTarget) {
+export function applyFootIk(rig, originY, probe, state, delta, lookAtTarget) {
     restoreFootIkPose(rig);
     for (const record of rig.poses) {
         record.animated.q.copy(record.bone.quaternion);
@@ -235,11 +238,12 @@ export function applyFootIk(rig, originY, probe, state, delta, cameraTarget) {
             writeWorldQuaternion(leg.tip, current.slerp(tilt.multiply(current), planted * weight * rig.alignToGround));
         }
     }
-    if (rig.head !== null && cameraTarget !== undefined) {
+    if (rig.head !== null && lookAtTarget !== undefined) {
         const from = rig.head.getWorldPosition(scratch.a);
-        const q = lookAt({ from: [from.x, from.y, from.z], target: cameraTarget, up: [0, 1, 0] });
+        const q = lookAt({ from: [from.x, from.y, from.z], target: lookAtTarget, up: [0, 1, 0], ...rig.lookAtLimits });
         const current = rig.head.getWorldQuaternion(scratch.q2);
-        writeWorldQuaternion(rig.head, current.slerp(scratch.q.set(q[0], q[1], q[2], q[3]), Math.max(weight, rig.legs.length === 0 ? 1 : 0)));
+        const reach = Math.max(weight, rig.legs.length === 0 ? 1 : 0) * rig.lookAtWeight;
+        writeWorldQuaternion(rig.head, current.slerp(scratch.q.set(q[0], q[1], q[2], q[3]), reach));
     }
     for (const record of rig.poses) {
         record.written.q.copy(record.bone.quaternion);
@@ -256,8 +260,11 @@ export function useFootIk(scene, config, ctx, instanceId, groundOffset = 0) {
     const camera = useThree((three) => three.camera);
     const rig = useMemo(() => (config === undefined ? null : resolveFootIkRig(scene, config)), [scene, config]);
     const state = useRef({ weight: 0, pelvis: 0 });
+    const lookAtConfig = config === undefined || config === "auto" ? undefined : config.lookAt;
+    const target = useRef(null);
     useLayoutEffect(() => {
         state.current = { weight: 0, pelvis: 0 };
+        target.current = null;
         return () => {
             if (rig !== null) {
                 restoreFootIkPose(rig);
@@ -271,11 +278,32 @@ export function useFootIk(scene, config, ctx, instanceId, groundOffset = 0) {
         const parent = scene.parent;
         const originY = parent === null ? scene.position.y : parent.localToWorld(scratch.a.set(0, groundOffset, 0)).y;
         const exclude = [instanceId];
+        const aim = resolveLookAtTarget(lookAtConfig?.target, ctx, target.current, lookAtConfig?.entityEyeHeight ?? DEFAULT_EYE_HEIGHT);
+        target.current = aim;
         applyFootIk(rig, originY, (input) => ctx.scene.raycast({
             ...input,
             excludeInstanceIds: exclude,
             filter: { entities: false, objects: true, walls: false, terrain: true },
             accept: (hit) => hit.blocks && hit.purpose === "physical",
-        }), state.current, delta, rig.head === null ? undefined : camera.getWorldPosition(scratch.b).toArray());
+        }), state.current, delta, aim === null ? camera.getWorldPosition(scratch.b).toArray() : [aim.x, aim.y, aim.z]);
     });
 }
+const DEFAULT_EYE_HEIGHT = 1.5;
+/**
+ * Where a look-at bone should aim this frame, or `null` when it aims at the camera. An entity
+ * target that is not spawned yet reuses `previous` rather than snapping back to the camera.
+ */
+function resolveLookAtTarget(spec, ctx, previous, eyeHeight) {
+    if (spec === undefined || spec === "camera")
+        return null;
+    if ("point" in spec) {
+        previous?.set(spec.point[0], spec.point[1], spec.point[2]);
+        return previous ?? new THREE.Vector3(spec.point[0], spec.point[1], spec.point[2]);
+    }
+    const entity = ctx.scene.entity.get(spec.entity);
+    if (entity === null || entity === undefined)
+        return previous;
+    const position = entity.position;
+    previous?.set(position[0], position[1] + eyeHeight, position[2]);
+    return previous ?? new THREE.Vector3(position[0], position[1] + eyeHeight, position[2]);
+}

package/dist/render/useModelAnimation.d.ts

@@ -13,14 +13,28 @@ export interface ModelAnimationDiagnostic {
  * @capability model-animation-diagnostics inspect imported clip mappings, layer masks and root-track compatibility
  */
 export declare function diagnoseModelAnimation(scene: THREE.Object3D, animation: ModelAnimationConfig, clips: readonly THREE.AnimationClip[]): readonly ModelAnimationDiagnostic[];
+/**
+ * One visual sample's measured motion, used to derive the directional locomotion parameters.
+ * `dx`/`dz` are world horizontal displacement since the previous sample, `dyaw` the yaw change in
+ * radians and `seconds` the time the sample covers.
+ */
+export interface ModelMotionStep {
+    dx: number;
+    dz: number;
+    dyaw: number;
+    seconds: number;
+}
 /**
  * Refreshes a caller-owned graph parameter dictionary from authored extras and known physical movement.
  * Grounded, verticalSpeed and crouched use the shared motor's resolved state when available; custom movers
- * retain their authored values. Speed always uses the supplied measured ground speed. Does not write game state.
+ * retain their authored values. Speed always uses the supplied measured ground speed. Passing `step`
+ * derives the directional parameters from the character's own motion: `direction` is the motion's share
+ * along the character's right axis, `facing` its share along the facing axis, and `turnRate` its yaw
+ * change per second. Derived values override conflicting authored extras. Does not write game state.
  *
  * @capability animation-motion-params read resolved player movement into reusable animation graph parameters
  */
-export declare function readModelAnimationParams(ctx: GameContext, instanceId: string, speed: number, out: Record<string, AnimParamValue>): Record<string, AnimParamValue>;
+export declare function readModelAnimationParams(ctx: GameContext, instanceId: string, speed: number, out: Record<string, AnimParamValue>, step?: ModelMotionStep): Record<string, AnimParamValue>;
 /**
  * For a frame where a `rootMotion` state is current: pins the root bone's horizontal translation to
  * its bind pose, so the clip plays in place, and returns that step's root travel as a world-space