loomlarge 1.0.0 → 1.0.1

package/dist/index.d.cts

@@ -36,6 +36,38 @@ interface AUMappingConfig {
  * Helper type for mesh categories in morphToMesh
  */
 type MorphCategory = 'face' | 'viseme' | 'eye' | 'tearLine' | 'tongue' | 'hair';
+/**
+ * Mesh category types for character mesh classification
+ */
+type MeshCategory = 'body' | 'eye' | 'eyeOcclusion' | 'tearLine' | 'teeth' | 'tongue' | 'hair' | 'eyebrow' | 'cornea' | 'eyelash';
+/**
+ * Blending mode names (matches Three.js constants)
+ */
+type BlendingMode = 'Normal' | 'Additive' | 'Subtractive' | 'Multiply' | 'None';
+/**
+ * Blending mode options for Three.js materials
+ * Maps mode name to Three.js blending constant value
+ */
+declare const BLENDING_MODES: Record<BlendingMode, number>;
+/**
+ * Material settings for mesh rendering
+ */
+interface MeshMaterialSettings {
+    renderOrder?: number;
+    transparent?: boolean;
+    opacity?: number;
+    depthWrite?: boolean;
+    depthTest?: boolean;
+    blending?: BlendingMode;
+}
+/**
+ * Mesh info including category, morph count, and optional material settings
+ */
+interface MeshInfo$1 {
+    category: MeshCategory;
+    morphCount: number;
+    material?: MeshMaterialSettings;
+}
 
 /**
  * LoomLarge - Core Type Definitions
@@ -68,6 +100,8 @@ interface BoneBinding {
     scale: -1 | 1;
     maxDegrees?: number;
     maxUnits?: number;
+    /** Rotation axis this binding affects (pitch/yaw/roll). Required for rotation channels. */
+    axis?: 'pitch' | 'yaw' | 'roll';
 }
 /**
  * RotationAxis - Defines which AUs control a specific rotation axis
@@ -203,10 +237,21 @@ interface LoomLarge {
     onReady(payload: ReadyPayload): void;
     /**
      * Update animation state. Call each frame with delta time in seconds.
+     * If using start(), this is called automatically.
      */
     update(deltaSeconds: number): void;
+    /**
+     * Start the internal animation loop (RAF-based).
+     * Automatically calls update() each frame with delta time.
+     */
+    start(): void;
+    /**
+     * Stop the internal animation loop.
+     */
+    stop(): void;
     /**
      * Dispose engine resources and cleanup.
+     * Stops the animation loop and clears all transitions.
      */
     dispose(): void;
     /**
@@ -369,16 +414,43 @@ declare class LoomLargeThree implements LoomLarge {
     private bones;
     private mixWeights;
     private visemeValues;
+    private clock;
+    private rafId;
+    private running;
     private static readonly VISEME_JAW_AMOUNTS;
     private static readonly JAW_MAX_DEGREES;
     constructor(config?: LoomLargeConfig, animation?: Animation);
     onReady(payload: ReadyPayload): void;
     update(deltaSeconds: number): void;
+    /** Start the internal RAF loop */
+    start(): void;
+    /** Stop the internal RAF loop */
+    stop(): void;
     dispose(): void;
     setAU(id: number | string, v: number, balance?: number): void;
     transitionAU(id: number | string, to: number, durationMs?: number, balance?: number): TransitionHandle;
     getAU(id: number): number;
+    /**
+     * Set a morph target value.
+     *
+     * Fast paths (in order of speed):
+     * 1. Pass pre-resolved { infl, idx } array directly - zero lookups
+     * 2. String key with cache hit - one Map lookup
+     * 3. String key cache miss - dictionary lookup, then cached for next time
+     */
     setMorph(key: string, v: number, meshNames?: string[]): void;
