@jgengine/shell 0.18.1 → 0.19.0

package/dist/render/displayColor.d.ts

@@ -0,0 +1,33 @@
+import { type Color, type ToneMapping } from "three";
+type Rgb = [number, number, number];
+/**
+ * three.js r182's tone-mapping curve for `mode`, applied to a linear scene color at `exposure`.
+ * Mirrors `tonemapping_pars_fragment`; `NoToneMapping` and custom curves pass through.
+ * @internal
+ */
+export declare function toneMapColor(color: readonly [number, number, number], mode: ToneMapping, exposure?: number): Rgb;
+/**
+ * The linear scene color that `mode` at `exposure` displays as `display` (linear sRGB, 0..1).
+ * Sky and fog colors are picked as on-screen swatches, but the output pass tone-maps them like
+ * lit surfaces, which turns a pale horizon grey. Solved by fixed-point iteration because AgX and
+ * ACES mix channels; a swatch a curve cannot reach (pure white, a saturated highlight under AgX)
+ * lands on the closest color it can show.
+ * @internal
+ */
+export declare function sceneColorForDisplay(display: readonly [number, number, number], mode: ToneMapping, exposure?: number): Rgb;
+/**
+ * Writes the scene color that displays as `display` into `target`, recomputing only when the
+ * swatch or the renderer's tone mapping changes, so per-frame sky drivers stay allocation-free.
+ * @internal
+ */
+export declare class DisplayColorWriter {
+    private hex;
+    private mode;
+    private exposure;
+    private scene;
+    write(target: Color, display: Color, renderer: {
+        toneMapping: ToneMapping;
+        toneMappingExposure: number;
+    }): void;
+}
+export {};

package/dist/render/displayColor.js

