@joshtol/emotive-engine 3.3.4 → 3.3.6

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@joshtol/emotive-engine",
-  "version": "3.3.4",
+  "version": "3.3.6",
   "description": "Open-source animation engine for AI-controlled emotional visualizations with musical time synchronization",
   "main": "dist/emotive-mascot.umd.js",
   "module": "dist/mascot.js",

package/src/3d/Core3DManager.js

@@ -291,6 +291,8 @@ export class Core3DManager {
         this.glowColor = [1.0, 1.0, 1.0]; // RGB
         this.glowColorHex = '#FFFFFF'; // Hex color for luminance normalization
         this.glowIntensity = 1.0;
+        // OPTIMIZATION: Cache normalized color to avoid recalculating every frame
+        this._normalizedGlowColor = null;
         this.coreGlowEnabled = true; // Toggle to enable/disable core glow
         this.glowIntensityOverride = null; // Manual override for testing
         this.intensityCalibrationOffset = 0; // Universal filter calibration offset
@@ -419,6 +421,9 @@ export class Core3DManager {
                 this.glowColor = rgb;
                 // Store hex color for bloom luminance normalization
                 this.glowColorHex = emotionData.visual.glowColor;
+                // OPTIMIZATION: Pre-compute normalized color (avoids recalculating every frame)
+                const normalized = normalizeRGBLuminance(rgb, 0.30);
+                this._normalizedGlowColor = [normalized.r, normalized.g, normalized.b];
 
                 // Calculate intensity using universal filter based on color luminance
                 // This ensures consistent visibility across all emotions regardless of color brightness
@@ -1832,11 +1837,9 @@ export class Core3DManager {
                     this.customMaterial.uniforms.glowIntensity.value = effectiveGlowIntensity;
                 }
 
-                // Normalize emotion color for consistent perceived brightness across all emotions
+                // OPTIMIZATION: Use pre-computed normalized color (calculated when emotion changes)
                 // This ensures yellow (joy) doesn't wash out the soul while blue (sadness) stays visible
-                // IMPORTANT: Use glowColor (RGB), not glowColorHex - glowColor has undertone saturation applied
-                const normalized = normalizeRGBLuminance(this.glowColor, 0.30);
-                const normalizedColor = [normalized.r, normalized.g, normalized.b];
+                const normalizedColor = this._normalizedGlowColor || [1, 1, 1];
 
                 // Update emotion color on outer shell (luminance-normalized)
                 this.customMaterial.uniforms.emotionColor.value.setRGB(
@@ -1848,12 +1851,10 @@ export class Core3DManager {
                     this.customMaterial.uniforms.blinkIntensity.value = blinkPulse;
                 }
             }
-            // Update inner core color and animation (also use normalized color)
+            // Update inner core color and animation (also use cached normalized color)
             // Only update if core glow is enabled
-            // IMPORTANT: Use glowColor (RGB), not glowColorHex - glowColor has undertone saturation applied
             if (this.coreGlowEnabled) {
-                const normalizedCore = normalizeRGBLuminance(this.glowColor, 0.30);
-                const normalizedCoreColor = [normalizedCore.r, normalizedCore.g, normalizedCore.b];
+                const normalizedCoreColor = this._normalizedGlowColor || [1, 1, 1];
                 this.updateCrystalInnerCore(normalizedCoreColor, deltaTime);
             }
         }

package/src/3d/ThreeRenderer.js

@@ -143,6 +143,13 @@ export class ThreeRenderer {
         this._zAxis = new THREE.Vector3(0, 0, 1);
         this._cameraToMesh = new THREE.Vector3();
         this._cameraDir = new THREE.Vector3();
+
+        // OPTIMIZATION: Reusable temp vector for soul position projection (avoids allocation per frame)
+        this._soulPosTemp = new THREE.Vector3();
+        // OPTIMIZATION: Cached soul mesh reference (avoids scene.traverse every frame)
+        this._cachedSoulMesh = null;
+        // OPTIMIZATION: Reusable Vector2 for drawing buffer size queries
+        this._drawingBufferSize = new THREE.Vector2();
     }
 
     /**
@@ -1494,14 +1501,15 @@ export class ThreeRenderer {
             // === STEP 0: Render soul (layer 2) to texture for refraction sampling ===
             // OPTIMIZATION: Skip soul pass entirely if geometry doesn't have a soul
             if (this.soulRenderTarget && hasSoul) {
-                // Find soul mesh in scene (needed for screen center calculation)
-                let soulMesh = null;
-                this.scene.traverse(obj => {
-                    if (obj.name === 'crystalSoul') soulMesh = obj;
-                });
+                // OPTIMIZATION: Use cached soul mesh reference instead of traversing every frame
+                if (!this._cachedSoulMesh) {
+                    this.scene.traverse(obj => {
+                        if (obj.name === 'crystalSoul') this._cachedSoulMesh = obj;
+                    });
+                }
+                const soulMesh = this._cachedSoulMesh;
 
                 this.renderer.setRenderTarget(this.soulRenderTarget);
-                this.renderer.setClearColor(0x000000, 0);
                 this.renderer.clear();
 
                 // Render only soul layer (layer 2)
@@ -1520,17 +1528,17 @@ export class ThreeRenderer {
                     }
                     // Compute soul's screen center position for refraction sampling
                     if (this.coreMesh.material.uniforms.soulScreenCenter && soulMesh) {
-                        const soulWorldPos = soulMesh.position.clone();
-                        const soulNDC = soulWorldPos.project(this.camera);
+                        // OPTIMIZATION: Reuse pooled vector instead of cloning every frame
+                        this._soulPosTemp.copy(soulMesh.position);
+                        this._soulPosTemp.project(this.camera);
                         // Convert from NDC (-1 to 1) to UV (0 to 1)
-                        const soulScreenU = (soulNDC.x + 1.0) * 0.5;
-                        const soulScreenV = (soulNDC.y + 1.0) * 0.5;
+                        const soulScreenU = (this._soulPosTemp.x + 1.0) * 0.5;
+                        const soulScreenV = (this._soulPosTemp.y + 1.0) * 0.5;
                         this.coreMesh.material.uniforms.soulScreenCenter.value.set(soulScreenU, soulScreenV);
                     }
                 }
 
                 this.renderer.setRenderTarget(null);
-                this.renderer.setClearColor(0x000000, 0);
             }
 
             // === STEP 1: Render main scene (layer 0) through bloom to screen ===

package/src/3d/animation/Rhythm3DAdapter.js

@@ -142,6 +142,12 @@ export class Rhythm3DAdapter {
         // Ranges from 0.15 (tentative) to 1.0 (fully locked), provided by BPM detector
         this.grooveConfidence = 1.0;      // Default to full when not using BPM detection
 
+        // BPM multiplier: scales the effective BPM used for animations
+        // Default 1.0 = use detected BPM as-is
+        // Set to 0.5 to halve animation speed (e.g., for high BPM songs)
+        // Set to 2.0 to double animation speed (e.g., for slow songs)
+        this.bpmMultiplier = 1.0;
+
         // Modulation output (computed each frame) - these are the SMOOTHED values
         this.modulation = {
             scaleMultiplier: 1.0,      // Applied to gesture scale output
@@ -532,21 +538,27 @@ export class Rhythm3DAdapter {
         // Compute groove motions from ABSOLUTE beat/bar progress
         // This is frame-rate independent because beatProgress/barProgress come from
         // RhythmEngine which uses performance.now(), not accumulated frame deltas
+        //
+        // Apply BPM multiplier to scale animation speed:
+        // - multiplier 0.5 = animations run at half speed (for high BPM songs)
+        // - multiplier 2.0 = animations run at double speed (for slow songs)
+        const effectiveBeatProgress = (this.beatProgress * this.bpmMultiplier) % 1;
+        const effectiveBarProgress = (this.barProgress * this.bpmMultiplier) % 1;
 
         // Vertical bounce: synced to beat with configurable frequency
-        const bouncePhase = (this.beatProgress * bounceFreq * Math.PI * 2) + phaseOffset;
+        const bouncePhase = (effectiveBeatProgress * bounceFreq * Math.PI * 2) + phaseOffset;
         const rawBounce = Math.sin(bouncePhase);
         const easedBounce = this._applyEasing(rawBounce, easing);
 
         // Horizontal sway: synced to bar with configurable frequency
-        const swayPhase = (this.barProgress * swayFreq * Math.PI * 2) + phaseOffset;
+        const swayPhase = (effectiveBarProgress * swayFreq * Math.PI * 2) + phaseOffset;
         const rawSway = Math.sin(swayPhase);
         const easedSway = this._applyEasing(rawSway, easing);
 
         // Accent response: smooth curve that peaks at beat start, scaled by accent level
         // Uses cosine curve centered on beat boundaries (0 and 1) for smooth falloff
         // beatProgress 0.0 → peak, 0.5 → minimum, 1.0 → peak again
-        const beatProximity = (Math.cos(this.beatProgress * Math.PI * 2) + 1) * 0.5; // 0-1, peaks at beat
+        const beatProximity = (Math.cos(effectiveBeatProgress * Math.PI * 2) + 1) * 0.5; // 0-1, peaks at beat
         const accentStrength = Math.max(0, this.accent - 0.4) / 0.6; // 0-1, normalized above 0.4 threshold
         const accentBoost = beatProximity * accentStrength * 0.25; // Smooth accent curve
 
@@ -774,6 +786,35 @@ export class Rhythm3DAdapter {
         this.grooveConfidence = Math.max(0, Math.min(1, confidence));
     }
 
+    /**
+     * Set BPM multiplier for animation speed control
+     *
+     * This scales the effective BPM used for groove animations without affecting
+     * the actual BPM detection or rhythm engine. Useful for:
+     * - Halving animation speed for high BPM songs (set to 0.5)
+     * - Doubling animation speed for slow songs (set to 2.0)
+     *
+     * @example
+     * // Halve animation speed for songs > 90 BPM
+     * const status = mascot.getBPMStatus();
+     * if (status.bpm > 90) {
+     *     mascot.setBPMMultiplier(0.5);
+     * }
+     *
+     * @param {number} multiplier - BPM multiplier (0.25 to 4.0, default 1.0)
+     */
+    setBPMMultiplier(multiplier) {
+        this.bpmMultiplier = Math.max(0.25, Math.min(4.0, multiplier));
+    }
+
+    /**
+     * Get current BPM multiplier
+     * @returns {number} Current BPM multiplier (default 1.0)
+     */
+    getBPMMultiplier() {
+        return this.bpmMultiplier;
+    }
+
     /**
      * Set groove configuration (for custom tuning)
      * @param {Object} config - Groove settings

package/src/3d/effects/CrystalSoul.js

@@ -291,7 +291,7 @@ export class CrystalSoul {
             uniforms: {
                 time: { value: 0 },
                 emotionColor: { value: new THREE.Color(1, 1, 1) },
-                energyIntensity: { value: 1.5 },
+                energyIntensity: { value: 0.8 },  // Fixed value - no per-frame update needed
                 driftEnabled: { value: 1.0 },
                 driftSpeed: { value: 0.5 },
                 crossWaveEnabled: { value: 1.0 },
@@ -420,17 +420,15 @@ export class CrystalSoul {
             uniforms.time.value += deltaTime / 1000;
         }
 
-        // Update emotion color
+        // Update emotion color only if changed (avoid unnecessary GPU uniform sync)
         if (uniforms.emotionColor && glowColor) {
-            uniforms.emotionColor.value.setRGB(
-                glowColor[0], glowColor[1], glowColor[2]
-            );
+            const current = uniforms.emotionColor.value;
+            if (current.r !== glowColor[0] || current.g !== glowColor[1] || current.b !== glowColor[2]) {
+                current.setRGB(glowColor[0], glowColor[1], glowColor[2]);
+            }
         }
 
-        // Fixed intensity matching original implementation
-        if (uniforms.energyIntensity) {
-            uniforms.energyIntensity.value = 0.8;
-        }
+        // Note: energyIntensity is fixed at 0.8 (set in constructor, no per-frame update needed)
 
         // Apply breathing scale
         if (this.mesh) {

package/src/3d/index.js

@@ -1245,6 +1245,43 @@ export class EmotiveMascot3D {
         return this.core3D?.rhythm3DAdapter?.grooveConfidence ?? 1.0;
     }
 
+    /**
+     * Set BPM multiplier for groove animation speed control
+     *
+     * This scales the effective BPM used for groove animations without affecting
+     * the actual BPM detection or rhythm engine. Useful for controlling how fast
+     * the mascot dances regardless of the detected song tempo.
+     *
+     * Common use cases:
+     * - Set to 0.5 to halve animation speed for high BPM songs (>90 BPM)
+     * - Set to 2.0 to double animation speed for very slow songs
+     * - Set to 1.0 (default) to use detected BPM as-is
+     *
+     * @example
+     * // Halve animation speed for fast songs
+     * const status = mascot.getBPMStatus();
+     * if (status.bpm > 90) {
+     *     mascot.setBPMMultiplier(0.5);
+     * } else {
+     *     mascot.setBPMMultiplier(1.0);
+     * }
+     *
+     * @param {number} multiplier - BPM multiplier (0.25 to 4.0, default 1.0)
+     */
+    setBPMMultiplier(multiplier) {
+        if (this.core3D?.rhythm3DAdapter) {
+            this.core3D.rhythm3DAdapter.setBPMMultiplier(multiplier);
+        }
+    }
+
+    /**
+     * Get current BPM multiplier
+     * @returns {number} Current BPM multiplier (default 1.0)
+     */
+    getBPMMultiplier() {
+        return this.core3D?.rhythm3DAdapter?.getBPMMultiplier() ?? 1.0;
+    }
+
     /**
      * Set groove configuration for idle animations (advanced tuning)
      * @param {Object} config - Groove settings