+    setMorph(key: string, v: number, targets: {
+        infl: number[];
+        idx: number;
+    }[]): void;
+    /**
+     * Resolve morph key to direct targets for ultra-fast repeated access.
+     * Use this when you need to set the same morph many times (e.g., in animation loops).
+     */
+    resolveMorphTargets(key: string, meshNames?: string[]): {
+        infl: number[];
+        idx: number;
+    }[];
     transitionMorph(key: string, to: number, durationMs?: number, meshNames?: string[]): TransitionHandle;
     setViseme(visemeIndex: number, value: number, jawScale?: number): void;
     transitionViseme(visemeIndex: number, to: number, durationMs?: number, jawScale?: number): TransitionHandle;
@@ -391,7 +463,34 @@ declare class LoomLargeThree implements LoomLarge {
     getActiveTransitionCount(): number;
     resetToNeutral(): void;
     getMeshList(): MeshInfo[];
+    /** Get all morph targets grouped by mesh name */
+    getMorphTargets(): Record<string, string[]>;
+    /** Get all resolved bone names and their current transforms */
+    getBones(): Record<string, {
+        position: [number, number, number];
+        rotation: [number, number, number];
+    }>;
     setMeshVisible(meshName: string, visible: boolean): void;
+    /** Blending mode options for Three.js materials */
+    private static readonly BLENDING_MODES;
+    /** Get material config for a mesh */
+    getMeshMaterialConfig(meshName: string): {
+        renderOrder: number;
+        transparent: boolean;
+        opacity: number;
+        depthWrite: boolean;
+        depthTest: boolean;
+        blending: string;
+    } | null;
+    /** Set material config for a mesh */
+    setMeshMaterialConfig(meshName: string, config: {
+        renderOrder?: number;
+        transparent?: boolean;
+        opacity?: number;
+        depthWrite?: boolean;
+        depthTest?: boolean;
+        blending?: string;
+    }): void;
     setAUMappings(mappings: AUMappingConfig): void;
     getAUMappings(): AUMappingConfig;
     private computeSideValues;
@@ -407,6 +506,11 @@ declare class LoomLargeThree implements LoomLarge {
     private applyCompositeRotation;
     private resolveBones;
     private combineHandles;
+    /**
+     * Apply render order and material settings from CC4_MESHES to all meshes.
+     * This ensures proper layering (e.g., hair renders on top of eyebrows).
+     */
+    private applyMeshMaterialSettings;
 }
 /**
  * Helper function to collect meshes with morph targets from a scene.
@@ -539,6 +643,51 @@ interface HairPhysics$1 {
  * and AU metadata that we painstakingly worked through.
  */
 
+declare const AU_TO_MORPHS: Record<number, string[]>;
+declare const VISEME_KEYS: string[];
+declare const BONE_AU_TO_BINDINGS: Record<number, BoneBinding[]>;
+/** Check if an AU has both morphs and bones (can blend between them) */
+declare const isMixedAU: (id: number) => boolean;
+/** Check if an AU has separate left/right morphs */
+declare const hasLeftRightMorphs: (auId: number) => boolean;
+declare const COMPOSITE_ROTATIONS: CompositeRotation[];
+/**
+ * Continuum pair mappings - precomputed from COMPOSITE_ROTATIONS
+ * Maps AU ID to its continuum partner info for bidirectional axes
+ * (e.g., AU 51 "Head Left" is paired with AU 52 "Head Right")
+ */
+declare const CONTINUUM_PAIRS_MAP: Record<number, {
+    pairId: number;
+    isNegative: boolean;
+    axis: 'pitch' | 'yaw' | 'roll';
+    node: 'JAW' | 'HEAD' | 'EYE_L' | 'EYE_R' | 'TONGUE';
+}>;
+/**
+ * Human-readable labels for continuum pairs
+ * Key format: "negativeAU-positiveAU"
+ * Used by UI components (ContinuumSlider, AUSection) to display friendly axis names
+ */
+declare const CONTINUUM_LABELS: Record<string, string>;
+declare const CC4_BONE_NODES: {
+    readonly EYE_L: "CC_Base_L_Eye";
+    readonly EYE_R: "CC_Base_R_Eye";
+    readonly HEAD: "CC_Base_Head";
+    readonly NECK: "CC_Base_NeckTwist01";
+    readonly NECK_TWIST: "CC_Base_NeckTwist02";
+    readonly JAW: "CC_Base_JawRoot";
+    readonly TONGUE: "CC_Base_Tongue01";
+};
+declare const CC4_EYE_MESH_NODES: {
+    readonly LEFT: "CC_Base_Eye";
+    readonly RIGHT: "CC_Base_Eye_1";
+};
+declare const AU_INFO: Record<string, AUInfo>;
+/** Default mix weights (0 = morph only, 1 = bone only) */
+declare const AU_MIX_DEFAULTS: Record<number, number>;
+/** Exact mesh name -> category mapping from the character GLB */
+declare const CC4_MESHES: Record<string, MeshInfo$1>;
+/** Which mesh each morph category applies to */
+declare const MORPH_TO_MESH: Record<MorphCategory, string[]>;
 declare const CC4_PRESET: AUMappingConfig;
 
 /**
@@ -628,4 +777,4 @@ declare class HairPhysics {
     reset(): void;
 }
 
-export { type AUInfo, type AUMappingConfig, type Animation, AnimationThree, type BoneBinding, type BoneKey, CC4_PRESET, type CompositeRotation, type CompositeRotationState, DEFAULT_HAIR_PHYSICS_CONFIG, type HairMorphOutput$1 as HairMorphOutput, HairPhysics, type HairPhysicsConfig$1 as HairPhysicsConfig, type HairPhysics$1 as HairPhysicsInterface, type HairMorphOutput as HairPhysicsMorphOutput, type HairPhysicsState, type HairState, type HairStrand, type HeadState$1 as HeadState, type LoomEuler, type LoomLarge, type LoomLargeConfig, LoomLargeThree, type LoomMesh, type LoomObject3D, type LoomQuaternion, type LoomVector3, type MeshInfo, type MorphCategory, type ReadyPayload, type RotationAxis, type RotationAxisState, type RotationsState, type TransitionHandle, collectMorphMeshes, LoomLargeThree as default };
+export { type AUInfo, type AUMappingConfig, AU_INFO, AU_MIX_DEFAULTS, AU_TO_MORPHS, type Animation, AnimationThree, BLENDING_MODES, BONE_AU_TO_BINDINGS, type BlendingMode, type BoneBinding, type BoneKey, CC4_BONE_NODES, CC4_EYE_MESH_NODES, CC4_MESHES, CC4_PRESET, COMPOSITE_ROTATIONS, CONTINUUM_LABELS, CONTINUUM_PAIRS_MAP, type CompositeRotation, type CompositeRotationState, DEFAULT_HAIR_PHYSICS_CONFIG, type HairMorphOutput$1 as HairMorphOutput, HairPhysics, type HairPhysicsConfig$1 as HairPhysicsConfig, type HairPhysics$1 as HairPhysicsInterface, type HairMorphOutput as HairPhysicsMorphOutput, type HairPhysicsState, type HairState, type HairStrand, type HeadState$1 as HeadState, type LoomEuler, type LoomLarge, type LoomLargeConfig, LoomLargeThree, type LoomMesh, type LoomObject3D, type LoomQuaternion, type LoomVector3, MORPH_TO_MESH, type MeshCategory, type MeshInfo, type MeshInfo$1 as MeshMaterialInfo, type MeshMaterialSettings, type MorphCategory, type ReadyPayload, type RotationAxis, type RotationAxisState, type RotationsState, type TransitionHandle, VISEME_KEYS, collectMorphMeshes, LoomLargeThree as default, hasLeftRightMorphs, isMixedAU };

package/dist/index.d.ts

@@ -36,6 +36,38 @@ interface AUMappingConfig {
  * Helper type for mesh categories in morphToMesh
  */
 type MorphCategory = 'face' | 'viseme' | 'eye' | 'tearLine' | 'tongue' | 'hair';
+/**
+ * Mesh category types for character mesh classification
+ */
+type MeshCategory = 'body' | 'eye' | 'eyeOcclusion' | 'tearLine' | 'teeth' | 'tongue' | 'hair' | 'eyebrow' | 'cornea' | 'eyelash';
+/**
+ * Blending mode names (matches Three.js constants)
+ */
+type BlendingMode = 'Normal' | 'Additive' | 'Subtractive' | 'Multiply' | 'None';
+/**
+ * Blending mode options for Three.js materials
+ * Maps mode name to Three.js blending constant value
+ */
+declare const BLENDING_MODES: Record<BlendingMode, number>;
+/**
+ * Material settings for mesh rendering
+ */
+interface MeshMaterialSettings {
+    renderOrder?: number;
+    transparent?: boolean;
+    opacity?: number;
+    depthWrite?: boolean;
+    depthTest?: boolean;
+    blending?: BlendingMode;
+}
+/**
+ * Mesh info including category, morph count, and optional material settings
+ */
+interface MeshInfo$1 {
+    category: MeshCategory;
+    morphCount: number;
+    material?: MeshMaterialSettings;
+}
 
 /**
  * LoomLarge - Core Type Definitions
@@ -68,6 +100,8 @@ interface BoneBinding {
     scale: -1 | 1;
     maxDegrees?: number;
     maxUnits?: number;
+    /** Rotation axis this binding affects (pitch/yaw/roll). Required for rotation channels. */
+    axis?: 'pitch' | 'yaw' | 'roll';
 }
 /**
  * RotationAxis - Defines which AUs control a specific rotation axis
@@ -203,10 +237,21 @@ interface LoomLarge {
     onReady(payload: ReadyPayload): void;
     /**
      * Update animation state. Call each frame with delta time in seconds.
+     * If using start(), this is called automatically.
      */
     update(deltaSeconds: number): void;
