@joshtol/emotive-engine 3.2.1 → 3.2.3

package/src/3d/managers/BehaviorController.js

@@ -0,0 +1,248 @@
+/**
+ * BehaviorController - Manages rotation, righting, and facing behaviors
+ *
+ * Centralizes behavior management for 3D mascot:
+ * - RotationBehavior: Emotion-driven rotation with wobble
+ * - RightingBehavior: Self-stabilization (punching bag effect)
+ * - FacingBehavior: Tidal lock for moon geometry
+ *
+ * Extracted from Core3DManager to improve separation of concerns.
+ *
+ * @module 3d/managers/BehaviorController
+ */
+
+import RotationBehavior from '../behaviors/RotationBehavior.js';
+import RightingBehavior from '../behaviors/RightingBehavior.js';
+import FacingBehavior from '../behaviors/FacingBehavior.js';
+
+/**
+ * Default righting behavior configuration
+ */
+const DEFAULT_RIGHTING_CONFIG = {
+    strength: 5.0,              // Strong righting without overdoing it
+    damping: 0.85,              // Critically damped for smooth return
+    centerOfMass: [0, -0.3, 0], // Bottom-heavy
+    axes: { pitch: true, roll: true, yaw: false }
+};
+
+export class BehaviorController {
+    /**
+     * Create behavior controller
+     * @param {Object} options - Configuration options
+     * @param {boolean} options.rotationDisabled - Whether rotation is disabled
+     * @param {boolean} options.wobbleEnabled - Whether wobble effects are enabled
+     */
+    constructor(options = {}) {
+        this.rotationBehavior = null;
+        this.rightingBehavior = null;
+        this.facingBehavior = null;
+
+        // State flags
+        this.rotationDisabled = options.rotationDisabled || false;
+        this.wobbleEnabled = options.wobbleEnabled !== false; // Default: enabled
+
+        // Initialize righting behavior (always active)
+        this.rightingBehavior = new RightingBehavior(DEFAULT_RIGHTING_CONFIG);
+    }
+
+    /**
+     * Configure rotation behavior based on emotion and geometry
+     * @param {Object} options - Configuration options
+     * @param {string} options.geometryType - Current geometry type
+     * @param {Object} options.emotionData - Emotion data with 3d rotation config
+     * @param {Object} options.facingConfig - Facing behavior config (for moon)
+     */
+    configureForEmotion(options = {}) {
+        const { geometryType, emotionData, facingConfig } = options;
+
+        // Moon is tidally locked - no rotation
+        if (geometryType === 'moon') {
+            this._disableRotation();
+            this._initFacingBehavior(facingConfig);
+            return;
+        }
+
+        // Dispose facing behavior if not moon
+        this._disposeFacingBehavior();
+
+        // Skip if rotation is disabled by user
+        if (this.rotationDisabled) {
+            this._disableRotation();
+            return;
+        }
+
+        // Configure rotation based on emotion
+        if (emotionData?.['3d']?.rotation) {
+            this._configureRotationFromEmotion(emotionData['3d'].rotation);
+        } else {
+            // Default rotation if no emotion-specific config
+            this._ensureDefaultRotation();
+        }
+
+        // Reset righting behavior on emotion change
+        if (this.rightingBehavior) {
+            this.rightingBehavior.reset();
+        }
+    }
+
+    /**
+     * Apply undertone modifiers to behaviors
+     * @param {Object} undertone3d - 3D undertone modifiers
+     */
+    applyUndertone(undertone3d) {
+        if (!undertone3d) return;
+
+        if (undertone3d.rotation && this.rotationBehavior) {
+            this.rotationBehavior.applyUndertoneMultipliers(undertone3d.rotation);
+        }
+
+        if (undertone3d.righting && this.rightingBehavior) {
+            this.rightingBehavior.applyUndertoneMultipliers(undertone3d.righting);
+        }
+    }
+
+    /**
+     * Update all behaviors for current frame
+     * @param {number} deltaTime - Time since last frame
+     * @param {THREE.Euler} baseEuler - Base euler rotation to modify
+     */
+    update(deltaTime, baseEuler) {
+        // Update rotation behavior
+        if (this.rotationBehavior) {
+            this.rotationBehavior.update(deltaTime, baseEuler);
+        }
+
+        // Update righting behavior (self-stabilization)
+        if (this.rightingBehavior) {
+            this.rightingBehavior.update(deltaTime, baseEuler);
+        }
+
+        // Update facing behavior (tidal lock)
+        if (this.facingBehavior) {
+            this.facingBehavior.update(deltaTime, baseEuler);
+        }
+    }
+
+    /**
+     * Set wobble enabled state
+     * @param {boolean} enabled - Whether wobble is enabled
+     */
+    setWobbleEnabled(enabled) {
+        this.wobbleEnabled = enabled;
+        if (this.rotationBehavior) {
+            this.rotationBehavior.setWobbleEnabled(enabled);
+        }
+
+        // When disabling wobble, reset to upright position
+        if (!enabled && this.rightingBehavior) {
+            this.rightingBehavior.reset();
+        }
+    }
+
+    /**
+     * Reset righting behavior
+     */
+    resetRighting() {
+        if (this.rightingBehavior) {
+            this.rightingBehavior.reset();
+        }
+    }
+
+    /**
+     * Get angular velocity from rotation behavior
+     * @returns {Array} [x, y, z] angular velocity or [0, 0, 0]
+     */
+    getAngularVelocity() {
+        return this.rotationBehavior ? this.rotationBehavior.axes : [0, 0, 0];
+    }
+
+    /**
+     * Check if rotation behavior is active
+     * @returns {boolean}
+     */
+    hasRotationBehavior() {
+        return !!this.rotationBehavior;
+    }
+
+    /**
+     * Configure rotation behavior from emotion data
+     * @private
+     */
+    _configureRotationFromEmotion(rotationConfig) {
+        if (this.rotationBehavior) {
+            this.rotationBehavior.updateConfig(rotationConfig);
+        } else {
+            this.rotationBehavior = new RotationBehavior(rotationConfig);
+        }
+        this.rotationBehavior.setWobbleEnabled(this.wobbleEnabled);
+    }
+
+    /**
+     * Ensure default rotation behavior exists
+     * @private
+     */
+    _ensureDefaultRotation() {
+        if (!this.rotationBehavior) {
+            this.rotationBehavior = new RotationBehavior({
+                axes: [0, 0.3, 0] // Default gentle Y rotation
+            });
+            this.rotationBehavior.setWobbleEnabled(this.wobbleEnabled);
+        }
+    }
+
+    /**
+     * Disable rotation behavior
+     * @private
+     */
+    _disableRotation() {
+        this.rotationBehavior = null;
+    }
+
+    /**
+     * Initialize facing behavior for tidal lock
+     * @private
+     */
+    _initFacingBehavior(facingConfig) {
+        if (!this.facingBehavior && facingConfig?.enabled) {
+            this.facingBehavior = new FacingBehavior({
+                strength: facingConfig.strength,
+                damping: facingConfig.damping,
+                faceAxis: facingConfig.faceAxis,
+                targetAxis: facingConfig.targetAxis
+            });
+        }
+    }
+
+    /**
+     * Dispose facing behavior
+     * @private
+     */
+    _disposeFacingBehavior() {
+        if (this.facingBehavior) {
+            this.facingBehavior.dispose();
+            this.facingBehavior = null;
+        }
+    }
+
+    /**
+     * Dispose all behaviors and clean up
+     */
+    dispose() {
+        if (this.rotationBehavior) {
+            this.rotationBehavior.destroy?.();
+            this.rotationBehavior = null;
+        }
+
+        if (this.rightingBehavior) {
+            this.rightingBehavior.destroy?.();
+            this.rightingBehavior = null;
+        }
+
+        if (this.facingBehavior) {
+            this.facingBehavior.dispose();
+            this.facingBehavior = null;
+        }
+    }
+}
+
+export default BehaviorController;

