@aura3d/engine 2.0.3 → 3.0.0

package/dist/assets/GLTFAnimationRuntime.js

@@ -1,4 +1,4 @@
-import { AnimationAction, AnimationClip, AnimationMixer, normalizeQuat, slerpQuat, solveTwoBoneIk } from "../animation/browser-index.js";
+import { AnimationAction, AnimationClip, AnimationMixer, createFootIkRig, normalizeQuat, slerpQuat, solveTwoBoneIk } from "../animation/browser-index.js";
 import { invertMat4, MAX_RENDERABLE_SKINNING_JOINTS, multiplyMat4, Renderable, Scene, transformPoint } from "../scene/index.js";
 /**
  * Synonym groups for fuzzy clip-name matching. Real catalog assets label the same
@@ -259,6 +259,8 @@ export class GLTFSceneAnimationRuntime {
     nodesByName = new Map();
     morphRenderablesByNodeName = new Map();
     skinningBindings = [];
+    footPlanting;
+    footRig;
     lastApply;
     constructor(options) {
         this.options = options;
@@ -266,6 +268,24 @@ 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.footPlanting = config;
     }
     applyClipByName(name, time) {
         const clip = this.clipsByName.get(name);
@@ -337,7 +357,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);
             }
@@ -534,6 +555,150 @@ export class GLTFSceneAnimationRuntime {
             }
         }
     }
+    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 and
+     * writes the solved hip/knee/ankle world positions back onto the skeleton. Position-only
+     * write-back (rotations stay as animated); 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 });
+        }
+        if (resolved.length === 0) {
+            return { groundedFeet: 0, averageTargetError: 0, lockedSides: [], missingLegNodes, hipOffset: 0 };
+        }
+        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)),
+                    ...(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 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)),
+                ...(entry.pole ? { pole: entry.pole } : {})
+            }))
+        });
+        for (const foot of solved.feet) {
+            const entry = resolved.find((candidate) => candidate.side === foot.side);
+            if (!entry)
+                continue;
+            // The rig returns the pelvis drop separately: apply it to the hip so an over-extended
+            // leg can reach its planted foot. Solved knee/ankle targets already account for the
+            // drop — the rig re-solves over-extended legs from the dropped hip — so they write
+            // back directly; a leg that needed no drop keeps phase-one targets and lets its knee
+            // absorb the pelvis motion by bending, the natural single-pelvis compromise.
+            // Refresh down the chain after each write: setWorldPosition reads the parent's world
+            // matrix, so the knee must see the new hip world before its own write (same for ankle).
+            // Solved targets are world-space; convert to actor-local for the write-back.
+            const hipTarget = actorPoint([foot.hip[0], foot.hip[1] + solved.hipOffset, foot.hip[2]]);
+            setWorldPosition(entry.hip, [hipTarget[0], hipTarget[1], hipTarget[2]]);
+            entry.hip.updateWorldTransform();
+            const kneeTarget = actorPoint(foot.knee);
+            setWorldPosition(entry.knee, [kneeTarget[0], kneeTarget[1], kneeTarget[2]]);
+            entry.knee.updateWorldTransform();
+            const ankleTarget = actorPoint(foot.ankle);
+            setWorldPosition(entry.ankle, [ankleTarget[0], ankleTarget[1], ankleTarget[2]]);
+        }
+        this.options.scene.updateWorldTransforms();
+        return {
+            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;
+    }
     refreshSkinningPalettes() {
         if (this.skinningBindings.length === 0) {
             return { updated: 0, missingTargets: [] };
@@ -571,6 +736,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 +750,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 +797,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 +813,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 +863,18 @@ export class GLTFSceneAnimationRuntime {
             transformTracksApplied += 1;
         }
         this.options.scene.updateWorldTransforms();
+        const footPlanting = this.applyFootPlanting();
         const skinning = this.refreshSkinningPalettes();
         return {
             clipName,
             time,
             ...(blendedClipCount === undefined ? {} : { blendedClipCount }),
-            tracksApplied: transformTracksApplied + morphWeightTracksApplied,
+            tracksApplied: transformTracksApplied + morphWeightTracksApplied + materialTracksApplied + lightTracksApplied,
             transformTracksApplied,
             morphWeightTracksApplied,
+            materialTracksApplied,
+            lightTracksApplied,
+            ...(footPlanting === undefined ? {} : { footPlanting }),
             skinningPalettesUpdated: skinning.updated,
             missingTargets: [...missingTargets, ...skinning.missingTargets],
             unsupportedTracks: sampled.unsupportedTracks
@@ -867,7 +1084,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 +1114,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,6 +1178,40 @@ 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.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.pole ?? []).join(",") === (other.pole ?? []).join(",");
+    });
+}
 function worldPosition(node) {
     node.updateWorldTransform();
     return [node.transform.worldMatrix[12], node.transform.worldMatrix[13], node.transform.worldMatrix[14]];
@@ -967,6 +1272,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 = [];