+    /**
+     * Start the internal animation loop (RAF-based).
+     * Automatically calls update() each frame with delta time.
+     */
+    start(): void;
+    /**
+     * Stop the internal animation loop.
+     */
+    stop(): void;
     /**
      * Dispose engine resources and cleanup.
+     * Stops the animation loop and clears all transitions.
      */
     dispose(): void;
     /**
@@ -369,16 +414,43 @@ declare class LoomLargeThree implements LoomLarge {
     private bones;
     private mixWeights;
     private visemeValues;
+    private clock;
+    private rafId;
+    private running;
     private static readonly VISEME_JAW_AMOUNTS;
     private static readonly JAW_MAX_DEGREES;
     constructor(config?: LoomLargeConfig, animation?: Animation);
     onReady(payload: ReadyPayload): void;
     update(deltaSeconds: number): void;
+    /** Start the internal RAF loop */
+    start(): void;
+    /** Stop the internal RAF loop */
+    stop(): void;
     dispose(): void;
     setAU(id: number | string, v: number, balance?: number): void;
     transitionAU(id: number | string, to: number, durationMs?: number, balance?: number): TransitionHandle;
     getAU(id: number): number;
+    /**
+     * Set a morph target value.
+     *
+     * Fast paths (in order of speed):
+     * 1. Pass pre-resolved { infl, idx } array directly - zero lookups
+     * 2. String key with cache hit - one Map lookup
+     * 3. String key cache miss - dictionary lookup, then cached for next time
+     */
     setMorph(key: string, v: number, meshNames?: string[]): void;
