canvasengine 2.0.0-beta.4 → 2.0.0-beta.40

package/src/directives/Shake.ts

@@ -0,0 +1,282 @@
+import { Container, Point } from 'pixi.js';
+import { Directive, registerDirective } from '../engine/directive';
+import { Element } from '../engine/reactive';
+import { effect } from '@signe/reactive';
+import { on, isTrigger, Trigger } from '../engine/trigger';
+import { useProps } from '../hooks/useProps';
+import { SignalOrPrimitive } from '../components/types';
+import { animatedSignal, AnimatedSignal } from '../engine/animation';
+import { Subscription } from 'rxjs';
+
+export type ShakeProps = {
+    /**
+     * Trigger that activates the shake animation
+     * When the trigger is activated, the shake animation will start
+     */
+    trigger?: Trigger<any>;
+    /**
+     * Intensity of the shake effect (in pixels)
+     * @default 10
+     */
+    intensity?: SignalOrPrimitive<number>;
+    /**
+     * Duration of the shake animation in milliseconds
+     * @default 500
+     */
+    duration?: SignalOrPrimitive<number>;
+    /**
+     * Number of shake oscillations during the animation
+     * Higher values create more rapid shaking
+     * @default 10
+     */
+    frequency?: SignalOrPrimitive<number>;
+    /**
+     * Direction of the shake: 'x', 'y', or 'both'
+     * @default 'both'
+     */
+    direction?: SignalOrPrimitive<'x' | 'y' | 'both'>;
+    /**
+     * Callback function called when shake starts
+     */
+    onStart?: () => void;
+    /**
+     * Callback function called when shake completes
+     */
+    onComplete?: () => void;
+}
+
+/**
+ * Shake directive that animates a display object's position when a trigger is activated.
+ * Creates a shake effect by rapidly oscillating the x and/or y position.
+ * 
+ * @example
+ * ```typescript
+ * // Basic usage with trigger
+ * const shakeTrigger = trigger();
+ * 
+ * onMount(element) {
+ *   // Element will shake when trigger is activated
+ *   element.props.shake = { trigger: shakeTrigger };
+ * }
+ * 
+ * // Trigger the shake
+ * shakeTrigger.start();
+ * ```
+ */
+export class Shake extends Directive {
+    private elementRef: Element<Container> | null = null;
+    private originalPosition: Point = new Point();
+    private progressSignal: AnimatedSignal<number> | null = null;
+    private shakeSubscription: any = null;
+    private positionEffect: Subscription | null = null;
+    private currentShakeConfig: {
+        intensity: number;
+        frequency: number;
+        direction: 'x' | 'y' | 'both';
+        randomSeed: number;
+    } | null = null;
+
+    /**
+     * Initializes the shake directive
+     * @param element - The element to attach the shake effect to
+     */
+    onInit(element: Element<Container>) {
+        this.elementRef = element;
+    }
+
+    /**
+     * Mounts the shake directive and sets up trigger listener
+     * @param element - The element being mounted
+     */
+    onMount(element: Element<Container>) {
+        const instance = element.componentInstance;
+        if (!instance) return;
+
+        const shakeProps = this.shakeProps;
+        
+        // Check if trigger is provided
+        if (!shakeProps.trigger || !isTrigger(shakeProps.trigger)) {
+            return;
+        }
+
+        // Store original position
+        this.originalPosition.set(instance.position.x, instance.position.y);
+
+        // Listen to trigger activation
+        this.shakeSubscription = on(shakeProps.trigger, async (data) => {
+            await this.performShake(data);
+        });
+    }
+
+    /**
+     * Gets the shake props with default values
+     * @returns ShakeProps with defaults applied
+     */
+    get shakeProps(): ShakeProps {
+        const shake = this.elementRef?.props.shake;
+        return useProps(shake?.value ?? shake, {
+            intensity: 10,
+            duration: 500,
+            frequency: 10,
+            direction: 'both',
+        });
+    }
+
+    /**
+     * Performs the shake animation using animatedSignal
+     * @param data - Optional data passed from the trigger that can override default options
+     */
+    private async performShake(data?: any): Promise<void> {
+        if (!this.elementRef?.componentInstance) return;
+
+        const instance = this.elementRef.componentInstance;
+        const shakeProps = this.shakeProps;
+        
+        // Use data from trigger to override defaults if provided
+        const intensity = data?.intensity ?? shakeProps.intensity();
+        const duration = data?.duration ?? shakeProps.duration();
+        const frequency = data?.frequency ?? shakeProps.frequency();
+        const direction = data?.direction ?? shakeProps.direction();
+
+        // Stop any existing animation and clean up
+        if (this.positionEffect) {
+            this.positionEffect.unsubscribe();
+            this.positionEffect = null;
+        }
+
+        // Reset position to original before starting new shake
+        this.originalPosition.set(instance.position.x, instance.position.y);
+        instance.position.x = this.originalPosition.x;
+        instance.position.y = this.originalPosition.y;
+
+        // Call onStart callback
+        shakeProps.onStart?.();
+
+        // Store current shake configuration for use in effect
+        this.currentShakeConfig = {
+            intensity,
+            frequency,
+            direction,
+            randomSeed: Math.random() * 1000, // Fixed random seed for this shake
+        };
+
+        // Create or recreate progress signal for shake animation
+        // We recreate it to ensure a fresh animation state
+        if (this.progressSignal) {
+            // Reset to 0 immediately without animation
+            this.progressSignal.set(0, { duration: 0 });
+            // Wait a bit to ensure the reset is complete
+            await new Promise(resolve => setTimeout(resolve, 0));
+        } else {
+            this.progressSignal = animatedSignal(0, {
+                duration: duration,
+                ease: (t) => t, // Linear ease, we'll handle oscillation in effect
+            });
+        }
+
+        const shakeX = direction === 'y' ? false : true;
+        const shakeY = direction === 'x' ? false : true;
+
+        // Create effect to update position based on progress
+        this.positionEffect = effect(() => {
+            if (!instance || !this.progressSignal || !this.currentShakeConfig) return;
+
+            const progress = this.progressSignal();
+            const config = this.currentShakeConfig;
+            
+            // Calculate decay factor (shake intensity decreases over time)
+            const decay = 1 - progress;
+            
+            // Generate oscillation based on progress and frequency
+            // progress goes from 0 to 1, so we multiply by frequency to get oscillations
+            const time = progress * config.frequency;
+            const oscillation = Math.sin(time * Math.PI * 2);
+            
+            // Apply shake with decay and consistent random variation
+            // Use the stored random seed for consistency during this shake
+            const randomValue = (Math.sin(config.randomSeed + progress * 10) * 0.25 + 1); // Between 0.75 and 1.25
+            const offsetX = shakeX ? oscillation * config.intensity * decay * randomValue : 0;
+            const offsetY = shakeY ? oscillation * config.intensity * decay * randomValue : 0;
+
+            // Update position
+            instance.position.x = this.originalPosition.x + offsetX;
+            instance.position.y = this.originalPosition.y + offsetY;
+        }).subscription;
+
+        // Start animation and wait for completion
+        // Note: animatedSignal.set() replaces onComplete with resolve, so we call onComplete after await
+        await this.progressSignal.set(1, {
+            duration: duration,
+        });
+
+        // Animation completed - clean up and call callbacks
+        // Reset to original position
+        if (instance) {
+            instance.position.x = this.originalPosition.x;
+            instance.position.y = this.originalPosition.y;
+        }
+        
+        // Clean up position effect
+        if (this.positionEffect) {
+            this.positionEffect.unsubscribe();
+            this.positionEffect = null;
+        }
+        
+        // Clear shake config
+        this.currentShakeConfig = null;
+        
+        // Call onComplete callback
+        shakeProps.onComplete?.();
+    }
+
+    /**
+     * Updates the shake directive when props change
+     * @param props - Updated props
+     */
+    onUpdate(props: any) {
+        // Re-mount if props change significantly
+        if (props.type && props.type === 'reset') {
+            this.onDestroy();
+            if (this.elementRef) {
+                this.onMount(this.elementRef);
+            }
+        }
+    }
+
+    /**
+     * Cleans up the shake directive
+     */
+    onDestroy() {
+        // Stop any running animation by resetting progress
+        if (this.progressSignal) {
+            this.progressSignal.set(0, { duration: 0 });
+            this.progressSignal = null;
+        }
+
+        // Clean up position effect
+        if (this.positionEffect) {
+            this.positionEffect.unsubscribe();
+            this.positionEffect = null;
+        }
+
+        // Clear shake config
+        this.currentShakeConfig = null;
+
+        // Reset position to original
+        if (this.elementRef?.componentInstance) {
+            const instance = this.elementRef.componentInstance;
+            instance.position.x = this.originalPosition.x;
+            instance.position.y = this.originalPosition.y;
+        }
+
+        // Clean up subscription
+        if (this.shakeSubscription) {
+            this.shakeSubscription = null;
+        }
+
+        this.elementRef = null;
+    }
+}
+
+registerDirective('shake', Shake);
+

