@vgai/engine 0.5.0-canary.20260719.0 → 0.5.0

package/dist/humanoid/body.js

@@ -0,0 +1,530 @@
+/**
+ * The procedural humanoid BODY: entirely procedural three.js geometry
+ * (capsules + one pelvis box via `CapsuleGeometry`/`BoxGeometry`, merged with
+ * `BufferGeometryUtils.mergeGeometries` into ONE `SkinnedMesh`). No imported
+ * mesh anywhere. Promoted from the accepted Phase-1 PoC
+ * (`packages/engine/e2e/humanoid-skin-proof/procedural-body.ts`) and
+ * parameterized by body dimensions — with all-default dims the output is
+ * bit-identical to the PoC body.
+ *
+ * Skin binding is **analytic per-segment with smooth 2-bone joint blending**:
+ * every body part is generated along one bone segment (proximal joint →
+ * distal joint, both known a priori from the rest pose), so each vertex's
+ * normalized position `t` along the bone axis is exact — no nearest-bone
+ * search, no heuristic falloff radius. Vertices in the interior of a segment
+ * bind 100% to that segment's bone; vertices inside a blend zone at either
+ * end split weight smoothstep-wise with the adjacent bone, reaching 50/50 at
+ * (and past) the joint itself. This is the standard cure for the two classic
+ * rigid-binding artifacts: gaps/interpenetration at elbows/knees (fixed by
+ * the overshoot + 50/50 blend across the joint) and hard shading creases
+ * (fixed by the smoothstep ramp). Because the blend zone is derived from the
+ * ACTUAL joint positions of the (possibly rescaled) skeleton, weights stay
+ * correct as body proportions change. Two influences per vertex is enough
+ * for a capsule-limb body; the vertex format still uses the standard 4-wide
+ * skinIndex/skinWeight attributes, zero-padded, exactly as GLTF skins do.
+ */
+import * as THREE from 'three';
+import { mergeGeometries } from 'three/addons/utils/BufferGeometryUtils.js';
+const C = {
+    torso: 0x4f8fba,
+    pelvis: 0x3a6ea5,
+    head: 0xd9a066,
+    neck: 0xc98b5e,
+    armL: 0xe07b39,
+    foreL: 0xf0a860,
+    armR: 0x4fae6a,
+    foreR: 0x7fd196,
+    hand: 0xd9c8b4,
+    thigh: 0x8a5fb0,
+    shin: 0xb08ad0,
+    foot: 0x555f6e,
+    toe: 0x6d7885,
+};
+/** The full body map. Radii/overshoots are metres at reference scale, tuned
+ *  to the reference rig's T-pose proportions (~1.83 m tall). */
+const SEGMENTS = [
+    // Torso column — three short, fat, overlapping capsules following the
+    // spine chain, each blending into its neighbours.
+    {
+        bone: 'mixamorigSpine',
+        from: 'mixamorigSpine',
+        to: 'mixamorigSpine1',
+        radius: 0.135,
+        group: 'torso',
+        proximalBlend: 'mixamorigHips',
+        distalBlend: 'mixamorigSpine1',
+        overshootFrom: 0.03,
+        overshootTo: 0.02,
+        color: C.torso,
+    },
+    {
+        bone: 'mixamorigSpine1',
+        from: 'mixamorigSpine1',
+        to: 'mixamorigSpine2',
+        radius: 0.145,
+        group: 'torso',
+        proximalBlend: 'mixamorigSpine',
+        distalBlend: 'mixamorigSpine2',
+        overshootFrom: 0.02,
+        overshootTo: 0.02,
+        color: C.torso,
+    },
+    {
+        bone: 'mixamorigSpine2',
+        from: 'mixamorigSpine2',
+        to: 'mixamorigNeck',
+        radius: 0.14,
+        group: 'torso',
+        proximalBlend: 'mixamorigSpine1',
+        distalBlend: 'mixamorigNeck',
+        overshootFrom: 0.02,
+        overshootTo: 0.01,
+        color: C.torso,
+    },
+    // Neck + head.
+    {
+        bone: 'mixamorigNeck',
+        from: 'mixamorigNeck',
+        to: 'mixamorigHead',
+        radius: 0.048,
+        group: 'head',
+        proximalBlend: 'mixamorigSpine2',
+        distalBlend: 'mixamorigHead',
+        overshootFrom: 0.02,
+        overshootTo: 0.02,
+        color: C.neck,
+    },
+    {
+        bone: 'mixamorigHead',
+        from: 'mixamorigHead',
+        to: 'mixamorigHeadTop_End',
+        radius: 0.105,
+        group: 'head',
+        proximalBlend: 'mixamorigNeck',
+        color: C.head,
+    },
+    // Left arm chain (shoulder → upper arm → forearm → hand).
+    {
+        bone: 'mixamorigLeftShoulder',
+        from: 'mixamorigLeftShoulder',
+        to: 'mixamorigLeftArm',
+        radius: 0.062,
+        group: 'torso',
+        proximalBlend: 'mixamorigSpine2',
+        distalBlend: 'mixamorigLeftArm',
+        overshootFrom: 0.02,
+        color: C.torso,
+    },
+    {
+        bone: 'mixamorigLeftArm',
+        from: 'mixamorigLeftArm',
+        to: 'mixamorigLeftForeArm',
+        radius: 0.052,
+        group: 'limb',
+        proximalBlend: 'mixamorigLeftShoulder',
+        distalBlend: 'mixamorigLeftForeArm',
+        overshootFrom: 0.015,
+        overshootTo: 0.01,
+        color: C.armL,
+    },
+    {
+        bone: 'mixamorigLeftForeArm',
+        from: 'mixamorigLeftForeArm',
+        to: 'mixamorigLeftHand',
+        radius: 0.044,
+        group: 'limb',
+        proximalBlend: 'mixamorigLeftArm',
+        distalBlend: 'mixamorigLeftHand',
+        overshootFrom: 0.01,
+        overshootTo: 0.01,
+        color: C.foreL,
+    },
+    {
+        bone: 'mixamorigLeftHand',
+        from: 'mixamorigLeftHand',
+        to: 'mixamorigLeftHandMiddle1',
+        radius: 0.04,
+        group: 'limb',
+        proximalBlend: 'mixamorigLeftForeArm',
+        overshootTo: 0.05,
+        color: C.hand,
+    },
+    // Right arm chain.
+    {
+        bone: 'mixamorigRightShoulder',
+        from: 'mixamorigRightShoulder',
+        to: 'mixamorigRightArm',
+        radius: 0.062,
+        group: 'torso',
+        proximalBlend: 'mixamorigSpine2',
+        distalBlend: 'mixamorigRightArm',
+        overshootFrom: 0.02,
+        color: C.torso,
+    },
+    {
+        bone: 'mixamorigRightArm',
+        from: 'mixamorigRightArm',
+        to: 'mixamorigRightForeArm',
+        radius: 0.052,
+        group: 'limb',
+        proximalBlend: 'mixamorigRightShoulder',
+        distalBlend: 'mixamorigRightForeArm',
+        overshootFrom: 0.015,
+        overshootTo: 0.01,
+        color: C.armR,
+    },
+    {
+        bone: 'mixamorigRightForeArm',
+        from: 'mixamorigRightForeArm',
+        to: 'mixamorigRightHand',
+        radius: 0.044,
+        group: 'limb',
+        proximalBlend: 'mixamorigRightArm',
+        distalBlend: 'mixamorigRightHand',
+        overshootFrom: 0.01,
+        overshootTo: 0.01,
+        color: C.foreR,
+    },
+    {
+        bone: 'mixamorigRightHand',
+        from: 'mixamorigRightHand',
+        to: 'mixamorigRightHandMiddle1',
+        radius: 0.04,
+        group: 'limb',
+        proximalBlend: 'mixamorigRightForeArm',
+        overshootTo: 0.05,
+        color: C.hand,
+    },
+    // Left leg chain (thigh → shin → foot → toes).
+    {
+        bone: 'mixamorigLeftUpLeg',
+        from: 'mixamorigLeftUpLeg',
+        to: 'mixamorigLeftLeg',
+        radius: 0.078,
+        group: 'limb',
+        proximalBlend: 'mixamorigHips',
+        distalBlend: 'mixamorigLeftLeg',
+        overshootFrom: 0.035,
+        overshootTo: 0.01,
+        color: C.thigh,
+    },
+    {
+        bone: 'mixamorigLeftLeg',
+        from: 'mixamorigLeftLeg',
+        to: 'mixamorigLeftFoot',
+        radius: 0.058,
+        group: 'limb',
+        proximalBlend: 'mixamorigLeftUpLeg',
+        distalBlend: 'mixamorigLeftFoot',
+        overshootFrom: 0.01,
+        overshootTo: 0.01,
+        color: C.shin,
+    },
+    {
+        bone: 'mixamorigLeftFoot',
+        from: 'mixamorigLeftFoot',
+        to: 'mixamorigLeftToeBase',
+        radius: 0.05,
+        group: 'foot',
+        proximalBlend: 'mixamorigLeftLeg',
+        distalBlend: 'mixamorigLeftToeBase',
+        overshootFrom: 0.01,
+        color: C.foot,
+    },
+    {
+        bone: 'mixamorigLeftToeBase',
+        from: 'mixamorigLeftToeBase',
+        to: 'mixamorigLeftToe_End',
+        radius: 0.042,
+        group: 'foot',
+        proximalBlend: 'mixamorigLeftFoot',
+        color: C.toe,
+    },
+    // Right leg chain.
+    {
+        bone: 'mixamorigRightUpLeg',
+        from: 'mixamorigRightUpLeg',
+        to: 'mixamorigRightLeg',
+        radius: 0.078,
+        group: 'limb',
+        proximalBlend: 'mixamorigHips',
+        distalBlend: 'mixamorigRightLeg',
+        overshootFrom: 0.035,
+        overshootTo: 0.01,
+        color: C.thigh,
+    },
+    {
+        bone: 'mixamorigRightLeg',
+        from: 'mixamorigRightLeg',
+        to: 'mixamorigRightFoot',
+        radius: 0.058,
+        group: 'limb',
+        proximalBlend: 'mixamorigRightUpLeg',
+        distalBlend: 'mixamorigRightFoot',
+        overshootFrom: 0.01,
+        overshootTo: 0.01,
+        color: C.shin,
+    },
+    {
+        bone: 'mixamorigRightFoot',
+        from: 'mixamorigRightFoot',
+        to: 'mixamorigRightToeBase',
+        radius: 0.05,
+        group: 'foot',
+        proximalBlend: 'mixamorigRightLeg',
+        distalBlend: 'mixamorigRightToeBase',
+        overshootFrom: 0.01,
+        color: C.foot,
+    },
+    {
+        bone: 'mixamorigRightToeBase',
+        from: 'mixamorigRightToeBase',
+        to: 'mixamorigRightToe_End',
+        radius: 0.042,
+        group: 'foot',
+        proximalBlend: 'mixamorigRightFoot',
+        color: C.toe,
+    },
+];
+/** The head capsule's reference radius — `generate.ts` feeds this (× headSize)
+ *  to the skeleton height normalization as the crown padding. */
+export const HEAD_CAPSULE_RADIUS = SEGMENTS.find((s) => s.bone === 'mixamorigHead')?.radius ?? 0.105;
+export const smoothstep = (x) => {
+    const t = Math.min(1, Math.max(0, x));
+    return t * t * (3 - 2 * t);
+};
+/** Blend-zone length as a fraction of a segment (≈10 cm at reference scale,
+ *  clamped to 20–50% of the segment) — shared verbatim by the body generator
+ *  and `skinToHumanoid` so clothing gets the SAME joint blend as the body. */
+export const blendZone = (len, heightFactor) => Math.min(0.5, Math.max(0.2, (0.1 * heightFactor) / len));
+/** World rest position of a named bone (scene must have updated matrices). */
+function jointPos(rig, name) {
+    const bone = rig.byName.get(name);
+    if (!bone)
+        throw new Error(`humanoid: unknown bone '${name}'`);
+    return new THREE.Vector3().setFromMatrixPosition(bone.matrixWorld);
+}
+/** name → skinIndex row, cached per rig (reviewer note: the former O(n)
+ *  findIndex per call was fine for 22 parts, not for per-prop/per-vertex use). */
+const boneIndexCache = new WeakMap();
+function boneIndex(rig, name) {
+    let map = boneIndexCache.get(rig);
+    if (!map) {
+        map = new Map(rig.bones.map((b, i) => [b.name, i]));
+        boneIndexCache.set(rig, map);
+    }
+    const i = map.get(name);
+    if (i === undefined)
+        throw new Error(`humanoid: unknown bone '${name}'`);
+    return i;
+}
+/** Fill vertex colors with a flat per-part color. */
+function paint(geo, color) {
+    const n = geo.attributes['position'].count;
+    const c = new THREE.Color(color);
+    const arr = new Float32Array(n * 3);
+    for (let i = 0; i < n; i++)
+        arr.set([c.r, c.g, c.b], i * 3);
+    geo.setAttribute('color', new THREE.BufferAttribute(arr, 3));
+}
+/**
+ * Compute skinIndex/skinWeight for a segment geometry: per-vertex projection
+ * onto the joint axis → smoothstep 2-bone blend inside the end zones. The
+ * blend zone length adapts to the segment (≈10 cm at reference scale,
+ * clamped to 20–50% of the segment) so short torso links still blend and
+ * long thighs stay mostly rigid.
+ */
+function skinSegment(geo, rig, spec, p0, p1, heightFactor) {
+    const primary = boneIndex(rig, spec.bone);
+    const proximal = spec.proximalBlend ? boneIndex(rig, spec.proximalBlend) : -1;
+    const distal = spec.distalBlend ? boneIndex(rig, spec.distalBlend) : -1;
+    const axis = p1.clone().sub(p0);
+    const len = axis.length();
+    const axisN = axis.clone().divideScalar(len);
+    const blend = blendZone(len, heightFactor);
+    const pos = geo.attributes['position'];
+    const n = pos.count;
+    const skinIndex = new Uint16Array(n * 4);
+    const skinWeight = new Float32Array(n * 4);
+    const v = new THREE.Vector3();
+    for (let i = 0; i < n; i++) {
+        v.fromBufferAttribute(pos, i);
+        const t = v.sub(p0).dot(axisN) / len; // may exceed [0,1] via overshoot
+        let other = primary;
+        let w2 = 0;
+        if (proximal >= 0 && t < blend) {
+            // 50/50 exactly at (and beyond) the joint, ramping to 100% primary.
+            other = proximal;
+            w2 = 0.5 * (1 - smoothstep(t / blend));
+        }
+        else if (distal >= 0 && t > 1 - blend) {
+            other = distal;
+            w2 = 0.5 * smoothstep((t - (1 - blend)) / blend);
+        }
+        skinIndex.set([primary, other, 0, 0], i * 4);
+        skinWeight.set([1 - w2, w2, 0, 0], i * 4);
+    }
+    geo.setAttribute('skinIndex', new THREE.BufferAttribute(skinIndex, 4));
+    geo.setAttribute('skinWeight', new THREE.BufferAttribute(skinWeight, 4));
+}
+/** Capsule spanning exactly `p0 - dir*overshootFrom` → `p1 + dir*overshootTo`. */
+function capsuleBetween(p0, p1, radius, overshootFrom, overshootTo) {
+    const dir = p1.clone().sub(p0).normalize();
+    const a = p0.clone().addScaledVector(dir, -overshootFrom);
+    const b = p1.clone().addScaledVector(dir, overshootTo);
+    const span = a.distanceTo(b);
+    const cyl = Math.max(0.01, span - 2 * radius);
+    const geo = new THREE.CapsuleGeometry(radius, cyl, 6, 16);
+    geo.deleteAttribute('uv'); // untextured; keeps merged attribute sets identical
+    const quat = new THREE.Quaternion().setFromUnitVectors(new THREE.Vector3(0, 1, 0), dir);
+    const mid = a.clone().add(b).multiplyScalar(0.5);
+    geo.applyMatrix4(new THREE.Matrix4().compose(mid, quat, new THREE.Vector3(1, 1, 1)));
+    return geo;
+}
+/** The pelvis is the one non-capsule part: a box centred between the hips
+ *  and the upper-leg roots, rigidly bound to `mixamorigHips` (the thigh
+ *  capsules overshoot up into it and carry the blending). */
+function buildPelvis(rig, dims) {
+    const hips = jointPos(rig, 'mixamorigHips');
+    const upL = jointPos(rig, 'mixamorigLeftUpLeg');
+    const upR = jointPos(rig, 'mixamorigRightUpLeg');
+    const centerY = (hips.y + (upL.y + upR.y) / 2) / 2;
+    const f = dims.heightFactor;
+    const geo = new THREE.BoxGeometry(0.3 * f * dims.hipWidth, 0.17 * f, 0.19 * f * dims.torsoGirth, 2, 2, 2);
+    geo.deleteAttribute('uv');
+    geo.translate(hips.x, centerY, hips.z);
+    paint(geo, C.pelvis);
+    const hipsIndex = boneIndex(rig, 'mixamorigHips');
+    const n = geo.attributes['position'].count;
+    const skinIndex = new Uint16Array(n * 4);
+    const skinWeight = new Float32Array(n * 4);
+    for (let i = 0; i < n; i++) {
+        skinIndex[i * 4] = hipsIndex;
+        skinWeight[i * 4] = 1;
+    }
+    geo.setAttribute('skinIndex', new THREE.BufferAttribute(skinIndex, 4));
+    geo.setAttribute('skinWeight', new THREE.BufferAttribute(skinWeight, 4));
+    return geo;
+}
+function radiusMultiplier(group, dims) {
+    switch (group) {
+        case 'torso':
+            return dims.torsoGirth;
+        case 'limb':
+            return dims.limbThickness;
+        case 'head':
+            return dims.headSize;
+        case 'foot':
+            return 1;
+    }
+}
+/**
+ * Build the whole body as ONE merged `SkinnedMesh` in the rig root's space
+ * (the skeleton's rest pose), and bind it. Callers must have called
+ * `updateMatrixWorld(true)` on the armature's parent after adding the bone
+ * hierarchy, so every bone's `matrixWorld` is its rest pose —
+ * `new THREE.Skeleton(bones)` captures the inverse bind matrices from
+ * exactly those.
+ */
+export function buildHumanoidBody(rig, dims, material) {
+    const geos = [buildPelvis(rig, dims)];
+    const parts = [];
+    let vertexCursor = geos[0].attributes['position'].count;
+    parts.push({
+        name: 'pelvis',
+        boneIndices: [boneIndex(rig, 'mixamorigHips')],
+        vertexStart: 0,
+        vertexCount: vertexCursor,
+    });
+    const f = dims.heightFactor;
+    for (const spec of SEGMENTS) {
+        const p0 = jointPos(rig, spec.from);
+        const p1 = jointPos(rig, spec.to);
+        const radius = spec.radius * f * radiusMultiplier(spec.group, dims);
+        const geo = capsuleBetween(p0, p1, radius, (spec.overshootFrom ?? 0) * f, (spec.overshootTo ?? 0) * f);
+        paint(geo, spec.color);
+        skinSegment(geo, rig, spec, p0, p1, f);
+        const count = geo.attributes['position'].count;
+        const boneIndices = [boneIndex(rig, spec.bone)];
+        if (spec.proximalBlend)
+            boneIndices.push(boneIndex(rig, spec.proximalBlend));
+        if (spec.distalBlend)
+            boneIndices.push(boneIndex(rig, spec.distalBlend));
+        parts.push({ name: spec.bone, boneIndices, vertexStart: vertexCursor, vertexCount: count });
+        vertexCursor += count;
+        geos.push(geo);
+    }
+    const merged = mergeGeometries(geos, false);
+    if (!merged)
+        throw new Error('humanoid: mergeGeometries failed');
+    for (const g of geos)
+        g.dispose();
+    const mat = material ??
+        new THREE.MeshStandardMaterial({
+            vertexColors: true,
+            roughness: 0.75,
+            metalness: 0.05,
+        });
+    const mesh = new THREE.SkinnedMesh(merged, mat);
+    mesh.name = 'ProceduralHumanoidBody';
+    mesh.castShadow = true;
+    // An animated skinned mesh moves far outside its static rest-pose bounds.
+    mesh.frustumCulled = false;
+    const skeleton = new THREE.Skeleton(rig.bones);
+    mesh.updateMatrixWorld(true);
+    mesh.bind(skeleton, mesh.matrixWorld.clone());
+    return {
+        mesh,
+        skeleton,
+        vertexCount: merged.attributes['position'].count,
+        parts,
+    };
+}
+/**
+ * Resolve the body's segment map (plus one synthetic rigid pelvis segment —
+ * the pelvis box binds 100% to Hips, and belts/skirts must get the same
+ * anchor to stay congruent with it) against a concrete rest pose.
+ * Parameterized on lookups rather than `BuiltSkeleton` because the compose
+ * path recovers rest joints from `Skeleton.boneInverses` (bones may be
+ * mid-animation by then), while the generator reads live rest matrices.
+ * `jointAt` must return a FRESH Vector3 per call (results are mutated here).
+ */
+export function computeBindingSegments(jointAt, indexOf, dims) {
+    const f = dims.heightFactor;
+    const segments = [];
+    // Axis LATERALLY along the hip-to-hip line (not hips→legs): a capsule
+    // there is the closest round proxy for the pelvis box, and — unlike a
+    // short vertical axis with a wide radius — it does not bulge spherically
+    // down between the thighs and steal inner-thigh vertices from the legs.
+    const upLegL = jointAt('mixamorigLeftUpLeg');
+    const upLegR = jointAt('mixamorigRightUpLeg');
+    const pelvisAxis = upLegR.clone().sub(upLegL);
+    const pelvisLen = Math.max(pelvisAxis.length(), 1e-6);
+    segments.push({
+        bone: indexOf('mixamorigHips'),
+        proximal: -1,
+        distal: -1,
+        p0: upLegL,
+        axis: pelvisAxis.divideScalar(pelvisLen),
+        len: pelvisLen,
+        blend: 0,
+        radius: 0.1 * f * dims.hipWidth,
+    });
+    for (const spec of SEGMENTS) {
+        const p0 = jointAt(spec.from);
+        const p1 = jointAt(spec.to);
+        const axis = p1.sub(p0);
+        const len = Math.max(axis.length(), 1e-6);
+        segments.push({
+            bone: indexOf(spec.bone),
+            proximal: spec.proximalBlend ? indexOf(spec.proximalBlend) : -1,
+            distal: spec.distalBlend ? indexOf(spec.distalBlend) : -1,
+            p0,
+            axis: axis.divideScalar(len),
+            len,
+            blend: blendZone(len, f),
+            radius: spec.radius * f * radiusMultiplier(spec.group, dims),
+        });
+    }
+    return segments;
+}

