@aura3d/assets 2.0.4 → 3.0.1

package/dist/GLTFAnimationRuntime.js

@@ -1,5 +1,5 @@
-import { AnimationAction, AnimationClip, AnimationMixer, normalizeQuat, slerpQuat, solveTwoBoneIk } from "@aura3d/animation";
-import { invertMat4, MAX_RENDERABLE_SKINNING_JOINTS, multiplyMat4, Renderable, Scene, transformPoint } from "@aura3d/scene";
+import { AnimationAction, AnimationClip, AnimationMixer, consumeRootMotion, extractRootMotion, createFootIkRig, normalizeQuat, slerpQuat, solveTwoBoneIk } from "@aura3d/animation";
+import { composeMat4, decomposeMat4, invertMat4, MAX_RENDERABLE_SKINNING_JOINTS, multiplyMat4, Renderable, Scene, transformPoint } from "@aura3d/scene";
 /**
  * Synonym groups for fuzzy clip-name matching. Real catalog assets label the same
  * motion wildly differently ("Loops" vs "Idle", "Take 001" vs "Run", "sprint" vs
@@ -259,6 +259,12 @@ export class GLTFSceneAnimationRuntime {
     nodesByName = new Map();
     morphRenderablesByNodeName = new Map();
     skinningBindings = [];
+    footBindMatrices = new Map();
+    footOrientationLocks = new Map();
+    footDescendantLocks = new Map();
+    footSurfaceVertices = new Map();
+    footPlanting;
+    footRig;
     lastApply;
     constructor(options) {
         this.options = options;
@@ -266,6 +272,80 @@ export class GLTFSceneAnimationRuntime {
             this.clipsByName.set(clip.name, clip);
         }
         this.reindexScene();
+        if (options.footPlanting)
+            this.setFootPlanting(options.footPlanting);
+    }
+    /**
+     * Enable, replace, or clear (undefined) the foot-planting post-pass. Replacing the leg
+     * set, ground, or solve parameters resets foot-lock state so a stale lock can never drag
+     * a foot after retargeting. A matrix-only refresh (same shape, new `worldFromLocal`)
+     * keeps locks: the engine re-sends the model matrix every frame because time-animated
+     * model nodes move, and world-space locks stay valid across that refresh.
+     */
+    setFootPlanting(config) {
+        if (config !== undefined && config.legs.length === 0) {
+            throw new Error("glTF foot planting requires at least one leg.");
+        }
+        if (!sameFootPlantingShape(this.footPlanting, config)) {
+            this.footRig = undefined;
+            this.footOrientationLocks.clear();
+            this.footDescendantLocks.clear();
+        }
+        this.footPlanting = config;
+    }
+    /**
+     * Extract real authored displacement over unwrapped clip time, hand it to the physical
+     * authority once, then apply an in-place root pose and solve feet in the updated actor
+     * transform. Rejected movement is returned and discarded rather than accumulating drift.
+     * The caller refreshes footPlanting.worldFromLocal inside move after committing movement.
+     */
+    applyRootMotionClip(name, options) {
+        return this.applyRootMotionClips([{ clipName: name, ...options }], options);
+    }
+    /** Blend displacement and consumed poses with the same base/additive weights. */
+    applyRootMotionClips(samples, options) {
+        if (samples.length === 0)
+            throw new Error("glTF root motion blend requires at least one clip sample.");
+        const accumulators = new Map();
+        const motionAccumulators = new Map();
+        const unsupportedTracks = [];
+        const names = [];
+        let maxTime = 0;
+        // Finish validation and sampling before the physical authority can mutate the actor.
+        for (const sample of samples) {
+            const clip = this.clipsByName.get(sample.clipName);
+            if (!clip)
+                throw new Error(`glTF animation clip "${sample.clipName}" was not found.`);
+            const weight = sample.weight ?? 1;
+            if (!Number.isFinite(weight) || weight < 0)
+                throw new Error("glTF root motion blend weight must be finite and non-negative.");
+            const extracted = extractRootMotion(clip, sample);
+            if (weight === 0)
+                continue;
+            const time = sample.loop && clip.duration > 0
+                ? ((sample.toTime % clip.duration) + clip.duration) % clip.duration
+                : Math.max(0, Math.min(clip.duration, sample.toTime));
+            maxTime = Math.max(maxTime, time);
+            names.push(`${clip.name}@${time}x${weight}${sample.additive ? "+add" : ""}`);
+            blendInto(motionAccumulators, "motion", "vector3", extracted.delta, weight, sample.additive === true);
+            for (const track of clip.tracks) {
+                if (!parseAnimationTarget(track.target)) {
+                    unsupportedTracks.push(track.target);
+                    continue;
+                }
+                // Consume each clip's own root before blending, including additive root tracks.
+                const value = track.sample(track.target === sample.target ? 0 : time);
+                blendInto(accumulators, track.target, track.valueType, value, weight, sample.additive === true);
+            }
+        }
+        const values = new Map();
+        for (const [target, accumulator] of accumulators)
+            values.set(target, finalizeTargetBlend(accumulator));
+        const motionAccumulator = motionAccumulators.get("motion");
+        const delta = motionAccumulator ? finalizeTargetBlend(motionAccumulator) : [0, 0, 0];
+        const motion = consumeRootMotion({ target: "blend", fromTime: 0, toTime: maxTime, looped: samples.some(sample => sample.loop), delta }, options.worldFromLocal, options.move);
+        this.lastApply = this.applySampledTargets(`root-motion:${names.join(",")}`, maxTime, { sampledTargets: values, unsupportedTracks }, samples.length);
+        return { motion, applyResult: this.lastApply };
     }
     applyClipByName(name, time) {
         const clip = this.clipsByName.get(name);
@@ -337,7 +417,8 @@ export class GLTFSceneAnimationRuntime {
                     unsupportedTracks.push(track.target);
                     continue;
                 }
-                if (!clipMaskAllowsNode(sample.mask, target.nodeName))
+                // Bone masks filter node tracks only; material/light property tracks always apply.
+                if (target.kind === "node" && !clipMaskAllowsNode(sample.mask, target.nodeName))
                     continue;
                 blendInto(accumulators, track.target, track.valueType, track.sample(wrappedTime), weight, sample.additive === true);
             }