@@ -0,0 +1,138 @@
+import { ACESFilmicToneMapping, AgXToneMapping, CineonToneMapping, LinearToneMapping, NeutralToneMapping, ReinhardToneMapping, } from "three";
+const saturate = (x) => Math.min(1, Math.max(0, x));
+/** GLSL `mat3(c0, c1, c2) * v` with the columns three's tonemapping chunk declares. */
+function mat3(c, v) {
+    return [
+        c[0][0] * v[0] + c[1][0] * v[1] + c[2][0] * v[2],
+        c[0][1] * v[0] + c[1][1] * v[1] + c[2][1] * v[2],
+        c[0][2] * v[0] + c[1][2] * v[1] + c[2][2] * v[2],
+    ];
+}
+const ACES_IN = [[0.59719, 0.076, 0.0284], [0.35458, 0.90834, 0.13383], [0.04823, 0.01566, 0.83777]];
+const ACES_OUT = [[1.60475, -0.10208, -0.00327], [-0.53108, 1.10813, -0.07276], [-0.07367, -0.00605, 1.07602]];
+const REC2020_TO_SRGB = [[1.6605, -0.1246, -0.0182], [-0.5876, 1.1329, -0.1006], [-0.0728, -0.0083, 1.1187]];
+const SRGB_TO_REC2020 = [[0.6274, 0.0691, 0.0164], [0.3293, 0.9195, 0.088], [0.0433, 0.0113, 0.8956]];
+const AGX_INSET = [
+    [0.856627153315983, 0.137318972929847, 0.11189821299995],
+    [0.0951212405381588, 0.761241990602591, 0.0767994186031903],
+    [0.0482516061458583, 0.101439036467562, 0.811302368396859],
+];
+const AGX_OUTSET = [
+    [1.1271005818144368, -0.1413297634984383, -0.14132976349843826],
+    [-0.11060664309660323, 1.157823702216272, -0.11060664309660294],
+    [-0.016493938717834573, -0.016493938717834257, 1.2519364065950405],
+];
+const AGX_MIN_EV = -12.47393;
+const AGX_MAX_EV = 4.026069;
+function aces(c) {
+    const v = mat3(ACES_IN, [c[0] / 0.6, c[1] / 0.6, c[2] / 0.6]);
+    const fit = v.map((x) => (x * (x + 0.0245786) - 0.000090537) / (x * (0.983729 * x + 0.432951) + 0.238081));
+    return mat3(ACES_OUT, fit).map(saturate);
+}
+function agx(c) {
+    const inset = mat3(AGX_INSET, mat3(SRGB_TO_REC2020, c));
+    const curved = inset.map((x) => {
+        const t = saturate((Math.log2(Math.max(x, 1e-10)) - AGX_MIN_EV) / (AGX_MAX_EV - AGX_MIN_EV));
+        const t2 = t * t;
+        const t4 = t2 * t2;
+        return 15.5 * t4 * t2 - 40.14 * t4 * t + 31.96 * t4 - 6.868 * t2 * t + 0.4298 * t2 + 0.1191 * t - 0.00232;
+    });
+    const out = mat3(AGX_OUTSET, curved).map((x) => Math.pow(Math.max(0, x), 2.2));
+    return mat3(REC2020_TO_SRGB, out).map(saturate);
+}
+function neutral(input) {
+    const x = Math.min(input[0], input[1], input[2]);
+    const offset = x < 0.08 ? x - 6.25 * x * x : 0.04;
+    const c = input.map((v) => v - offset);
+    const peak = Math.max(c[0], c[1], c[2]);
+    const start = 0.76;
+    if (peak < start)
+        return c;
+    const d = 1 - start;
+    const newPeak = 1 - (d * d) / (peak + d - start);
+    const g = 1 - 1 / (0.15 * (peak - newPeak) + 1);
+    return c.map((v) => v * (newPeak / peak) * (1 - g) + newPeak * g);
+}
+/**
+ * three.js r182's tone-mapping curve for `mode`, applied to a linear scene color at `exposure`.
+ * Mirrors `tonemapping_pars_fragment`; `NoToneMapping` and custom curves pass through.
+ * @internal
+ */
+export function toneMapColor(color, mode, exposure = 1) {
+    const c = [color[0] * exposure, color[1] * exposure, color[2] * exposure];
+    switch (mode) {
+        case LinearToneMapping:
+            return c.map(saturate);
+        case ReinhardToneMapping:
+            return c.map((x) => saturate(x / (1 + x)));
+        case CineonToneMapping:
+            return c.map((v) => {
+                const x = Math.max(0, v - 0.004);
+                return Math.pow((x * (6.2 * x + 0.5)) / (x * (6.2 * x + 1.7) + 0.06), 2.2);
+            });
+        case ACESFilmicToneMapping:
+            return aces(c);
+        case AgXToneMapping:
+            return agx(c);
+        case NeutralToneMapping:
+            return neutral(c);
+        default:
+            return c;
+    }
+}
+const CURVED = new Set([ReinhardToneMapping, CineonToneMapping, ACESFilmicToneMapping, AgXToneMapping, NeutralToneMapping]);
+/** Keeps a compensated sky inside half-float range; the brightest pastel under AgX needs ~13. */
+const MAX_SCENE_VALUE = 32;
+/**
+ * The linear scene color that `mode` at `exposure` displays as `display` (linear sRGB, 0..1).
+ * Sky and fog colors are picked as on-screen swatches, but the output pass tone-maps them like
+ * lit surfaces, which turns a pale horizon grey. Solved by fixed-point iteration because AgX and
+ * ACES mix channels; a swatch a curve cannot reach (pure white, a saturated highlight under AgX)
+ * lands on the closest color it can show.
+ * @internal
+ */
+export function sceneColorForDisplay(display, mode, exposure = 1) {
+    const target = [saturate(display[0]), saturate(display[1]), saturate(display[2])];
+    if (mode === LinearToneMapping)
+        return target.map((v) => v / Math.max(exposure, 1e-6));
+    if (!CURVED.has(mode))
+        return target;
+    const scene = [...target];
+    let best = [...target];
+    let bestError = Number.POSITIVE_INFINITY;
+    for (let iteration = 0; iteration < 48; iteration += 1) {
+        const shown = toneMapColor(scene, mode, exposure);
+        const error = Math.abs(shown[0] - target[0]) + Math.abs(shown[1] - target[1]) + Math.abs(shown[2] - target[2]);
+        if (error < bestError) {
+            bestError = error;
+            best = [scene[0], scene[1], scene[2]];
+        }
+        for (let channel = 0; channel < 3; channel += 1) {
+            // Clamped so a channel a curve's toe or shoulder cannot reach does not blow up its neighbors.
+            const ratio = Math.min(2, Math.max(0.5, Math.max(target[channel], 1e-5) / Math.max(shown[channel], 1e-5)));
+            scene[channel] = Math.min(MAX_SCENE_VALUE, Math.max(1e-5, scene[channel] * Math.pow(ratio, 0.8)));
+        }
+    }
+    return best;
+}
+/**
+ * Writes the scene color that displays as `display` into `target`, recomputing only when the
+ * swatch or the renderer's tone mapping changes, so per-frame sky drivers stay allocation-free.
+ * @internal
+ */
+export class DisplayColorWriter {
+    hex = -1;
+    mode = -1;
+    exposure = Number.NaN;
+    scene = [0, 0, 0];
+    write(target, display, renderer) {
+        const hex = display.getHex();
+        if (hex !== this.hex || renderer.toneMapping !== this.mode || renderer.toneMappingExposure !== this.exposure) {
+            this.hex = hex;
+            this.mode = renderer.toneMapping;
+            this.exposure = renderer.toneMappingExposure;
+            this.scene = sceneColorForDisplay([display.r, display.g, display.b], this.mode, this.exposure);
+        }
+        target.setRGB(this.scene[0], this.scene[1], this.scene[2]);
+    }
+}

