@vgai/engine 0.5.0 → 0.5.1

package/dist/humanoid/clips.js

@@ -1,121 +0,0 @@
-/**
- * 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';
-import { buildClipMap } from '../animation/clip-map';
-import { HUMANOID_HIPS_BONE } from './skeleton';
-/** Resolve a clip-track node name to a canonical bone name, or null. */
-export function resolveHumanoidBoneName(nodeName, bonesByName) {
-    if (bonesByName.has(nodeName))
-        return nodeName;
-    // `mixamorig:Hips` → `mixamorigHips` (what GLTFLoader itself does).
-    const sanitized = THREE.PropertyBinding.sanitizeNodeName(nodeName);
-    if (bonesByName.has(sanitized))
-        return sanitized;
-    // `mixamorig_Hips` → `Hips`; bare `Hips` passes through unchanged.
-    const bare = sanitized.replace(/^mixamorig_?/i, '');
-    const canonical = `mixamorig${bare}`;
-    if (bonesByName.has(canonical))
-        return canonical;
-    return null;
-}
-/** Retarget one track: a rebuilt track to keep, 'drop' (by policy), or
- *  'unresolved' (not a standard bone TRS channel). */
-function retargetTrack(track, target) {
-    const dot = track.name.lastIndexOf('.');
-    if (dot <= 0)
-        return 'unresolved';
-    const bone = resolveHumanoidBoneName(track.name.slice(0, dot), target.bonesByName);
-    if (!bone)
-        return 'unresolved';
-    const property = track.name.slice(dot + 1);
-    if (property === 'quaternion') {
-        const kept = track.clone();
-        kept.name = `${bone}.quaternion`;
-        return kept;
-    }
-    if (property === 'position') {
-        if (bone !== HUMANOID_HIPS_BONE)
-            return 'drop'; // policy: rest owns segment lengths
-        const kept = track.clone();
-        kept.name = `${bone}.position`;
-        const s = target.hipsPositionScale;
-        if (s !== 1)
-            kept.values = kept.values.map((v) => v * s);
-        return kept;
-    }
-    if (property === 'scale')
-        return 'drop'; // policy: rest scale is always 1
-    // Not a bone TRS channel (morphs etc.) — nothing on a generated humanoid
-    // can consume it; loud beats silent.
-    return 'unresolved';
-}
-/**
- * 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 function retargetClipToHumanoid(clip, target) {
-    const tracks = [];
-    const unresolved = [];
-    for (const track of clip.tracks) {
-        const result = retargetTrack(track, target);
-        if (result === 'unresolved')
-            unresolved.push(track.name);
-        else if (result !== 'drop')
-            tracks.push(result);
-    }
-    if (unresolved.length > 0) {
-        throw new Error(`humanoid: clip '${clip.name}' has ${unresolved.length} track(s) that do not resolve ` +
-            `to standard humanoid bones: ${unresolved.join(', ')}`);
-    }
-    return new THREE.AnimationClip(clip.name, clip.duration, tracks, clip.blendMode);
-}
-/**
- * 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 function createHumanoidClipLibrary(animations, aliases = {}) {
-    const map = buildClipMap(animations, aliases);
-    return {
-        clips: map,
-        get(name) {
-            const clip = map.get(name) ?? map.get(name.toLowerCase());
-            if (!clip) {
-                const have = [...new Set(animations.map((c) => c.name))].join(', ');
-                throw new Error(`humanoid: no clip named '${name}' in library (have: ${have})`);
-            }
-            return clip;
-        },
-    };
-}

package/dist/humanoid/compose.d.ts

@@ -1,75 +0,0 @@
-/**
- * Character-composition primitives — how a generated humanoid BECOMES a
- * distinct character (a viking, a policeman, …).
- *
- * PHILOSOPHY (owner directive): this file is deliberately NOT a customization
- * system. No recipe DSL, no slot/preset registry, no outfit library. It ships
- * the BARE MINIMUM an agent needs to compose ANY character with ordinary,
- * idiomatic three.js code written at generation time:
- *
- *   1. `skinToHumanoid(geometry, rig)` — skin arbitrary generated geometry
- *      (a tunic lathe, a sleeve cylinder, …) to the rig's shared skeleton so
- *      it deforms with the body,
- *   2. `attachToBone(rig, boneName, object)` — parent a rigid prop (helmet,
- *      axe, badge) to a named bone with a model-space authoring contract,
- *   3. `restJointPosition(rig, boneName)` — the one placement query: agents
- *      must size/place geometry against the PARAMETRIC body (joints move
- *      with body-type params), and reading `bone.matrixWorld` is wrong once
- *      a clip is playing — rest pose comes from the bind data instead.
- *
- * Everything else (shapes, colors, layering, which prop goes where) is the
- * agent's ordinary code. Worked agent-artifact examples:
- * `packages/engine/e2e/humanoid-character-proof/{viking,policeman}.ts`.
- *
- * AUTHORING SPACE: both primitives speak the rig's MODEL SPACE — Y-up metres,
- * rest pose, origin at the rig root (the same space `generateHumanoid` builds
- * the body in, and the space `rig.mesh.geometry` positions live in). The
- * armature's internal Z-up-centimetre frame (ARMATURE_SCALE) never leaks:
- * `skinToHumanoid` binds with the body's own bind matrix, and `attachToBone`
- * converts through the skeleton's inverse bind matrices.
- *
- * OWNERSHIP: both primitives parent their object under the rig (`rig.root`
- * for skinned meshes, the bone for props), and `rig.dispose()` frees every
- * geometry/material found under the root — dressing a rig hands the
- * resources' lifetime to it. Detach first to keep something alive.
- */
-import * as THREE from 'three';
-import type { HumanoidRig } from './generate';
-/** Rest-pose (bind-pose) position of a named joint in the rig's model space —
- *  stable regardless of the current animation pose, because it is read from
- *  the skeleton's inverse bind matrices rather than live bone transforms. */
-export declare function restJointPosition(rig: HumanoidRig, boneName: string, target?: THREE.Vector3): THREE.Vector3;
-/**
- * Skin arbitrary generated geometry to a humanoid rig's skeleton.
- *
- * `geometry` is authored in the rig's model space (Y-up metres, rest pose —
- * build a sleeve around the rest arm, a tunic around the rest torso). The
- * function computes 4-wide zero-padded `skinIndex`/`skinWeight` attributes on
- * the geometry (in place), wraps it in a `THREE.SkinnedMesh` bound to the
- * SAME `THREE.Skeleton` as the body, parents it under `rig.root`, and returns
- * it. From then on it deforms with the body and is freed by `rig.dispose()`.
- *
- * Weighting is the body's own analytic scheme, per vertex: pick the body
- * segment whose SURFACE is nearest (distance to the joint-to-joint axis minus
- * the part's radius — so a loose tunic still binds to the torso it covers),
- * project the vertex onto that segment's axis, and apply the same smoothstep
- * 2-bone joint blend the body uses (50/50 exactly at each joint). Geometry
- * spanning a joint therefore blends across it exactly like the body does —
- * give clothing a slightly larger radius than the body part underneath and
- * the two move together with no relative sliding.
- */
-export declare function skinToHumanoid(geometry: THREE.BufferGeometry, rig: HumanoidRig, material?: THREE.Material): THREE.SkinnedMesh;
-/**
- * Attach a rigid prop (helmet, axe, badge, …) to a named bone.
- *
- * Authoring contract: position/rotate/scale `object` in the rig's MODEL SPACE
- * (Y-up metres, rest pose — e.g. a helmet at `restJointPosition(rig,
- * 'mixamorigHead')` plus a bit of Y). The function converts that placement
- * into the bone's local frame — including the armature's internal
- * Z-up-centimetre transform, which is why the local values you'd read back
- * afterwards look like centimetres with a ~100× scale — parents the object to
- * the bone, and returns it. The prop then rides the bone through every pose,
- * and `rig.dispose()` frees its geometry/materials.
- */
-export declare function attachToBone<T extends THREE.Object3D>(rig: HumanoidRig, boneName: string, object: T): T;
-//# sourceMappingURL=compose.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"compose.d.ts","sourceRoot":"","sources":["../../src/humanoid/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAO/B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG9C;;6EAE6E;AAC7E,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,gBAAsB,GAC3B,KAAK,CAAC,OAAO,CAGf;AA0CD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,KAAK,CAAC,cAAc,EAC9B,GAAG,EAAE,WAAW,EAChB,QAAQ,GAAE,KAAK,CAAC,QAA6D,GAC5E,KAAK,CAAC,WAAW,CAyDnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,KAAK,CAAC,QAAQ,EACnD,GAAG,EAAE,WAAW,EAChB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,CAAC,GACR,CAAC,CAYH"}

