@lovelace_lol/loom3 1.0.2 → 1.0.4

package/README.md

@@ -1,6 +1,6 @@
 # Loom3
 
-The missing character controller for Three.js, allowing you to bring humanoid and animal characters to life. Loom3 is based on the Facial Action Coding System (FACS) as the basis of its mappings, providing a morph and bone mapping library for controlling high-definition 3D characters in Three.js.
+The missing character controller for Three.js! Loom3 allows you to bring humanoid and animal characters to life. Loom3 is based on the Facial Action Coding System (FACS) as the basis of its mappings, providing a morph and bone mapping library for controlling high-definition 3D characters in Three.js.
 
 Loom3 provides mappings that connect [Facial Action Coding System (FACS)](https://en.wikipedia.org/wiki/Facial_Action_Coding_System) Action Units to the morph targets and bone transforms found in Character Creator 4 (CC4) characters. Instead of manually figuring out which blend shapes correspond to which facial movements, you can simply say `setAU(12, 0.8)` and the library handles the rest.
 

package/dist/index.cjs

@@ -150,6 +150,32 @@ var BakedAnimationController = class {
     __publicField(this, "actionIdToClip", /* @__PURE__ */ new Map());
     this.host = host;
   }
+  getMeshNamesForAU(auId, config, explicitMeshNames) {
+    if (explicitMeshNames && explicitMeshNames.length > 0) {
+      return explicitMeshNames;
+    }
+    if (typeof this.host.getMeshNamesForAU === "function") {
+      return this.host.getMeshNamesForAU(auId) || [];
+    }
+    const facePart = config.auInfo?.[String(auId)]?.facePart;
+    if (facePart) {
+      const category = config.auFacePartToMeshCategory?.[facePart];
+      if (category) return config.morphToMesh?.[category] || [];
+    }
+    return config.morphToMesh?.face || [];
+  }
+  getMeshNamesForViseme(config, explicitMeshNames) {
+    if (explicitMeshNames && explicitMeshNames.length > 0) {
+      return explicitMeshNames;
+    }
+    if (typeof this.host.getMeshNamesForViseme === "function") {
+      return this.host.getMeshNamesForViseme() || [];
+    }
+    const category = config.visemeMeshCategory || (config.morphToMesh?.viseme ? "viseme" : "face");
+    const visemeMeshes = config.morphToMesh?.[category];
+    if (visemeMeshes && visemeMeshes.length > 0) return visemeMeshes;
+    return config.morphToMesh?.face || [];
+  }
   update(dtSeconds) {
     if (this.animationMixer) {
       this.animationMixer.update(dtSeconds);
@@ -443,13 +469,15 @@ var BakedAnimationController = class {
       if (isNumericAU(curveId)) {
         const auId = Number(curveId);
         if (isVisemeIndex(curveId)) {
+          const visemeMeshNames = this.getMeshNamesForViseme(config, meshNames);
           const visemeKey = config.visemeKeys[auId];
           if (typeof visemeKey === "number") {
-            this.addMorphIndexTracks(tracks, visemeKey, keyframes, intensityScale, meshNames);
+            this.addMorphIndexTracks(tracks, visemeKey, keyframes, intensityScale, visemeMeshNames);
           } else if (visemeKey) {
-            this.addMorphTracks(tracks, visemeKey, keyframes, intensityScale, meshNames);
+            this.addMorphTracks(tracks, visemeKey, keyframes, intensityScale, visemeMeshNames);
           }
         } else {
+          const auMeshNames = this.getMeshNamesForAU(auId, config, meshNames);
           const morphsBySide = config.auToMorphs[auId];
           const mixWeight = this.host.isMixedAU(auId) ? this.host.getAUMixWeight(auId) : 1;
           const leftKeys = morphsBySide?.left ?? [];
@@ -460,26 +488,26 @@ var BakedAnimationController = class {
             let effectiveScale = intensityScale * mixWeight;
             if (curveBalance > 0) effectiveScale *= 1 - curveBalance;
             if (typeof morphKey === "number") {
-              this.addMorphIndexTracks(tracks, morphKey, keyframes, effectiveScale, meshNames);
+              this.addMorphIndexTracks(tracks, morphKey, keyframes, effectiveScale, auMeshNames);
             } else {
-              this.addMorphTracks(tracks, morphKey, keyframes, effectiveScale, meshNames);
+              this.addMorphTracks(tracks, morphKey, keyframes, effectiveScale, auMeshNames);
             }
           }
           for (const morphKey of rightKeys) {
             let effectiveScale = intensityScale * mixWeight;
             if (curveBalance < 0) effectiveScale *= 1 + curveBalance;
             if (typeof morphKey === "number") {
-              this.addMorphIndexTracks(tracks, morphKey, keyframes, effectiveScale, meshNames);
+              this.addMorphIndexTracks(tracks, morphKey, keyframes, effectiveScale, auMeshNames);
             } else {
-              this.addMorphTracks(tracks, morphKey, keyframes, effectiveScale, meshNames);
+              this.addMorphTracks(tracks, morphKey, keyframes, effectiveScale, auMeshNames);
             }
           }
           for (const morphKey of centerKeys) {
             const effectiveScale = intensityScale * mixWeight;
             if (typeof morphKey === "number") {
-              this.addMorphIndexTracks(tracks, morphKey, keyframes, effectiveScale, meshNames);
+              this.addMorphIndexTracks(tracks, morphKey, keyframes, effectiveScale, auMeshNames);
             } else {
-              this.addMorphTracks(tracks, morphKey, keyframes, effectiveScale, meshNames);
+              this.addMorphTracks(tracks, morphKey, keyframes, effectiveScale, auMeshNames);
             }
           }
         }
@@ -867,11 +895,9 @@ var BakedAnimationController = class {
   }
   addMorphTracks(tracks, morphKey, keyframes, intensityScale, meshNames) {
     const config = this.host.getConfig();
-    const meshes = this.host.getMeshes();
     const hasExplicitMeshes = !!(meshNames && meshNames.length > 0);
     const targetMeshNames = hasExplicitMeshes ? meshNames : config.morphToMesh?.face || [];
-    const targetMeshes = targetMeshNames.length ? targetMeshNames.map((name) => this.host.getMeshByName(name)).filter(Boolean) : meshes;
-    let added = false;
+    const targetMeshes = targetMeshNames.length ? targetMeshNames.map((name) => this.host.getMeshByName(name)).filter(Boolean) : [];
     const addTrackForMesh = (mesh) => {
       const dict = mesh.morphTargetDictionary;
       if (!dict || dict[morphKey] === void 0) return;
@@ -885,25 +911,17 @@ var BakedAnimationController = class {
       const trackName = `${mesh.uuid}.morphTargetInfluences[${morphIndex}]`;
       const track = new THREE.NumberKeyframeTrack(trackName, times, values);
       tracks.push(track);
-      added = true;
     };
     for (const mesh of targetMeshes) {
       addTrackForMesh(mesh);
     }
-    if (!added && !hasExplicitMeshes && targetMeshes !== meshes) {
-      for (const mesh of meshes) {
-        addTrackForMesh(mesh);
-      }
-    }
   }
   addMorphIndexTracks(tracks, morphIndex, keyframes, intensityScale, meshNames) {
     if (!Number.isInteger(morphIndex) || morphIndex < 0) return;
     const config = this.host.getConfig();
-    const meshes = this.host.getMeshes();
     const hasExplicitMeshes = !!(meshNames && meshNames.length > 0);
     const targetMeshNames = hasExplicitMeshes ? meshNames : config.morphToMesh?.face || [];
-    const targetMeshes = targetMeshNames.length ? targetMeshNames.map((name) => this.host.getMeshByName(name)).filter(Boolean) : meshes;
-    let added = false;
+    const targetMeshes = targetMeshNames.length ? targetMeshNames.map((name) => this.host.getMeshByName(name)).filter(Boolean) : [];
     const addTrackForMesh = (mesh) => {
       const infl = mesh.morphTargetInfluences;
       if (!infl || morphIndex < 0 || morphIndex >= infl.length) return;
@@ -916,16 +934,10 @@ var BakedAnimationController = class {
       const trackName = `${mesh.uuid}.morphTargetInfluences[${morphIndex}]`;
       const track = new THREE.NumberKeyframeTrack(trackName, times, values);
       tracks.push(track);
-      added = true;
     };
     for (const mesh of targetMeshes) {
       addTrackForMesh(mesh);
     }
-    if (!added && !hasExplicitMeshes && targetMeshes !== meshes) {
-      for (const mesh of meshes) {
-        addTrackForMesh(mesh);
-      }
-    }
   }
   ensureMixer() {
     const model = this.host.getModel();
@@ -1787,6 +1799,12 @@ var MORPH_TO_MESH = {
   tongue: ["CC_Base_Tongue", "CC_Base_Tongue_1"],
   hair: ["Side_part_wavy", "Side_part_wavy_1", "Side_part_wavy_2"]
 };
+var AU_FACEPART_TO_MESH_CATEGORY = {
+  Eye: "eye",
+  Eyes: "eye",
+  Eyelids: "eye",
+  Tongue: "tongue"
+};
 var CC4_HAIR_PHYSICS = {
   stiffness: 7.5,
   damping: 0.18,
@@ -1832,7 +1850,9 @@ var CC4_PRESET = {
   bonePrefix: CC4_BONE_PREFIX,
   suffixPattern: CC4_SUFFIX_PATTERN,
   morphToMesh: MORPH_TO_MESH,
+  auFacePartToMeshCategory: AU_FACEPART_TO_MESH_CATEGORY,
   visemeKeys: VISEME_KEYS,
+  visemeMeshCategory: "viseme",
   visemeJawAmounts: VISEME_JAW_AMOUNTS,
   auMixDefaults: AU_MIX_DEFAULTS,
   auInfo: AU_INFO,
@@ -2152,9 +2172,10 @@ var HairPhysicsController = class {
     if (meshName) {
       targetMesh = this.registeredHairObjects.get(meshName);
     } else {
-      for (const [name, mesh] of this.registeredHairObjects) {
-        const info = CC4_MESHES[name];
-        if (info?.category === "hair") {
+      const hairMeshNames = this.getHairMeshNames();
+      for (const name of hairMeshNames) {
+        const mesh = this.registeredHairObjects.get(name) || this.host.getMeshByName(name);
+        if (mesh) {
           targetMesh = mesh;
           break;
         }
@@ -2248,6 +2269,15 @@ var HairPhysicsController = class {
   }
   getHairMeshNames() {
     if (this.cachedHairMeshNames) return this.cachedHairMeshNames;
+    if (typeof this.host.getSelectedHairMeshNames === "function") {
+      const selectedHairMeshNames = this.host.getSelectedHairMeshNames() || [];
+      const resolved = selectedHairMeshNames.filter((name) => {
+        const mesh = this.registeredHairObjects.get(name) || this.host.getMeshByName(name);
+        return !!mesh;
+      });
+      this.cachedHairMeshNames = Array.from(new Set(resolved));
+      return this.cachedHairMeshNames;
+    }
     const names = [];
     this.registeredHairObjects.forEach((mesh, name) => {
       const info = CC4_MESHES[name];
@@ -2263,6 +2293,18 @@ var HairPhysicsController = class {
     this.cachedHairMeshNames = names;
     return names;
   }
+  refreshMeshSelection() {
+    this.cachedHairMeshNames = null;
+    this.idleClipDirty = true;
+    this.gravityClipDirty = true;
+    this.impulseClipDirty = true;
+    this.warnMissingHairMorphTargets();
+    if (this.hairPhysicsEnabled) {
+      this.startIdleClip();
+      this.startGravityClip();
+      this.buildImpulseClips();
+    }
+  }
   supportsMixerClips() {
     return typeof this.host.buildClip === "function";
   }
@@ -2277,7 +2319,11 @@ var HairPhysicsController = class {
       return;
     }
     const hairMeshNames = this.getHairMeshNames();
-    if (hairMeshNames.length === 0) return;
+    if (hairMeshNames.length === 0) {
+      this.stopIdleClip();
+      this.idleClipDirty = false;
+      return;
+    }
     if (!this.idleClipDirty && this.idleClipHandle) return;
     this.stopIdleClip();
     const duration = Math.max(0.5, cfg.idleClipDuration);
@@ -2295,7 +2341,11 @@ var HairPhysicsController = class {
   startGravityClip() {
     if (!this.hairPhysicsEnabled || !this.supportsMixerClips()) return;
     const hairMeshNames = this.getHairMeshNames();
-    if (hairMeshNames.length === 0) return;
+    if (hairMeshNames.length === 0) {
+      this.stopGravityClip();
+      this.gravityClipDirty = false;
+      return;
+    }
     if (!this.gravityClipDirty && this.gravityClipHandle) return;
     this.stopGravityClip();
     const morphTargets = this.hairPhysicsConfig.morphTargets;
@@ -2348,7 +2398,11 @@ var HairPhysicsController = class {
   buildImpulseClips() {
     if (!this.hairPhysicsEnabled || !this.supportsMixerClips()) return;
     const hairMeshNames = this.getHairMeshNames();
-    if (hairMeshNames.length === 0) return;
+    if (hairMeshNames.length === 0) {
+      this.stopImpulseClips();
+      this.impulseClipDirty = false;
+      return;
+    }
     if (!this.impulseClipDirty && this.impulseClips.left && this.impulseClips.right && this.impulseClips.front) {
       return;
     }
@@ -2684,7 +2738,9 @@ function resolveProfile(base, override) {
     auToBones: mergeRecord(base.auToBones, override.auToBones),
     boneNodes: mergeRecord(base.boneNodes, override.boneNodes),
     morphToMesh: mergeRecord(base.morphToMesh, override.morphToMesh),
+    auFacePartToMeshCategory: base.auFacePartToMeshCategory || override.auFacePartToMeshCategory ? mergeRecord(base.auFacePartToMeshCategory || {}, override.auFacePartToMeshCategory || {}) : void 0,
     visemeKeys: override.visemeKeys ? [...override.visemeKeys] : [...base.visemeKeys],
+    visemeMeshCategory: override.visemeMeshCategory ?? base.visemeMeshCategory,
     auMixDefaults: base.auMixDefaults || override.auMixDefaults ? mergeRecord(base.auMixDefaults || {}, override.auMixDefaults || {}) : void 0,
     auInfo: base.auInfo || override.auInfo ? mergeRecord(base.auInfo || {}, override.auInfo || {}) : void 0,
     eyeMeshNodes: override.eyeMeshNodes ?? base.eyeMeshNodes,
@@ -3522,6 +3578,7 @@ var _Loom3 = class _Loom3 {
     this.auToCompositeMap = buildAUToCompositeMap(this.compositeRotations);
     this.hairPhysics = new HairPhysicsController({
       getMeshByName: (name) => this.meshByName.get(name),
+      getSelectedHairMeshNames: () => this.config.morphToMesh?.hair || [],
       buildClip: (clipName, curves, options) => this.buildClip(clipName, curves, options),
       cleanupSnippet: (name) => this.cleanupSnippet(name)
     });
@@ -3529,6 +3586,8 @@ var _Loom3 = class _Loom3 {
       getModel: () => this.model,
       getMeshes: () => this.meshes,
       getMeshByName: (name) => this.meshByName.get(name),
+      getMeshNamesForAU: (auId) => this.getMeshNamesForAU(auId),
+      getMeshNamesForViseme: () => this.getMeshNamesForViseme(),
       getBones: () => this.bones,
       getConfig: () => this.config,
       getCompositeRotations: () => this.compositeRotations,
@@ -3574,15 +3633,11 @@ var _Loom3 = class _Loom3 {
     this.resolvedFaceMeshes = this.resolveFaceMeshes(this.meshes);
     this.faceMesh = this.resolvedFaceMeshes.length > 0 ? this.meshByName.get(this.resolvedFaceMeshes[0]) || null : null;
     if (!this.config.morphToMesh?.face || this.config.morphToMesh.face.length === 0) {
-      const morphMeshNames = this.meshes.filter((m) => {
-        const infl = m.morphTargetInfluences;
-        const dict = m.morphTargetDictionary;
-        return Array.isArray(infl) && infl.length > 0 || dict && Object.keys(dict).length > 0;
-      }).map((m) => m.name).filter(Boolean);
-      if (morphMeshNames.length > 0) {
+      const faceMeshNames = this.resolvedFaceMeshes.filter((name) => this.meshByName.has(name));
+      if (faceMeshNames.length > 0) {
         this.config.morphToMesh = {
           ...this.config.morphToMesh,
-          face: Array.from(new Set(morphMeshNames))
+          face: Array.from(new Set(faceMeshNames))
         };
       }
     }
@@ -3629,7 +3684,8 @@ var _Loom3 = class _Loom3 {
     }
     for (let i = 0; i < (this.config.visemeKeys || []).length; i += 1) {
       const key = this.config.visemeKeys[i];
-      const targets = typeof key === "number" ? this.resolveMorphTargetsByIndex(key) : this.resolveMorphTargets(key);
+      const visemeMeshNames = this.getMeshNamesForViseme();
+      const targets = typeof key === "number" ? this.resolveMorphTargetsByIndex(key, visemeMeshNames) : this.resolveMorphTargets(key, visemeMeshNames);
       this.resolvedVisemeTargets[i] = targets;
     }
   }
@@ -4061,10 +4117,11 @@ var _Loom3 = class _Loom3 {
       this.applyMorphTargets(targets, val);
     } else {
       const morphKey = this.config.visemeKeys[visemeIndex];
+      const visemeMeshNames = this.getMeshNamesForViseme();
       if (typeof morphKey === "number") {
-        this.setMorphInfluence(morphKey, val);
+        this.setMorphInfluence(morphKey, val, visemeMeshNames);
       } else if (typeof morphKey === "string") {
-        this.setMorph(morphKey, val);
+        this.setMorph(morphKey, val, visemeMeshNames);
       }
     }
     const jawAmount = _Loom3.VISEME_JAW_AMOUNTS[visemeIndex] * val * jawScale;
@@ -4082,7 +4139,8 @@ var _Loom3 = class _Loom3 {
     const morphKey = this.config.visemeKeys[visemeIndex];
     const target = clamp012(to);
     this.visemeValues[visemeIndex] = target;
-    const morphHandle = typeof morphKey === "number" ? this.transitionMorphInfluence(morphKey, target, durationMs) : this.transitionMorph(morphKey, target, durationMs);
+    const visemeMeshNames = this.getMeshNamesForViseme();
+    const morphHandle = typeof morphKey === "number" ? this.transitionMorphInfluence(morphKey, target, durationMs, visemeMeshNames) : this.transitionMorph(morphKey, target, durationMs, visemeMeshNames);
     const jawAmount = _Loom3.VISEME_JAW_AMOUNTS[visemeIndex] * target * jawScale;
     if (Math.abs(jawScale) <= 1e-6 || Math.abs(jawAmount) <= 1e-6) {
       return morphHandle;
@@ -4386,6 +4444,7 @@ var _Loom3 = class _Loom3 {
     if (this.model) {
       this.rebuildMorphTargetsCache();
     }
+    this.hairPhysics.refreshMeshSelection();
     this.applyHairPhysicsProfileConfig();
   }
   getProfile() {
@@ -4393,20 +4452,24 @@ var _Loom3 = class _Loom3 {
   }
   /**
    * Get the mesh names that should receive morph influences for a given AU.
-   * Routes by facePart: Tongue → tongue, Eye → eye, everything else → face.
+   * Routing is driven by `auFacePartToMeshCategory` in profile config.
    */
   getMeshNamesForAU(auId) {
     const m = this.config.morphToMesh;
     const info = this.config.auInfo?.[String(auId)];
-    if (!info?.facePart) return m?.face || [];
-    switch (info.facePart) {
-      case "Tongue":
-        return m?.tongue || [];
-      case "Eye":
-        return m?.eye || [];
-      default:
-        return m?.face || [];
+    const facePart = info?.facePart;
+    if (facePart) {
+      const category = this.config.auFacePartToMeshCategory?.[facePart];
+      if (category) {
+        return m?.[category] || [];
+      }
     }
+    return m?.face || [];
+  }
+  getMeshNamesForViseme() {
+    const m = this.config.morphToMesh;
+    const category = this.config.visemeMeshCategory || (m?.viseme ? "viseme" : "face");
+    return m?.[category] || m?.face || [];
   }
   // ============================================================================
   // HAIR PHYSICS