@jgengine/shell 0.32.0 → 0.33.0

package/dist/postfx/PostProcessing.js

@@ -6,23 +6,39 @@ import { OutputPass } from "three/examples/jsm/postprocessing/OutputPass.js";
 import { GTAOPass } from "three/examples/jsm/postprocessing/GTAOPass.js";
 import { BokehPass } from "three/examples/jsm/postprocessing/BokehPass.js";
 import { SMAAPass } from "three/examples/jsm/postprocessing/SMAAPass.js";
-import { DEFAULT_AO } from "@jgengine/core/render/postProcessing";
-import { adaptExposure, DEFAULT_AUTO_EXPOSURE, exposureForKey, keyLuminanceFromSamples } from "@jgengine/core/render/colorPipeline";
+import { DEFAULT_AO, } from "@jgengine/core/render/postProcessing";
+import { adaptExposure, DEFAULT_AUTO_EXPOSURE, exposureForKey, keyLuminanceFromSamples, } from "@jgengine/core/render/colorPipeline";
 import { ExposureMeterPass } from "./autoExposure.js";
 import { createGradePass } from "./gradeShader.js";
+import { releasePostfxOverlayTracking } from "./postfxOverlay.js";
 import { StylizePass } from "./stylizePass.js";
 import { renderShadowlessPrepass } from "./shadowPrepass.js";
-/**
- * GTAO renders the scene with an `overrideMaterial` normal/depth prepass, which stamps
- * transparent overlay quads (additive VFX sprites, telegraphs, debug gizmos) into the AO
- * buffers as opaque squares — the AO composite then multiplies them toward black. Hide
- * marked overlay subtrees for the whole pass: the beauty buffer it composites over was
- * already rendered with them in.
- */
+/** Point three's GTAO pass at the prepass that already hid its points and lines. @internal */
+export function skipGtaoVisibilityWalk(pass) {
+    const hooks = pass;
+    if (typeof hooks._overrideVisibility !== "function" || typeof hooks._restoreVisibility !== "function")
+        return false;
+    const restore = hooks._restoreVisibility;
+    hooks._overrideVisibility = () => { };
+    hooks._restoreVisibility = () => {
+        // three's restore only touches its own cache, which stays empty while the walk is skipped.
+        restore.call(pass);
+    };
+    return true;
+}
 class OverlayAwareGTAOPass extends GTAOPass {
     hiddenOverlays = [];
+    constructor(scene, camera, width, height) {
+        super(scene, camera, width, height);
+        skipGtaoVisibilityWalk(this);
+    }
     render(renderer, writeBuffer, readBuffer, deltaTime, maskActive) {
-        renderShadowlessPrepass(renderer, this.scene, this.hiddenOverlays, () => super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive));
+        const rendersGbuffer = this._renderGBuffer !== false;
+        if (!rendersGbuffer) {
+            super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive);
+            return;
+        }
+        renderShadowlessPrepass(renderer, this.scene, this.hiddenOverlays, () => super.render(renderer, writeBuffer, readBuffer, deltaTime, maskActive), true);
     }
 }
 /** DOF's depth prepass has the same `overrideMaterial` overlay-stamping problem as GTAO. */
@@ -65,6 +81,125 @@ export function resolveAoStage(ao, tierAllowsAo) {
         return null;
     return ao ?? DEFAULT_AO;
 }