package/dist/humanoid/compose.js

@@ -1,176 +0,0 @@
-/**
- * Character-composition primitives — how a generated humanoid BECOMES a
- * distinct character (a viking, a policeman, …).
- *
- * PHILOSOPHY (owner directive): this file is deliberately NOT a customization
- * system. No recipe DSL, no slot/preset registry, no outfit library. It ships
- * the BARE MINIMUM an agent needs to compose ANY character with ordinary,
- * idiomatic three.js code written at generation time:
- *
- *   1. `skinToHumanoid(geometry, rig)` — skin arbitrary generated geometry
- *      (a tunic lathe, a sleeve cylinder, …) to the rig's shared skeleton so
- *      it deforms with the body,
- *   2. `attachToBone(rig, boneName, object)` — parent a rigid prop (helmet,
- *      axe, badge) to a named bone with a model-space authoring contract,
- *   3. `restJointPosition(rig, boneName)` — the one placement query: agents
- *      must size/place geometry against the PARAMETRIC body (joints move
- *      with body-type params), and reading `bone.matrixWorld` is wrong once
- *      a clip is playing — rest pose comes from the bind data instead.
- *
- * Everything else (shapes, colors, layering, which prop goes where) is the
- * agent's ordinary code. Worked agent-artifact examples:
- * `packages/engine/e2e/humanoid-character-proof/{viking,policeman}.ts`.
- *
- * AUTHORING SPACE: both primitives speak the rig's MODEL SPACE — Y-up metres,
- * rest pose, origin at the rig root (the same space `generateHumanoid` builds
- * the body in, and the space `rig.mesh.geometry` positions live in). The
- * armature's internal Z-up-centimetre frame (ARMATURE_SCALE) never leaks:
- * `skinToHumanoid` binds with the body's own bind matrix, and `attachToBone`
- * converts through the skeleton's inverse bind matrices.
- *
- * OWNERSHIP: both primitives parent their object under the rig (`rig.root`
- * for skinned meshes, the bone for props), and `rig.dispose()` frees every
- * geometry/material found under the root — dressing a rig hands the
- * resources' lifetime to it. Detach first to keep something alive.
- */
-import * as THREE from 'three';
-import { computeBindingSegments, HEAD_CAPSULE_RADIUS, smoothstep, } from './body';
-import { scaleSkeletonDef } from './skeleton';
-/** Rest-pose (bind-pose) position of a named joint in the rig's model space —
- *  stable regardless of the current animation pose, because it is read from
- *  the skeleton's inverse bind matrices rather than live bone transforms. */
-export function restJointPosition(rig, boneName, target = new THREE.Vector3()) {
-    const inverse = rig.skeleton.boneInverses[requireBoneIndex(rig, boneName)];
-    return target.setFromMatrixPosition(restMatrix.copy(inverse).invert());
-}
-const restMatrix = new THREE.Matrix4();
-function requireBoneIndex(rig, boneName) {
-    const bone = rig.bonesByName.get(boneName);
-    const index = bone ? rig.bones.indexOf(bone) : -1;
-    if (index < 0) {
-        throw new Error(`humanoid: unknown bone '${boneName}' (standard names are the sanitized ` +
-            `Mixamo set, e.g. 'mixamorigHead', 'mixamorigRightHand')`);
-    }
-    return index;
-}
-/** Per-rig cache of the resolved binding segments (a rig is typically dressed
- *  with several meshes; the segment map is identical for all of them). */
-const segmentCache = new WeakMap();
-function bindingSegments(rig) {
-    let segments = segmentCache.get(rig);
-    if (segments)
-        return segments;
-    // The uniform height factor is a pure function of the rig's (resolved)
-    // params — recompute it exactly as `generateHumanoid` did rather than
-    // widening the public HumanoidRig surface with a field only this needs.
-    const { heightFactor } = scaleSkeletonDef(rig.params, HEAD_CAPSULE_RADIUS * rig.params.headSize);
-    segments = computeBindingSegments((name) => restJointPosition(rig, name), (name) => requireBoneIndex(rig, name), {
-        heightFactor,
-        limbThickness: rig.params.limbThickness,
-        torsoGirth: rig.params.torsoGirth,
-        headSize: rig.params.headSize,
-        hipWidth: rig.params.hipWidth,
-    });
-    segmentCache.set(rig, segments);
-    return segments;
-}
-/**
- * Skin arbitrary generated geometry to a humanoid rig's skeleton.
- *
- * `geometry` is authored in the rig's model space (Y-up metres, rest pose —
- * build a sleeve around the rest arm, a tunic around the rest torso). The
- * function computes 4-wide zero-padded `skinIndex`/`skinWeight` attributes on
- * the geometry (in place), wraps it in a `THREE.SkinnedMesh` bound to the
- * SAME `THREE.Skeleton` as the body, parents it under `rig.root`, and returns
- * it. From then on it deforms with the body and is freed by `rig.dispose()`.
- *
- * Weighting is the body's own analytic scheme, per vertex: pick the body
- * segment whose SURFACE is nearest (distance to the joint-to-joint axis minus
- * the part's radius — so a loose tunic still binds to the torso it covers),
- * project the vertex onto that segment's axis, and apply the same smoothstep
- * 2-bone joint blend the body uses (50/50 exactly at each joint). Geometry
- * spanning a joint therefore blends across it exactly like the body does —
- * give clothing a slightly larger radius than the body part underneath and
- * the two move together with no relative sliding.
- */
-export function skinToHumanoid(geometry, rig, material = new THREE.MeshStandardMaterial({ roughness: 0.8 })) {
-    const position = geometry.getAttribute('position');
-    if (!position)
-        throw new Error('humanoid: skinToHumanoid needs a position attribute');
-    const segments = bindingSegments(rig);
-    const n = position.count;
-    const skinIndex = new Uint16Array(n * 4);
-    const skinWeight = new Float32Array(n * 4);
-    const v = new THREE.Vector3();
-    const w = new THREE.Vector3();
-    for (let i = 0; i < n; i++) {
-        v.fromBufferAttribute(position, i);
-        // Nearest segment by distance to the part SURFACE (t clamped to the
-        // joint span for the distance test only).
-        let best = segments[0];
-        let bestT = 0;
-        let bestD = Number.POSITIVE_INFINITY;
-        for (const seg of segments) {
-            w.copy(v).sub(seg.p0);
-            const t = w.dot(seg.axis) / seg.len;
-            const tc = Math.min(1, Math.max(0, t));
-            const d = w.addScaledVector(seg.axis, -tc * seg.len).length() - seg.radius;
-            if (d < bestD) {
-                bestD = d;
-                best = seg;
-                bestT = t;
-            }
-        }
-        // The body's own 2-bone joint blend (skinSegment in body.ts), verbatim.
-        let other = best.bone;
-        let w2 = 0;
-        if (best.proximal >= 0 && bestT < best.blend) {
-            other = best.proximal;
-            w2 = 0.5 * (1 - smoothstep(bestT / best.blend));
-        }
-        else if (best.distal >= 0 && bestT > 1 - best.blend) {
-            other = best.distal;
-            w2 = 0.5 * smoothstep((bestT - (1 - best.blend)) / best.blend);
-        }
-        skinIndex.set([best.bone, other, 0, 0], i * 4);
-        skinWeight.set([1 - w2, w2, 0, 0], i * 4);
-    }
-    geometry.setAttribute('skinIndex', new THREE.BufferAttribute(skinIndex, 4));
-    geometry.setAttribute('skinWeight', new THREE.BufferAttribute(skinWeight, 4));
-    const mesh = new THREE.SkinnedMesh(geometry, material);
-    mesh.name = 'HumanoidSkinnedAttachment';
-    mesh.castShadow = true;
-    // Same as the body: an animated skinned mesh leaves its rest-pose bounds.
-    mesh.frustumCulled = false;
-    rig.root.add(mesh);
-    // Bind in the body's bind space (model space at generate time) — NOT the
-    // mesh's current matrixWorld, which already includes wherever the caller
-    // has moved `rig.root` by now.
-    mesh.bind(rig.skeleton, rig.mesh.bindMatrix.clone());
-    return mesh;
-}
-/**
- * Attach a rigid prop (helmet, axe, badge, …) to a named bone.
- *
- * Authoring contract: position/rotate/scale `object` in the rig's MODEL SPACE
- * (Y-up metres, rest pose — e.g. a helmet at `restJointPosition(rig,
- * 'mixamorigHead')` plus a bit of Y). The function converts that placement
- * into the bone's local frame — including the armature's internal
- * Z-up-centimetre transform, which is why the local values you'd read back
- * afterwards look like centimetres with a ~100× scale — parents the object to
- * the bone, and returns it. The prop then rides the bone through every pose,
- * and `rig.dispose()` frees its geometry/materials.
- */
-export function attachToBone(rig, boneName, object) {
-    const index = requireBoneIndex(rig, boneName);
-    const bone = rig.bones[index];
-    object.updateMatrix();
-    // local = inverse(boneRestWorld) × authoredModelMatrix; boneInverses IS
-    // inverse(boneRestWorld) in model space (root at identity at bind time).
-    // The bone's rest world scale is uniform (ARMATURE_SCALE), so the
-    // decompose below is exact.
-    const local = rig.skeleton.boneInverses[index].clone().multiply(object.matrix);
-    local.decompose(object.position, object.quaternion, object.scale);
-    bone.add(object);
-    return object;
-}

