@lovelace_lol/loom3 1.0.39 → 1.0.40

package/README.md

@@ -1356,6 +1356,25 @@ const targets = loom.resolveMorphTargets('Mouth_Smile_L', ['CC_Base_Body']);
 const value = targets.length > 0 ? (targets[0].infl[targets[0].idx] ?? 0) : 0;
 ```
 
+### Adding runtime morph targets
+
+Generated or sidecar morph targets can be registered after a model loads. Deltas use the same relative `POSITION` format as glTF morph targets: one XYZ delta per base mesh vertex. Optional `normal` and `tangent` deltas can be supplied when available.
+
+```typescript
+const index = loom.addMorphTarget({
+  meshName: 'CC_Base_Body',
+  name: 'BodyType_Muscular',
+  position: bodyTypeMuscularDeltas,
+});
+
+loom.setMorphInfluence(index, 0.6, ['CC_Base_Body']);
+loom.setMorph('BodyType_Muscular', 0.6, ['CC_Base_Body']);
+```
+
+By default, Loom3 replaces and disposes the mesh `BufferGeometry` before appending morph attributes. This is intentional: Three.js does not support mutating `geometry.morphAttributes` in place after a geometry has rendered. For pre-render authoring paths, pass `{ forceGeometryReplacement: false }`.
+
+If you need a named slot before real deltas are available, use `ensureMorphInfluence(meshName, morphName)`. It creates a zero-delta target and returns the assigned `morphTargetInfluences` index. After external code changes morph dictionaries or geometry, call `refreshMorphTargets()` so AU, viseme, hair, and clip-building caches see the updated targets.
+
 ### Morph caching
 
 Loom3 caches morph target lookups for performance. The first time you access a morph, it searches all meshes and caches the index. Subsequent accesses are O(1).
@@ -2128,6 +2147,7 @@ This is a compact reference for the public surface exported by `@lovelace_lol/lo
 - Lifecycle: `onReady()`, `update()`, `start()`, `stop()`, `dispose()`.
 - Preset state: `setProfile()`, `getProfile()`.
 - Control APIs: `setAU()`, `transitionAU()`, `setContinuum()`, `transitionContinuum()`, `setMorph()`, `transitionMorph()`, `setViseme()`, `transitionViseme()`.
+- Runtime morph authoring: `addMorphTarget()`, `addMorphTargets()`, `ensureMorphInfluence()`, `refreshMorphTargets()`.
 - Transition state: `pause()`, `resume()`, `getPaused()`, `clearTransitions()`, `getActiveTransitionCount()`, `resetToNeutral()`.
 
 ### Presets and profiles

package/dist/index.cjs