+/** The stages one chain asks for, before any pass is built. Pure data. @internal */
+export function planPostStages(config, quality = "high", stages) {
+    const aa = config.aa === undefined ? "smaa" : config.aa;
+    const tierStages = stages ?? { ao: quality === "high", bloom: true, dof: quality === "high", smaa: true };
+    const ao = resolveAoStage(config.ao, tierStages.ao);
+    const authoredDof = tierStages.dof && config.dof !== undefined && config.dof !== false ? config.dof : null;
+    const bloom = tierStages.bloom && config.bloom !== false ? (config.bloom ?? {}) : null;
+    const smaa = tierStages.smaa && aa === "smaa";
+    return {
+        samples: aa === false ? 0 : 2,
+        ao,
+        aoSamples: quality === "ultra" ? 16 : quality === "high" ? 12 : 8,
+        aoGbuffer: smaa || aa === false ? "beauty" : "prepass",
+        bloom,
+        dof: authoredDof === null ? null : { ...authoredDof, aperture: authoredDof.aperture ?? (quality === "high" ? 0.00025 : 0.00012) },
+        smaa,
+        autoExposure: config.autoExposure === false ? null : { ...DEFAULT_AUTO_EXPOSURE, ...(config.autoExposure ?? {}) },
+        stylize: config.stylize !== undefined && config.stylize !== false ? config.stylize : null,
+        grade: config.grade !== false ? (config.grade ?? {}) : null,
+        exposure: config.exposure ?? 1,
+    };
+}
+/**
+ * The toggle stages a chain built from `config` can contain on its most permissive tier, with the
+ * player's own toggles ignored. A row for any other stage switches a pass the chain never builds, so
+ * nothing the player picks reaches the screen.
+ * @internal
+ */
+export function availablePostfxStages(config) {
+    const plan = planPostStages(config, "high", { ao: true, bloom: true, dof: true, smaa: true });
+    const stages = [];
+    if (plan.ao !== null)
+        stages.push("ao");
+    if (plan.bloom !== null)
+        stages.push("bloom");
+    if (plan.dof !== null)
+        stages.push("dof");
+    if (plan.smaa)
+        stages.push("smaa");
+    return stages;
+}
+/**
+ * Build the composer for a plan. A stage the plan left out adds no pass, so it draws nothing and
+ * allocates no render target.
+ * @internal
+ */
+export function buildPostGraph(gl, scene, camera, plan, width, height) {
+    const beautyDepth = plan.ao !== null && plan.aoGbuffer === "beauty" ? new THREE.DepthTexture(width, height) : null;
+    const target = new THREE.WebGLRenderTarget(width, height, {
+        type: THREE.HalfFloatType,
+        samples: beautyDepth === null ? plan.samples : 0,
+        ...(beautyDepth === null ? {} : { depthTexture: beautyDepth }),
+    });
+    const composer = new EffectComposer(gl, target);
+    const built = [];
+    composer.addPass(new RenderPass(scene, camera));
+    if (plan.ao !== null) {
+        const ao = new OverlayAwareGTAOPass(scene, camera, width, height);
+        if (beautyDepth !== null)
+            ao.setGBuffer(beautyDepth);
+        ao.blendIntensity = plan.ao.blend ?? 1;
+        ao.updateGtaoMaterial({
+            radius: plan.ao.radius ?? 1.8,
+            distanceExponent: 1,
+            thickness: plan.ao.distanceFalloff ?? 3.6,
+            scale: plan.ao.intensity ?? 2.4,
+            samples: plan.aoSamples,
+        });
+        composer.addPass(ao);
+        built.push("ao");
+    }
+    if (plan.bloom !== null) {
+        composer.addPass(new UnrealBloomPass(new THREE.Vector2(width, height), plan.bloom.strength ?? 0.32, plan.bloom.radius ?? 0.55, plan.bloom.threshold ?? 0.85));
+        built.push("bloom");
+    }
+    if (plan.dof !== null) {
+        const dof = new OverlayAwareBokehPass(scene, camera, {
+            focus: plan.dof.focus ?? 18,
+            aperture: plan.dof.aperture ?? 0.00025,
+            maxblur: plan.dof.maxBlur ?? 0.01,
+        });
+        composer.addPass(dof);
+        built.push("dof");
+    }
+    // SMAA must run before OutputPass (linear-sRGB). Default on for post chains.
+    if (plan.smaa) {
+        composer.addPass(new SMAAPass());
+        built.push("smaa");
+    }
+    // Clamped auto-exposure meters the pre-tone-map buffer, so the meter sits before OutputPass and
+    // hands the adaptation to the renderer's exposure — the one value the sky swatches also read.
+    const authoredExposure = plan.exposure;
+    if (plan.autoExposure !== null) {
+        const autoExposure = plan.autoExposure;
+        let current = authoredExposure;
+        let sampled = false;
+        composer.addPass(new ExposureMeterPass((samples, seconds) => {
+            const target = authoredExposure * exposureForKey(keyLuminanceFromSamples(samples), autoExposure);
+            // The first sample lands on its own target; fading in from the authored exposure would
+            // open every load on a visible exposure slideshow.
+            current = sampled ? adaptExposure(current, target, seconds, autoExposure.adaptationSeconds) : target;
+            sampled = true;
+            gl.toneMappingExposure = quantizeExposure(current);
+        }));
+        built.push("exposure");
+    }
+    composer.addPass(new OutputPass());
+    if (plan.stylize !== null) {
+        composer.addPass(new StylizePass(scene, camera, plan.stylize));
+        built.push("stylize");
+    }
+    let grade = null;
+    if (plan.grade !== null) {
+        grade = createGradePass(plan.grade);
+        composer.addPass(grade);
+        built.push("grade");
+    }
+    return { composer, grade, stages: built };
+}
 /**
  * Mounts an `EffectComposer` inside the shell Canvas and takes over rendering
  * (priority-1 `useFrame`, which disables R3F auto-render) to run the configured
@@ -73,7 +208,8 @@ export function resolveAoStage(ao, tierAllowsAo) {
  *
  * `stages` (resolved from the player's graphics profile) controls expensive passes
  * independently. Medium keeps AO and DOF with reduced AO sampling; low can disable
- * them while retaining cheaper bloom, SMAA, tone mapping, and grade stages.
+ * them while retaining cheaper bloom, SMAA, tone mapping, and grade stages. A stage
+ * that is off adds no pass at all, so it costs no draw and allocates no target.
  */
 export function PostProcessing({ config, quality = "high", stages }) {
     const gl = useThree((s) => s.gl);
@@ -84,75 +220,12 @@ export function PostProcessing({ config, quality = "high", stages }) {
     useEffect(() => {
         const width = Math.max(1, size.width);
         const height = Math.max(1, size.height);
-        const aa = config.aa === undefined ? "smaa" : config.aa;
-        const msaaSamples = aa === false ? 0 : 2;
-        const target = new THREE.WebGLRenderTarget(width, height, {
-            type: THREE.HalfFloatType,
-            samples: msaaSamples,
-        });
-        const composer = new EffectComposer(gl, target);
-        composer.addPass(new RenderPass(scene, camera));
-        const resolvedStages = stages ?? { ao: quality === "high", bloom: true, dof: quality === "high", smaa: true };
-        const aoStage = resolveAoStage(config.ao, resolvedStages.ao);
-        if (aoStage !== null) {
-            const ao = new OverlayAwareGTAOPass(scene, camera, width, height);
-            ao.blendIntensity = aoStage.blend ?? 1;
-            ao.updateGtaoMaterial({
-                radius: aoStage.radius ?? 1.8,
-                distanceExponent: 1,
-                thickness: aoStage.distanceFalloff ?? 3.6,
-                scale: aoStage.intensity ?? 2.4,
-                samples: quality === "ultra" ? 16 : quality === "high" ? 12 : 8,
-            });
-            composer.addPass(ao);
-        }
-        if (resolvedStages.bloom && config.bloom !== false) {
-            const b = config.bloom ?? {};
-            composer.addPass(new UnrealBloomPass(new THREE.Vector2(width, height), b.strength ?? 0.32, b.radius ?? 0.55, b.threshold ?? 0.85));
-        }
-        if (resolvedStages.dof && config.dof !== undefined && config.dof !== false) {
-            const d = config.dof;
-            const dof = new OverlayAwareBokehPass(scene, camera, {
-                focus: d.focus ?? 18,
-                aperture: d.aperture ?? (quality === "high" ? 0.00025 : 0.00012),
-                maxblur: d.maxBlur ?? 0.01,
-            });
-            composer.addPass(dof);
-        }
-        // SMAA must run before OutputPass (linear-sRGB). Default on for post chains.
-        if (resolvedStages.smaa && aa === "smaa") {
-            composer.addPass(new SMAAPass());
-        }
-        // Clamped auto-exposure meters the pre-tone-map buffer, so the meter sits before OutputPass and
-        // hands the adaptation to the renderer's exposure — the one value the sky swatches also read.
-        const autoExposure = config.autoExposure === false ? null : { ...DEFAULT_AUTO_EXPOSURE, ...(config.autoExposure ?? {}) };
-        const authoredExposure = config.exposure ?? 1;
-        if (autoExposure !== null) {
-            let current = authoredExposure;
-            let sampled = false;
-            composer.addPass(new ExposureMeterPass((samples, seconds) => {
-                const target = authoredExposure * exposureForKey(keyLuminanceFromSamples(samples), autoExposure);
-                // The first sample lands on its own target; fading in from the authored exposure would
-                // open every load on a visible exposure slideshow.
-                current = sampled ? adaptExposure(current, target, seconds, autoExposure.adaptationSeconds) : target;
-                sampled = true;
-                gl.toneMappingExposure = quantizeExposure(current);
-            }));
-        }
-        composer.addPass(new OutputPass());
-        if (config.stylize !== undefined && config.stylize !== false) {
-            composer.addPass(new StylizePass(scene, camera, config.stylize));
-        }
-        let grade = null;
-        if (config.grade !== false) {
-            grade = createGradePass(config.grade ?? {});
-            composer.addPass(grade);
-        }
-        const graph = { composer, grade };
+        const graph = buildPostGraph(gl, scene, camera, planPostStages(config, quality, stages), width, height);
         syncSize(graph, width, height, gl.getPixelRatio());
         builtRef.current = graph;
         return () => {
             disposeGraph(graph);
+            releasePostfxOverlayTracking(scene);
             builtRef.current = null;
         };
     }, [gl, scene, camera, config, quality, stages]);

package/dist/postfx/postfxOverlay.d.ts

@@ -15,10 +15,20 @@ export declare function isPostfxOverlay(object: {
     userData?: Record<string, unknown>;
 }): boolean;
 /**
- * Hide every currently visible marked object under `scene`, recording what was hidden into
- * `out` (cleared first, no allocation on the hot path) so {@link restorePostfxOverlays} can
- * undo exactly that set.
+ * Hide every currently visible object `scene`'s prepasses must skip, recording what was hidden into
+ * `out` (cleared first, no allocation on the hot path) so {@link restorePostfxOverlays} can undo
+ * exactly that set. `withUnmodelled` also hides points and lines, which three's GTAO pass excludes
+ * from its normal buffer but a depth prepass keeps.
+ *
+ * The set is cached and rescanned only when the scene graph changes: walking the whole scene per
+ * prepass cost 2.4 ms/frame in Drift Foundry and 0.6 ms/frame in Harbor Heat, and the graph changes
+ * when something mounts, not between frames.
  */
-export declare function hidePostfxOverlays(scene: THREE.Object3D, out: THREE.Object3D[]): void;
+export declare function hidePostfxOverlays(scene: THREE.Object3D, out: THREE.Object3D[], withUnmodelled?: boolean): void;
 /** Restore visibility for the objects hidden by {@link hidePostfxOverlays} and clear the list. */
 export declare function restorePostfxOverlays(hidden: THREE.Object3D[]): void;
+/**
+ * Drop the cached set and its listeners for a scene that is going away, so a torn-down world does
+ * not keep its node graph reachable through this module.
+ */
+export declare function releasePostfxOverlayTracking(scene: THREE.Object3D): void;

package/dist/postfx/postfxOverlay.js

@@ -13,19 +13,84 @@ export const POSTFX_OVERLAY_USERDATA = {
 export function isPostfxOverlay(object) {
     return object.userData?.jgPostfxOverlay === true;
 }
+/** Whether a normal-material prepass must leave `object` out: three's AO pass cannot describe these. */
+function isUnmodelledDrawable(object) {
+    const drawable = object;
+    return drawable.isPoints === true || drawable.isLine === true || drawable.isLine2 === true;
+}
+const tracks = new WeakMap();
+function unwatchAll(track, node) {
+    track.listeners.get(node)?.();
+    track.listeners.delete(node);
+    for (const child of node.children)
+        unwatchAll(track, child);
+}
+function watch(track, node) {
+    if (track.listeners.has(node))
+        return;
+    const added = ({ child }) => {
+        track.revision += 1;
+        watch(track, child);
+    };
+    const removed = ({ child }) => {
+        track.revision += 1;
+        unwatchAll(track, child);
+    };
+    node.addEventListener("childadded", added);
+    node.addEventListener("childremoved", removed);
+    track.listeners.set(node, () => {
+        node.removeEventListener("childadded", added);
+        node.removeEventListener("childremoved", removed);
+    });
+    for (const child of node.children)
+        watch(track, child);
+}
+function trackFor(scene) {
+    const existing = tracks.get(scene);
+    if (existing !== undefined)
+        return existing;
+    const track = { revision: 0, scanned: -1, overlays: [], drawables: [], listeners: new Map() };
+    tracks.set(scene, track);
+    watch(track, scene);
+    return track;
+}
+function rescan(scene, track) {
+    track.overlays.length = 0;
+    track.drawables.length = 0;
+    scene.traverse((object) => {
+        if (isPostfxOverlay(object))
+            track.overlays.push(object);
+        else if (isUnmodelledDrawable(object))
+            track.drawables.push(object);
+    });
+    track.scanned = track.revision;
+}
+function hideAll(objects, out) {
+    for (const object of objects) {
+        if (!object.visible)
+            continue;
+        object.visible = false;
+        out.push(object);
+    }
+}
 /**
- * Hide every currently visible marked object under `scene`, recording what was hidden into
- * `out` (cleared first, no allocation on the hot path) so {@link restorePostfxOverlays} can
- * undo exactly that set.
+ * Hide every currently visible object `scene`'s prepasses must skip, recording what was hidden into
+ * `out` (cleared first, no allocation on the hot path) so {@link restorePostfxOverlays} can undo
+ * exactly that set. `withUnmodelled` also hides points and lines, which three's GTAO pass excludes
+ * from its normal buffer but a depth prepass keeps.
+ *
+ * The set is cached and rescanned only when the scene graph changes: walking the whole scene per
+ * prepass cost 2.4 ms/frame in Drift Foundry and 0.6 ms/frame in Harbor Heat, and the graph changes
+ * when something mounts, not between frames.
  */
-export function hidePostfxOverlays(scene, out) {
+export function hidePostfxOverlays(scene, out, withUnmodelled = false) {
     out.length = 0;
-    scene.traverse((object) => {
-        if (object.visible && isPostfxOverlay(object)) {
-            object.visible = false;
-            out.push(object);
-        }
-    });
+    const track = trackFor(scene);
+    if (track.scanned !== track.revision)
+        rescan(scene, track);
+    hideAll(track.overlays, out);
+    if (withUnmodelled)
+        hideAll(track.drawables, out);
 }
 /** Restore visibility for the objects hidden by {@link hidePostfxOverlays} and clear the list. */
 export function restorePostfxOverlays(hidden) {
@@ -33,3 +98,18 @@ export function restorePostfxOverlays(hidden) {
         object.visible = true;
     hidden.length = 0;
 }
+/**
+ * Drop the cached set and its listeners for a scene that is going away, so a torn-down world does
+ * not keep its node graph reachable through this module.
+ */
+export function releasePostfxOverlayTracking(scene) {
+    const track = tracks.get(scene);
+    if (track === undefined)
+        return;
+    tracks.delete(scene);
+    for (const off of track.listeners.values())
+        off();
+    track.listeners.clear();
+    track.overlays.length = 0;
+    track.drawables.length = 0;
+}

package/dist/postfx/shadowPrepass.d.ts

@@ -6,5 +6,9 @@ import type * as THREE from "three";
  * @internal
  */
 export declare function renderWithCurrentMatrices<T>(scene: THREE.Object3D, render: () => T): T;
-/** Reuse the beauty pass's shadow maps and world matrices while drawing a scene prepass. @internal */
-export declare function renderShadowlessPrepass<T>(renderer: Pick<THREE.WebGLRenderer, "shadowMap">, scene: THREE.Object3D, hiddenOverlays: THREE.Object3D[], render: () => T): T;
+/**
+ * Reuse the beauty pass's shadow maps and world matrices while drawing a scene prepass.
+ * `withUnmodelled` also hides points and lines, which GTAO's normal buffer excludes anyway.
+ * @internal
+ */
+export declare function renderShadowlessPrepass<T>(renderer: Pick<THREE.WebGLRenderer, "shadowMap">, scene: THREE.Object3D, hiddenOverlays: THREE.Object3D[], render: () => T, withUnmodelled?: boolean): T;

package/dist/postfx/shadowPrepass.js

@@ -15,12 +15,16 @@ export function renderWithCurrentMatrices(scene, render) {
         scene.matrixWorldAutoUpdate = autoUpdate;
     }
 }
-/** Reuse the beauty pass's shadow maps and world matrices while drawing a scene prepass. @internal */
-export function renderShadowlessPrepass(renderer, scene, hiddenOverlays, render) {
+/**
+ * Reuse the beauty pass's shadow maps and world matrices while drawing a scene prepass.
+ * `withUnmodelled` also hides points and lines, which GTAO's normal buffer excludes anyway.
+ * @internal
+ */
+export function renderShadowlessPrepass(renderer, scene, hiddenOverlays, render, withUnmodelled = false) {
     const shadowMap = renderer.shadowMap;
     const autoUpdate = shadowMap.autoUpdate;
     const needsUpdate = shadowMap.needsUpdate;
-    hidePostfxOverlays(scene, hiddenOverlays);
+    hidePostfxOverlays(scene, hiddenOverlays, withUnmodelled);
     shadowMap.autoUpdate = false;
     shadowMap.needsUpdate = false;
     try {

package/dist/render/characterLod.js

@@ -94,6 +94,12 @@ export function noteCharacterPose(instanceId) {
 }
 /** Publish the clip and time a rig is posing at, so the crowd can continue the same pose at the swap. @internal */
 export function noteAnimationPhase(instanceId, clip, time) {
+    const published = phases.get(instanceId);
+    if (published !== undefined) {
+        published.clip = clip;
+        published.time = time;
+        return;
+    }
     phases.set(instanceId, { clip, time });
 }
 /** The clip phase a character was last posed at, or `undefined` when it never posed. @internal */

package/dist/render/useFootIk.js

@@ -174,6 +174,14 @@ function restoreFootIkPose(rig) {
             record.bone.position.copy(record.animated.p);
     }
 }
+/**
+ * Reused per frame by {@link applyFootIk}: the ground probes, their hits and the solver input are read
+ * synchronously inside one call, so a rig posing every frame allocates nothing.
+ */
+const probeInput = { origin: [0, 0, 0], direction: [0, -1, 0], maxDistance: 0 };
+const samplesScratch = [];
+const normalsScratch = [];
+const samplePool = [];
 /**
  * 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
@@ -187,8 +195,8 @@ export function applyFootIk(rig, originY, probe, state, delta, lookAtTarget) {
         record.animated.q.copy(record.bone.quaternion);
         record.animated.p.copy(record.bone.position);
     }
-    const samples = [];
-    const normals = [];
+    samplesScratch.length = 0;
+    normalsScratch.length = 0;
     let length = 0;
     let ankleHeight = 0;
     for (const leg of rig.legs) {
@@ -197,11 +205,19 @@ export function applyFootIk(rig, originY, probe, state, delta, lookAtTarget) {
         length = Math.max(length, legSize);
         ankleHeight = Math.max(ankleHeight, leg.ankleRatio * legSize);
         const from = Math.max(scratch.tip.y, originY) + legSize * 0.5;
-        const hit = probe({ origin: [scratch.tip.x, from, scratch.tip.z], direction: [0, -1, 0], maxDistance: legSize * 2 });
-        samples.push({ ankleY: scratch.tip.y, groundY: hit === null ? null : hit.point[1] });
-        normals.push(hit === null ? null : hit.normal);
+        probeInput.origin[0] = scratch.tip.x;
+        probeInput.origin[1] = from;
+        probeInput.origin[2] = scratch.tip.z;
+        probeInput.maxDistance = legSize * 2;
+        const hit = probe(probeInput);
+        const index = samplesScratch.length;
+        const sample = samplePool[index] ?? (samplePool[index] = { ankleY: 0, groundY: null });
+        sample.ankleY = scratch.tip.y;
+        sample.groundY = hit === null ? null : hit.point[1];
+        samplesScratch.push(sample);
+        normalsScratch.push(hit === null ? null : hit.normal);
     }
-    const placement = placeFeet({ feet: samples, originY, ankleHeight, maxAdjust: rig.maxAdjust * length, airborneGap: length * 0.3 });
+    const placement = placeFeet({ feet: samplesScratch, originY, ankleHeight, maxAdjust: rig.maxAdjust * length, airborneGap: length * 0.3 });
     const blend = Math.min(1, delta * (placement.grounded ? 12 : 6));
     state.weight += ((placement.grounded ? 1 : 0) - state.weight) * blend;
     state.pelvis += (placement.pelvisOffset - state.pelvis) * Math.min(1, delta * 15);
@@ -230,9 +246,9 @@ export function applyFootIk(rig, originY, probe, state, delta, lookAtTarget) {
         aimSegment(leg.root, root, mid, solved.mid);
         // Rotating the thigh also moved the tip; aim the shin from that updated pose.
         aimSegment(leg.mid, leg.mid.getWorldPosition(scratch.mid), leg.tip.getWorldPosition(scratch.tip), solved.tip);
-        const normal = normals[i];
+        const normal = normalsScratch[i];
         if (normal !== null && normal !== undefined && rig.alignToGround > 0) {
-            const planted = 1 - Math.min(1, Math.max(0, samples[i].ankleY - ankleHeight - samples[i].groundY) / Math.max(ankleHeight, length * 0.05));
+            const planted = 1 - Math.min(1, Math.max(0, samplesScratch[i].ankleY - ankleHeight - samplesScratch[i].groundY) / Math.max(ankleHeight, length * 0.05));
             const tilt = scratch.q.setFromUnitVectors(UP, scratch.b.set(normal[0], normal[1], normal[2]).normalize());
             const current = leg.tip.getWorldQuaternion(scratch.q2);
             writeWorldQuaternion(leg.tip, current.slerp(tilt.multiply(current), planted * weight * rig.alignToGround));
@@ -251,6 +267,8 @@ export function applyFootIk(rig, originY, probe, state, delta, lookAtTarget) {
     }
     return placement.grounded;
 }
+/** Materials a foot probe may hit: blocking physical objects and terrain, never the model's own entity. */
+const IK_FILTER = { entities: false, objects: true, walls: false, terrain: true };
 /**
  * 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
@@ -262,6 +280,16 @@ export function useFootIk(scene, config, ctx, instanceId, groundOffset = 0) {
     const state = useRef({ weight: 0, pelvis: 0 });
     const lookAtConfig = config === undefined || config === "auto" ? undefined : config.lookAt;
     const target = useRef(null);
+    // One probe input and one look-at triple per mount: a rig that poses every frame allocates nothing.
+    const probe = useMemo(() => ({
+        origin: [0, 0, 0],
+        direction: [0, -1, 0],
+        maxDistance: 0,
+        excludeInstanceIds: instanceId === undefined ? [] : [instanceId],
+        filter: IK_FILTER,
+        accept: (hit) => hit.blocks && hit.purpose === "physical",
+    }), [instanceId]);
+    const lookAtPoint = useMemo(() => [0, 0, 0], []);
     useLayoutEffect(() => {
         state.current = { weight: 0, pelvis: 0 };
         target.current = null;
@@ -277,15 +305,26 @@ export function useFootIk(scene, config, ctx, instanceId, groundOffset = 0) {
             return;
         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, aim === null ? camera.getWorldPosition(scratch.b).toArray() : [aim.x, aim.y, aim.z]);
+        if (aim === null) {
+            const world = camera.getWorldPosition(scratch.b);
+            lookAtPoint[0] = world.x;
+            lookAtPoint[1] = world.y;
+            lookAtPoint[2] = world.z;
+        }
+        else {
+            lookAtPoint[0] = aim.x;
+            lookAtPoint[1] = aim.y;
+            lookAtPoint[2] = aim.z;
+        }
+        applyFootIk(rig, originY, (input) => {
+            probe.origin[0] = input.origin[0];
+            probe.origin[1] = input.origin[1];
+            probe.origin[2] = input.origin[2];
+            probe.maxDistance = input.maxDistance;
+            return ctx.scene.raycast(probe);
+        }, state.current, delta, lookAtPoint);
     });
 }
 const DEFAULT_EYE_HEIGHT = 1.5;

package/dist/render/useModelAnimation.js

@@ -187,13 +187,17 @@ function applyGraphClips(actions, clips) {
     }
 }
 /** The clip with the largest weight in one graph output: the pose the rig is mostly showing. */
-function dominantPhase(clips) {
+function dominantPhase(clips, out) {
     let best;
     for (const entry of clips) {
         if (entry.weight > 0 && (best === undefined || entry.weight > best.weight))
             best = entry;
     }
-    return best === undefined ? undefined : { clip: best.clip, time: best.time };
+    if (best === undefined)
+        return undefined;
+    out.clip = best.clip;
+    out.time = best.time;
+    return out;
 }
 /**
  * Binds a graph's clips to a rig exactly as `useModelAnimation` does (masked layers get filtered
@@ -282,6 +286,8 @@ function buildGraphPlayback(scene, mixer, graph, clips, rng) {
         lastYaw: null,
         smoothedSpeed: 0,
         params: {},
+        step: { dx: 0, dz: 0, dyaw: 0, seconds: 0 },
+        phase: { clip: "", time: 0 },
     };
 }
 /**
@@ -465,10 +471,21 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
                         else {
                             const instantSpeed = Math.hypot(dx, dz) / playbackDelta;
                             playback.smoothedSpeed += (instantSpeed - playback.smoothedSpeed) * Math.min(1, playbackDelta * 12);
-                            step = { dx, dz, dyaw: playback.lastYaw === null ? 0 : shortestAngle(yaw - playback.lastYaw), seconds: playbackDelta };
+                            const sample = playback.step;
+                            sample.dx = dx;
+                            sample.dz = dz;
+                            sample.dyaw = playback.lastYaw === null ? 0 : shortestAngle(yaw - playback.lastYaw);
+                            sample.seconds = playbackDelta;
+                            step = sample;
                         }
                     }
-                    playback.lastPos = [x, entity.position[1], z];
+                    if (playback.lastPos === null)
+                        playback.lastPos = [x, entity.position[1], z];
+                    else {
+                        playback.lastPos[0] = x;
+                        playback.lastPos[1] = entity.position[1];
+                        playback.lastPos[2] = z;
+                    }
                     playback.lastYaw = yaw;
                     readModelAnimationParams(ctx, instanceId, playback.smoothedSpeed, params, step);
                 }
@@ -487,7 +504,7 @@ export function useModelAnimation(scene, clips, animationInput, instanceId) {
             mixerRef.current.update(0);
             if (instanceId !== undefined) {
                 noteCharacterPose(instanceId);
-                const phase = dominantPhase(out.clips);
+                const phase = dominantPhase(out.clips, playback.phase);
                 if (phase !== undefined)
                     noteAnimationPhase(instanceId, phase.clip, phase.time);
             }