package/dist/humanoid/generate.d.ts

@@ -1,92 +0,0 @@
-/**
- * `generateHumanoid` — the engine's procedural humanoid character generator.
- *
- * vgai generates buildings and terrain procedurally; this is the same idea
- * for CHARACTERS: no downloaded model, no Quaternius/Mixamo mesh dependency —
- * a ready-to-animate skinned humanoid built entirely from code:
- *
- *   - the STANDARD skeleton (Mixamo-named, reference rest pose) rescaled by
- *     authored body-type params (`skeleton.ts`),
- *   - a fully procedural capsule/box body with analytic per-segment skin
- *     weights that stay correct across proportions (`body.ts`),
- *   - standard-clip playback with prefix-variant resolution and the
- *     translation-track retarget policy (`clips.ts`).
- *
- * The one external thing a game still supplies is ANIMATION CLIPS (from any
- * Mixamo-named GLB — e.g. the repo's vendored Soldier.glb Idle/Walk/Run).
- *
- * Usage (a game's `setup()` or any three.js world):
- *
- *   import { generateHumanoid, createHumanoidClipLibrary } from '@vgai/engine/humanoid';
- *
- *   const rig = generateHumanoid({ height: 1.6, limbThickness: 1.3, torsoGirth: 1.4 });
- *   scene.add(rig.root);
- *   const clips = createHumanoidClipLibrary(gltf.animations);
- *   rig.playClip(clips.get('Walk'));
- *   // per frame: rig.update(dt)   // e.g. from a SystemPhase.ANIMATION system
- *   // teardown:  rig.dispose()
- *
- * Scene-file authoring status: this is a code API (like `GameComponent`
- * schemas), NOT yet a `.vscn` generator — the scene `generator` seam
- * (`scene/geometry-registry.ts`) produces bare `BufferGeometry`, while a
- * humanoid is a SkinnedMesh + bone hierarchy + mixer. Wiring a scene-entity
- * spelling is future work (see docs/PROCEDURAL-HUMANOID.md).
- */
-import * as THREE from 'three';
-import { type HumanoidBodyPart } from './body';
-import { type HumanoidParams, type ResolvedHumanoidParams } from './schema';
-export interface GenerateHumanoidOptions {
-    /** Override the body material (default: a vertex-colored MeshStandardMaterial
-     *  that visualizes the body-part/blend-zone map). A caller-supplied material
-     *  is NOT disposed by `rig.dispose()`. */
-    material?: THREE.Material;
-}
-export interface PlayClipOptions {
-    /** Crossfade seconds from the previous action (0 = hard cut). Default 0.25. */
-    fade?: number;
-}
-/** A generated, ready-to-use humanoid character rig. */
-export interface HumanoidRig {
-    /** Add this to the scene; position/rotate/scale it like any Object3D. */
-    root: THREE.Group;
-    /** The single merged skinned body mesh (child of `root`). */
-    mesh: THREE.SkinnedMesh;
-    skeleton: THREE.Skeleton;
-    /** All bones in canonical row order (skinIndex order). */
-    bones: THREE.Bone[];
-    /** Bone lookup by canonical Mixamo name (`mixamorigHips`, …). */
-    bonesByName: ReadonlyMap<string, THREE.Bone>;
-    /** The resolved (defaulted) params this rig was generated from. */
-    params: ResolvedHumanoidParams;
-    /** Realized standing height in metres (crown of head, rest pose). */
-    height: number;
-    /** Hips-height ratio vs the reference rig — the hips `.position` track
-     *  remap factor (see `clips.ts`). */
-    hipsPositionScale: number;
-    vertexCount: number;
-    /** Per-part vertex ranges + allowed bone influences (test/debug surface). */
-    parts: readonly HumanoidBodyPart[];
-    /** The rig's own mixer, rooted at `root`. Drive it via `update(dt)`. */
-    mixer: THREE.AnimationMixer;
-    /**
-     * Play a standard humanoid clip: retargets it (prefix variants, the
-     * translation-track policy — cached per source clip), crossfades from the
-     * currently-playing action, returns the started `AnimationAction` for
-     * further control (timeScale, loop mode, …). Throws, listing every
-     * offender, if the clip has tracks that don't resolve to standard bones.
-     */
-    playClip(clip: THREE.AnimationClip, options?: PlayClipOptions): THREE.AnimationAction;
-    /** Advance the rig's animation. Call once per frame with seconds. */
-    update(dt: number): void;
-    /** Stop animation, release GPU resources (the body AND every geometry/
-     *  material parented under the rig — skinned clothing, bone props),
-     *  detach from parent. */
-    dispose(): void;
-}
-/**
- * Generate a skinned humanoid character from body-type params (validated by
- * `HumanoidParamsSchema`; `generateHumanoid()` with no args yields the
- * reference body). Pure and synchronous — no assets are loaded.
- */
-export declare function generateHumanoid(params?: HumanoidParams, options?: GenerateHumanoidOptions): HumanoidRig;
-//# sourceMappingURL=generate.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/humanoid/generate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAA0C,KAAK,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAEvF,OAAO,EAAE,KAAK,cAAc,EAAwB,KAAK,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAGlG,MAAM,WAAW,uBAAuB;IACtC;;8CAE0C;IAC1C,QAAQ,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC;IAClB,6DAA6D;IAC7D,IAAI,EAAE,KAAK,CAAC,WAAW,CAAC;IACxB,QAAQ,EAAE,KAAK,CAAC,QAAQ,CAAC;IACzB,0DAA0D;IAC1D,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;IAC7C,mEAAmE;IACnE,MAAM,EAAE,sBAAsB,CAAC;IAC/B,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf;yCACqC;IACrC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACnC,wEAAwE;IACxE,KAAK,EAAE,KAAK,CAAC,cAAc,CAAC;IAC5B;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC,aAAa,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,KAAK,CAAC,eAAe,CAAC;IACtF,qEAAqE;IACrE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;8BAE0B;IAC1B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,GAAE,cAAmB,EAC3B,OAAO,GAAE,uBAA4B,GACpC,WAAW,CAwFb"}

