@joshtol/emotive-engine 3.2.2 → 3.2.3

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

@@ -0,0 +1,385 @@
+/**
+ * EffectManager - Manages geometry-specific visual effects
+ *
+ * Handles lifecycle management for:
+ * - SolarEclipse (sun geometry)
+ * - LunarEclipse (moon geometry)
+ * - CrystalSoul (crystal-type geometries)
+ *
+ * Extracted from Core3DManager to improve separation of concerns.
+ *
+ * @module 3d/managers/EffectManager
+ */
+
+import { SolarEclipse } from '../effects/SolarEclipse.js';
+import { LunarEclipse } from '../effects/LunarEclipse.js';
+import { CrystalSoul } from '../effects/CrystalSoul.js';
+
+/**
+ * Geometry types that use CrystalSoul effect
+ */
+const CRYSTAL_SOUL_GEOMETRIES = ['crystal', 'rough', 'heart', 'star'];
+
+export class EffectManager {
+    /**
+     * Create effect manager
+     * @param {ThreeRenderer} renderer - The Three.js renderer
+     * @param {string} assetBasePath - Base path for loading assets
+     */
+    constructor(renderer, assetBasePath = '/assets') {
+        this.renderer = renderer;
+        this.assetBasePath = assetBasePath;
+
+        // Effect instances
+        this.solarEclipse = null;
+        this.lunarEclipse = null;
+        this.crystalSoul = null;
+
+        // State tracking
+        this.currentGeometryType = null;
+        this.coreGlowEnabled = true;
+    }
+
+    /**
+     * Initialize effects for a specific geometry type
+     * @param {string} geometryType - The geometry type (sun, moon, crystal, etc.)
+     * @param {Object} options - Options for initialization
+     * @param {THREE.Mesh} options.coreMesh - The core mesh to attach effects to
+     * @param {Object} options.customMaterial - Custom material (for lunar eclipse)
+     * @param {number} options.sunRadius - Sun radius (for solar eclipse)
+     */
+    initializeForGeometry(geometryType, options = {}) {
+        const { coreMesh, customMaterial, sunRadius = 1.0 } = options;
+        this.currentGeometryType = geometryType;
+
+        // Clean up effects not needed for this geometry
+        this._cleanupUnneededEffects(geometryType);
+
+        // Initialize geometry-specific effects
+        if (geometryType === 'sun') {
+            this._initSolarEclipse(sunRadius, coreMesh);
+        } else if (geometryType === 'moon') {
+            this._initLunarEclipse(customMaterial);
+        } else if (CRYSTAL_SOUL_GEOMETRIES.includes(geometryType)) {
+            // CrystalSoul is initialized separately via createCrystalSoul()
+            // because it has complex async loading requirements
+        }
+    }
+
+    /**
+     * Initialize solar eclipse effect
+     * @private
+     */
+    _initSolarEclipse(sunRadius, coreMesh) {
+        if (!this.solarEclipse && this.renderer?.scene) {
+            this.solarEclipse = new SolarEclipse(this.renderer.scene, sunRadius, coreMesh);
+        }
+    }
+
+    /**
+     * Initialize lunar eclipse effect
+     * @private
+     */
+    _initLunarEclipse(customMaterial) {
+        if (!this.lunarEclipse && customMaterial) {
+            this.lunarEclipse = new LunarEclipse(customMaterial);
+        }
+    }
+
+    /**
+     * Clean up effects that are not needed for the current geometry
+     * @private
+     */
+    _cleanupUnneededEffects(geometryType) {
+        // Dispose solar eclipse if not sun
+        if (geometryType !== 'sun' && this.solarEclipse) {
+            this.solarEclipse.dispose();
+            this.solarEclipse = null;
+        }
+
+        // Dispose lunar eclipse if not moon
+        if (geometryType !== 'moon' && this.lunarEclipse) {
+            this.lunarEclipse.dispose();
+            this.lunarEclipse = null;
+        }
+
+        // Dispose crystal soul if not a crystal-type geometry
+        if (!CRYSTAL_SOUL_GEOMETRIES.includes(geometryType) && this.crystalSoul) {
+            this.crystalSoul.dispose();
+            this.crystalSoul = null;
+        }
+    }
+
+    /**
+     * Create crystal soul effect (async due to inclusion geometry loading)
+     * @param {Object} options - Crystal soul options
+     * @param {THREE.Mesh} options.coreMesh - Core mesh to attach to
+     * @param {string} options.geometryType - Geometry type for configuration
+     * @returns {Object} Soul configuration { mesh, material, baseScale, shellBaseScale }
+     */
+    async createCrystalSoul(options = {}) {
+        const { coreMesh, geometryType } = options;
+
+        // Dispose existing soul
+        if (this.crystalSoul) {
+            this.crystalSoul.dispose();
+            this.crystalSoul = null;
+        }
+
+        if (!coreMesh) {
+            return null;
+        }
+
+        // Preload inclusion geometry
+        await CrystalSoul._loadInclusionGeometry(this.assetBasePath);
+
+        // Create new soul
+        this.crystalSoul = new CrystalSoul({
+            radius: 0.35,
+            detail: 1,
+            geometryType,
+            renderer: this.renderer,
+            assetBasePath: this.assetBasePath
+        });
+
+        this.crystalSoul.attachTo(coreMesh, this.renderer?.scene);
+
+        // Get geometry-specific scale configuration
+        const { shellBaseScale, soulScale } = this._getCrystalScaleConfig(geometryType);
+
+        this.crystalSoul.baseScale = soulScale;
+        this.crystalSoul.mesh.scale.setScalar(soulScale);
+        this.crystalSoul.setVisible(this.coreGlowEnabled);
+
+        return {
+            mesh: this.crystalSoul.mesh,
+            material: this.crystalSoul.material,
+            baseScale: this.crystalSoul.baseScale,
+            shellBaseScale
+        };
+    }
+
+    /**
+     * Create crystal soul synchronously (non-async version)
+     * @param {Object} options - Crystal soul options
+     * @returns {Object} Soul configuration
+     */
+    createCrystalSoulSync(options = {}) {
+        const { coreMesh, geometryType } = options;
+
+        if (this.crystalSoul) {
+            this.crystalSoul.dispose();
+            this.crystalSoul = null;
+        }
+
+        if (!coreMesh) {
+            return null;
+        }
+
+        this.crystalSoul = new CrystalSoul({
+            radius: 0.35,
+            detail: 1,
+            geometryType,
+            renderer: this.renderer,
+            assetBasePath: this.assetBasePath
+        });
+
+        this.crystalSoul.attachTo(coreMesh, this.renderer?.scene);
+
+        const { shellBaseScale, soulScale } = this._getCrystalScaleConfig(geometryType);
+
+        this.crystalSoul.baseScale = soulScale;
+        this.crystalSoul.mesh.scale.setScalar(soulScale);
+        this.crystalSoul.setVisible(this.coreGlowEnabled);
+
+        return {
+            mesh: this.crystalSoul.mesh,
+            material: this.crystalSoul.material,
+            baseScale: this.crystalSoul.baseScale,
+            shellBaseScale
+        };
+    }
+
+    /**
+     * Get scale configuration for crystal-type geometries
+     * @private
+     */
+    _getCrystalScaleConfig(geometryType) {
+        let shellBaseScale = 2.0;  // Default crystal shell size
+        let soulScale = 1.0;       // Default: full size
+
+        if (geometryType === 'heart') {
+            shellBaseScale = 2.4;
+            soulScale = 1.0;
+        } else if (geometryType === 'rough') {
+            shellBaseScale = 1.6;
+            soulScale = 1.0;
+        } else if (geometryType === 'star') {
+            shellBaseScale = 2.0;
+            soulScale = 1.4;  // Larger soul for star to fill the shape
+        } else if (geometryType === 'crystal') {
+            shellBaseScale = 2.0;
+            soulScale = 1.0;
+        }
+
+        return { shellBaseScale, soulScale };
+    }
+
+    /**
+     * Set solar eclipse type
+     * @param {string} eclipseType - 'off', 'annular', or 'total'
+     * @returns {boolean} True if eclipse was set
+     */
+    setSolarEclipse(eclipseType) {
+        if (!this.solarEclipse) {
+            return false;
+        }
+        this.solarEclipse.setEclipseType(eclipseType);
+        return true;
+    }
+
+    /**
+     * Set lunar eclipse type
+     * @param {string} eclipseType - 'off', 'penumbral', 'partial', 'total'
+     * @returns {boolean} True if eclipse was set
+     */
+    setLunarEclipse(eclipseType) {
+        if (!this.lunarEclipse) {
+            return false;
+        }
+        this.lunarEclipse.setEclipseType(eclipseType);
+        return true;
+    }
+
+    /**
+     * Stop all eclipse effects
+     */
+    stopAllEclipses() {
+        if (this.solarEclipse) {
+            this.solarEclipse.setEclipseType('off');
+        }
+        if (this.lunarEclipse) {
+            this.lunarEclipse.setEclipseType('off');
+        }
+    }
+
+    /**
+     * Update crystal soul
+     * @param {number} deltaTime - Time since last frame
+     * @param {Array} glowColor - RGB color [r, g, b]
+     * @param {number} breathScale - Breathing animation scale
+     */
+    updateCrystalSoul(deltaTime, glowColor, breathScale = 1.0) {
+        if (this.crystalSoul) {
+            this.crystalSoul.update(deltaTime, glowColor, breathScale);
+        }
+    }
+
+    /**
+     * Update lunar eclipse
+     * @param {number} deltaTime - Time since last frame
+     */
+    updateLunarEclipse(deltaTime) {
+        if (this.lunarEclipse) {
+            this.lunarEclipse.update(deltaTime);
+        }
+    }
+
+    /**
+     * Set crystal soul effect parameters
+     * @param {Object} params - Effect parameters
+     */
+    setCrystalSoulEffects(params) {
+        if (this.crystalSoul) {
+            this.crystalSoul.setEffects(params);
+        }
+    }
+
+    /**
+     * Set crystal soul size
+     * @param {number} size - Size value
+     * @returns {number} The new base scale
+     */
+    setCrystalSoulSize(size) {
+        if (this.crystalSoul) {
+            this.crystalSoul.setSize(size);
+            return this.crystalSoul.baseScale;
+        }
+        return 1.0;
+    }
+
+    /**
+     * Set crystal soul visibility
+     * @param {boolean} visible - Whether soul should be visible
+     */
+    setCrystalSoulVisible(visible) {
+        this.coreGlowEnabled = visible;
+        if (this.crystalSoul) {
+            this.crystalSoul.setVisible(visible);
+        }
+    }
+
+    /**
+     * Check if crystal soul exists
+     * @returns {boolean}
+     */
+    hasCrystalSoul() {
+        return !!this.crystalSoul;
+    }
+
+    /**
+     * Get crystal soul base scale
+     * @returns {number}
+     */
+    getCrystalSoulBaseScale() {
+        return this.crystalSoul?.baseScale ?? 1.0;
+    }
+
+    /**
+     * Check if solar eclipse is active
+     * @returns {boolean}
+     */
+    hasSolarEclipse() {
+        return !!this.solarEclipse;
+    }
+
+    /**
+     * Check if lunar eclipse is active
+     * @returns {boolean}
+     */
+    hasLunarEclipse() {
+        return !!this.lunarEclipse;
+    }
+
+    /**
+     * Get solar eclipse instance (for render pass)
+     * @returns {SolarEclipse|null}
+     */
+    getSolarEclipse() {
+        return this.solarEclipse;
+    }
+
+    /**
+     * Dispose all effects
+     */
+    dispose() {
+        if (this.solarEclipse) {
+            this.solarEclipse.dispose();
+            this.solarEclipse = null;
+        }
+
+        if (this.lunarEclipse) {
+            this.lunarEclipse.dispose();
+            this.lunarEclipse = null;
+        }
+
+        if (this.crystalSoul) {
+            this.crystalSoul.dispose();
+            this.crystalSoul = null;
+        }
+
+        this.renderer = null;
+    }
+}
+
+export default EffectManager;

