loomlarge 0.2.1 → 1.0.1

package/README.md

@@ -10,16 +10,17 @@ LoomLarge provides pre-built mappings that connect [Facial Action Coding System
 
 1. [Installation & Setup](#1-installation--setup)
 2. [Using Presets](#2-using-presets)
-3. [Extending & Custom Presets](#3-extending--custom-presets)
-4. [Action Unit Control](#4-action-unit-control)
-5. [Mix Weight System](#5-mix-weight-system)
-6. [Composite Rotation System](#6-composite-rotation-system)
-7. [Continuum Pairs](#7-continuum-pairs)
-8. [Direct Morph Control](#8-direct-morph-control)
-9. [Viseme System](#9-viseme-system)
-10. [Transition System](#10-transition-system)
-11. [Playback & State Control](#11-playback--state-control)
-12. [Hair Physics](#12-hair-physics)
+3. [Getting to Know Your Character](#3-getting-to-know-your-character)
+4. [Extending & Custom Presets](#4-extending--custom-presets)
+5. [Action Unit Control](#5-action-unit-control)
+6. [Mix Weight System](#6-mix-weight-system)
+7. [Composite Rotation System](#7-composite-rotation-system)
+8. [Continuum Pairs](#8-continuum-pairs)
+9. [Direct Morph Control](#9-direct-morph-control)
+10. [Viseme System](#10-viseme-system)
+11. [Transition System](#11-transition-system)
+12. [Playback & State Control](#12-playback--state-control)
+13. [Hair Physics](#13-hair-physics)
 
 ---
 
@@ -198,7 +199,112 @@ const loom = new LoomLargeThree({ auMappings: CC4_PRESET });
 
 ---
 
-## 3. Extending & Custom Presets
+## 3. Getting to Know Your Character
+
+Before customizing presets or extending mappings, it's helpful to understand what's actually in your character model. LoomLarge provides several methods to inspect meshes, morph targets, and bones.
+
+### Listing meshes
+
+Get all meshes in your character with their visibility and morph target counts:
+
+```typescript
+const meshes = loom.getMeshList();
+console.log(meshes);
+// [
+//   { name: 'CC_Base_Body', visible: true, morphCount: 142 },
+//   { name: 'CC_Base_Tongue', visible: true, morphCount: 12 },
+//   { name: 'CC_Base_EyeOcclusion_L', visible: true, morphCount: 8 },
+//   { name: 'CC_Base_EyeOcclusion_R', visible: true, morphCount: 8 },
+//   { name: 'Male_Bushy_1', visible: true, morphCount: 142 },
+//   ...
+// ]
+```
+
+### Listing morph targets
+
+Get all morph target names grouped by mesh:
+
+```typescript
+const morphs = loom.getMorphTargets();
+console.log(morphs);
+// {
+//   'CC_Base_Body': [
+//     'A01_Brow_Inner_Up', 'A02_Brow_Down_Left', 'A02_Brow_Down_Right',
+//     'A04_Brow_Outer_Up_Left', 'A04_Brow_Outer_Up_Right',
+//     'Mouth_Smile_L', 'Mouth_Smile_R', 'Eye_Blink_L', 'Eye_Blink_R',
+//     ...
+//   ],
+//   'CC_Base_Tongue': [
+//     'V_Tongue_Out', 'V_Tongue_Up', 'V_Tongue_Down', ...
+//   ],
+//   ...
+// }
+```
+
+This is invaluable when creating custom presets—you need to know the exact morph target names your character uses.
+
+### Listing bones
+
+Get all resolved bones with their current positions and rotations (in degrees):
+
+```typescript
+const bones = loom.getBones();
+console.log(bones);
+// {
+//   'HEAD': { position: [0, 156.2, 0], rotation: [0, 0, 0] },
+//   'JAW': { position: [0, 154.1, 2.3], rotation: [0, 0, 0] },
+//   'EYE_L': { position: [-3.2, 160.5, 8.1], rotation: [0, 0, 0] },
+//   'EYE_R': { position: [3.2, 160.5, 8.1], rotation: [0, 0, 0] },
+//   'TONGUE': { position: [0, 152.3, 1.8], rotation: [0, 0, 0] },
+// }
+```
+
+### Controlling mesh visibility
+
+Hide or show individual meshes:
+
+```typescript
+// Hide hair mesh
+loom.setMeshVisible('Side_part_wavy_1', false);
+
+// Show it again
+loom.setMeshVisible('Side_part_wavy_1', true);
+```
+
+### Adjusting material properties
+
+Fine-tune render order, transparency, and blending for each mesh:
+
+```typescript
+// Get current material config
+const config = loom.getMeshMaterialConfig('CC_Base_Body');
+console.log(config);
+// {
+//   renderOrder: 0,
+//   transparent: false,
+//   opacity: 1,
+//   depthWrite: true,
+//   depthTest: true,
+//   blending: 'Normal'
+// }
+
+// Set custom material config
+loom.setMeshMaterialConfig('CC_Base_EyeOcclusion_L', {
+  renderOrder: 10,
+  transparent: true,
+  opacity: 0.8,
+  blending: 'Normal'  // 'Normal', 'Additive', 'Subtractive', 'Multiply', 'None'
+});
+```
+
+This is especially useful for:
+- Fixing render order issues (eyebrows behind hair, etc.)
+- Making meshes semi-transparent for debugging
+- Adjusting blending modes for special effects
+
+---
+
+## 4. Extending & Custom Presets
 
 ### Extending an existing preset
 
@@ -275,7 +381,7 @@ const current = loom.getAUMappings();
 
 ---
 
-## 4. Action Unit Control
+## 5. Action Unit Control
 
 Action Units are the core of FACS. Each AU represents a specific muscular movement of the face.
 
@@ -349,7 +455,7 @@ loom.setAU(12, 0.8, 1);    // Right side only
 
 ---
 
-## 5. Mix Weight System
+## 6. Mix Weight System
 
 Some AUs can be driven by both morph targets (blend shapes) AND bone rotations. The mix weight controls the blend between them.
 
@@ -394,7 +500,7 @@ if (isMixedAU(26)) {
 
 ---
 
-## 6. Composite Rotation System
+## 7. Composite Rotation System
 
 Bones like the head and eyes need multi-axis rotation (pitch, yaw, roll). The composite rotation system handles this automatically.
 
@@ -452,7 +558,7 @@ loom.setAU(64, 0.4);
 
 ---
 
-## 7. Continuum Pairs
+## 8. Continuum Pairs
 
 Continuum pairs are bidirectional AU pairs that represent opposite directions on the same axis. They're linked so that activating one should deactivate the other.
 
@@ -498,7 +604,7 @@ const pair = CONTINUUM_PAIRS_MAP[51];
 
 ---
 
-## 8. Direct Morph Control
+## 9. Direct Morph Control
 
 Sometimes you need to control morph targets directly by name, bypassing the AU system.
 
@@ -537,7 +643,7 @@ LoomLarge caches morph target lookups for performance. The first time you access
 
 ---
 
-## 9. Viseme System
+## 10. Viseme System
 
 Visemes are mouth shapes used for lip-sync. LoomLarge includes 15 visemes with automatic jaw coupling.
 
@@ -622,7 +728,7 @@ speak([5, 0, 10, 4]);
 
 ---
 
-## 10. Transition System
+## 11. Transition System
 
 All animated changes in LoomLarge go through the transition system, which provides smooth interpolation with easing.
 
@@ -702,7 +808,7 @@ loom.clearTransitions();
 
 ---
 
-## 11. Playback & State Control
+## 12. Playback & State Control
 
 ### Pausing and resuming
 
@@ -757,7 +863,7 @@ loom.dispose();
 
 ---
 
-## 12. Hair Physics
+## 13. Hair Physics
 
 LoomLarge includes an experimental hair physics system that simulates hair movement based on head motion.
 

package/dist/index.cjs

@@ -245,119 +245,121 @@ var VISEME_KEYS = [
 ];
 var BONE_AU_TO_BINDINGS = {
   // Head turn and tilt (M51-M56) - use HEAD bone only (NECK should not rotate with head)
-  // Three.js Y rotation: positive = counter-clockwise from above = head turns LEFT (character POV)
   51: [
-    { node: "HEAD", channel: "ry", scale: 1, maxDegrees: 30 }
+    { node: "HEAD", channel: "ry", scale: 1, maxDegrees: 30, axis: "yaw" }
     // Head turn left
   ],
   52: [
-    { node: "HEAD", channel: "ry", scale: -1, maxDegrees: 30 }
+    { node: "HEAD", channel: "ry", scale: -1, maxDegrees: 30, axis: "yaw" }
     // Head turn right
   ],
   53: [
-    { node: "HEAD", channel: "rx", scale: -1, maxDegrees: 20 }
+    { node: "HEAD", channel: "rx", scale: -1, maxDegrees: 20, axis: "pitch" }
     // Head up
   ],
   54: [
-    { node: "HEAD", channel: "rx", scale: 1, maxDegrees: 20 }
+    { node: "HEAD", channel: "rx", scale: 1, maxDegrees: 20, axis: "pitch" }
     // Head down
   ],
   55: [
-    { node: "HEAD", channel: "rz", scale: -1, maxDegrees: 15 }
+    { node: "HEAD", channel: "rz", scale: -1, maxDegrees: 15, axis: "roll" }
     // Head tilt left
   ],
   56: [
-    { node: "HEAD", channel: "rz", scale: 1, maxDegrees: 15 }
+    { node: "HEAD", channel: "rz", scale: 1, maxDegrees: 15, axis: "roll" }
     // Head tilt right
   ],
   // Eyes horizontal (yaw) - CC4 rigs use rz for horizontal eye rotation
   61: [
-    { node: "EYE_L", channel: "rz", scale: 1, maxDegrees: 32 },
+    { node: "EYE_L", channel: "rz", scale: 1, maxDegrees: 32, axis: "yaw" },
     // Eyes look left
-    { node: "EYE_R", channel: "rz", scale: 1, maxDegrees: 32 }
+    { node: "EYE_R", channel: "rz", scale: 1, maxDegrees: 32, axis: "yaw" }
   ],
   62: [
-    { node: "EYE_L", channel: "rz", scale: -1, maxDegrees: 32 },
+    { node: "EYE_L", channel: "rz", scale: -1, maxDegrees: 32, axis: "yaw" },
     // Eyes look right
-    { node: "EYE_R", channel: "rz", scale: -1, maxDegrees: 32 }
+    { node: "EYE_R", channel: "rz", scale: -1, maxDegrees: 32, axis: "yaw" }
   ],
   63: [
-    { node: "EYE_L", channel: "rx", scale: -1, maxDegrees: 32 },
-    { node: "EYE_R", channel: "rx", scale: -1, maxDegrees: 32 }
+    { node: "EYE_L", channel: "rx", scale: -1, maxDegrees: 32, axis: "pitch" },
+    // Eyes Up
+    { node: "EYE_R", channel: "rx", scale: -1, maxDegrees: 32, axis: "pitch" }
   ],
   64: [
-    { node: "EYE_L", channel: "rx", scale: 1, maxDegrees: 32 },
-    { node: "EYE_R", channel: "rx", scale: 1, maxDegrees: 32 }
+    { node: "EYE_L", channel: "rx", scale: 1, maxDegrees: 32, axis: "pitch" },
+    // Eyes Down
+    { node: "EYE_R", channel: "rx", scale: 1, maxDegrees: 32, axis: "pitch" }
   ],
   // Single-eye (Left) — horizontal (rz for CC4) and vertical (rx)
-  65: [{ node: "EYE_L", channel: "rz", scale: -1, maxDegrees: 15 }],
-  66: [{ node: "EYE_L", channel: "rz", scale: 1, maxDegrees: 15 }],
-  67: [{ node: "EYE_L", channel: "rx", scale: -1, maxDegrees: 12 }],
-  68: [{ node: "EYE_L", channel: "rx", scale: 1, maxDegrees: 12 }],
+  65: [{ node: "EYE_L", channel: "rz", scale: -1, maxDegrees: 15, axis: "yaw" }],
+  66: [{ node: "EYE_L", channel: "rz", scale: 1, maxDegrees: 15, axis: "yaw" }],
+  67: [{ node: "EYE_L", channel: "rx", scale: -1, maxDegrees: 12, axis: "pitch" }],
+  // Left Eye Up
+  68: [{ node: "EYE_L", channel: "rx", scale: 1, maxDegrees: 12, axis: "pitch" }],
+  // Left Eye Down
   // Single-eye (Right) — horizontal (rz for CC4) and vertical (rx)
-  69: [{ node: "EYE_R", channel: "rz", scale: -1, maxDegrees: 15 }],
-  70: [{ node: "EYE_R", channel: "rz", scale: 1, maxDegrees: 15 }],
-  71: [{ node: "EYE_R", channel: "rx", scale: -1, maxDegrees: 12 }],
-  72: [{ node: "EYE_R", channel: "rx", scale: 1, maxDegrees: 12 }],
+  69: [{ node: "EYE_R", channel: "rz", scale: -1, maxDegrees: 15, axis: "yaw" }],
+  70: [{ node: "EYE_R", channel: "rz", scale: 1, maxDegrees: 15, axis: "yaw" }],
+  71: [{ node: "EYE_R", channel: "rx", scale: -1, maxDegrees: 12, axis: "pitch" }],
+  // Right Eye Up
+  72: [{ node: "EYE_R", channel: "rx", scale: 1, maxDegrees: 12, axis: "pitch" }],
+  // Right Eye Down
   // Jaw / Mouth
   8: [
     // Lips Toward Each Other - slight jaw open helps sell the lip press
-    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 8 }
-    // Small downward rotation (jaw opening slightly)
+    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 8, axis: "roll" }
   ],
   25: [
     // Lips Part — small jaw open
-    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 5.84 }
-    // 73% of 8
+    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 5.84, axis: "roll" }
   ],
   26: [
-    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 28 }
-    // 73% of 20
+    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 28, axis: "roll" }
   ],
   27: [
     // Mouth Stretch — larger jaw open
-    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 32 }
-    // 73% of 25
+    { node: "JAW", channel: "rz", scale: 1, maxDegrees: 32, axis: "roll" }
   ],
   29: [
     { node: "JAW", channel: "tz", scale: -1, maxUnits: 0.02 }
-    // Negative for forward thrust
+    // Translation - no axis needed
   ],
   30: [
     // Jaw Left
-    { node: "JAW", channel: "ry", scale: -1, maxDegrees: 5 }
+    { node: "JAW", channel: "ry", scale: -1, maxDegrees: 5, axis: "yaw" }
   ],
   35: [
     // Jaw Right
-    { node: "JAW", channel: "ry", scale: 1, maxDegrees: 5 }
+    { node: "JAW", channel: "ry", scale: 1, maxDegrees: 5, axis: "yaw" }
   ],
   // Tongue
   19: [
     { node: "TONGUE", channel: "tz", scale: -1, maxUnits: 8e-3 }
+    // Translation - no axis needed
   ],
   37: [
     // Tongue Up
-    { node: "TONGUE", channel: "rz", scale: -1, maxDegrees: 45 }
+    { node: "TONGUE", channel: "rz", scale: -1, maxDegrees: 45, axis: "pitch" }
   ],
   38: [
     // Tongue Down
-    { node: "TONGUE", channel: "rz", scale: 1, maxDegrees: 45 }
+    { node: "TONGUE", channel: "rz", scale: 1, maxDegrees: 45, axis: "pitch" }
   ],
   39: [
     // Tongue Left
-    { node: "TONGUE", channel: "ry", scale: -1, maxDegrees: 10 }
+    { node: "TONGUE", channel: "ry", scale: -1, maxDegrees: 10, axis: "yaw" }
   ],
   40: [
     // Tongue Right
-    { node: "TONGUE", channel: "ry", scale: 1, maxDegrees: 10 }
+    { node: "TONGUE", channel: "ry", scale: 1, maxDegrees: 10, axis: "yaw" }
   ],
   41: [
     // Tongue Tilt Left
-    { node: "TONGUE", channel: "rx", scale: -1, maxDegrees: 20 }
+    { node: "TONGUE", channel: "rx", scale: -1, maxDegrees: 20, axis: "roll" }
   ],
   42: [
     // Tongue Tilt Right
-    { node: "TONGUE", channel: "rx", scale: 1, maxDegrees: 20 }
+    { node: "TONGUE", channel: "rx", scale: 1, maxDegrees: 20, axis: "roll" }
   ]
 };
 var isMixedAU = (id) => !!(AU_TO_MORPHS[id]?.length && BONE_AU_TO_BINDINGS[id]?.length);
@@ -799,8 +801,9 @@ var _LoomLargeThree = class _LoomLargeThree {
     if (bindings) {
       for (const binding of bindings) {
         if (binding.channel === "rx" || binding.channel === "ry" || binding.channel === "rz") {
-          const axis = binding.channel === "rx" ? "pitch" : binding.channel === "ry" ? "yaw" : "roll";
-          this.updateBoneRotation(binding.node, axis, v * binding.scale, binding.maxDegrees ?? 0);
+          if (binding.axis) {
+            this.updateBoneRotation(binding.node, binding.axis, v * binding.scale, binding.maxDegrees ?? 0);
+          }
         } else if (binding.channel === "tx" || binding.channel === "ty" || binding.channel === "tz") {
           if (binding.maxUnits !== void 0) {
             this.updateBoneTranslation(binding.node, binding.channel, v * binding.scale, binding.maxUnits);
@@ -838,8 +841,9 @@ var _LoomLargeThree = class _LoomLargeThree {
     }
     for (const binding of bindings) {
       if (binding.channel === "rx" || binding.channel === "ry" || binding.channel === "rz") {
-        const axis = binding.channel === "rx" ? "pitch" : binding.channel === "ry" ? "yaw" : "roll";
-        handles.push(this.transitionBoneRotation(binding.node, axis, target * binding.scale, binding.maxDegrees ?? 0, durationMs));
+        if (binding.axis) {
+          handles.push(this.transitionBoneRotation(binding.node, binding.axis, target * binding.scale, binding.maxDegrees ?? 0, durationMs));
+        }
       } else if (binding.channel === "tx" || binding.channel === "ty" || binding.channel === "tz") {
         if (binding.maxUnits !== void 0) {
           handles.push(this.transitionBoneTranslation(binding.node, binding.channel, target * binding.scale, binding.maxUnits, durationMs));
@@ -851,11 +855,16 @@ var _LoomLargeThree = class _LoomLargeThree {
   getAU(id) {
     return this.auValues[id] ?? 0;
   }
-  // ============================================================================
-  // MORPH CONTROL
-  // ============================================================================
-  setMorph(key, v, meshNames) {
+  setMorph(key, v, meshNamesOrTargets) {
     const val = clamp01(v);
+    if (Array.isArray(meshNamesOrTargets) && meshNamesOrTargets.length > 0 && typeof meshNamesOrTargets[0] === "object" && "infl" in meshNamesOrTargets[0]) {
+      const targets2 = meshNamesOrTargets;
+      for (const target of targets2) {
+        target.infl[target.idx] = val;
+      }
+      return;
+    }
+    const meshNames = meshNamesOrTargets;
     const targetMeshes = meshNames || this.config.morphToMesh?.face || [];
     const cached = this.morphCache.get(key);
     if (cached) {
@@ -894,11 +903,54 @@ var _LoomLargeThree = class _LoomLargeThree {
       this.morphCache.set(key, targets);
     }
   }
+  /**
+   * 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, meshNames) {
+    const cached = this.morphCache.get(key);
+    if (cached) return cached;
+    const targetMeshes = meshNames || this.config.morphToMesh?.face || [];
+    const targets = [];
+    if (targetMeshes.length) {
+      for (const name of targetMeshes) {
+        const mesh = this.meshByName.get(name);
+        if (!mesh) continue;
+        const dict = mesh.morphTargetDictionary;
+        const infl = mesh.morphTargetInfluences;
+        if (!dict || !infl) continue;
+        const idx = dict[key];
+        if (idx !== void 0) {
+          targets.push({ infl, idx });
+        }
+      }
+    } else {
+      for (const mesh of this.meshes) {
+        const dict = mesh.morphTargetDictionary;
+        const infl = mesh.morphTargetInfluences;
+        if (!dict || !infl) continue;
+        const idx = dict[key];
+        if (idx !== void 0) {
+          targets.push({ infl, idx });
+        }
+      }
+    }
+    if (targets.length > 0) {
+      this.morphCache.set(key, targets);
+    }
+    return targets;
+  }
   transitionMorph(key, to, durationMs = 120, meshNames) {
     const transitionKey = `morph_${key}`;
     const from = this.getMorphValue(key);
     const target = clamp01(to);
-    return this.animation.addTransition(transitionKey, from, target, durationMs, (value) => this.setMorph(key, value, meshNames));
+    const targets = this.resolveMorphTargets(key, meshNames);
+    return this.animation.addTransition(transitionKey, from, target, durationMs, (value) => {
+      const val = clamp01(value);
+      for (const t of targets) {
+        t.infl[t.idx] = val;
+      }
+    });
   }
   // ============================================================================
   // VISEME CONTROL
@@ -1001,6 +1053,33 @@ var _LoomLargeThree = class _LoomLargeThree {
     });
     return result;
   }
+  /** Get all morph targets grouped by mesh name */
+  getMorphTargets() {
+    const result = {};
+    for (const mesh of this.meshes) {
+      const dict = mesh.morphTargetDictionary;
+      if (dict) {
+        result[mesh.name] = Object.keys(dict).sort();
+      }
+    }
+    return result;
+  }
+  /** Get all resolved bone names and their current transforms */
+  getBones() {
+    const result = {};
+    for (const name of Object.keys(this.bones)) {
+      const entry = this.bones[name];
+      if (entry) {
+        const pos = entry.obj.position;
+        const rot = entry.obj.rotation;
+        result[name] = {
+          position: [pos.x, pos.y, pos.z],
+          rotation: [rot.x * 180 / Math.PI, rot.y * 180 / Math.PI, rot.z * 180 / Math.PI]
+        };
+      }
+    }
+    return result;
+  }
   setMeshVisible(meshName, visible) {
     if (!this.model) return;
     this.model.traverse((obj) => {
@@ -1009,6 +1088,70 @@ var _LoomLargeThree = class _LoomLargeThree {
       }
     });
   }
+  /** Get material config for a mesh */
+  getMeshMaterialConfig(meshName) {
+    if (!this.model) return null;
+    let result = null;
+    this.model.traverse((obj) => {
+      if (obj.isMesh && obj.name === meshName) {
+        const mat = obj.material;
+        if (mat) {
+          let blendingName = "Normal";
+          for (const [name, value] of Object.entries(_LoomLargeThree.BLENDING_MODES)) {
+            if (mat.blending === value) {
+              blendingName = name;
+              break;
+            }
+          }
+          result = {
+            renderOrder: obj.renderOrder,
+            transparent: mat.transparent,
+            opacity: mat.opacity,
+            depthWrite: mat.depthWrite,
+            depthTest: mat.depthTest,
+            blending: blendingName
+          };
+        }
+      }
+    });
+    return result;
+  }
+  /** Set material config for a mesh */
+  setMeshMaterialConfig(meshName, config) {
+    if (!this.model) return;
+    this.model.traverse((obj) => {
+      if (obj.isMesh && obj.name === meshName) {
+        const mat = obj.material;
+        if (config.renderOrder !== void 0) {
+          obj.renderOrder = config.renderOrder;
+        }
+        if (mat) {
+          if (config.opacity !== void 0) {
+            mat.opacity = config.opacity;
+            if (config.opacity < 1 && config.transparent === void 0) {
+              mat.transparent = true;
+            }
+          }
+          if (config.transparent !== void 0) {
+            mat.transparent = config.transparent;
+          }
+          if (config.depthWrite !== void 0) {
+            mat.depthWrite = config.depthWrite;
+          }
+          if (config.depthTest !== void 0) {
+            mat.depthTest = config.depthTest;
+          }
+          if (config.blending !== void 0) {
+            const blendValue = _LoomLargeThree.BLENDING_MODES[config.blending];
+            if (blendValue !== void 0) {
+              mat.blending = blendValue;
+            }
+          }
+          mat.needsUpdate = true;
+        }
+      }
+    });
+  }
   // ============================================================================
   // CONFIGURATION
   // ============================================================================
@@ -1200,6 +1343,13 @@ var _LoomLargeThree = class _LoomLargeThree {
         if (typeof settings.depthTest === "boolean") {
           obj.material.depthTest = settings.depthTest;
         }
+        if (typeof settings.blending === "string") {
+          const blendValue = _LoomLargeThree.BLENDING_MODES[settings.blending];
+          if (blendValue !== void 0) {
+            obj.material.blending = blendValue;
+          }
+        }
+        obj.material.needsUpdate = true;
       }
     });
   }
@@ -1223,6 +1373,19 @@ __publicField(_LoomLargeThree, "VISEME_JAW_AMOUNTS", [
   0.4
 ]);
 __publicField(_LoomLargeThree, "JAW_MAX_DEGREES", 28);
+/** Blending mode options for Three.js materials */
+__publicField(_LoomLargeThree, "BLENDING_MODES", {
+  "Normal": 1,
+  // THREE.NormalBlending
+  "Additive": 2,
+  // THREE.AdditiveBlending
+  "Subtractive": 3,
+  // THREE.SubtractiveBlending
+  "Multiply": 4,
+  // THREE.MultiplyBlending
+  "None": 0
+  // THREE.NoBlending
+});
 var LoomLargeThree = _LoomLargeThree;
 function collectMorphMeshes(root) {
   const meshes = [];
@@ -1236,6 +1399,20 @@ function collectMorphMeshes(root) {
   return meshes;
 }
 
+// src/mappings/types.ts
+var BLENDING_MODES = {
+  "Normal": 1,
+  // THREE.NormalBlending
+  "Additive": 2,
+  // THREE.AdditiveBlending
+  "Subtractive": 3,
+  // THREE.SubtractiveBlending
+  "Multiply": 4,
+  // THREE.MultiplyBlending
+  "None": 0
+  // THREE.NoBlending
+};
+
 // src/physics/HairPhysics.ts
 var DEFAULT_HAIR_PHYSICS_CONFIG = {
   mass: 1,
@@ -1364,6 +1541,7 @@ exports.AU_INFO = AU_INFO;
 exports.AU_MIX_DEFAULTS = AU_MIX_DEFAULTS;
 exports.AU_TO_MORPHS = AU_TO_MORPHS;
 exports.AnimationThree = AnimationThree;
+exports.BLENDING_MODES = BLENDING_MODES;
 exports.BONE_AU_TO_BINDINGS = BONE_AU_TO_BINDINGS;
 exports.CC4_BONE_NODES = CC4_BONE_NODES;
 exports.CC4_EYE_MESH_NODES = CC4_EYE_MESH_NODES;