@@ -504,10 +585,16 @@ export class GLTFSceneAnimationRuntime {
         return [...this.clipsByName.values()].map((clip) => this.inspectClipBinding(clip));
     }
     reindexScene() {
+        this.options.scene.updateWorldTransforms();
+        this.footBindMatrices.clear();
+        this.footOrientationLocks.clear();
+        this.footDescendantLocks.clear();
         this.nodesByName.clear();
         this.morphRenderablesByNodeName.clear();
         this.skinningBindings.length = 0;
+        this.footSurfaceVertices.clear();
         this.options.scene.traverse((node) => {
+            this.footBindMatrices.set(node.id, { world: [...node.transform.worldMatrix], local: [...node.transform.localMatrix] });
             const nodes = this.nodesByName.get(node.name) ?? [];
             nodes.push(node);
             this.nodesByName.set(node.name, nodes);
@@ -530,9 +617,326 @@ export class GLTFSceneAnimationRuntime {
                 const skin = mesh?.skinIndex === undefined ? undefined : this.options.asset.skins[mesh.skinIndex];
                 if (!mesh || !skin || skin.joints.length > MAX_RENDERABLE_SKINNING_JOINTS)
                     continue;
-                this.skinningBindings.push({ node, renderable, mesh, skin });
+                this.skinningBindings.push({ node, renderable, mesh, skin, bindWorldMatrix: [...node.transform.worldMatrix] });
+            }
+        }
+    }
+    findSceneLight(name) {
+        return this.options.scene.collectLights().find((light) => light.name === name);
+    }
+    /**
+     * Foot-planting post-pass (E2): solves the configured leg chains against the ground,
+     * applies a shared pelvis reach correction, and rotates rigid hip/knee chains toward the
+     * solved targets. Missing leg nodes are reported in
+     * `missingLegNodes` and skipped, never faked. Returns undefined when unconfigured.
+     */
+    applyFootPlanting() {
+        const config = this.footPlanting;
+        if (!config)
+            return undefined;
+        this.options.scene.updateWorldTransforms();
+        // Actor-local → world for the solve, world → actor-local for write-back. The rig and
+        // the ground both speak world space (meters); the skeleton may live in import units
+        // (centimeters). Points convert through the matrix pair; hipOffset rides along inside
+        // the converted hip target point so any affine (scale, rotation, centering) is exact.
+        const toWorld = config.worldFromLocal;
+        const toLocal = toWorld ? invertMat4(toWorld) : undefined;
+        const solvePoint = (point) => (toWorld ? transformPoint(toWorld, point) : point);
+        // Solved legs arrive as readonly tuples; copy into mutable points for the transform.
+        const actorPoint = (point) => {
+            const mutable = [point[0], point[1], point[2]];
+            return toLocal ? transformPoint(toLocal, mutable) : mutable;
+        };
+        const missingLegNodes = [];
+        const resolved = [];
+        for (const leg of config.legs) {
+            const hip = this.nodesByName.get(leg.hip)?.[0];
+            const knee = this.nodesByName.get(leg.knee)?.[0];
+            const ankle = this.nodesByName.get(leg.ankle)?.[0];
+            if (!hip)
+                missingLegNodes.push(`${leg.side}:hip:${leg.hip}`);
+            if (!knee)
+                missingLegNodes.push(`${leg.side}:knee:${leg.knee}`);
+            if (!ankle)
+                missingLegNodes.push(`${leg.side}:ankle:${leg.ankle}`);
+            if (!hip || !knee || !ankle)
+                continue;
+            resolved.push({ side: leg.side, hip, knee, ankle, pole: leg.pole, ...(leg.contact === undefined ? {} : { contact: leg.contact }), ...(leg.support ? { support: leg.support } : {}) });
+        }
+        if (resolved.length === 0) {
+            return { groundedFeet: 0, averageTargetError: 0, lockedSides: [], missingLegNodes, hipOffset: 0 };
+        }
+        // Measure each animated ankle-to-sole offset from the exact pre-solve skinning
+        // palette. One global value cannot plant asymmetric shoes or a rotated touchdown.
+        this.refreshSkinningPalettes();
+        const rawSoles = this.sampleFootSurfaces();
+        const measuredAnkleHeights = new Map(resolved.map(entry => {
+            const ankle = solvePoint(worldPosition(entry.ankle));
+            const minimum = Math.min(Infinity, ...rawSoles.filter(point => point.side === entry.side).map(point => point.worldPosition[1]));
+            return [entry.side, Number.isFinite(minimum) ? Math.max(0, ankle[1] - minimum) : undefined];
+        }));
+        if (!this.footRig) {
+            this.footRig = createFootIkRig({
+                legs: resolved.map((entry) => ({
+                    side: entry.side,
+                    hip: solvePoint(worldPosition(entry.hip)),
+                    knee: solvePoint(worldPosition(entry.knee)),
+                    ankle: solvePoint(worldPosition(entry.ankle)),
+                    ...(measuredAnkleHeights.get(entry.side) ?? config.ankleHeight) !== undefined ? { ankleHeight: measuredAnkleHeights.get(entry.side) ?? config.ankleHeight } : {},
+                    ...(entry.pole ? { pole: entry.pole } : {})
+                })),
+                raycaster: config.ground,
+                ...(config.ankleHeight !== undefined ? { ankleHeight: config.ankleHeight } : {}),
+                ...(config.rayStartHeight !== undefined ? { rayStartHeight: config.rayStartHeight } : {}),
+                ...(config.maxRayDistance !== undefined ? { maxRayDistance: config.maxRayDistance } : {}),
+                ...(config.plantThreshold !== undefined ? { plantThreshold: config.plantThreshold } : {}),
+                ...(config.hipDropFactor !== undefined ? { hipDropFactor: config.hipDropFactor } : {})
+            });
+        }
+        const distance = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+        const originalLengths = new Map(resolved.map(entry => [entry.side, {
+                upper: distance(solvePoint(worldPosition(entry.hip)), solvePoint(worldPosition(entry.knee))),
+                lower: distance(solvePoint(worldPosition(entry.knee)), solvePoint(worldPosition(entry.ankle)))
+            }]));
+        const solved = this.footRig.solveFootPlacement({
+            legs: resolved.map((entry) => ({
+                side: entry.side,
+                hip: solvePoint(worldPosition(entry.hip)),
+                knee: solvePoint(worldPosition(entry.knee)),
+                ankle: solvePoint(worldPosition(entry.ankle)),
+                ...(measuredAnkleHeights.get(entry.side) ?? config.ankleHeight) !== undefined ? { ankleHeight: measuredAnkleHeights.get(entry.side) ?? config.ankleHeight } : {},
+                ...(entry.pole ? { pole: entry.pole } : {}),
+                ...(entry.contact === undefined ? {} : { contact: entry.contact }),
+                ...(entry.support ? { support: entry.support } : {})
+            }))
+        });
+        // A reach correction belongs to the shared pelvis owner. Move it once before
+        // rotating either leg; translating each upper-leg root dislocates the chain,
+        // while omitting the drop leaves a fully extended stance foot above ground.
+        if (solved.hipOffset < 0) {
+            const common = commonAncestor(resolved.map(entry => entry.hip));
+            const anchors = common && common.parent ? [common] : [...new Set(resolved.map(entry => entry.hip))];
+            for (const anchor of anchors) {
+                const currentWorld = solvePoint(worldPosition(anchor));
+                const dropped = actorPoint([currentWorld[0], currentWorld[1] + solved.hipOffset, currentWorld[2]]);
+                setWorldPosition(anchor, dropped);
+            }
+            this.options.scene.updateWorldTransforms();
+        }
+        for (const foot of solved.feet) {
+            const entry = resolved.find((candidate) => candidate.side === foot.side);
+            if (!entry)
+                continue;
+            // Apply the two-bone solution with joint rotations. Moving hip/knee/ankle
+            // translations directly changes authored bone lengths and deforms every weighted
+            // mesh. The solver targets are world-space; orient each parent toward its solved
+            // child while preserving the animation's local translations and scales.
+            const kneeTarget = actorPoint(foot.knee);
+            orientJointToward(entry.hip, entry.knee, kneeTarget);
+            entry.hip.updateWorldTransform();
+            const ankleTarget = actorPoint(foot.ankle);
+            orientJointToward(entry.knee, entry.ankle, ankleTarget);
+            entry.knee.updateWorldTransform();
+        }
+        this.options.scene.updateWorldTransforms();
+        for (const foot of solved.feet) {
+            const entry = resolved.find(candidate => candidate.side === foot.side);
+            if (!foot.locked || config.lockFootRotation === false) {
+                this.footOrientationLocks.delete(foot.side);
+                this.footDescendantLocks.delete(foot.side);
+                continue;
+            }
+            let locked = this.footOrientationLocks.get(foot.side);
+            if (!locked) {
+                // Capture the actual animated sole orientation and toe pose at touchdown.
+                // Reusing the asset bind pose snaps arbitrary rigs and moves their sole vertices.
+                locked = toWorld ? multiplyMat4(toWorld, entry.ankle.transform.worldMatrix) : [...entry.ankle.transform.worldMatrix];
+                const descendants = new Map();
+                entry.ankle.children.forEach(child => child.traverse(node => descendants.set(node.id, [...node.transform.localMatrix])));
+                this.footDescendantLocks.set(foot.side, descendants);
+                const normal = foot.sample.groundNormal;
+                const norm = Math.hypot(...normal);
+                if (!(norm > 0))
+                    throw new Error("Foot contact requires a nonzero ground normal.");
+                const nx = normal[0] / norm, ny = normal[1] / norm, nz = normal[2] / norm;
+                if (ny <= -0.999)
+                    throw new Error("Foot contact cannot plant on a downward facing surface.");
+                const vx = nz, vz = -nx, t = 1 / (1 + ny);
+                const tilt = [1 - vz * vz * t, vz, vx * vz * t, 0, -vz, 1 - (vx * vx + vz * vz) * t, vx, 0, vx * vz * t, -vx, 1 - vx * vx * t, 0, 0, 0, 0, 1];
+                locked = multiplyMat4(tilt, locked);
+                this.footOrientationLocks.set(foot.side, locked);
+            }
+            // Keep the solved ankle position while holding the sole orientation in world space.
+            const ankleWorld = solvePoint(worldPosition(entry.ankle));
+            const desired = [...locked];
+            desired[12] = ankleWorld[0];
+            desired[13] = ankleWorld[1];
+            desired[14] = ankleWorld[2];
+            const actorMatrix = toLocal ? multiplyMat4(toLocal, desired) : desired;
+            const parent = entry.ankle.parent;
+            const local = parent ? multiplyMat4(invertMat4(parent.transform.worldMatrix), actorMatrix) : actorMatrix;
+            entry.ankle.transform.setFromLocalMatrix(local);
+            // Toe joints remain in their touchdown relationship during stance; animated
+            // toe curl otherwise moves the sole while the ankle still reports zero slip.
+            const touchdown = this.footDescendantLocks.get(foot.side);
+            const restore = (node) => {
+                const rest = touchdown?.get(node.id);
+                if (rest)
+                    node.transform.setFromLocalMatrix(rest);
+                node.children.forEach(restore);
+            };
+            entry.ankle.children.forEach(restore);
+            entry.ankle.updateWorldTransform();
+        }
+        this.options.scene.updateWorldTransforms();
+        return {
+            legDeformation: resolved.map(entry => {
+                const before = originalLengths.get(entry.side);
+                const upperAfter = distance(solvePoint(worldPosition(entry.hip)), solvePoint(worldPosition(entry.knee)));
+                const lowerAfter = distance(solvePoint(worldPosition(entry.knee)), solvePoint(worldPosition(entry.ankle)));
+                return { side: entry.side, upperBefore: before.upper, lowerBefore: before.lower, upperAfter, lowerAfter,
+                    maxRelativeLengthChange: Math.max(Math.abs(upperAfter - before.upper) / Math.max(1e-9, before.upper), Math.abs(lowerAfter - before.lower) / Math.max(1e-9, before.lower)) };
+            }),
+            feet: solved.feet.map(foot => {
+                const entry = resolved.find(candidate => candidate.side === foot.side);
+                const position = solvePoint(worldPosition(entry.ankle));
+                return { side: foot.side, worldPosition: position, locked: foot.locked,
+                    contactError: Math.hypot(...position.map((value, axis) => value - foot.sample.plantedFoot[axis])) };
+            }),
+            groundedFeet: solved.groundedFeet,
+            averageTargetError: solved.averageTargetError,
+            lockedSides: solved.feet.filter((foot) => foot.locked).map((foot) => foot.side),
+            missingLegNodes,
+            hipOffset: solved.hipOffset
+        };
+    }
+    /**
+     * Applies one sampled `material:<name>.<leaf-path>` value to the live material sink.
+     * Returns false (→ missing target, diagnosed) when no sink resolves, the leaf maps to no
+     * renderer uniform, or the value shape is wrong. Throws on a sampled value that is not
+     * finite, matching the node-path converters below.
+     */
+    applyMaterialTrackValue(materialName, leafPath, value, trackTarget) {
+        const parameters = materialParametersForLeaf(leafPath);
+        const sink = this.options.resolveAnimationMaterial?.(materialName);
+        if (parameters === undefined || sink === undefined)
+            return false;
+        const numeric = asMaterialLeafValue(value, trackTarget);
+        for (const parameter of parameters) {
+            sink.setAnimationParameter(parameter, numeric);
+        }
+        return true;
+    }
+    /**
+     * Applies one sampled `light:<name>.<leaf>` value to the live scene light of that name.
+     * The loader instantiates each node-referenced `KHR_lights_punctual` light as a scene light
+     * carrying its node's name; extension-defined lights no node references have no scene object,
+     * so a light track matching no scene light is reported missing (diagnosed, never silent).
+     */
+    applyLightTrackValue(lightName, leaf, value, trackTarget) {
+        if (lightLeafApplies(leaf) === false)
+            return false;
+        const light = this.findSceneLight(lightName);
+        if (!light)
+            return false;
+        if (leaf === "intensity") {
+            light.intensity = asScalar(value, trackTarget);
+            return true;
+        }
+        if (leaf === "color") {
+            light.color = asVec3(value, trackTarget);
+            return true;
+        }
+        const rangeHolder = light;
+        if (typeof rangeHolder.range !== "number")
+            return false;
+        light.range = asPositiveScalar(value, trackTarget);
+        return true;
+    }
+    /** CPU skinning oracle using the exact palette submitted to rendering, not IK targets. */
+    sampleFootSurfaces() {
+        const config = this.footPlanting;
+        if (!config)
+            return [];
+        const samples = [];
+        for (const leg of config.legs) {
+            const ankle = this.nodesByName.get(leg.ankle)?.[0];
+            if (!ankle)
+                continue;
+            const footNames = new Set();
+            const visit = (node) => { footNames.add(node.name); node.children.forEach(visit); };
+            visit(ankle);
+            for (const binding of this.skinningBindings) {
+                const palette = binding.renderable.skinning;
+                if (!palette)
+                    continue;
+                const mesh = binding.mesh;
+                const cacheKey = `${leg.ankle}:${binding.node.id}:${mesh.name}`;
+                let selected = this.footSurfaceVertices.get(cacheKey);
+                if (!selected) {
+                    const candidates = [];
+                    for (let vertex = 0; vertex < mesh.positions.length; vertex++) {
+                        let footWeight = 0;
+                        for (let lane = 0; lane < 4; lane++) {
+                            if (footNames.has(binding.skin.jointNames[mesh.joints[vertex]?.[lane] ?? -1] ?? ""))
+                                footWeight += mesh.weights[vertex]?.[lane] ?? 0;
+                            if (footNames.has(binding.skin.jointNames[mesh.joints1?.[vertex]?.[lane] ?? -1] ?? ""))
+                                footWeight += mesh.weights1?.[vertex]?.[lane] ?? 0;
+                        }
+                        if (footWeight >= 0.5)
+                            candidates.push(vertex);
+                    }
+                    if (!candidates.length) {
+                        this.footSurfaceVertices.set(cacheKey, []);
+                        continue;
+                    }
+                    // Fixed bind-space sole strip: never reselect vertices from animated positions.
+                    const bindHeights = new Map(candidates.map(vertex => [vertex, transformPoint(binding.bindWorldMatrix, [...mesh.positions[vertex]])[1]]));
+                    const ys = [...bindHeights.values()];
+                    const minimum = Math.min(...ys), maximum = Math.max(...ys);
+                    const strip = Math.max(1e-6, (maximum - minimum) * 0.001);
+                    selected = candidates.filter(index => bindHeights.get(index) <= minimum + strip);
+                    this.footSurfaceVertices.set(cacheKey, selected);
+                }
+                const toWorld = config.worldFromLocal ? multiplyMat4(config.worldFromLocal, binding.node.transform.worldMatrix) : binding.node.transform.worldMatrix;
+                for (const vertex of selected) {
+                    const authored = [...mesh.positions[vertex]];
+                    for (let morph = 0; morph < mesh.morphTargets.length; morph++) {
+                        const weight = binding.renderable.morphWeights?.[morph] ?? 0;
+                        const delta = mesh.morphTargets[morph]?.positions[vertex];
+                        if (delta && weight)
+                            for (let axis = 0; axis < 3; axis++)
+                                authored[axis] += delta[axis] * weight;
+                    }
+                    const skinned = [0, 0, 0];
+                    let total = 0;
+                    for (let set = 0; set < 2; set++)
+                        for (let lane = 0; lane < 4; lane++) {
+                            const weight = (set ? mesh.weights1?.[vertex]?.[lane] : mesh.weights[vertex]?.[lane]) ?? 0;
+                            const joint = (set ? mesh.joints1?.[vertex]?.[lane] : mesh.joints[vertex]?.[lane]) ?? -1;
+                            if (weight <= 0)
+                                continue;
+                            if (joint < 0 || joint >= palette.jointCount)
+                                throw new Error("Foot surface vertex has an invalid palette influence.");
+                            const point = transformPoint(Array.from(palette.matrices.subarray(joint * 16, joint * 16 + 16)), authored);
+                            for (let axis = 0; axis < 3; axis++)
+                                skinned[axis] += point[axis] * weight;
+                            total += weight;
+                        }
+                    if (Math.abs(total - 1) > 0.001)
+                        throw new Error("Foot surface vertex weights must sum to one.");
+                    const worldPosition = transformPoint(toWorld, skinned);
+                    const hit = config.ground.raycastDown([worldPosition[0], worldPosition[1] + 2, worldPosition[2]], 4);
+                    samples.push({ side: leg.side, mesh: `${binding.node.userData.gltfNodeIndex ?? binding.node.name}:${mesh.name}`, vertex, worldPosition,
+                        groundError: hit ? worldPosition[1] - hit.point[1] : null,
+                        ...(vertex === selected[0] ? { skinningProbe: { position: authored,
+                                joints: [...(mesh.joints[vertex] ?? [0, 0, 0, 0]), ...(mesh.joints1?.[vertex] ?? [0, 0, 0, 0])],
+                                weights: [...(mesh.weights[vertex] ?? [0, 0, 0, 0]), ...(mesh.weights1?.[vertex] ?? [0, 0, 0, 0])],
+                                matrices: Array.from(palette.matrices), modelMatrix: [...toWorld], expectedWorldPosition: worldPosition } } : {}) });
+                }
             }
         }
+        return samples;
     }
     refreshSkinningPalettes() {
         if (this.skinningBindings.length === 0) {
@@ -571,6 +975,10 @@ export class GLTFSceneAnimationRuntime {
         let boundTrackCount = 0;
         let transformTrackCount = 0;
         let morphWeightTrackCount = 0;
+        let materialTrackCount = 0;
+        let lightTrackCount = 0;
+        const boundMaterialNames = new Set();
+        const boundLightNames = new Set();
         const boundNodeNames = new Set();
         const missingTargets = new Set();
         const unsupportedTracks = new Set();
@@ -581,6 +989,26 @@ export class GLTFSceneAnimationRuntime {
                 continue;
             }
             supportedTrackCount += 1;
+            if (target.kind === "material") {
+                materialTrackCount += 1;
+                if (materialParametersForLeaf(target.leaf) === undefined || this.options.resolveAnimationMaterial?.(target.materialName) === undefined) {
+                    missingTargets.add(track.target);
+                    continue;
+                }
+                boundTrackCount += 1;
+                boundMaterialNames.add(target.materialName);
+                continue;
+            }
+            if (target.kind === "light") {
+                lightTrackCount += 1;
+                if (lightLeafApplies(target.leaf) === false || this.findSceneLight(target.lightName) === undefined) {
+                    missingTargets.add(track.target);
+                    continue;
+                }
+                boundTrackCount += 1;
+                boundLightNames.add(target.lightName);
+                continue;
+            }
             if (target.path === "weights") {
                 morphWeightTrackCount += 1;
                 const renderables = this.morphRenderablesByNodeName.get(target.nodeName) ?? [];
@@ -608,6 +1036,10 @@ export class GLTFSceneAnimationRuntime {
             boundTrackCount,
             transformTrackCount,
             morphWeightTrackCount,
+            materialTrackCount,
+            lightTrackCount,
+            boundMaterialNames: [...boundMaterialNames].sort(),
+            boundLightNames: [...boundLightNames].sort(),
             missingTargetCount: missingTargets.size,
             unsupportedTrackCount: unsupportedTracks.size,
             skinningBindingCount: this.skinningBindings.length,
@@ -620,12 +1052,32 @@ export class GLTFSceneAnimationRuntime {
     applySampledTargets(clipName, time, sampled, blendedClipCount) {
         let transformTracksApplied = 0;
         let morphWeightTracksApplied = 0;
+        let materialTracksApplied = 0;
+        let lightTracksApplied = 0;
         const missingTargets = [];
         for (const [trackTarget, value] of sampled.sampledTargets) {
             const target = parseAnimationTarget(trackTarget);
             if (!target) {
                 continue;
             }
+            if (target.kind === "material") {
+                if (this.applyMaterialTrackValue(target.materialName, target.leaf, value, trackTarget)) {
+                    materialTracksApplied += 1;
+                }
+                else {
+                    missingTargets.push(trackTarget);
+                }
+                continue;
+            }
+            if (target.kind === "light") {
+                if (this.applyLightTrackValue(target.lightName, target.leaf, value, trackTarget)) {
+                    lightTracksApplied += 1;
+                }
+                else {
+                    missingTargets.push(trackTarget);
+                }
+                continue;
+            }
             if (target.path === "weights") {
                 const renderables = this.morphRenderablesByNodeName.get(target.nodeName) ?? [];
                 if (renderables.length === 0) {
@@ -650,14 +1102,19 @@ export class GLTFSceneAnimationRuntime {
             transformTracksApplied += 1;
         }
         this.options.scene.updateWorldTransforms();
+        const footPlanting = this.applyFootPlanting();
         const skinning = this.refreshSkinningPalettes();
+        const measuredFootPlanting = footPlanting ? { ...footPlanting, surfaces: this.sampleFootSurfaces() } : undefined;
         return {
             clipName,
             time,
             ...(blendedClipCount === undefined ? {} : { blendedClipCount }),
-            tracksApplied: transformTracksApplied + morphWeightTracksApplied,
+            tracksApplied: transformTracksApplied + morphWeightTracksApplied + materialTracksApplied + lightTracksApplied,
             transformTracksApplied,
             morphWeightTracksApplied,
+            materialTracksApplied,
+            lightTracksApplied,
+            ...(measuredFootPlanting === undefined ? {} : { footPlanting: measuredFootPlanting }),
             skinningPalettesUpdated: skinning.updated,
             missingTargets: [...missingTargets, ...skinning.missingTargets],
             unsupportedTracks: sampled.unsupportedTracks
@@ -679,6 +1136,7 @@ export class GLTFSceneAnimationMixerBinding {
     constructor(options) {
         this.runtime = new GLTFSceneAnimationRuntime(options);
         this.mixer = new AnimationMixer({
+            ...(options.consumeRootMotion ? { consumeRootMotion: options.consumeRootMotion } : {}),
             setAnimationValue: (target, value) => {
                 this.pendingValues.set(target, cloneAnimationValue(value));
             }
@@ -867,7 +1325,27 @@ export class GLTFSceneAnimationMixerBinding {
 export function createGLTFSceneAnimationMixer(options) {
     return new GLTFSceneAnimationMixerBinding(options);
 }
+/**
+ * Pointer-bound leaf paths (`material:`/`light:`) use the FIRST dot as the name/leaf split:
+ * the binding emits `material:<name>.<property-path…>` where the property path itself may
+ * contain dots (`pbrMetallicRoughness.baseColorFactor`), while glTF material/light names with
+ * dots are rare. Names containing "." therefore resolve by first segment and are documented
+ * as unsupported in the animation-pointer limits.
+ */
 function parseAnimationTarget(target) {
+    for (const prefix of ["material:", "light:"]) {
+        if (target.startsWith(prefix)) {
+            const rest = target.slice(prefix.length);
+            const separator = rest.indexOf(".");
+            if (separator <= 0 || separator === rest.length - 1)
+                return undefined;
+            const name = rest.slice(0, separator);
+            const leaf = rest.slice(separator + 1);
+            return prefix === "material:"
+                ? { kind: "material", materialName: name, leaf }
+                : { kind: "light", lightName: name, leaf };
+        }
+    }
     const separator = target.lastIndexOf(".");
     if (separator <= 0 || separator === target.length - 1) {
         return undefined;
@@ -877,10 +1355,44 @@ function parseAnimationTarget(target) {
         return undefined;
     }
     return {
+        kind: "node",
         nodeName: target.slice(0, separator),
         path
     };
 }
+/**
+ * Maps an animation-pointer material leaf path to the renderer uniform parameters it drives.
+ * Only leaves with uniforms the production bridge provably writes (see TypedGLBActor tint
+ * path: `u_baseColor`, `u_baseColorFactor`, `u_emissiveColor`, `u_emissiveFactor`,
+ * `u_emissiveStrength`, `u_metallic`, `u_roughness`) are supported; every other leaf stays
+ * diagnostic-only, preserving diagnose-and-drop for the unmapped remainder. Matches on the
+ * last path segment so `pbrMetallicRoughness.baseColorFactor` and `baseColorFactor` agree.
+ */
+function materialParametersForLeaf(leafPath) {
+    const leaf = leafPath.slice(leafPath.lastIndexOf(".") + 1);
+    switch (leaf) {
+        case "baseColorFactor":
+            return ["u_baseColorFactor", "u_baseColor"];
+        case "emissiveFactor":
+            return ["u_emissiveFactor", "u_emissiveColor"];
+        case "metallicFactor":
+            return ["u_metallic"];
+        case "roughnessFactor":
+            return ["u_roughness"];
+        case "emissiveStrength":
+            return ["u_emissiveStrength"];
+        case "clearcoatFactor":
+            return ["u_clearcoatFactor"];
+        case "clearcoatRoughnessFactor":
+            return ["u_clearcoatRoughnessFactor"];
+        default:
+            return undefined;
+    }
+}
+/** Light leaves the runtime can drive on a live scene light. Anything else stays diagnostic-only. */
+function lightLeafApplies(leaf) {
+    return leaf === "intensity" || leaf === "color" || leaf === "range";
+}
 function resolveIKSkin(skins, skinName) {
     if (skinName === undefined) {
         const skin = skins.find((candidate) => candidate.jointNames.length >= 3);
@@ -907,10 +1419,88 @@ function firstTwoBoneJointChain(skin) {
     }
     return [root, mid, end];
 }
+/**
+ * True when two foot-planting configs solve the same rig the same way. The world matrix is
+ * deliberately excluded: the engine refreshes `worldFromLocal` every frame (time-animated
+ * model nodes move) and that refresh must not reset world-space foot locks.
+ */
+function sameFootPlantingShape(previous, next) {
+    if (previous === next)
+        return true;
+    if (!previous || !next)
+        return false;
+    if (previous.ground !== next.ground)
+        return false;
+    if (previous.ankleHeight !== next.ankleHeight)
+        return false;
+    if (previous.rayStartHeight !== next.rayStartHeight)
+        return false;
+    if (previous.maxRayDistance !== next.maxRayDistance)
+        return false;
+    if (previous.plantThreshold !== next.plantThreshold)
+        return false;
+    if (previous.hipDropFactor !== next.hipDropFactor)
+        return false;
+    if (previous.lockFootRotation !== next.lockFootRotation)
+        return false;
+    if (previous.legs.length !== next.legs.length)
+        return false;
+    return previous.legs.every((leg, index) => {
+        const other = next.legs[index];
+        return other !== undefined
+            && leg.side === other.side
+            && leg.hip === other.hip
+            && leg.knee === other.knee
+            && leg.ankle === other.ankle
+            && leg.ankleHeight === other.ankleHeight
+            && (leg.pole ?? []).join(",") === (other.pole ?? []).join(",");
+    });
+}
 function worldPosition(node) {
     node.updateWorldTransform();
     return [node.transform.worldMatrix[12], node.transform.worldMatrix[13], node.transform.worldMatrix[14]];
 }
+function commonAncestor(nodes) {
+    if (nodes.length === 0)
+        return undefined;
+    const first = [];
+    for (let node = nodes[0]; node; node = node.parent)
+        first.push(node);
+    return first.find(candidate => nodes.every(node => node === candidate || candidate.isAncestorOf(node)));
+}
+function orientJointToward(node, child, target) {
+    node.updateWorldTransform();
+    child.updateWorldTransform();
+    const origin = worldPosition(node);
+    const current = worldPosition(child);
+    const from = [current[0] - origin[0], current[1] - origin[1], current[2] - origin[2]];
+    const to = [target[0] - origin[0], target[1] - origin[1], target[2] - origin[2]];
+    const delta = quatFromUnitVectors(from, to);
+    const worldRotation = multiplyRigidQuat(delta, decomposeMat4(node.transform.worldMatrix).rotation);
+    const parentRotation = node.parent ? decomposeMat4(node.parent.transform.worldMatrix).rotation : [0, 0, 0, 1];
+    const localRotation = multiplyRigidQuat(invertRigidQuat(parentRotation), worldRotation);
+    node.transform.setRotation(localRotation[0], localRotation[1], localRotation[2], localRotation[3]);
+}
+function quatFromUnitVectors(from, to) {
+    const fl = Math.hypot(...from), tl = Math.hypot(...to);
+    if (!(fl > 1e-12) || !(tl > 1e-12))
+        return [0, 0, 0, 1];
+    const fx = from[0] / fl, fy = from[1] / fl, fz = from[2] / fl, tx = to[0] / tl, ty = to[1] / tl, tz = to[2] / tl;
+    const dot = fx * tx + fy * ty + fz * tz;
+    if (dot < -0.999999) {
+        const axis = Math.abs(fx) > 0.1 ? [-fz, 0, fx] : [0, fz, -fy];
+        const length = Math.hypot(...axis);
+        return [axis[0] / length, axis[1] / length, axis[2] / length, 0];
+    }
+    if (dot > 0.999999)
+        return [0, 0, 0, 1];
+    return normalizeQuaternion([fy * tz - fz * ty, fz * tx - fx * tz, fx * ty - fy * tx, 1 + dot]);
+}
+function multiplyRigidQuat(a, b) {
+    return normalizeQuaternion([a[3] * b[0] + a[0] * b[3] + a[1] * b[2] - a[2] * b[1], a[3] * b[1] - a[0] * b[2] + a[1] * b[3] + a[2] * b[0], a[3] * b[2] + a[0] * b[1] - a[1] * b[0] + a[2] * b[3], a[3] * b[3] - a[0] * b[0] - a[1] * b[1] - a[2] * b[2]]);
+}
+function invertRigidQuat(q) { return [-q[0], -q[1], -q[2], q[3]]; }
+function normalizeQuaternion(q) { const n = Math.hypot(...q); return n > 0 ? [q[0] / n, q[1] / n, q[2] / n, q[3] / n] : [0, 0, 0, 1]; }
 function setWorldPosition(node, position) {
     const local = node.parent
         ? transformPoint(invertMat4(node.parent.transform.worldMatrix), [position[0], position[1], position[2]])
@@ -967,6 +1557,26 @@ function asNumberArray(value) {
     }
     return [...value];
 }
+function asScalar(value, target) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`glTF animation track "${target}" sampled an invalid scalar.`);
+    }
+    return value;
+}
+function asPositiveScalar(value, target) {
+    const scalar = asScalar(value, target);
+    if (!(scalar > 0)) {
+        throw new Error(`glTF animation track "${target}" sampled a non-positive range.`);
+    }
+    return scalar;
+}
+function asMaterialLeafValue(value, target) {
+    if (typeof value === "number")
+        return asScalar(value, target);
+    if (Array.isArray(value))
+        return asNumberArray(value);
+    throw new Error(`glTF animation track "${target}" sampled an invalid material value.`);
+}
 function sampleClipTracks(clip, time, weight, additive) {
     const accumulators = new Map();
     const unsupportedTracks = [];