package/src/directives/Sound.ts

@@ -8,8 +8,18 @@ import { calculateDistance, error } from '../engine/utils';
 
 const EVENTS = ['load', 'loaderror', 'playerror', 'play', 'end', 'pause', 'stop', 'mute', 'volume', 'rate', 'seek', 'fade', 'unlock']
 
+/**
+ * Sound directive for playing audio with support for spatial audio and multiple sound sources
+ * 
+ * This directive manages audio playback using Howler.js library. It supports:
+ * - Single or multiple sound sources
+ * - Spatial audio with distance-based volume calculation
+ * - All standard audio controls (play, pause, volume, etc.)
+ * - Event handling for audio lifecycle
+ * 
+ */
 export class Sound extends Directive {
-    private sound: Howl
+    private sounds: Howl[] = []
     private eventsFn: ((...args: any[]) => void)[] = []
     private maxVolume: number = 1
     private maxDistance: number = 100
@@ -20,21 +30,42 @@ export class Sound extends Directive {
     onMount(element: Element<Container>) {
         const { props } = element
         const tick = props.context.tick
-        const { src, autoplay, loop, volume, spatial } = props.sound
-        this.sound = new Howl({
-            src,
-            autoplay,
-            loop,
-            volume
-        })
-        for (let event of EVENTS) {
-            if (!props.sound[event]) continue
-            const fn = props.sound[event]
-            this.eventsFn.push(fn)
-            this.sound.on(event, fn);
+        const propsSound = props.sound.value ?? props.sound
+
+        // Check if src is null or undefined
+        if (!propsSound.src) {
+            return
         }
 
-        if (spatial) {
+        const { src, autoplay, loop, volume, spatial } = propsSound
+        
+        // Handle multiple sources
+        const sources = Array.isArray(src) ? src : [src]
+
+        // Create Howl instances for each source
+        for (const source of sources) {
+            if (!source) continue // Skip null/undefined sources
+            
+            const sound = new Howl({
+                src: source,
+                autoplay,
+                loop,
+                volume
+            })
+ 
+            // Add event listeners for each sound
+            for (let event of EVENTS) {
+                if (!propsSound[event]) continue
+                const fn = propsSound[event]
+                this.eventsFn.push(fn)
+                sound.on(event, fn);
+            }
+            
+            this.sounds.push(sound)
+        }
+
+        // Setup spatial audio if enabled
+        if (spatial && this.sounds.length > 0) {
             const { soundListenerPosition } = props.context
             if (!soundListenerPosition) {
                 throw new error('SoundListenerPosition directive is required for spatial sound in component parent')
@@ -45,39 +76,71 @@ export class Sound extends Directive {
                 const { x, y } = element.componentInstance
                 const distance = calculateDistance(x, y, listenerX(), listenerY());
                 const volume = Math.max(this.maxVolume - (distance / this.maxDistance), 0)
-                this.sound.volume(volume)
+                
+                // Apply volume to all sounds
+                this.sounds.forEach(sound => sound.volume(volume))
             }).subscription
         }
+
+        this.onUpdate(propsSound)
     }
 
     onUpdate(props: any) {
-        const { volume, loop, mute, seek, playing, rate, spatial } = props
-        if (volume != undefined) this.sound.volume(volume)
-        if (loop != undefined) this.sound.loop(loop)
-        if (mute != undefined) this.sound.mute(mute)
-        if (seek != undefined) this.sound.seek(seek)
-        if (playing != undefined) {
-            if (playing) this.sound.play()
-            else this.sound.pause()
-        }
+        const soundProps = props.value ?? props
+        const { volume, loop, mute, seek, playing, rate, spatial } = soundProps
+        // Apply updates to all sounds
+        this.sounds.forEach(sound => {
+            if (volume !== undefined) sound.volume(volume)
+            if (loop !== undefined) sound.loop(loop)
+            if (mute !== undefined) sound.mute(mute)
+            if (seek !== undefined) sound.seek(seek)
+            if (playing !== undefined) {
+                if (playing) sound.play()
+                else sound.pause()
+            }
+            if (rate !== undefined) sound.rate(rate)
+        })
+        
+        // Update spatial audio settings
         if (spatial) {
             this.maxVolume = spatial.maxVolume ?? this.maxVolume
             this.maxDistance = spatial.maxDistance ?? this.maxDistance
         }
-        if (rate != undefined) this.sound.rate(rate)
     }
 
     onDestroy() {
-        this.sound.stop()
-        this.tickSubscription?.unsubscribe()
-        for (let event of EVENTS) {
-            if (this.eventsFn[event]) {
-                this.sound.off(event, this.eventsFn[event]);
+        // Stop and clean up all sounds
+        this.sounds.forEach(sound => {
+            sound.stop()
+            
+            // Remove event listeners
+            for (let event of EVENTS) {
+                const eventFn = this.eventsFn.find(fn => fn === this.eventsFn[event])
+                if (eventFn) {
+                    sound.off(event, eventFn);
+                }
             }
-        }
+        })
+        
+        this.sounds = []
+        this.eventsFn = []
+        this.tickSubscription?.unsubscribe()
     }
 }
 
+/**
+ * SoundListenerPosition directive for spatial audio
+ * 
+ * This directive provides the listener position for spatial audio calculations.
+ * It should be placed on a parent component that contains spatial sound sources.
+ * 
+ * @example
+ * ```tsx
+ * <Player soundListenerPosition={{ x: playerX, y: playerY }}>
+ *   <Enemy sound={{ src: 'growl.mp3', spatial: { maxDistance: 100 } }} />
+ * </Player>
+ * ```
+ */
 class SoundListenerPosition extends Directive {
     onMount(element: Element<any>) {
         element.props.context.soundListenerPosition = element.propObservables?.soundListenerPosition

package/src/directives/ViewportFollow.ts

@@ -1,25 +1,53 @@
 import { ComponentInstance } from '../components/DisplayObject';
+import { SignalOrPrimitive } from '../components/types';
 import { Directive, registerDirective } from '../engine/directive';
 import { Element } from '../engine/reactive';
 import { error } from '../engine/utils';
+import { useProps } from '../hooks/useProps';
+
+export type ViewportFollowProps = {
+    viewportFollow?: boolean | {
+        speed?: SignalOrPrimitive<number>;
+        acceleration?: SignalOrPrimitive<number>;
+        radius?: SignalOrPrimitive<number>;
+    };
+}
 
 export class ViewportFollow extends Directive {
     onInit(element: Element<ComponentInstance>) {
 
     }
     onMount(element: Element) {
-        const { viewportFollow } = element.props
+       this.onUpdate(element.props.viewportFollow, element)
+    }
+    onUpdate(viewportFollow: any, element: Element) {
         const { viewport } = element.props.context
         if (!viewport) {
             throw error('ViewportFollow directive requires a Viewport component to be mounted in the same context')
         }
-        viewport.follow(element.componentInstance)
-    }
-    onUpdate(props: any) {
-
+        if (viewportFollow) {
+            if (viewportFollow === true) {
+                viewport.follow(element.componentInstance)
+            } else {
+                const options = useProps(viewportFollow, {
+                    speed: undefined,
+                    acceleration: undefined,
+                    radius: undefined
+                })
+                viewport.follow(element.componentInstance, {
+                    speed: options.speed(),
+                    acceleration: options.acceleration(),
+                    radius: options.radius()
+                })
+            }
+        } else if (viewportFollow === null) {
+            viewport.plugins.remove('follow')
+        }
     }
-    onDestroy() {
-
+    onDestroy(element: Element) {
+        const { viewportFollow } = element.props
+        const { viewport } = element.props.context
+        if (viewportFollow) viewport.plugins.remove('follow')
     }
 }
 

package/src/directives/index.ts

@@ -1,7 +1,13 @@
-import './KeyboardControls'
-import './Scheduler'
-import './ViewportFollow'
+export * from './ControlsBase'
+export * from './KeyboardControls'
+export * from './GamepadControls'
+export * from './JoystickControls'
+export * from './Controls'
+export * from './Scheduler'
+export * from './ViewportFollow'
 //import './ViewportCull'
-import './Sound'
-import './Drag'
-import './Transition'
+export * from './Sound'
+export * from './Drag'
+export * from './Transition'
+export * from './Shake'
+export * from './Flash'