package/src/3d/managers/BreathingPhaseManager.js

@@ -0,0 +1,163 @@
+/**
+ * BreathingPhaseManager - Imperative breathing phase animation
+ *
+ * Provides explicit control over breathing animations for meditation:
+ * - breathePhase('inhale', 4) animates scale up over 4 seconds
+ * - breathePhase('exhale', 4) animates scale down over 4 seconds
+ * - breathePhase('hold', 4) maintains current scale
+ *
+ * Extracted from Core3DManager to improve separation of concerns.
+ *
+ * @module 3d/managers/BreathingPhaseManager
+ */
+
+/**
+ * Scale targets for different phases
+ */
+const PHASE_SCALES = {
+    inhale: 1.3,    // Max inhale size
+    exhale: 0.85,   // Min exhale size
+    neutral: 1.0    // Default/reset scale
+};
+
+/**
+ * Duration limits in seconds
+ */
+const MIN_DURATION = 0.5;
+const MAX_DURATION = 30;
+
+export class BreathingPhaseManager {
+    constructor() {
+        // Current phase state
+        this._phase = null;           // 'inhale' | 'hold' | 'exhale' | null
+        this._startTime = 0;
+        this._duration = 0;           // Duration in ms
+        this._startScale = 1.0;
+        this._targetScale = 1.0;
+        this._currentScale = 1.0;     // Current animated scale
+    }
+
+    /**
+     * Start a breathing phase animation
+     * @param {string} phase - 'inhale' | 'exhale' | 'hold'
+     * @param {number} durationSec - Duration in seconds for the animation
+     */
+    startPhase(phase, durationSec) {
+        // Clamp duration to reasonable values
+        const duration = Math.max(MIN_DURATION, Math.min(MAX_DURATION, durationSec));
+
+        // Store current scale as starting point
+        this._startScale = this._currentScale;
+        this._startTime = performance.now();
+        this._duration = duration * 1000; // Convert to ms
+        this._phase = phase;
+
+        // Set target scale based on phase
+        switch (phase) {
+            case 'inhale':
+                this._targetScale = PHASE_SCALES.inhale;
+                break;
+            case 'exhale':
+                this._targetScale = PHASE_SCALES.exhale;
+                break;
+            case 'hold':
+            default:
+                // Hold at current scale - no animation needed
+                this._targetScale = this._startScale;
+                break;
+        }
+    }
+
+    /**
+     * Stop any active breathing phase animation and reset to neutral scale
+     */
+    stop() {
+        this._phase = null;
+        this._currentScale = PHASE_SCALES.neutral;
+        this._startScale = PHASE_SCALES.neutral;
+        this._targetScale = PHASE_SCALES.neutral;
+    }
+
+    /**
+     * Check if a breathing phase is currently active
+     * @returns {boolean}
+     */
+    isActive() {
+        return this._phase !== null;
+    }
+
+    /**
+     * Get current phase name
+     * @returns {string|null}
+     */
+    getPhase() {
+        return this._phase;
+    }
+
+    /**
+     * Update breathing phase animation
+     * @param {number} _deltaTime - Time since last frame in ms (unused, we use elapsed time)
+     * @returns {number} Current breathing phase scale multiplier (1.0 if inactive)
+     */
+    update(_deltaTime) {
+        // If no active phase, return current scale
+        if (!this._phase) {
+            return this._currentScale;
+        }
+
+        const now = performance.now();
+        const elapsed = now - this._startTime;
+
+        // Calculate progress (0 to 1)
+        const progress = Math.min(1.0, elapsed / this._duration);
+
+        // Use sine easing for natural breathing rhythm
+        // sin(0 to π/2) maps 0→1 smoothly, reaches target exactly at end
+        // This feels more like natural breathing than cubic easing
+        const eased = Math.sin(progress * Math.PI / 2);
+
+        // Interpolate between start and target scale
+        this._currentScale = this._startScale +
+            (this._targetScale - this._startScale) * eased;
+
+        // Clear phase when complete
+        if (progress >= 1.0) {
+            this._currentScale = this._targetScale;
+            this._phase = null;
+        }
+
+        return this._currentScale;
+    }
+
+    /**
+     * Get current scale multiplier
+     * @returns {number}
+     */
+    getScaleMultiplier() {
+        return this._currentScale;
+    }
+
+    /**
+     * Get current animation state for debugging
+     * @returns {Object}
+     */
+    getState() {
+        return {
+            phase: this._phase,
+            startScale: this._startScale,
+            targetScale: this._targetScale,
+            currentScale: this._currentScale,
+            duration: this._duration,
+            isActive: this._phase !== null
+        };
+    }
+
+    /**
+     * Dispose manager (nothing to clean up, but follows pattern)
+     */
+    dispose() {
+        this._phase = null;
+    }
+}
+
+export default BreathingPhaseManager;