package/dist/humanoid/generate.js

@@ -1,124 +0,0 @@
-/**
- * `generateHumanoid` — the engine's procedural humanoid character generator.
- *
- * vgai generates buildings and terrain procedurally; this is the same idea
- * for CHARACTERS: no downloaded model, no Quaternius/Mixamo mesh dependency —
- * a ready-to-animate skinned humanoid built entirely from code:
- *
- *   - the STANDARD skeleton (Mixamo-named, reference rest pose) rescaled by
- *     authored body-type params (`skeleton.ts`),
- *   - a fully procedural capsule/box body with analytic per-segment skin
- *     weights that stay correct across proportions (`body.ts`),
- *   - standard-clip playback with prefix-variant resolution and the
- *     translation-track retarget policy (`clips.ts`).
- *
- * The one external thing a game still supplies is ANIMATION CLIPS (from any
- * Mixamo-named GLB — e.g. the repo's vendored Soldier.glb Idle/Walk/Run).
- *
- * Usage (a game's `setup()` or any three.js world):
- *
- *   import { generateHumanoid, createHumanoidClipLibrary } from '@vgai/engine/humanoid';
- *
- *   const rig = generateHumanoid({ height: 1.6, limbThickness: 1.3, torsoGirth: 1.4 });
- *   scene.add(rig.root);
- *   const clips = createHumanoidClipLibrary(gltf.animations);
- *   rig.playClip(clips.get('Walk'));
- *   // per frame: rig.update(dt)   // e.g. from a SystemPhase.ANIMATION system
- *   // teardown:  rig.dispose()
- *
- * Scene-file authoring status: this is a code API (like `GameComponent`
- * schemas), NOT yet a `.vscn` generator — the scene `generator` seam
- * (`scene/geometry-registry.ts`) produces bare `BufferGeometry`, while a
- * humanoid is a SkinnedMesh + bone hierarchy + mixer. Wiring a scene-entity
- * spelling is future work (see docs/PROCEDURAL-HUMANOID.md).
- */
-import * as THREE from 'three';
-import { buildHumanoidBody, HEAD_CAPSULE_RADIUS } from './body';
-import { retargetClipToHumanoid } from './clips';
-import { HumanoidParamsSchema } from './schema';
-import { buildHumanoidSkeleton, createArmatureGroup, scaleSkeletonDef } from './skeleton';
-/**
- * Generate a skinned humanoid character from body-type params (validated by
- * `HumanoidParamsSchema`; `generateHumanoid()` with no args yields the
- * reference body). Pure and synchronous — no assets are loaded.
- */
-export function generateHumanoid(params = {}, options = {}) {
-    const resolved = HumanoidParamsSchema.parse(params);
-    const scaledDef = scaleSkeletonDef(resolved, HEAD_CAPSULE_RADIUS * resolved.headSize);
-    const skeletonRig = buildHumanoidSkeleton(scaledDef.defs);
-    const root = new THREE.Group();
-    root.name = 'ProceduralHumanoid';
-    const armature = createArmatureGroup(skeletonRig);
-    root.add(armature);
-    // Rest-pose world matrices (root at identity) → bind pose + body geometry.
-    root.updateMatrixWorld(true);
-    const body = buildHumanoidBody(skeletonRig, {
-        heightFactor: scaledDef.heightFactor,
-        limbThickness: resolved.limbThickness,
-        torsoGirth: resolved.torsoGirth,
-        headSize: resolved.headSize,
-        hipWidth: resolved.hipWidth,
-    }, options.material);
-    root.add(body.mesh);
-    const mixer = new THREE.AnimationMixer(root);
-    const retargetCache = new Map();
-    let currentAction = null;
-    const rig = {
-        root,
-        mesh: body.mesh,
-        skeleton: body.skeleton,
-        bones: skeletonRig.bones,
-        bonesByName: skeletonRig.byName,
-        params: resolved,
-        height: scaledDef.height,
-        hipsPositionScale: scaledDef.hipsPositionScale,
-        vertexCount: body.vertexCount,
-        parts: body.parts,
-        mixer,
-        playClip(clip, playOptions = {}) {
-            const fade = playOptions.fade ?? 0.25;
-            let prepared = retargetCache.get(clip.uuid);
-            if (!prepared) {
-                prepared = retargetClipToHumanoid(clip, rig);
-                retargetCache.set(clip.uuid, prepared);
-            }
-            const action = mixer.clipAction(prepared);
-            const previous = currentAction;
-            if (previous && previous !== action && fade > 0) {
-                previous.fadeOut(fade);
-                action.reset().fadeIn(fade).play();
-            }
-            else {
-                previous?.stop();
-                action.reset().play();
-            }
-            currentAction = action;
-            return action;
-        },
-        update(dt) {
-            mixer.update(dt);
-        },
-        dispose() {
-            mixer.stopAllAction();
-            mixer.uncacheRoot(root);
-            body.skeleton.dispose();
-            // Free EVERYTHING parented under the rig — the body plus whatever the
-            // composition primitives (`skinToHumanoid` clothing, `attachToBone`
-            // props — see compose.ts's ownership contract) added since. The one
-            // exception stays: a caller-supplied body material is never disposed.
-            root.traverse((obj) => {
-                const withResources = obj;
-                withResources.geometry?.dispose();
-                const material = withResources.material;
-                if (!material)
-                    return;
-                for (const mat of Array.isArray(material) ? material : [material]) {
-                    if (mat !== options.material)
-                        mat.dispose();
-                }
-            });
-            root.removeFromParent();
-        },
-    };
-    return rig;
-}