package/dist/humanoid/clips.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Standard-clip playback for generated humanoids: map Mixamo-named
+ * `AnimationClip`s (from any GLB/FBX-derived source) onto the engine's
+ * standard skeleton, across naming variants, with the translation-track
+ * policy body-type rescaling requires.
+ *
+ * TRANSLATION-TRACK POLICY (the reviewer-flagged trap, documented choice):
+ * humanoid clips carry per-bone `.position` tracks baked for the SOURCE
+ * rig's segment lengths — played raw on a rescaled skeleton they snap limb
+ * proportions back to the source's. `retargetClipToHumanoid` therefore
+ *   - DROPS every non-hips `.position` track (bones keep the generated
+ *     rig's rest translations — segment lengths come from the body params),
+ *   - KEEPS the hips `.position` track but multiplies it by the rig's
+ *     `hipsPositionScale` (root motion / bob authored for the reference
+ *     hip height lands at the generated hip height),
+ *   - DROPS `.scale` tracks (rest scale is always 1), and
+ *   - KEEPS every `.quaternion` track verbatim — rotations are
+ *     proportion-independent, which is the whole point of a shared rest
+ *     pose. This is the standard humanoid-retarget policy (the alternative,
+ *     per-bone translation rescale, buys nothing for rigid capsule bodies
+ *     and reintroduces per-bone coupling).
+ *
+ * NAME VARIANTS: track node names resolve across the three spellings in the
+ * wild — sanitized `mixamorigHips` (what GLTFLoader yields), raw
+ * `mixamorig:Hips` / `mixamorig_Hips` (FBX-side exports), and bare `Hips`
+ * (renamed rigs). A track whose node cannot be resolved to a standard bone
+ * — or whose property is not a bone TRS channel — is collected, and
+ * `retargetClipToHumanoid` throws ONE hard error listing every unresolved
+ * track (degrade loudly, never a silently-frozen limb).
+ */
+import * as THREE from 'three';
+/** What retargeting needs to know about a generated rig — `HumanoidRig`
+ *  satisfies this structurally. */
+export interface HumanoidClipTarget {
+    /** Bone lookup by canonical (sanitized-Mixamo) name. */
+    bonesByName: ReadonlyMap<string, THREE.Bone>;
+    /** Hips-height ratio vs the reference rig (see `ScaledSkeletonDef`). */
+    hipsPositionScale: number;
+}
+/** Resolve a clip-track node name to a canonical bone name, or null. */
+export declare function resolveHumanoidBoneName(nodeName: string, bonesByName: ReadonlyMap<string, THREE.Bone>): string | null;
+/**
+ * Rebuild `clip` for a generated humanoid: node names canonicalized, the
+ * translation policy above applied. The input clip is never mutated. Throws
+ * (listing every offender) if any track fails to resolve to a standard bone
+ * TRS channel.
+ */
+export declare function retargetClipToHumanoid(clip: THREE.AnimationClip, target: HumanoidClipTarget): THREE.AnimationClip;
+/**
+ * Build a name → clip library from a loaded GLB's `animations` array —
+ * `buildClipMap` semantics (exact names, case-insensitive lookup,
+ * armature-prefix stripping, `walking`→`walk`-style aliases), plus a
+ * loud getter.
+ */
+export declare function createHumanoidClipLibrary(animations: THREE.AnimationClip[], aliases?: Record<string, string>): HumanoidClipLibrary;
+export interface HumanoidClipLibrary {
+    /** The full lookup map (exact + lowercase + aliased names). */
+    clips: ReadonlyMap<string, THREE.AnimationClip>;
+    /** Resolve a clip by name — throws listing available clips if absent. */
+    get(name: string): THREE.AnimationClip;
+}
+//# sourceMappingURL=clips.d.ts.map

package/dist/humanoid/clips.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clips.d.ts","sourceRoot":"","sources":["../../src/humanoid/clips.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B;mCACmC;AACnC,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7C,wEAAwE;IACxE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,wEAAwE;AACxE,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,GAC3C,MAAM,GAAG,IAAI,CAUf;AAgCD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,KAAK,CAAC,aAAa,EACzB,MAAM,EAAE,kBAAkB,GACzB,KAAK,CAAC,aAAa,CAkBrB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,KAAK,CAAC,aAAa,EAAE,EACjC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACnC,mBAAmB,CAarB;AAED,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAChD,yEAAyE;IACzE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC;CACxC"}