package/src/3d/managers/CameraPresetManager.js

@@ -0,0 +1,182 @@
+/**
+ * CameraPresetManager - Manages camera preset views and transitions
+ *
+ * Provides smooth camera transitions to predefined viewpoints:
+ * - front, side, top, angle, back, bottom
+ *
+ * Extracted from ThreeRenderer to improve separation of concerns.
+ *
+ * @module 3d/managers/CameraPresetManager
+ */
+
+import * as THREE from 'three';
+
+/**
+ * Available camera preset positions
+ * @param {number} d - Camera distance from origin
+ */
+const getPresets = d => ({
+    front: { x: 0, y: 0, z: d },
+    side: { x: d, y: 0, z: 0 },
+    top: { x: 0, y: d, z: 0 },
+    angle: { x: d * 0.67, y: d * 0.5, z: d * 0.67 },
+    back: { x: 0, y: 0, z: -d },
+    bottom: { x: 0, y: -d, z: 0 }
+});
+
+export class CameraPresetManager {
+    /**
+     * Create camera preset manager
+     * @param {THREE.Camera} camera - The camera to control
+     * @param {OrbitControls} controls - The orbit controls
+     * @param {number} cameraDistance - Default distance from origin
+     */
+    constructor(camera, controls, cameraDistance = 3) {
+        this.camera = camera;
+        this.controls = controls;
+        this.cameraDistance = cameraDistance;
+        this.animationId = null;
+    }
+
+    /**
+     * Get list of available presets
+     * @returns {string[]}
+     */
+    getAvailablePresets() {
+        return Object.keys(getPresets(this.cameraDistance));
+    }
+
+    /**
+     * Set camera to a preset view with smooth transition
+     * @param {string} preset - Preset name ('front', 'side', 'top', 'angle', 'back', 'bottom')
+     * @param {number} duration - Transition duration in ms (default 1000)
+     * @param {boolean} preserveTarget - If true, keep the current controls.target (default false)
+     */
+    setPreset(preset, duration = 1000, preserveTarget = false) {
+        if (!this.controls) return;
+
+        const presets = getPresets(this.cameraDistance);
+        const targetPos = presets[preset];
+
+        if (!targetPos) {
+            console.warn(`Unknown camera preset: ${preset}`);
+            return;
+        }
+
+        // Cancel any ongoing animation
+        this.cancelAnimation();
+
+        // Save current target if we need to preserve it
+        const savedTarget = preserveTarget ? this.controls.target.clone() : null;
+
+        // If instant (duration = 0), set position directly
+        if (duration === 0) {
+            this._setInstant(targetPos, savedTarget);
+            return;
+        }
+
+        // Animated transition
+        this._animateTo(targetPos, duration, savedTarget, preserveTarget);
+    }
+
+    /**
+     * Set camera position instantly
+     * @private
+     */
+    _setInstant(targetPos, savedTarget) {
+        // Fully reset OrbitControls to initial state
+        this.controls.reset();
+        // Then set to target position
+        this.camera.position.set(targetPos.x, targetPos.y, targetPos.z);
+        // Preserve or reset the controls target
+        if (savedTarget) {
+            this.controls.target.copy(savedTarget);
+            this.camera.lookAt(savedTarget);
+        } else {
+            this.controls.target.set(0, 0, 0);
+            this.camera.lookAt(0, 0, 0);
+        }
+        this.controls.update();
+    }
+
+    /**
+     * Animate camera to target position
+     * @private
+     */
+    _animateTo(targetPos, duration, savedTarget, preserveTarget) {
+        // Reset OrbitControls target to center (origin) for animated presets
+        if (!preserveTarget) {
+            this.controls.target.set(0, 0, 0);
+        }
+
+        // Smoothly animate camera to target position
+        const startPos = this.camera.position.clone();
+        const endPos = new THREE.Vector3(targetPos.x, targetPos.y, targetPos.z);
+        const startTime = performance.now();
+
+        const animate = currentTime => {
+            const elapsed = currentTime - startTime;
+            const progress = Math.min(elapsed / duration, 1.0);
+
+            // Ease out cubic for smooth deceleration
+            const eased = 1 - Math.pow(1 - progress, 3);
+
+            this.camera.position.lerpVectors(startPos, endPos, eased);
+            this.camera.lookAt(0, 0, 0);
+            this.controls.update();
+
+            if (progress < 1.0) {
+                this.animationId = requestAnimationFrame(animate);
+            } else {
+                this.animationId = null;
+            }
+        };
+
+        this.animationId = requestAnimationFrame(animate);
+    }
+
+    /**
+     * Check if animation is in progress
+     * @returns {boolean}
+     */
+    isAnimating() {
+        return this.animationId !== null;
+    }
+
+    /**
+     * Cancel any ongoing camera animation
+     */
+    cancelAnimation() {
+        if (this.animationId !== null) {
+            cancelAnimationFrame(this.animationId);
+            this.animationId = null;
+        }
+    }
+
+    /**
+     * Reset camera to default front view
+     * @param {number} duration - Transition duration in ms
+     */
+    reset(duration = 1000) {
+        this.setPreset('front', duration);
+    }
+
+    /**
+     * Update camera distance (affects preset positions)
+     * @param {number} distance - New camera distance
+     */
+    setCameraDistance(distance) {
+        this.cameraDistance = distance;
+    }
+
+    /**
+     * Dispose manager and clean up
+     */
+    dispose() {
+        this.cancelAnimation();
+        this.camera = null;
+        this.controls = null;
+    }
+}
+
+export default CameraPresetManager;