package/dist/humanoid/index.d.ts

@@ -1,24 +0,0 @@
-/**
- * `@vgai/engine/humanoid` — procedural humanoid character generation.
- *
- * Generate skinned, animation-ready humanoid characters entirely from code
- * (the way the engine generates terrain/props): a standard Mixamo-named
- * skeleton rescaled by body-type params, a procedural capsule body with
- * analytic skin weights, and standard-clip playback with the humanoid
- * retarget policy. Start at `generateHumanoid`; turn the result into a
- * distinct CHARACTER with the composition primitives (`skinToHumanoid`,
- * `attachToBone`, `restJointPosition` — see compose.ts's philosophy note).
- * Full guide: docs/PROCEDURAL-HUMANOID.md.
- */
-export type { HumanoidBody, HumanoidBodyDims, HumanoidBodyPart } from './body';
-export { buildHumanoidBody, HEAD_CAPSULE_RADIUS } from './body';
-export type { HumanoidClipLibrary, HumanoidClipTarget } from './clips';
-export { createHumanoidClipLibrary, resolveHumanoidBoneName, retargetClipToHumanoid, } from './clips';
-export { attachToBone, restJointPosition, skinToHumanoid } from './compose';
-export type { GenerateHumanoidOptions, HumanoidRig, PlayClipOptions } from './generate';
-export { generateHumanoid } from './generate';
-export type { HumanoidParams, ResolvedHumanoidParams } from './schema';
-export { HumanoidParamsSchema } from './schema';
-export type { BoneDef, BuiltSkeleton, ScaledSkeletonDef } from './skeleton';
-export { ARMATURE_ROTATION_X, ARMATURE_SCALE, buildHumanoidSkeleton, createArmatureGroup, HUMANOID_HIPS_BONE, MIXAMO_SKELETON_DEF, scaleSkeletonDef, } from './skeleton';
-//# sourceMappingURL=index.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/humanoid/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAC;AAChE,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EACL,yBAAyB,EACzB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC5E,YAAY,EAAE,uBAAuB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AACvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,YAAY,EAAE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EACL,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,YAAY,CAAC"}

