@lovelace_lol/loom3 1.0.12 → 1.0.14

package/README.md

@@ -27,6 +27,7 @@ Loom3 provides mappings that connect [Facial Action Coding System (FACS)](https:
 13. [Playback & State Control](#13-playback--state-control)
 14. [Hair Physics](#14-hair-physics)
 15. [Baked Animations](#15-baked-animations)
+16. [API Reference](#16-api-reference)
 
 ---
 
@@ -81,7 +82,7 @@ loader.load('/character.glb', (gltf) => {
 // This drives all transitions and animations
 ```
 
-If you’re implementing a custom renderer, target the `LoomLarge` interface exported from `@lovelace_lol/loom3`.
+If you’re implementing a custom renderer, target the `Loom3` interface exported from `@lovelace_lol/loom3` (legacy alias: `LoomLarge`).
 
 ### Quick start examples
 
@@ -162,26 +163,31 @@ import { CC4_PRESET } from '@lovelace_lol/loom3';
   },
 
   boneNodes: {
-    // Logical bone name → actual node name in skeleton
-    'HEAD': 'CC_Base_Head',
-    'JAW': 'CC_Base_JawRoot',
-    'EYE_L': 'CC_Base_L_Eye',
-    'EYE_R': 'CC_Base_R_Eye',
-    'TONGUE': 'CC_Base_Tongue01',
+    // Logical bone name → base node name used with bonePrefix
+    'HEAD': 'Head',
+    'JAW': 'JawRoot',
+    'EYE_L': 'L_Eye',
+    'EYE_R': 'R_Eye',
+    'TONGUE': 'Tongue01',
   },
 
+  bonePrefix: 'CC_Base_',
+  suffixPattern: '_\\d+$|\\.\\d+$',
+
   visemeKeys: [
     // 15 viseme morph names for lip-sync
-    'V_EE', 'V_Er', 'V_IH', 'V_Ah', 'V_Oh',
-    'V_W_OO', 'V_S_Z', 'V_Ch_J', 'V_F_V', 'V_TH',
-    'V_T_L_D_N', 'V_B_M_P', 'V_K_G_H_NG', 'V_AE', 'V_R'
+    'EE', 'Ah', 'Oh', 'OO', 'I',
+    'U', 'W', 'L', 'F_V', 'Th',
+    'S_Z', 'B_M_P', 'K_G_H_NG', 'AE', 'R'
   ],
 
   morphToMesh: {
     // Routes morph categories to specific meshes
     'face': ['CC_Base_Body'],
+    'viseme': ['CC_Base_Body', 'CC_Base_Body_1'],
     'tongue': ['CC_Base_Tongue'],
-    'eye': ['CC_Base_EyeOcclusion_L', 'CC_Base_EyeOcclusion_R'],
+    'eye': ['CC_Base_EyeOcclusion_1', 'CC_Base_EyeOcclusion_2'],
+    'hair': ['Side_part_wavy_1', 'Side_part_wavy_2'],
   },
 
   auMixDefaults: {
@@ -203,6 +209,25 @@ import { CC4_PRESET } from '@lovelace_lol/loom3';
 }
 ```
 
+### Name resolution and profile fields
+
+The runtime resolves bone nodes by composing `bonePrefix + boneNodes[key] + boneSuffix`, then falling back to suffix-pattern matching when a model uses numbered exports such as `_01` or `.001`. The same prefix/suffix rules are used by validation and correction helpers, which is why `CC4_PRESET` can keep base bone names like `Head` and `JawRoot` instead of repeating the full node names everywhere.
+
+For region and marker configs, `resolveBoneName()` treats any mapped bone name that already contains `_` or `.` as a fully qualified name and skips prefix/suffix composition.
+
+Two caveats are worth calling out:
+- `morphPrefix` and `morphSuffix` are part of `Profile`, but morph playback still resolves exact morph keys on the targeted meshes today. They are already used by validation and correction helpers.
+- `leftMorphSuffixes` and `rightMorphSuffixes` are profile metadata for laterality detection in tooling, not core runtime behavior.
+
+Other `Profile` fields that are easy to miss:
+- `morphToMesh` routes categories such as `face`, `viseme`, `eye`, `tongue`, and `hair` to specific mesh names.
+- `eyeMeshNodes` provides fallback eye nodes when a rig uses meshes instead of bones for eye control.
+- `auMixDefaults` sets the default morph/bone blend weight per AU.
+- `compositeRotations` defines the per-node pitch/yaw/roll axis layout used by the composite rotation system.
+- `continuumPairs` and `continuumLabels` describe bidirectional AU pairs and their UI labels.
+- `annotationRegions` defines the regions used by the marker and camera tooling.
+- `hairPhysics` stores the mixer-driven hair defaults, including direction signs and morph target mappings.
+
 ### Passing a preset to Loom3
 
 ```typescript
@@ -319,6 +344,7 @@ Loom3 includes validation and analysis helpers so you can verify presets against
 
 ```typescript
 import {
+  extractFromGLTF,
   extractModelData,
   analyzeModel,
   validateMappings,
@@ -327,16 +353,41 @@ import {
 } from '@lovelace_lol/loom3';
 
 const preset = resolvePreset('cc4');
-const modelData = extractModelData({ model, meshes, animations });
-const analysis = analyzeModel(modelData, { preset });
-const validation = validateMappings(modelData, preset);
-const corrections = generateMappingCorrections(modelData, preset);
+const modelData = extractModelData(model, meshes, animations);
+const gltfData = extractFromGLTF(gltf); // Same ModelData shape, one-step GLTF wrapper
+
+const analysis = await analyzeModel({
+  source: { type: 'gltf', gltf },
+  preset,
+  suggestCorrections: true,
+});
+
+// Validate against lower-level mesh + skeleton inputs when you already have them
+const validation = validateMappings(meshes, skeleton, preset, { suggestCorrections: true });
+const corrections = generateMappingCorrections(meshes, skeleton, preset, { useResolvedNames: true });
 ```
 
+If you already have a `ModelData` bundle, `analyzeModel()` is the higher-level path; `validateMappings()` and `generateMappingCorrections()` are intentionally lower-level mesh/skeleton helpers.
+
 Use these helpers to:
-- Find missing morphs/bones and mesh mismatches
-- Score preset compatibility
-- Suggest corrections before you ship a profile
+- Extract raw model facts with `extractModelData(model, meshes?, animations?)` or `extractFromGLTF(gltf)`
+- Validate a preset against mesh/skeleton data with `validateMappings(meshes, skeleton, preset, options)`
+- Generate best-effort fixes with `generateMappingCorrections(meshes, skeleton, preset, options)`
+- Run a single end-to-end pass with `analyzeModel({ source, preset, suggestCorrections })`
+
+`validateMappings()` returns a `ValidationResult` with:
+- `valid` and `score`
+- `missingMorphs`, `missingBones`, `foundMorphs`, `foundBones`
+- `missingMeshes`, `foundMeshes`, `unmappedMorphs`, `unmappedBones`, `unmappedMeshes`
+- `warnings`
+- optional `suggestedConfig`, `corrections`, and `unresolved` when suggestion mode is enabled
+
+`generateMappingCorrections()` returns:
+- `correctedConfig`
+- `corrections`
+- `unresolved`
+
+`analyzeModel()` returns a `ModelAnalysisReport` containing the extracted model data, optional validation results, animation summary, `overallScore`, and a plain-language `summary`.
 
 ### Controlling mesh visibility
 
@@ -387,16 +438,16 @@ This is especially useful for:
 
 ## 4. Extending & Custom Presets
 
-![Diagram showing preset inheritance and mergePreset overrides](./assets/readme/preset-inheritance.svg)
+![Diagram showing preset inheritance and profile override merging](./assets/readme/preset-inheritance.svg)
 
 ### Extending an existing preset
 
-Use `mergePreset` to override specific mappings while keeping the rest:
+Use `resolveProfile` to override specific mappings while keeping the rest:
 
 ```typescript
-import { CC4_PRESET, mergePreset } from '@lovelace_lol/loom3';
+import { CC4_PRESET, resolveProfile } from '@lovelace_lol/loom3';
 
-const MY_PRESET = mergePreset(CC4_PRESET, {
+const MY_PRESET = resolveProfile(CC4_PRESET, {
 
   // Override AU12 (smile) with custom morph names
   auToMorphs: {
@@ -420,7 +471,7 @@ const loom = new Loom3({ profile: MY_PRESET });
 ### Creating a preset from scratch
 
 ```typescript
-import { Profile } from '@lovelace_lol/loom3';
+import type { Profile } from '@lovelace_lol/loom3';
 
 const CUSTOM_PRESET: Profile = {
   auToMorphs: {
@@ -1075,19 +1126,21 @@ Visemes are mouth shapes used for lip-sync. Loom3 includes 15 visemes with autom
 
 ### The 15 visemes
 
+The `VISEME_KEYS` export uses unprefixed keys in this order.
+
 | Index | Key | Phoneme Example |
 |-------|-----|-----------------|
 | 0 | EE | "b**ee**" |
-| 1 | Er | "h**er**" |
-| 2 | IH | "s**i**t" |
-| 3 | Ah | "f**a**ther" |
-| 4 | Oh | "g**o**" |
-| 5 | W_OO | "t**oo**" |
-| 6 | S_Z | "**s**un, **z**oo" |
-| 7 | Ch_J | "**ch**ip, **j**ump" |
+| 1 | Ah | "f**a**ther" |
+| 2 | Oh | "g**o**" |
+| 3 | OO | "t**oo**" |
+| 4 | I | "s**i**t" |
+| 5 | U | "fl**u**te" |
+| 6 | W | "**w**e" |
+| 7 | L | "**l**ip" |
 | 8 | F_V | "**f**un, **v**an" |
-| 9 | TH | "**th**ink" |
-| 10 | T_L_D_N | "**t**op, **l**ip, **d**og, **n**o" |
+| 9 | Th | "**th**ink" |
+| 10 | S_Z | "**s**un, **z**oo" |
 | 11 | B_M_P | "**b**at, **m**an, **p**op" |
 | 12 | K_G_H_NG | "**k**ite, **g**o, **h**at, si**ng**" |
 | 13 | AE | "c**a**t" |
@@ -1117,16 +1170,7 @@ loom.transitionViseme(3, 1.0, 80, 0);
 
 ### Automatic jaw coupling
 
-Each viseme has a predefined jaw opening amount. When you set a viseme, the jaw automatically opens proportionally:
-
-| Viseme | Jaw Amount |
-|--------|------------|
-| EE | 0.15 |
-| Ah | 0.70 |
-| Oh | 0.50 |
-| B_M_P | 0.20 |
-
-The `jawScale` parameter multiplies this amount:
+Each viseme has a predefined jaw opening amount in the preset. When you set a viseme, the jaw automatically opens proportionally, and the `jawScale` parameter multiplies that amount:
 - `jawScale = 1.0`: Normal jaw opening
 - `jawScale = 0.5`: Half jaw opening
 - `jawScale = 0`: No jaw movement (viseme only)
@@ -1653,6 +1697,33 @@ loom.transitionAU(45, 1.0, 100);  // Blink
 
 ---
 
+## 16. API Reference
+
+This is a compact reference for the public surface exported by `@lovelace_lol/loom3`.
+
+### Engine surface
+
+`Loom3` (legacy alias: `LoomLarge`) covers:
+- Initialization and lifecycle: `onReady()`, `update()`, `start()`, `stop()`, `dispose()`
+- AU, morph, viseme, and continuum control: `setAU()`, `transitionAU()`, `setMorph()`, `transitionMorph()`, `setViseme()`, `transitionViseme()`, `setContinuum()`, `transitionContinuum()`
+- Preset state: `setProfile()`, `getProfile()`
+- Validation and analysis helpers: `validateMappings()`, `generateMappingCorrections()`, `extractModelData()`, `extractFromGLTF()`, `analyzeModel()`
+- Mixer and baked animation helpers: `loadAnimationClips()`, `getAnimationClips()`, `playAnimation()`, `playClip()`, `playSnippet()`, `snippetToClip()`
+- Hair physics helpers: `setHairPhysicsEnabled()`, `setHairPhysicsConfig()`, `validateHairMorphTargets()`
+
+### Core types and helpers
+
+- `Profile` groups the mapping tables, name-resolution fields, `morphToMesh`, `visemeKeys`, `auMixDefaults`, `compositeRotations`, `continuumPairs`, `continuumLabels`, `eyeMeshNodes`, `annotationRegions`, and `hairPhysics`.
+- `TransitionHandle` exposes `promise`, `pause()`, `resume()`, and `cancel()`.
+- `ClipHandle` exposes `clipName`, `play()`, `stop()`, `pause()`, `resume()`, optional live-update setters, `getTime()`, `getDuration()`, and `finished`.
+- `collectMorphMeshes()` gathers meshes that already have morph targets.
+- `resolvePreset()` picks a built-in preset by name.
+- `resolvePresetWithOverrides()` resolves a preset and merges partial overrides.
+- `resolveProfile()` merges a base preset with a partial profile override.
+- `isMixedAU()` checks whether an AU has both morph and bone support in the CC4 preset.
+
+---
+
 ## Resources
 
 ![Reference cards for FACS, Paul Ekman Group, Character Creator 4, and Three.js](./assets/readme/resources-cards.svg)

package/dist/index.cjs

@@ -192,6 +192,17 @@ var BakedAnimationController = class {
     __publicField(this, "actionIdToClip", /* @__PURE__ */ new Map());
     this.host = host;
   }
+  getActionId(action) {
+    if (!action) return void 0;
+    return this.actionIds.get(action) ?? action.__actionId;
+  }
+  setActionId(action, clipName) {
+    const actionId = makeActionId();
+    this.actionIds.set(action, actionId);
+    this.actionIdToClip.set(actionId, clipName);
+    action.__actionId = actionId;
+    return actionId;
+  }
   getMeshNamesForAU(auId, config, explicitMeshNames) {
     if (explicitMeshNames && explicitMeshNames.length > 0) {
       return explicitMeshNames;
@@ -696,19 +707,13 @@ var BakedAnimationController = class {
       mixerWeight
     } = options || {};
     let action = this.clipActions.get(clip.name);
-    let actionId = action ? this.actionIds.get(action) || action.__actionId : void 0;
+    let actionId = this.getActionId(action);
     if (action && !actionId) {
-      actionId = makeActionId();
-      this.actionIds.set(action, actionId);
-      this.actionIdToClip.set(actionId, clip.name);
-      action.__actionId = actionId;
+      actionId = this.setActionId(action, clip.name);
     }
     if (!action) {
       action = this.animationMixer.clipAction(clip);
-      actionId = makeActionId();
-      this.actionIds.set(action, actionId);
-      this.actionIdToClip.set(actionId, clip.name);
-      action.__actionId = actionId;
+      actionId = this.setActionId(action, clip.name);
     }
     const existingClip = this.animationClips.find((c) => c.name === clip.name);
     if (!existingClip) {
@@ -861,10 +866,10 @@ var BakedAnimationController = class {
     const debugSnapshot = () => ({
       target: name,
       params,
-      clipActions: Array.from(this.clipActions.entries()).map(([k, a]) => ({ name: k, actionId: this.actionIds.get(a) || a.__actionId })),
-      animationActions: Array.from(this.animationActions.entries()).map(([k, a]) => ({ name: k, actionId: this.actionIds.get(a) || a.__actionId })),
+      clipActions: Array.from(this.clipActions.entries()).map(([k, a]) => ({ name: k, actionId: this.getActionId(a) })),
+      animationActions: Array.from(this.animationActions.entries()).map(([k, a]) => ({ name: k, actionId: this.getActionId(a) })),
       clipHandles: Array.from(this.clipHandles.entries()).map(([k, h]) => ({ name: k, actionId: h.actionId })),
-      mixerActions: (this.animationMixer?._actions || []).map((a) => ({ name: a?.getClip?.()?.name || "", actionId: this.actionIds.get(a) || a.__actionId }))
+      mixerActions: (this.animationMixer?._actions || []).map((a) => ({ name: a?.getClip?.()?.name || "", actionId: this.getActionId(a) }))
     });
     console.log("[Loom3] updateClipParams start", debugSnapshot());
     const apply = (action) => {
@@ -1498,53 +1503,53 @@ var BONE_AU_TO_BINDINGS = {
   42: [{ node: "TONGUE", channel: "rx", scale: 1, maxDegrees: 20 }]
 };
 var VISEME_KEYS = [
-  "EE",
+  "AE",
   "Ah",
-  "Oh",
-  "OO",
-  "I",
-  "U",
-  "W",
-  "L",
-  "F_V",
-  "Th",
-  "S_Z",
   "B_M_P",
+  "Ch_J",
+  "EE",
+  "Er",
+  "F_V",
+  "Ih",
   "K_G_H_NG",
-  "AE",
-  "R"
+  "Oh",
+  "R",
+  "S_Z",
+  "T_L_D_N",
+  "Th",
+  "W_OO"
 ];
 var VISEME_JAW_AMOUNTS = [
-  0.2,
-  // 0: EE
+  0.75,
+  // 0: AE
   0.8,
   // 1: Ah
-  0.6,
-  // 2: Oh
-  0.5,
-  // 3: OO
-  0.2,
-  // 4: I
-  0.5,
-  // 5: U
-  0.4,
-  // 6: W
+  0,
+  // 2: B_M_P
   0.3,
-  // 7: L
-  0.1,
-  // 8: F_V
-  0.15,
-  // 9: Th
+  // 3: Ch_J
+  0.2,
+  // 4: EE
+  0.35,
+  // 5: Er
   0.1,
-  // 10: S_Z
-  0,
-  // 11: B_M_P
+  // 6: F_V
+  0.2,
+  // 7: Ih
   0.35,
-  // 12: K_G_H_NG
-  0.75,
-  // 13: AE
-  0.35
-  // 14: R
+  // 8: K_G_H_NG
+  0.6,
+  // 9: Oh
+  0.35,
+  // 10: R
+  0.1,
+  // 11: S_Z
+  0.3,
+  // 12: T_L_D_N
+  0.15,
+  // 13: Th
+  0.5
+  // 14: W_OO
 ];
 var isMixedAU = (id) => {
   const morphs = AU_TO_MORPHS[id];
@@ -2064,7 +2069,7 @@ var HairPhysicsController = class {
     this.clearRegisteredHairObjects();
     const result = [];
     for (const obj of objects) {
-      if (obj.isMesh) {
+      if (obj instanceof THREE.Mesh) {
         const mesh = obj;
         this.registeredHairObjects.set(mesh.name, mesh);
         const meshInfo = CC4_MESHES[mesh.name];
@@ -2140,7 +2145,7 @@ var HairPhysicsController = class {
       }
     } : this.hairPhysicsConfig.morphTargets;
     this.hairPhysicsConfig = { ...this.hairPhysicsConfig, ...config, direction, morphTargets };
-    const idleChanged = [
+    const idleKeys = [
       "idleSwayAmount",
       "idleSwaySpeed",
       "windStrength",
@@ -2149,14 +2154,16 @@ var HairPhysicsController = class {
       "windTurbulence",
       "windFrequency",
       "idleClipDuration"
-    ].some((key) => config[key] !== void 0);
+    ];
+    const idleChanged = idleKeys.some((key) => config[key] !== void 0);
     const morphTargetsChanged = config.morphTargets !== void 0;
     const directionChanged = config.direction !== void 0;
-    const impulseChanged = [
+    const impulseKeys = [
       "stiffness",
       "damping",
       "impulseClipDuration"
-    ].some((key) => config[key] !== void 0);
+    ];
+    const impulseChanged = impulseKeys.some((key) => config[key] !== void 0);
     const gravityChanged = morphTargetsChanged;
     if (idleChanged || morphTargetsChanged) {
       this.idleClipDirty = true;
@@ -2297,7 +2304,7 @@ var HairPhysicsController = class {
     if (state.position) {
       obj.position.set(state.position.x, state.position.y, state.position.z);
     }
-    if (state.color && obj.material) {
+    if (state.color && obj.material && !Array.isArray(obj.material)) {
       const mat = obj.material;
       if (mat.color) {
         mat.color.set(state.color.baseColor);
@@ -2675,35 +2682,29 @@ var HairPhysicsController = class {
 };
 
 // src/mappings/resolveProfile.ts
-var cloneArray = (value) => value.map((item) => {
-  if (item && typeof item === "object") {
-    return { ...item };
-  }
-  return item;
-});
+var isPlainObject = (value) => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
 var cloneValue = (value) => {
   if (Array.isArray(value)) {
-    return cloneArray(value);
+    return value.map((item) => cloneValue(item));
   }
-  if (value && typeof value === "object") {
+  if (isPlainObject(value)) {
     return { ...value };
   }
   return value;
 };
 var mergeRecord = (base, override) => {
-  if (!override) {
-    const next2 = {};
-    for (const [key, value] of Object.entries(base)) {
-      next2[key] = cloneValue(value);
-    }
-    return next2;
-  }
   const next = {};
   for (const [key, value] of Object.entries(base)) {
     next[key] = cloneValue(value);
   }
-  for (const [key, value] of Object.entries(override)) {
-    next[key] = cloneValue(value);
+  if (override) {
+    for (const [key, value] of Object.entries(override)) {
+      if (value !== void 0) {
+        next[key] = cloneValue(value);
+      }
+    }
   }
   return next;
 };