@@ -4638,11 +4638,7 @@ var _Loom3 = class _Loom3 {
     this.morphIndexCache.clear();
     model.traverse((obj) => {
       if (obj.isMesh && obj.name) {
-        const infl = obj.morphTargetInfluences;
-        const dict = obj.morphTargetDictionary;
-        if (Array.isArray(infl) && infl.length > 0 || dict && Object.keys(dict).length > 0) {
-          this.meshByName.set(obj.name, obj);
-        }
+        this.meshByName.set(obj.name, obj);
       }
     });
     this.bones = this.resolveBones(model);
@@ -5010,6 +5006,58 @@ var _Loom3 = class _Loom3 {
     const currentContinuum = currentPos - currentNeg;
     return this.animation.addTransition(driverKey, currentContinuum, target, durationMs, (value) => this.setContinuum(negAU, posAU, value, balance));
   }
+  // ============================================================================
+  // MORPH CONTROL
+  // ============================================================================
+  addMorphTarget(target, options = {}) {
+    const staleMorphTargets = this.collectResolvedExpressionMorphTargets();
+    const index = this.applyMorphTargetDelta(target, options);
+    this.refreshMorphTargets([target.meshName]);
+    this.reinitializeRuntimeStateFromCurrentControls(staleMorphTargets);
+    return index;
+  }
+  addMorphTargets(targets, options = {}) {
+    const staleMorphTargets = this.collectResolvedExpressionMorphTargets();
+    const result = {};
+    for (const target of targets) {
+      const index = this.applyMorphTargetDelta(target, options);
+      result[`${target.meshName}:${target.name}`] = index;
+    }
+    this.refreshMorphTargets(Array.from(new Set(targets.map((target) => target.meshName))));
+    this.reinitializeRuntimeStateFromCurrentControls(staleMorphTargets);
+    return result;
+  }
+  ensureMorphInfluence(meshName, morphName) {
+    const mesh = this.requireNamedMesh(meshName);
+    const dict = this.getMeshMorphDictionary(mesh);
+    const existing = dict[morphName];
+    if (existing !== void 0) return existing;
+    const position = mesh.geometry.getAttribute("position");
+    if (!position) {
+      throw new Error(`Cannot create morph target "${morphName}" on mesh "${meshName}": geometry has no position attribute.`);
+    }
+    return this.addMorphTarget({
+      meshName,
+      name: morphName,
+      position: new Float32Array(position.count * position.itemSize),
+      relative: true
+    });
+  }
+  refreshMorphTargets(_meshNames) {
+    this.morphKeyCache.clear();
+    this.morphIndexCache.clear();
+    if (this.model) {
+      this.meshByName.clear();
+      this.model.traverse((obj) => {
+        if (obj.isMesh && obj.name) {
+          this.meshByName.set(obj.name, obj);
+        }
+      });
+      this.meshes = collectMorphMeshes(this.model);
+    }
+    this.rebuildMorphTargetsCache();
+    this.hairPhysics.refreshMeshSelection();
+  }
   setMorph(key, v, meshNamesOrTargets) {
     const val = clamp012(v);
     if (Array.isArray(meshNamesOrTargets) && meshNamesOrTargets.length > 0 && typeof meshNamesOrTargets[0] === "object" && "infl" in meshNamesOrTargets[0]) {
@@ -5628,6 +5676,148 @@ var _Loom3 = class _Loom3 {
     }
     return 0;
   }
+  applyMorphTargetDelta(target, options) {
+    const mesh = this.requireNamedMesh(target.meshName);
+    const sourceGeometry = mesh.geometry;
+    const position = sourceGeometry.getAttribute("position");
+    if (!position) {
+      throw new Error(`Cannot add morph target "${target.name}" to mesh "${target.meshName}": geometry has no position attribute.`);
+    }
+    if (!target.name || !target.name.trim()) {
+      throw new Error(`Cannot add morph target to mesh "${target.meshName}": target name is required.`);
+    }
+    const replace = options.replace === true;
+    const resetInfluence = options.resetInfluence !== false;
+    const forceGeometryReplacement = options.forceGeometryReplacement !== false;
+    const previousInfluences = mesh.morphTargetInfluences ? [...mesh.morphTargetInfluences] : [];
+    const previousDictionary = this.getMeshMorphDictionary(mesh);
+    const existingIndex = previousDictionary[target.name];
+    if (existingIndex !== void 0 && !replace) {
+      throw new Error(`Morph target "${target.name}" already exists on mesh "${target.meshName}". Pass replace: true to overwrite it.`);
+    }
+    const geometry = forceGeometryReplacement ? sourceGeometry.clone() : sourceGeometry;
+    const dictionary = { ...previousDictionary };
+    const usedIndices = Object.values(dictionary).filter(Number.isInteger);
+    const existingAttributeTargetCount = Math.max(
+      0,
+      ...Object.values(geometry.morphAttributes).map((attributes) => attributes?.length ?? 0)
+    );
+    const nextIndex = Math.max(existingAttributeTargetCount, usedIndices.length ? Math.max(...usedIndices) + 1 : 0);
+    const index = existingIndex ?? nextIndex;
+    dictionary[target.name] = index;
+    this.setMorphAttributeAtIndex(geometry, "position", target.position, position.itemSize, position.count, index, target.name);
+    const normal = geometry.getAttribute("normal");
+    if (target.normal) {
+      this.setMorphAttributeAtIndex(geometry, "normal", target.normal, normal?.itemSize ?? 3, position.count, index, target.name);
+    } else {
+      this.setZeroMorphAttributeAtIndex(geometry, "normal", normal?.itemSize ?? 3, position.count, index, target.name);
+    }
+    const tangent = geometry.getAttribute("tangent");
+    if (target.tangent) {
+      this.setMorphAttributeAtIndex(geometry, "tangent", target.tangent, tangent?.itemSize ?? 4, position.count, index, target.name);
+    } else {
+      this.setZeroMorphAttributeAtIndex(geometry, "tangent", tangent?.itemSize ?? 4, position.count, index, target.name);
+    }
+    const color = geometry.getAttribute("color");
+    const existingColorMorph = geometry.morphAttributes.color?.find(Boolean);
+    this.setZeroMorphAttributeAtIndex(
+      geometry,
+      "color",
+      color?.itemSize ?? existingColorMorph?.itemSize ?? 3,
+      position.count,
+      index,
+      target.name
+    );
+    geometry.morphTargetsRelative = target.relative !== false;
+    geometry.morphTargetDictionary = dictionary;
+    if (forceGeometryReplacement) {
+      mesh.geometry = geometry;
+      sourceGeometry.dispose();
+    }
+    const influenceLength = Math.max(previousInfluences.length, index + 1);
+    const influences = previousInfluences.slice(0, influenceLength);
+    while (influences.length < influenceLength) {
+      influences.push(0);
+    }
+    if (resetInfluence) {
+      influences[index] = 0;
+    }
+    mesh.morphTargetDictionary = dictionary;
+    mesh.morphTargetInfluences = influences;
+    this.addRuntimeMorphMesh(mesh);
+    if (!this.config.morphToMesh?.face?.length) {
+      this.config.morphToMesh = {
+        ...this.config.morphToMesh,
+        face: [mesh.name]
+      };
+    }
+    return index;
+  }
+  requireNamedMesh(meshName) {
+    const mesh = this.meshByName.get(meshName);
+    if (mesh) return mesh;
+    if (this.model) {
+      let found = null;
+      this.model.traverse((obj) => {
+        if (!found && obj.isMesh && obj.name === meshName) {
+          found = obj;
+        }
+      });
+      if (found) {
+        this.meshByName.set(meshName, found);
+        return found;
+      }
+    }
+    throw new Error(`Mesh "${meshName}" was not found in the current model.`);
+  }
+  getMeshMorphDictionary(mesh) {
+    const meshDictionary = mesh.morphTargetDictionary;
+    const geometryDictionary = mesh.geometry.morphTargetDictionary;
+    const dictionary = meshDictionary || geometryDictionary || {};
+    mesh.morphTargetDictionary = dictionary;
+    mesh.geometry.morphTargetDictionary = dictionary;
+    return dictionary;
+  }
+  setMorphAttributeAtIndex(geometry, semantic, data, itemSize, vertexCount, index, name) {
+    const expectedLength = vertexCount * itemSize;
+    if (data.length !== expectedLength) {
+      throw new Error(
+        `Morph target "${name}" ${semantic} data has ${data.length} values; expected ${expectedLength} (${vertexCount} vertices * itemSize ${itemSize}).`
+      );
+    }
+    const attributes = geometry.morphAttributes[semantic] ? [...geometry.morphAttributes[semantic]] : [];
+    while (attributes.length < index) {
+      const empty = new THREE2.BufferAttribute(new Float32Array(expectedLength), itemSize);
+      empty.name = `morph_${attributes.length}`;
+      attributes.push(empty);
+    }
+    const values = data instanceof Float32Array ? new Float32Array(data) : Float32Array.from(data);
+    const attribute = new THREE2.BufferAttribute(values, itemSize);
+    attribute.name = name;
+    attributes[index] = attribute;
+    geometry.morphAttributes[semantic] = attributes;
+  }
+  setZeroMorphAttributeAtIndex(geometry, semantic, itemSize, vertexCount, index, name) {
+    if (!geometry.morphAttributes[semantic]?.length) return;
+    const expectedLength = vertexCount * itemSize;
+    const attributes = [...geometry.morphAttributes[semantic]];
+    while (attributes.length < index) {
+      const empty2 = new THREE2.BufferAttribute(new Float32Array(expectedLength), itemSize);
+      empty2.name = `morph_${attributes.length}`;
+      attributes.push(empty2);
+    }
+    const empty = new THREE2.BufferAttribute(new Float32Array(expectedLength), itemSize);
+    empty.name = name;
+    attributes[index] = empty;
+    geometry.morphAttributes[semantic] = attributes;
+  }
+  addRuntimeMorphMesh(mesh) {
+    const key = mesh.name || mesh.uuid;
+    const exists = this.meshes.some((candidate) => (candidate.name || candidate.uuid) === key);
+    if (!exists) {
+      this.meshes.push(mesh);
+    }
+  }
   getMorphKeyCacheKey(key, meshNames) {
     return meshNames?.length ? `key:${key}@${meshNames.join(",")}` : `key:${key}`;
   }
@@ -7465,7 +7655,7 @@ function extractMorphs(meshes) {
   for (const mesh of meshes) {
     const geo = mesh.geometry;
     if (!geo.morphAttributes) continue;
-    const dict = geo.morphTargetDictionary;
+    const dict = mesh.morphTargetDictionary || geo.morphTargetDictionary;
     if (dict) {
       for (const [name, index] of Object.entries(dict)) {
         morphs.push({