package/dist/humanoid/index.js

@@ -1,18 +0,0 @@
-/**
- * `@vgai/engine/humanoid` — procedural humanoid character generation.
- *
- * Generate skinned, animation-ready humanoid characters entirely from code
- * (the way the engine generates terrain/props): a standard Mixamo-named
- * skeleton rescaled by body-type params, a procedural capsule body with
- * analytic skin weights, and standard-clip playback with the humanoid
- * retarget policy. Start at `generateHumanoid`; turn the result into a
- * distinct CHARACTER with the composition primitives (`skinToHumanoid`,
- * `attachToBone`, `restJointPosition` — see compose.ts's philosophy note).
- * Full guide: docs/PROCEDURAL-HUMANOID.md.
- */
-export { buildHumanoidBody, HEAD_CAPSULE_RADIUS } from './body';
-export { createHumanoidClipLibrary, resolveHumanoidBoneName, retargetClipToHumanoid, } from './clips';
-export { attachToBone, restJointPosition, skinToHumanoid } from './compose';
-export { generateHumanoid } from './generate';
-export { HumanoidParamsSchema } from './schema';
-export { ARMATURE_ROTATION_X, ARMATURE_SCALE, buildHumanoidSkeleton, createArmatureGroup, HUMANOID_HIPS_BONE, MIXAMO_SKELETON_DEF, scaleSkeletonDef, } from './skeleton';