package/dist/render/modelLoad.d.ts

@@ -61,6 +61,35 @@ export declare function modelLoadFallbacks(): readonly {
 }[];
 /** Drops the recorded placeholder list. For tests and between capture runs. @internal */
 export declare function clearModelLoadFallbacks(): void;
+/** Per-model triangle ceiling before the loader warns. A prop is a few thousand triangles; a hero rig tens of thousands. */
+export declare const DEFAULT_MODEL_TRIANGLE_BUDGET = 100000;
+/** Retune the per-model triangle budget (a cinematic game may raise it; a mobile target lowers it). Non-finite or non-positive values restore the default. */
+export declare function setModelTriangleBudget(triangles: number): void;
+/** Triangles a loaded model contributes per draw, summing every mesh (instanced meshes count once per instance). @internal */
+export declare function countSceneTriangles(root: THREE.Object3D): number;
+/** One over-budget model as {@link heavyModels} reports it: the URL the loader fetched, its triangle count, and the budget it exceeded. */
+export interface HeavyModelRecord {
+    url: string;
+    triangles: number;
+    budget: number;
+}
+/**
+ * Record a loaded model's triangle count against the budget: over budget warns once per URL and lands in
+ * {@link heavyModels}; under budget is silent. Split out so the wiring is unit-testable without a GL context.
+ * @internal
+ */
+export declare function recordModelTriangles(url: string, triangles: number, overrides?: {
+    warn?: (record: HeavyModelRecord) => void;
+}): void;
+/**
+ * Every model the shared loader resolved whose triangle count exceeds the budget, in load order. A heavy
+ * prop is invisible in a screenshot and only shows up as a slow frame, so the loader measures each GLB as it
+ * lands and this exposes the verdict for `debug_snapshot` probes and smoke tests to assert against.
+ * @capability heavy-models models over the per-model triangle budget, for perf probes and smoke assertions
+ */
+export declare function heavyModels(): readonly HeavyModelRecord[];
+/** Drops the heavy-model list and the once-per-URL warning memory. For tests and between capture runs. @internal */
+export declare function clearHeavyModels(): void;
 /**
  * A {@link GLTFLoader} whose success path is unchanged but whose failures degrade
  * gracefully: when a load errors, it probes the URL and — for a diagnosed broken

package/dist/render/modelLoad.js

@@ -140,6 +140,63 @@ export function modelLoadFallbacks() {
 export function clearModelLoadFallbacks() {
     servedFallbacks.length = 0;
 }
+/** Per-model triangle ceiling before the loader warns. A prop is a few thousand triangles; a hero rig tens of thousands. */
+export const DEFAULT_MODEL_TRIANGLE_BUDGET = 100_000;
+let modelTriangleBudget = DEFAULT_MODEL_TRIANGLE_BUDGET;
+/** Retune the per-model triangle budget (a cinematic game may raise it; a mobile target lowers it). Non-finite or non-positive values restore the default. */
+export function setModelTriangleBudget(triangles) {
+    modelTriangleBudget = Number.isFinite(triangles) && triangles > 0 ? triangles : DEFAULT_MODEL_TRIANGLE_BUDGET;
+}
+/** Triangles a loaded model contributes per draw, summing every mesh (instanced meshes count once per instance). @internal */
+export function countSceneTriangles(root) {
+    let total = 0;
+    root.traverse((node) => {
+        const mesh = node;
+        if (mesh.isMesh !== true || mesh.geometry === undefined)
+            return;
+        const geometry = mesh.geometry;
+        const vertices = geometry.index !== null ? geometry.index.count : geometry.attributes.position?.count ?? 0;
+        const instances = mesh.isInstancedMesh === true && typeof mesh.count === "number" ? mesh.count : 1;
+        total += Math.floor(vertices / 3) * instances;
+    });
+    return total;
+}
+const heavyModelRecords = [];
+const warnedHeavyUrls = new Set();
+function warnHeavyModel(record) {
+    if (typeof console === "undefined")
+        return;
+    console.warn(`[jgengine] model ${record.url} has ${record.triangles.toLocaleString()} triangles (budget ${record.budget.toLocaleString()}). A game prop should be a few thousand — pick a lighter asset or decimate it.`);
+}
+/**
+ * Record a loaded model's triangle count against the budget: over budget warns once per URL and lands in
+ * {@link heavyModels}; under budget is silent. Split out so the wiring is unit-testable without a GL context.
+ * @internal
+ */
+export function recordModelTriangles(url, triangles, overrides = {}) {
+    if (triangles <= modelTriangleBudget)
+        return;
+    const record = { url, triangles, budget: modelTriangleBudget };
+    heavyModelRecords.push(record);
+    if (warnedHeavyUrls.has(url))
+        return;
+    warnedHeavyUrls.add(url);
+    (overrides.warn ?? warnHeavyModel)(record);
+}
+/**
+ * Every model the shared loader resolved whose triangle count exceeds the budget, in load order. A heavy
+ * prop is invisible in a screenshot and only shows up as a slow frame, so the loader measures each GLB as it
+ * lands and this exposes the verdict for `debug_snapshot` probes and smoke tests to assert against.
+ * @capability heavy-models models over the per-model triangle budget, for perf probes and smoke assertions
+ */
+export function heavyModels() {
+    return heavyModelRecords;
+}
+/** Drops the heavy-model list and the once-per-URL warning memory. For tests and between capture runs. @internal */
+export function clearHeavyModels() {
+    heavyModelRecords.length = 0;
+    warnedHeavyUrls.clear();
+}
 /**
  * A {@link GLTFLoader} whose success path is unchanged but whose failures degrade
  * gracefully: when a load errors, it probes the URL and — for a diagnosed broken
@@ -151,7 +208,10 @@ export function clearModelLoadFallbacks() {
  */
 export class DiagnosticGLTFLoader extends GLTFLoader {
     load(url, onLoad, onProgress, onError) {
-        super.load(url, onLoad, onProgress, (event) => {
+        super.load(url, (gltf) => {
+            recordModelTriangles(url, countSceneTriangles(gltf.scene));
+            onLoad(gltf);
+        }, onProgress, (event) => {
             if (onError === undefined)
                 return;
             // Probe the URL the loader actually fetched (base-resolved), not the raw input.

package/dist/render/resolveModel.js

@@ -1,3 +1,4 @@
+import { warnOnce } from "@jgengine/core/devtools/warnOnce";
 /**
  * The `ModelConfig` a resolved catalog ref renders as. Stamps `animation: "auto"` so any rigged
  * catalog asset animates by default — the shell derives idle/walk/run states and one-shots from
@@ -74,6 +75,9 @@ export function resolveEntityModel(value, assets, key) {
  * @internal
  */
 export function pickModel(assets, pick) {
+    if (pick.fallbackModel !== undefined && !assets.has(pick.fallbackModel)) {
+        warnOnce(`pickModel:fallback:${pick.fallbackModel}`, `[jgengine] fallbackModel "${pick.fallbackModel}" is not in the asset catalog, so it can never stand in for "${pick.model ?? "(none)"}" — fix the id or declare its pack in the catalog sources.`);
+    }
     for (const id of [pick.model, pick.fallbackModel]) {
         if (id === undefined)
             continue;

package/dist/render/useFootIk.d.ts

@@ -1,9 +1,58 @@
 import * as THREE from "three";
 import type { GameContext } from "@jgengine/core/runtime/gameContextTypes";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
+import type { SceneRaycastHit, SceneRaycastInput } from "@jgengine/core/scene/sceneRaycast";
 type FootIkConfig = NonNullable<ModelConfig["ik"]>;
-/** Applies one frame of foot IK to a loaded rig. Exported for renderer tests and custom model hosts. */
-export declare function applyFootIk(scene: THREE.Object3D, config: FootIkConfig, raycast: GameContext["scene"]["raycast"], weight: number, cameraTarget?: readonly [number, number, number]): boolean;
-/** Runs foot IK after the model animation mixer, fading the correction out while the entity is airborne. */
-export declare function useFootIk(scene: THREE.Object3D, config: FootIkConfig | undefined, ctx: GameContext | null, instanceId?: string): void;
+type GroundProbe = (input: SceneRaycastInput) => SceneRaycastHit | null;
+interface IkLeg {
+    root: THREE.Object3D;
+    mid: THREE.Object3D;
+    tip: THREE.Object3D;
+    /** Rest-pose ankle height above the sole divided by rest leg length, so it survives any scale. */
+    ankleRatio: number;
+}
+interface PoseRecord {
+    bone: THREE.Object3D;
+    animated: {
+        q: THREE.Quaternion;
+        p: THREE.Vector3;
+    };
+    written: {
+        q: THREE.Quaternion;
+        p: THREE.Vector3;
+    };
+}
+/** Bones resolved once per loaded scene for {@link applyFootIk}. */
+export interface FootIkRig {
+    legs: IkLeg[];
+    pelvis: THREE.Object3D | null;
+    head: THREE.Object3D | null;
+    maxAdjust: number;
+    alignToGround: number;
+    /** Pose before and after last frame's correction, so a bone no clip animates never accumulates it. */
+    poses: PoseRecord[];
+}
+/** Per-model state carried between frames: the faded weight and the smoothed pelvis drop. */
+export interface FootIkState {
+    weight: number;
+    pelvis: number;
+}
+/**
+ * Resolves foot-IK bones on a loaded rig: explicit chains, or legs found by bone name for `"auto"`
+ * and configs without `feet`. Returns `null` when no leg resolves.
+ */
+export declare function resolveFootIkRig(scene: THREE.Object3D, config: FootIkConfig): FootIkRig | null;
+/**
+ * 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.
+ */
+export declare function applyFootIk(rig: FootIkRig, originY: number, probe: GroundProbe, state: FootIkState, delta: number, cameraTarget?: 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
+ * its soles rest on (`ModelConfig.y`).
+ */
+export declare function useFootIk(scene: THREE.Object3D, config: FootIkConfig | undefined, ctx: GameContext | null, instanceId?: string, groundOffset?: number): void;
 export {};

package/dist/render/useFootIk.js

@@ -1,89 +1,216 @@
 import { useFrame, useThree } from "@react-three/fiber";
-import { useRef } from "react";
+import { useMemo, useRef } from "react";
 import * as THREE from "three";
+import { inferLegChains, placeFeet } from "@jgengine/core/anim/footPlacement";
 import { lookAt, solveTwoBone } from "@jgengine/core/anim/ikSolver";
-function tuple(value) {
-    return [value.x, value.y, value.z];
+const DEFAULT_MAX_ADJUST = 0.4;
+const UP = new THREE.Vector3(0, 1, 0);
+const scratch = {
+    root: new THREE.Vector3(),
+    mid: new THREE.Vector3(),
+    tip: new THREE.Vector3(),
+    a: new THREE.Vector3(),
+    b: new THREE.Vector3(),
+    q: new THREE.Quaternion(),
+    q2: new THREE.Quaternion(),
+    parent: new THREE.Quaternion(),
+    m: new THREE.Matrix4(),
+};
+const solved = { mid: [0, 0, 0], tip: [0, 0, 0] };
+function bindPosition(skeleton, bone, out) {
+    const index = skeleton.bones.indexOf(bone);
+    if (index < 0)
+        return null;
+    return out.setFromMatrixPosition(scratch.m.copy(skeleton.boneInverses[index]).invert());
 }
-function worldQuaternion(bone) {
-    const result = new THREE.Quaternion();
-    bone.getWorldQuaternion(result);
-    return result;
+function restAnkleRatio(scene, leg) {
+    let soleY = Infinity;
+    let ratio = 0;
+    const root = new THREE.Vector3();
+    const mid = new THREE.Vector3();
+    const tip = new THREE.Vector3();
+    scene.traverse((object) => {
+        const mesh = object;
+        if (mesh.isSkinnedMesh !== true || !(leg.tip instanceof THREE.Bone) || !(leg.mid instanceof THREE.Bone) || !(leg.root instanceof THREE.Bone))
+            return;
+        if (bindPosition(mesh.skeleton, leg.tip, tip) === null || bindPosition(mesh.skeleton, leg.mid, mid) === null || bindPosition(mesh.skeleton, leg.root, root) === null)
+            return;
+        if (mesh.geometry.boundingBox === null)
+            mesh.geometry.computeBoundingBox();
+        const box = mesh.geometry.boundingBox.clone().applyMatrix4(mesh.bindMatrix);
+        soleY = Math.min(soleY, box.min.y);
+        const length = root.distanceTo(mid) + mid.distanceTo(tip);
+        if (length > 1e-6)
+            ratio = Math.max(0, tip.y - soleY) / length;
+    });
+    return ratio;
+}
+/**
+ * Resolves foot-IK bones on a loaded rig: explicit chains, or legs found by bone name for `"auto"`
+ * and configs without `feet`. Returns `null` when no leg resolves.
+ */
+export function resolveFootIkRig(scene, config) {
+    const options = config === "auto" ? {} : config;
+    let chains = options.feet;
+    if (chains === undefined) {
+        const bones = [];
+        scene.traverse((object) => {
+            if (object.isBone === true)
+                bones.push({ name: object.name, parent: object.parent?.isBone === true ? object.parent.name : null });
+        });
+        chains = inferLegChains(bones);
+    }
+    const legs = [];
+    for (const chain of chains) {
+        const root = scene.getObjectByName(chain.root);
+        const mid = scene.getObjectByName(chain.mid);
+        const tip = scene.getObjectByName(chain.tip);
+        if (root === undefined || mid === undefined || tip === undefined)
+            continue;
+        legs.push({ root, mid, tip, ankleRatio: restAnkleRatio(scene, { root, mid, tip }) });
+    }
+    const head = options.lookAt === undefined ? null : (scene.getObjectByName(options.lookAt.bone) ?? null);
+    if (legs.length === 0 && head === null)
+        return null;
+    const found = options.pelvis !== undefined ? (scene.getObjectByName(options.pelvis) ?? null) : (legs[0]?.root.parent ?? null);
+    const pelvis = found === scene ? null : found;
+    const bones = new Set(legs.flatMap((leg) => [leg.root, leg.mid, leg.tip]));
+    if (pelvis !== null)
+        bones.add(pelvis);
+    if (head !== null)
+        bones.add(head);
+    return {
+        legs,
+        pelvis,
+        head,
+        maxAdjust: options.maxAdjust ?? DEFAULT_MAX_ADJUST,
+        alignToGround: Math.max(0, Math.min(1, options.alignToGround ?? 1)),
+        poses: [...bones].map((bone) => ({
+            bone,
+            animated: { q: bone.quaternion.clone(), p: bone.position.clone() },
+            written: { q: bone.quaternion.clone(), p: bone.position.clone() },
+        })),
+    };
 }
 function writeWorldQuaternion(bone, world) {
     if (bone.parent === null)
         bone.quaternion.copy(world);
-    else {
-        const parent = worldQuaternion(bone.parent).invert();
-        bone.quaternion.copy(parent.multiply(world));
-    }
+    else
+        bone.quaternion.copy(bone.parent.getWorldQuaternion(scratch.parent).invert().multiply(world));
     bone.updateMatrixWorld(true);
 }
-function aimSegment(bone, from, currentTo, solvedTo, weight) {
-    const current = currentTo.clone().sub(from).normalize();
-    const solved = new THREE.Vector3(solvedTo[0] - from.x, solvedTo[1] - from.y, solvedTo[2] - from.z).normalize();
-    if (current.lengthSq() < 1e-8 || solved.lengthSq() < 1e-8)
+function aimSegment(bone, from, currentTo, solvedTo) {
+    const current = scratch.a.copy(currentTo).sub(from);
+    const desired = scratch.b.set(solvedTo[0] - from.x, solvedTo[1] - from.y, solvedTo[2] - from.z);
+    if (current.lengthSq() < 1e-10 || desired.lengthSq() < 1e-10)
         return;
-    const correction = new THREE.Quaternion().setFromUnitVectors(current, solved);
-    const currentWorld = worldQuaternion(bone);
-    const desiredWorld = correction.multiply(currentWorld);
-    currentWorld.slerp(desiredWorld, weight);
-    writeWorldQuaternion(bone, currentWorld);
+    const correction = scratch.q.setFromUnitVectors(current.normalize(), desired.normalize());
+    writeWorldQuaternion(bone, correction.multiply(bone.getWorldQuaternion(scratch.q2)));
 }
-/** Applies one frame of foot IK to a loaded rig. Exported for renderer tests and custom model hosts. */
-export function applyFootIk(scene, config, raycast, weight, cameraTarget) {
-    let grounded = false;
-    scene.updateMatrixWorld(true);
-    for (const foot of config.feet) {
-        const root = scene.getObjectByName(foot.root);
-        const mid = scene.getObjectByName(foot.mid);
-        const tip = scene.getObjectByName(foot.tip);
-        if (root === undefined || mid === undefined || tip === undefined)
-            continue;
-        const rootPosition = root.getWorldPosition(new THREE.Vector3());
-        const midPosition = mid.getWorldPosition(new THREE.Vector3());
-        const tipPosition = tip.getWorldPosition(new THREE.Vector3());
-        const hit = raycast({
-            origin: [tipPosition.x, tipPosition.y + 0.75, tipPosition.z],
-            direction: [0, -1, 0],
-            maxDistance: 2,
-            filter: { entities: false, objects: false, walls: false, terrain: true },
-        });
-        if (hit === null)
-            continue;
-        grounded = true;
-        const target = new THREE.Vector3(hit.point[0], hit.point[1], hit.point[2]);
-        const output = { mid: [0, 0, 0], tip: [0, 0, 0] };
-        solveTwoBone({ root: tuple(rootPosition), mid: tuple(midPosition), tip: tuple(tipPosition), target: tuple(target), pole: [rootPosition.x, rootPosition.y, rootPosition.z + 1] }, output);
-        aimSegment(root, rootPosition, midPosition, output.mid, weight);
-        root.updateMatrixWorld(true);
-        const solvedMid = mid.getWorldPosition(new THREE.Vector3());
-        // Rotating the root also moves the tip; aim the shin from that updated pose.
-        const currentTip = tip.getWorldPosition(new THREE.Vector3());
-        aimSegment(mid, solvedMid, currentTip, output.tip, weight);
+function legLength(leg) {
+    leg.root.getWorldPosition(scratch.root);
+    leg.mid.getWorldPosition(scratch.mid);
+    leg.tip.getWorldPosition(scratch.tip);
+    return scratch.root.distanceTo(scratch.mid) + scratch.mid.distanceTo(scratch.tip);
+}
+/**
+ * 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.
+ */
+export function applyFootIk(rig, originY, probe, state, delta, cameraTarget) {
+    for (const record of rig.poses) {
+        if (record.bone.quaternion.equals(record.written.q))
+            record.bone.quaternion.copy(record.animated.q);
+        if (record.bone.position.equals(record.written.p))
+            record.bone.position.copy(record.animated.p);
+        record.animated.q.copy(record.bone.quaternion);
+        record.animated.p.copy(record.bone.position);
     }
-    if (config.lookAt !== undefined && cameraTarget !== undefined) {
-        const bone = scene.getObjectByName(config.lookAt.bone);
-        if (bone !== undefined) {
-            const from = bone.getWorldPosition(new THREE.Vector3());
-            const q = lookAt({ from: tuple(from), target: cameraTarget, up: [0, 1, 0] });
-            const desired = new THREE.Quaternion(q[0], q[1], q[2], q[3]);
-            const current = worldQuaternion(bone);
-            current.slerp(desired, weight);
-            writeWorldQuaternion(bone, current);
+    const samples = [];
+    const normals = [];
+    let length = 0;
+    let ankleHeight = 0;
+    for (const leg of rig.legs) {
+        leg.root.updateWorldMatrix(true, true);
+        const legSize = legLength(leg);
+        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);
+    }
+    const placement = placeFeet({ feet: samples, 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);
+    const weight = state.weight;
+    if (rig.pelvis !== null && weight > 1e-3 && Math.abs(state.pelvis) > 1e-6) {
+        const world = rig.pelvis.getWorldPosition(scratch.a);
+        world.y += state.pelvis * weight;
+        rig.pelvis.position.copy(rig.pelvis.parent === null ? world : rig.pelvis.parent.worldToLocal(world));
+        rig.pelvis.updateMatrixWorld(true);
+    }
+    for (let i = 0; i < rig.legs.length && weight > 1e-3; i += 1) {
+        const target = placement.ankleTargets[i];
+        if (target === null || target === undefined)
+            continue;
+        const leg = rig.legs[i];
+        const root = leg.root.getWorldPosition(scratch.root);
+        const mid = leg.mid.getWorldPosition(scratch.mid);
+        const tip = leg.tip.getWorldPosition(scratch.tip);
+        const bend = scratch.a.copy(root).add(tip).multiplyScalar(0.5);
+        bend.subVectors(mid, bend);
+        if (bend.lengthSq() < 1e-8)
+            bend.set(0, 0, 1).applyQuaternion(leg.root.parent?.getWorldQuaternion(scratch.q) ?? scratch.q.identity());
+        const pole = bend.normalize().multiplyScalar(length).add(mid);
+        const targetY = tip.y + (target - tip.y) * weight;
+        solveTwoBone({ root: [root.x, root.y, root.z], mid: [mid.x, mid.y, mid.z], tip: [tip.x, tip.y, tip.z], target: [tip.x, targetY, tip.z], pole: [pole.x, pole.y, pole.z] }, solved);
+        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];
+        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 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));
         }
     }
-    return grounded;
+    if (rig.head !== null && cameraTarget !== 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 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)));
+    }
+    for (const record of rig.poses) {
+        record.written.q.copy(record.bone.quaternion);
+        record.written.p.copy(record.bone.position);
+    }
+    return placement.grounded;
 }
-/** Runs foot IK after the model animation mixer, fading the correction out while the entity is airborne. */
-export function useFootIk(scene, config, ctx, instanceId) {
-    const camera = useThree((state) => state.camera);
-    const weight = useRef(0);
-    useFrame((_state, delta) => {
-        if (config === undefined || ctx === null || instanceId === undefined)
+/**
+ * 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
+ * its soles rest on (`ModelConfig.y`).
+ */
+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 });
+    useFrame((_three, delta) => {
+        if (rig === null || ctx === null || instanceId === undefined)
             return;
-        const grounded = applyFootIk(scene, config, (input) => ctx.scene.raycast({ ...input, excludeInstanceIds: [instanceId] }), weight.current, tuple(camera.getWorldPosition(new THREE.Vector3())));
-        const target = grounded ? 1 : 0;
-        weight.current += (target - weight.current) * Math.min(1, delta * (grounded ? 12 : 5));
+        const parent = scene.parent;
+        const originY = parent === null ? scene.position.y : parent.localToWorld(scratch.a.set(0, groundOffset, 0)).y;
+        const exclude = [instanceId];
+        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());
     });
 }