+    setMorph(key: string, v: number, targets: {
+        infl: number[];
+        idx: number;
+    }[]): void;
+    /**
+     * Resolve morph key to direct targets for ultra-fast repeated access.
+     * Use this when you need to set the same morph many times (e.g., in animation loops).
+     */
+    resolveMorphTargets(key: string, meshNames?: string[]): {
+        infl: number[];
+        idx: number;
+    }[];
     transitionMorph(key: string, to: number, durationMs?: number, meshNames?: string[]): TransitionHandle;
     setViseme(visemeIndex: number, value: number, jawScale?: number): void;
     transitionViseme(visemeIndex: number, to: number, durationMs?: number, jawScale?: number): TransitionHandle;
@@ -391,7 +463,34 @@ declare class LoomLargeThree implements LoomLarge {
     getActiveTransitionCount(): number;
     resetToNeutral(): void;
     getMeshList(): MeshInfo[];
+    /** Get all morph targets grouped by mesh name */
+    getMorphTargets(): Record<string, string[]>;
+    /** Get all resolved bone names and their current transforms */
+    getBones(): Record<string, {
+        position: [number, number, number];
+        rotation: [number, number, number];
+    }>;
     setMeshVisible(meshName: string, visible: boolean): void;
+    /** Blending mode options for Three.js materials */
+    private static readonly BLENDING_MODES;
+    /** Get material config for a mesh */
+    getMeshMaterialConfig(meshName: string): {
+        renderOrder: number;
+        transparent: boolean;
+        opacity: number;
+        depthWrite: boolean;
+        depthTest: boolean;
+        blending: string;
+    } | null;
+    /** Set material config for a mesh */
+    setMeshMaterialConfig(meshName: string, config: {
+        renderOrder?: number;
+        transparent?: boolean;
+        opacity?: number;
+        depthWrite?: boolean;
+        depthTest?: boolean;
+        blending?: string;
+    }): void;
     setAUMappings(mappings: AUMappingConfig): void;
     getAUMappings(): AUMappingConfig;
     private computeSideValues;
@@ -407,6 +506,11 @@ declare class LoomLargeThree implements LoomLarge {
     private applyCompositeRotation;
     private resolveBones;
     private combineHandles;
+    /**
+     * Apply render order and material settings from CC4_MESHES to all meshes.
+     * This ensures proper layering (e.g., hair renders on top of eyebrows).
+     */
+    private applyMeshMaterialSettings;
 }
 /**
  * Helper function to collect meshes with morph targets from a scene.
@@ -539,6 +643,51 @@ interface HairPhysics$1 {
  * and AU metadata that we painstakingly worked through.
  */
 
+declare const AU_TO_MORPHS: Record<number, string[]>;
+declare const VISEME_KEYS: string[];
+declare const BONE_AU_TO_BINDINGS: Record<number, BoneBinding[]>;
+/** Check if an AU has both morphs and bones (can blend between them) */
+declare const isMixedAU: (id: number) => boolean;
+/** Check if an AU has separate left/right morphs */
+declare const hasLeftRightMorphs: (auId: number) => boolean;
+declare const COMPOSITE_ROTATIONS: CompositeRotation[];
+/**
+ * Continuum pair mappings - precomputed from COMPOSITE_ROTATIONS
+ * Maps AU ID to its continuum partner info for bidirectional axes
+ * (e.g., AU 51 "Head Left" is paired with AU 52 "Head Right")
+ */
+declare const CONTINUUM_PAIRS_MAP: Record<number, {
+    pairId: number;
+    isNegative: boolean;
+    axis: 'pitch' | 'yaw' | 'roll';
+    node: 'JAW' | 'HEAD' | 'EYE_L' | 'EYE_R' | 'TONGUE';
+}>;
+/**
+ * Human-readable labels for continuum pairs
+ * Key format: "negativeAU-positiveAU"
+ * Used by UI components (ContinuumSlider, AUSection) to display friendly axis names
+ */
+declare const CONTINUUM_LABELS: Record<string, string>;
+declare const CC4_BONE_NODES: {
+    readonly EYE_L: "CC_Base_L_Eye";
+    readonly EYE_R: "CC_Base_R_Eye";
+    readonly HEAD: "CC_Base_Head";
+    readonly NECK: "CC_Base_NeckTwist01";
+    readonly NECK_TWIST: "CC_Base_NeckTwist02";
+    readonly JAW: "CC_Base_JawRoot";
+    readonly TONGUE: "CC_Base_Tongue01";
+};
+declare const CC4_EYE_MESH_NODES: {
+    readonly LEFT: "CC_Base_Eye";
+    readonly RIGHT: "CC_Base_Eye_1";
+};
+declare const AU_INFO: Record<string, AUInfo>;
+/** Default mix weights (0 = morph only, 1 = bone only) */
+declare const AU_MIX_DEFAULTS: Record<number, number>;
+/** Exact mesh name -> category mapping from the character GLB */
+declare const CC4_MESHES: Record<string, MeshInfo$1>;
+/** Which mesh each morph category applies to */
+declare const MORPH_TO_MESH: Record<MorphCategory, string[]>;
 declare const CC4_PRESET: AUMappingConfig;
 
 /**
@@ -628,4 +777,4 @@ declare class HairPhysics {
     reset(): void;
 }
 
-export { type AUInfo, type AUMappingConfig, type Animation, AnimationThree, type BoneBinding, type BoneKey, CC4_PRESET, type CompositeRotation, type CompositeRotationState, DEFAULT_HAIR_PHYSICS_CONFIG, type HairMorphOutput$1 as HairMorphOutput, HairPhysics, type HairPhysicsConfig$1 as HairPhysicsConfig, type HairPhysics$1 as HairPhysicsInterface, type HairMorphOutput as HairPhysicsMorphOutput, type HairPhysicsState, type HairState, type HairStrand, type HeadState$1 as HeadState, type LoomEuler, type LoomLarge, type LoomLargeConfig, LoomLargeThree, type LoomMesh, type LoomObject3D, type LoomQuaternion, type LoomVector3, type MeshInfo, type MorphCategory, type ReadyPayload, type RotationAxis, type RotationAxisState, type RotationsState, type TransitionHandle, collectMorphMeshes, LoomLargeThree as default };
+export { type AUInfo, type AUMappingConfig, AU_INFO, AU_MIX_DEFAULTS, AU_TO_MORPHS, type Animation, AnimationThree, BLENDING_MODES, BONE_AU_TO_BINDINGS, type BlendingMode, type BoneBinding, type BoneKey, CC4_BONE_NODES, CC4_EYE_MESH_NODES, CC4_MESHES, CC4_PRESET, COMPOSITE_ROTATIONS, CONTINUUM_LABELS, CONTINUUM_PAIRS_MAP, type CompositeRotation, type CompositeRotationState, DEFAULT_HAIR_PHYSICS_CONFIG, type HairMorphOutput$1 as HairMorphOutput, HairPhysics, type HairPhysicsConfig$1 as HairPhysicsConfig, type HairPhysics$1 as HairPhysicsInterface, type HairMorphOutput as HairPhysicsMorphOutput, type HairPhysicsState, type HairState, type HairStrand, type HeadState$1 as HeadState, type LoomEuler, type LoomLarge, type LoomLargeConfig, LoomLargeThree, type LoomMesh, type LoomObject3D, type LoomQuaternion, type LoomVector3, MORPH_TO_MESH, type MeshCategory, type MeshInfo, type MeshInfo$1 as MeshMaterialInfo, type MeshMaterialSettings, type MorphCategory, type ReadyPayload, type RotationAxis, type RotationAxisState, type RotationsState, type TransitionHandle, VISEME_KEYS, collectMorphMeshes, LoomLargeThree as default, hasLeftRightMorphs, isMixedAU };