loomlarge 0.2.0 → 0.2.5

package/dist/index.d.cts

@@ -35,7 +35,39 @@ interface AUMappingConfig {
 /**
  * Helper type for mesh categories in morphToMesh
  */
-type MorphCategory$1 = 'face' | 'viseme' | 'eye' | 'tearLine' | 'tongue' | 'hair';
+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
@@ -98,15 +130,11 @@ interface AUInfo {
     faceArea?: 'Upper' | 'Lower';
     facePart?: string;
 }
-/** Per-axis rotation state */
-interface RotationAxisState {
-    value: number;
-    maxRadians: number;
-}
+/** Per-axis rotation state - simple -1 to 1 values like stable version */
 interface CompositeRotationState {
-    pitch: RotationAxisState;
-    yaw: RotationAxisState;
-    roll: RotationAxisState;
+    pitch: number;
+    yaw: number;
+    roll: number;
 }
 type RotationsState = Record<string, CompositeRotationState>;
 
@@ -188,6 +216,7 @@ interface MeshInfo {
     name: string;
     visible: boolean;
     morphCount: number;
+    category?: string;
 }
 /**
  * LoomLarge Engine Interface
@@ -396,7 +425,49 @@ declare class LoomLargeThree implements LoomLarge {
     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 continuum AU pair immediately (no animation).
+     *
+     * Sign convention:
+     * - Negative value (-1 to 0): activates negAU (e.g., head left, eyes left)
+     * - Positive value (0 to +1): activates posAU (e.g., head right, eyes right)
+     *
+     * @param negAU - AU ID for negative direction (e.g., 61 for eyes left)
+     * @param posAU - AU ID for positive direction (e.g., 62 for eyes right)
+     * @param continuumValue - Value from -1 (full negative) to +1 (full positive)
+     */
+    setContinuum(negAU: number, posAU: number, continuumValue: number): void;
+    /**
+     * Smoothly transition a continuum AU pair (e.g., eyes left/right, head up/down).
+     * Takes a continuum value from -1 to +1 and internally manages both AU values.
+     *
+     * @param negAU - AU ID for negative direction (e.g., 61 for eyes left)
+     * @param posAU - AU ID for positive direction (e.g., 62 for eyes right)
+     * @param continuumValue - Target value from -1 (full negative) to +1 (full positive)
+     * @param durationMs - Transition duration in milliseconds
+     */
+    transitionContinuum(negAU: number, posAU: number, continuumValue: number, durationMs?: number): TransitionHandle;
+    /**
+     * 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;
@@ -409,7 +480,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;
@@ -417,11 +515,16 @@ declare class LoomLargeThree implements LoomLarge {
     private getMorphValue;
     private isMixedAU;
     private initBoneRotations;
+    /** Update rotation state - just stores -1 to 1 value like stable version */
     private updateBoneRotation;
     private updateBoneTranslation;
     private transitionBoneRotation;
     private transitionBoneTranslation;
     private flushPendingComposites;
+    /**
+     * Apply composite rotation using quaternion composition like stable version.
+     * Looks up maxDegrees and channel from BONE_AU_TO_BINDINGS.
+     */
     private applyCompositeRotation;
     private resolveBones;
     private combineHandles;
@@ -603,27 +706,8 @@ declare const CC4_EYE_MESH_NODES: {
 declare const AU_INFO: Record<string, AUInfo>;
 /** Default mix weights (0 = morph only, 1 = bone only) */
 declare const AU_MIX_DEFAULTS: Record<number, number>;
-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';
-/** 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 CC4MeshInfo {
-    category: MeshCategory;
-    morphCount: number;
-    material?: MeshMaterialSettings;
-}
 /** Exact mesh name -> category mapping from the character GLB */
-declare const CC4_MESHES: Record<string, CC4MeshInfo>;
-type MorphCategory = 'face' | 'viseme' | 'eye' | 'tearLine' | 'tongue' | 'hair';
+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;
@@ -715,4 +799,4 @@ declare class HairPhysics {
     reset(): void;
 }
 
-export { type AUInfo, type AUMappingConfig, AU_INFO, AU_MIX_DEFAULTS, AU_TO_MORPHS, type Animation, AnimationThree, BONE_AU_TO_BINDINGS, 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 MeshInfo, type MorphCategory$1 as MorphCategory, type ReadyPayload, type RotationAxis, type RotationAxisState, type RotationsState, type TransitionHandle, VISEME_KEYS, collectMorphMeshes, LoomLargeThree as default, hasLeftRightMorphs, isMixedAU };
+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 RotationsState, type TransitionHandle, VISEME_KEYS, collectMorphMeshes, LoomLargeThree as default, hasLeftRightMorphs, isMixedAU };

package/dist/index.d.ts

@@ -35,7 +35,39 @@ interface AUMappingConfig {
 /**
  * Helper type for mesh categories in morphToMesh
  */
-type MorphCategory$1 = 'face' | 'viseme' | 'eye' | 'tearLine' | 'tongue' | 'hair';
+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
@@ -98,15 +130,11 @@ interface AUInfo {
     faceArea?: 'Upper' | 'Lower';
     facePart?: string;
 }
-/** Per-axis rotation state */
-interface RotationAxisState {
-    value: number;
-    maxRadians: number;
-}
+/** Per-axis rotation state - simple -1 to 1 values like stable version */
 interface CompositeRotationState {
-    pitch: RotationAxisState;
-    yaw: RotationAxisState;
-    roll: RotationAxisState;
+    pitch: number;
+    yaw: number;
+    roll: number;
 }
 type RotationsState = Record<string, CompositeRotationState>;
 
@@ -188,6 +216,7 @@ interface MeshInfo {
     name: string;
     visible: boolean;
     morphCount: number;
+    category?: string;
 }
 /**
  * LoomLarge Engine Interface
@@ -396,7 +425,49 @@ declare class LoomLargeThree implements LoomLarge {
     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 continuum AU pair immediately (no animation).
+     *
+     * Sign convention:
+     * - Negative value (-1 to 0): activates negAU (e.g., head left, eyes left)
+     * - Positive value (0 to +1): activates posAU (e.g., head right, eyes right)
+     *
+     * @param negAU - AU ID for negative direction (e.g., 61 for eyes left)
+     * @param posAU - AU ID for positive direction (e.g., 62 for eyes right)
+     * @param continuumValue - Value from -1 (full negative) to +1 (full positive)
+     */
+    setContinuum(negAU: number, posAU: number, continuumValue: number): void;
+    /**
+     * Smoothly transition a continuum AU pair (e.g., eyes left/right, head up/down).
+     * Takes a continuum value from -1 to +1 and internally manages both AU values.
+     *
+     * @param negAU - AU ID for negative direction (e.g., 61 for eyes left)
+     * @param posAU - AU ID for positive direction (e.g., 62 for eyes right)
+     * @param continuumValue - Target value from -1 (full negative) to +1 (full positive)
+     * @param durationMs - Transition duration in milliseconds
+     */
+    transitionContinuum(negAU: number, posAU: number, continuumValue: number, durationMs?: number): TransitionHandle;
+    /**
+     * 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;
@@ -409,7 +480,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;
@@ -417,11 +515,16 @@ declare class LoomLargeThree implements LoomLarge {
     private getMorphValue;
     private isMixedAU;
     private initBoneRotations;
+    /** Update rotation state - just stores -1 to 1 value like stable version */
     private updateBoneRotation;
     private updateBoneTranslation;
     private transitionBoneRotation;
     private transitionBoneTranslation;
     private flushPendingComposites;
+    /**
+     * Apply composite rotation using quaternion composition like stable version.
+     * Looks up maxDegrees and channel from BONE_AU_TO_BINDINGS.
+     */
     private applyCompositeRotation;
     private resolveBones;
     private combineHandles;
@@ -603,27 +706,8 @@ declare const CC4_EYE_MESH_NODES: {
 declare const AU_INFO: Record<string, AUInfo>;
 /** Default mix weights (0 = morph only, 1 = bone only) */
 declare const AU_MIX_DEFAULTS: Record<number, number>;
-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';
-/** 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 CC4MeshInfo {
-    category: MeshCategory;
-    morphCount: number;
-    material?: MeshMaterialSettings;
-}
 /** Exact mesh name -> category mapping from the character GLB */
-declare const CC4_MESHES: Record<string, CC4MeshInfo>;
-type MorphCategory = 'face' | 'viseme' | 'eye' | 'tearLine' | 'tongue' | 'hair';
+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;
@@ -715,4 +799,4 @@ declare class HairPhysics {
     reset(): void;
 }
 
-export { type AUInfo, type AUMappingConfig, AU_INFO, AU_MIX_DEFAULTS, AU_TO_MORPHS, type Animation, AnimationThree, BONE_AU_TO_BINDINGS, 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 MeshInfo, type MorphCategory$1 as MorphCategory, type ReadyPayload, type RotationAxis, type RotationAxisState, type RotationsState, type TransitionHandle, VISEME_KEYS, collectMorphMeshes, LoomLargeThree as default, hasLeftRightMorphs, isMixedAU };
+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 RotationsState, type TransitionHandle, VISEME_KEYS, collectMorphMeshes, LoomLargeThree as default, hasLeftRightMorphs, isMixedAU };