package/src/3d/utils/MaterialFactory.js

@@ -75,10 +75,10 @@ function createCrystalMaterial(glowColor, glowIntensity, textureType = 'crystal'
     if (textureType) {
         const textureLoader = new THREE.TextureLoader();
         const texturePaths = {
-            crystal: `${assetBasePath}/textures/Crystal/crystal.jpg`,
-            rough: `${assetBasePath}/textures/Crystal/rough.jpg`,
-            heart: `${assetBasePath}/textures/Crystal/heart.jpg`,
-            star: `${assetBasePath}/textures/Crystal/star.jpg`
+            crystal: `${assetBasePath}/textures/Crystal/crystal.png`,
+            rough: `${assetBasePath}/textures/Crystal/rough.png`,
+            heart: `${assetBasePath}/textures/Crystal/heart.png`,
+            star: `${assetBasePath}/textures/Crystal/star.png`
         };
         const texturePath = texturePaths[textureType] || texturePaths.crystal;
         crystalTexture = textureLoader.load(texturePath,
@@ -191,7 +191,8 @@ function createCrystalMaterial(glowColor, glowIntensity, textureType = 'crystal'
 }
 
 function createMoonMaterial(textureLoader, glowColor, glowIntensity, materialVariant = null, assetBasePath = '/assets') {
-    const resolution = '2k';
+    const isMobile = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
+    const resolution = isMobile ? '2k' : '4k';
 
     if (materialVariant === 'multiplexer') {
         const material = createMoonMultiplexerMaterial(textureLoader, {

package/types/index.d.ts

@@ -207,22 +207,28 @@ declare namespace EmotiveEngine {
     // Main Emotive Mascot
     export interface EmotiveMascotConfig {
         canvas?: HTMLCanvasElement;
+        canvasId?: string | HTMLCanvasElement;
         width?: number;
         height?: number;
         autoStart?: boolean;
         fps?: number;
+        targetFPS?: number;
         adaptive?: boolean;
         theme?: Theme;
         enableAudio?: boolean;
         enableParticles?: boolean;
+        enableGazeTracking?: boolean;
+        defaultEmotion?: string;
     }
 
     export interface Theme {
-        primary: string;
-        secondary: string;
-        accent: string;
+        primary?: string;
+        secondary?: string;
+        accent?: string;
         background?: string;
         particles?: string[];
+        core?: string;
+        glow?: string;
     }
 
     export interface EmotionalState {
@@ -231,22 +237,212 @@ declare namespace EmotiveEngine {
         dominance?: number;
     }
 
+    export interface FeelResult {
+        success: boolean;
+        error: string | null;
+        parsed: ParsedIntent | null;
+    }
+
+    export interface ParsedIntent {
+        emotion: string | null;
+        gestures: string[];
+        shape: string | null;
+        undertone: string | null;
+        intensity: number;
+    }
+
+    export interface FeelVocabulary {
+        emotions: string[];
+        undertones: string[];
+        gestures: string[];
+        shapes: string[];
+    }
+
+    export interface BackdropOptions {
+        enabled?: boolean;
+        radius?: number;
+        shape?: 'circle' | 'ellipse' | 'fullscreen';
+        color?: string;
+        intensity?: number;
+        blendMode?: 'normal' | 'multiply' | 'overlay' | 'screen';
+        falloff?: 'linear' | 'smooth' | 'exponential' | 'custom';
+        falloffCurve?: Array<{ stop: number; alpha: number }>;
+        edgeSoftness?: number;
+        coreTransparency?: number;
+        blur?: number;
+        responsive?: boolean;
+        pulse?: boolean;
+        offset?: { x: number; y: number };
+        type?: 'radial-gradient' | 'vignette' | 'glow';
+    }
+
+    export interface AttachOptions {
+        offsetX?: number;
+        offsetY?: number;
+        animate?: boolean;
+        duration?: number;
+        scale?: number;
+        containParticles?: boolean;
+    }
+
+    export interface PerformanceMetrics {
+        fps: number;
+        frameTime: number;
+        particleCount?: number;
+    }
+
+    export interface AudioAnalysis {
+        beats?: any;
+        tempo?: number;
+        energy?: number;
+    }
+
+    export interface GazeState {
+        x: number;
+        y: number;
+        enabled: boolean;
+    }
+
+    export interface Capabilities {
+        audio: boolean;
+        recording: boolean;
+        timeline: boolean;
+        export: boolean;
+        shapes: boolean;
+        gestures: boolean;
+        emotions: boolean;
+        particles: boolean;
+        gazeTracking: boolean;
+    }
+
+    export interface TimelineEvent {
+        type: 'emotion' | 'gesture' | 'shape';
+        name: string;
+        time: number;
+        undertone?: string;
+        config?: any;
+    }
+
+    export interface ScaleOptions {
+        global?: number;
+        core?: number;
+        particles?: number;
+    }
+
     export class EmotiveMascot {
         constructor(config?: EmotiveMascotConfig);
-        init(container: HTMLElement): void;
+
+        // Lifecycle
+        init(canvas: HTMLCanvasElement | string): Promise<void>;
         start(): void;
         stop(): void;
         pause(): void;
         resume(): void;
         destroy(): void;
-        setEmotion(emotion: string | EmotionalState): void;
-        setTheme(theme: Theme): void;
+
+        // LLM Integration - Natural Language API
+        feel(intent: string): FeelResult;
+        static getFeelVocabulary(): FeelVocabulary;
+        parseIntent(intent: string): ParsedIntent;
+
+        // Emotion & Expression
+        setEmotion(emotion: string, undertoneOrDurationOrOptions?: string | number | { undertone?: string; duration?: number }, timestamp?: number): void;
+        express(gestureName: string, timestamp?: number): void;
+        triggerGesture(gestureName: string, timestamp?: number): void;
+        chain(chainName: string): void;
+        updateUndertone(undertone: string | null): void;
+
+        // Shape Morphing
+        morphTo(shape: string, config?: any): void;
+        setShape(shape: string, configOrTimestamp?: any | number): void;
+
+        // Audio
+        loadAudio(source: string | Blob): Promise<void>;
+        connectAudio(audioElement: HTMLAudioElement): void;
+        disconnectAudio(audioElement?: HTMLAudioElement): void;
+        getAudioAnalysis(): AudioAnalysis;
+        getSpectrumData(): number[];
+        startRhythmSync(bpm?: number): void;
+        stopRhythmSync(): void;
+        setSoundEnabled(enabled: boolean): void;
         setBPM(bpm: number): void;
-        addBehavior(behavior: Behavior): void;
-        removeBehavior(name: string): void;
-        on(event: string, handler: Function): void;
-        off(event: string, handler?: Function): void;
-        getState(): any;
+
+        // Gaze Tracking
+        enableGazeTracking(): void;
+        disableGazeTracking(): void;
+        setGazeTarget(x: number, y: number): void;
+        getGazeState(): GazeState | null;
+
+        // Positioning
+        setPosition(x: number, y: number, z?: number): void;
+        animateToPosition(x: number, y: number, z?: number, duration?: number, easing?: string): void;
+        attachToElement(elementOrSelector: string | HTMLElement, options?: AttachOptions): EmotiveMascot;
+        detachFromElement(): void;
+        isAttachedToElement(): boolean;
+        setContainment(bounds: { width: number; height: number } | null, scale?: number): void;
+
+        // Visual Customization
+        setScale(scaleOrOptions: number | ScaleOptions): EmotiveMascot;
+        getScale(): number;
+        setOpacity(opacity: number): EmotiveMascot;
+        getOpacity(): number;
+        fadeIn(duration?: number): EmotiveMascot;
+        fadeOut(duration?: number): EmotiveMascot;
+        setColor(color: string): EmotiveMascot;
+        setGlowColor(color: string): EmotiveMascot;
+        setTheme(theme: Theme): EmotiveMascot;
+        setBackdrop(options: BackdropOptions): EmotiveMascot;
+        getBackdrop(): BackdropOptions | null;
+
+        // Particles
+        clearParticles(): void;
+        setMaxParticles(maxParticles: number): EmotiveMascot;
+        getParticleCount(): number;
+        setParticleSystemCanvasDimensions(width: number, height: number): EmotiveMascot;
+
+        // Performance
+        setQuality(level: 'low' | 'medium' | 'high'): void;
+        setSpeed(speed: number): EmotiveMascot;
+        getSpeed(): number;
+        setFPS(fps: number): EmotiveMascot;
+        getFPS(): number;
+        isPaused(): boolean;
+        getPerformanceMetrics(): PerformanceMetrics;
+        batch(callback: (mascot: EmotiveMascot) => void): EmotiveMascot;
+
+        // Timeline Recording
+        startRecording(): void;
+        stopRecording(): TimelineEvent[];
+        playTimeline(timeline: TimelineEvent[]): void;
+        stopPlayback(): void;
+        getTimeline(): TimelineEvent[];
+        loadTimeline(timeline: TimelineEvent[]): void;
+        exportTimeline(): string;
+        importTimeline(json: string): void;
+        getCurrentTime(): number;
+        seek(time: number): void;
+
+        // Export
+        getFrameData(format?: string): string;
+        getFrameBlob(format?: string): Promise<Blob>;
+        getAnimationData(): any;
+
+        // Query
+        getAvailableGestures(): string[];
+        getAvailableEmotions(): string[];
+        getAvailableShapes(): string[];
+        getVersion(): string;
+        getCapabilities(): Capabilities;
+
+        // Events
+        on(event: string, handler: Function): EmotiveMascot;
+        off(event: string, handler?: Function): EmotiveMascot;
+
+        // Component access (safe proxies)
+        readonly renderer: any;
+        readonly shapeMorpher: any;
+        readonly gazeTracker: any;
+        readonly canvas: HTMLCanvasElement;
     }
 
     // Particle System