canvasengine 2.0.0-beta.34 → 2.0.0-beta.36

package/src/directives/ControlsBase.ts

@@ -0,0 +1,266 @@
+import { fps2ms } from "../engine/utils";
+
+export interface ControlOptions {
+    repeat?: boolean;
+    bind: string | string[];
+    keyUp?: Function;
+    keyDown?: Function;
+    delay?: number | {
+        duration: number;
+        otherControls?: (string)[];
+    };
+}
+
+export interface Controls {
+    [controlName: string]: ControlOptions;
+}
+
+export type BoundKey = { actionName: string, options: ControlOptions, parameters?: any };
+
+/**
+ * Abstract base class for control systems (keyboard, gamepad, etc.)
+ * 
+ * This class provides common functionality shared across all control implementations:
+ * - Input binding and management
+ * - Control configuration
+ * - Input state management
+ * - Common methods for querying and triggering controls
+ * 
+ * @example
+ * ```ts
+ * class MyControls extends ControlsBase {
+ *   protected setupListeners() {
+ *     // Setup specific input listeners
+ *   }
+ *   
+ *   protected cleanup() {
+ *     // Cleanup specific resources
+ *   }
+ *   
+ *   protected preStep() {
+ *     // Process inputs each frame
+ *   }
+ * }
+ * ```
+ */
+export abstract class ControlsBase {
+    protected boundKeys: {
+        [keyName: string]: BoundKey
+    } = {}
+    protected stop: boolean = false
+    protected _controlsOptions: Controls = {}
+    protected interval: any
+    protected serverFps: number = 60
+
+    /**
+     * Setup input listeners specific to this control implementation
+     * Must be implemented by subclasses
+     */
+    protected abstract setupListeners(): void;
+
+    /**
+     * Cleanup resources specific to this control implementation
+     * Must be implemented by subclasses
+     */
+    protected abstract cleanup(): void;
+
+    /**
+     * Process inputs each step/frame
+     * Must be implemented by subclasses
+     */
+    protected abstract preStep(): void;
+
+    /**
+     * Start the control processing loop
+     * Initializes listeners and starts the interval
+     */
+    start() {
+        this.setupListeners();
+        this.interval = setInterval(() => {
+            this.preStep()
+        }, fps2ms(this.serverFps ?? 60))
+    }
+
+    /**
+     * Stop the control processing and cleanup resources
+     */
+    destroy() {
+        if (this.interval) {
+            clearInterval(this.interval)
+        }
+        this.cleanup();
+    }
+
+    /**
+     * Bind a key/input to a control action
+     * 
+     * @param keys - Single key or array of keys to bind
+     * @param actionName - Name of the control action
+     * @param options - Control options (repeat, keyDown, keyUp, etc.)
+     * @param parameters - Optional parameters to pass to the control callbacks
+     */
+    protected bindKey(keys: string | string[], actionName: string, options: ControlOptions, parameters?: object) {
+        if (!Array.isArray(keys)) keys = [keys]
+        const keyOptions = Object.assign({
+            repeat: false
+        }, options);
+        keys.forEach(keyName => {
+            this.boundKeys[keyName] = { actionName, options: keyOptions, parameters }
+        })
+    }
+
+    /**
+     * Apply an input action for a bound key
+     * Can be overridden by subclasses for custom behavior
+     * 
+     * @param keyName - Name of the key/input to process
+     */
+    protected applyInput(keyName: string) {
+        const boundKey = this.boundKeys[keyName];
+        if (!boundKey) return;
+        
+        const { repeat, keyDown } = boundKey.options;
+        // Default implementation - subclasses may override for state tracking
+        if (keyDown) {
+            let parameters = boundKey.parameters;
+            if (typeof parameters === "function") {
+                parameters = parameters();
+            }
+            keyDown(boundKey);
+        }
+    }
+
+    /**
+     * Get a control by input name
+     * 
+     * @param inputName - Name of the input/key
+     * @returns BoundKey if found, undefined otherwise
+     * @example
+     * ```ts
+     * const control = controls.getControl('up');
+     * if (control) {
+     *   console.log(control.actionName); // 'up'
+     * }
+     * ```
+     */
+    getControl(inputName: string): BoundKey | undefined {
+        return this.boundKeys[inputName]
+    }
+
+    /**
+     * Get all bound controls
+     * 
+     * @returns Object mapping input names to BoundKey objects
+     * @example
+     * ```ts
+     * const allControls = controls.getControls();
+     * console.log(Object.keys(allControls)); // ['up', 'down', 'left', 'right', ...]
+     * ```
+     */
+    getControls(): { [key: string]: BoundKey } {
+        return this.boundKeys
+    }
+
+    /**
+     * Apply a control action programmatically
+     * 
+     * Must be implemented by subclasses to provide input-specific behavior
+     * 
+     * @param controlName - Name or identifier of the control
+     * @param isDown - Whether the control is pressed down (true) or released (false)
+     * @returns Promise that resolves when the control action is complete
+     * @example
+     * ```ts
+     * // Press a control
+     * await controls.applyControl('action', true);
+     * 
+     * // Release a control
+     * await controls.applyControl('action', false);
+     * 
+     * // Press and release (default)
+     * await controls.applyControl('action');
+     * ```
+     */
+    abstract applyControl(controlName: string | number, isDown?: boolean): Promise<void>;
+
+    /**
+     * Stop listening to inputs
+     * Input events will be ignored until listenInputs() is called
+     * 
+     * @example
+     * ```ts
+     * controls.stopInputs();
+     * // ... later
+     * controls.listenInputs();
+     * ```
+     */
+    stopInputs() {
+        this.stop = true
+    }
+
+    /**
+     * Resume listening to inputs after stopInputs() was called
+     * 
+     * @example
+     * ```ts
+     * controls.stopInputs();
+     * // ... later
+     * controls.listenInputs();
+     * ```
+     */
+    listenInputs() {
+        this.stop = false
+    }
+
+    /**
+     * Configure controls with input mappings
+     * 
+     * This method sets up the binding between input keys/buttons and control actions.
+     * It clears existing bindings and creates new ones based on the provided configuration.
+     * 
+     * @param inputs - Control configuration object
+     * @example
+     * ```ts
+     * controls.setInputs({
+     *   up: {
+     *     repeat: true,
+     *     bind: 'up',
+     *     keyDown() {
+     *       console.log('Up pressed');
+     *     }
+     *   },
+     *   action: {
+     *     bind: ['space', 'enter'],
+     *     keyDown() {
+     *       console.log('Action triggered');
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    setInputs(inputs: Controls) {
+        if (!inputs) return
+        this.boundKeys = {}
+        for (let control in inputs) {
+            const option = inputs[control]
+            const { bind } = option
+            let inputsKey: any = bind
+            if (!Array.isArray(inputsKey)) {
+                inputsKey = [bind]
+            }
+            for (let input of inputsKey) {
+                this.bindKey(input, control, option)
+            }
+        }
+        this._controlsOptions = inputs
+    }
+
+    /**
+     * Get the current controls configuration
+     * 
+     * @returns The controls options object
+     */
+    get options(): Controls {
+        return this._controlsOptions
+    }
+}

package/src/directives/Flash.ts

@@ -0,0 +1,409 @@
+import { Container } from 'pixi.js';
+import { Directive, registerDirective } from '../engine/directive';
+import { Element } from '../engine/reactive';
+import { effect, isSignal } 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 FlashType = 'alpha' | 'tint' | 'both';
+
+export type FlashProps = {
+    /**
+     * Trigger that activates the flash animation
+     * When the trigger is activated, the flash animation will start
+     */
+    trigger?: Trigger<any>;
+    /**
+     * Type of flash effect: 'alpha' (opacity), 'tint' (color), or 'both'
+     * @default 'alpha'
+     */
+    type?: SignalOrPrimitive<FlashType>;
+    /**
+     * Duration of the flash animation in milliseconds
+     * @default 300
+     */
+    duration?: SignalOrPrimitive<number>;
+    /**
+     * Number of flash cycles (flash on/off)
+     * @default 1
+     */
+    cycles?: SignalOrPrimitive<number>;
+    /**
+     * Alpha value when flashing (0 to 1)
+     * Only used when type is 'alpha' or 'both'
+     * @default 0.3
+     */
+    alpha?: SignalOrPrimitive<number>;
+    /**
+     * Tint color when flashing (hex color value)
+     * Only used when type is 'tint' or 'both'
+     * @default 0xffffff (white)
+     */
+    tint?: SignalOrPrimitive<number>;
+    /**
+     * Original alpha value to restore after flash
+     * If not provided, uses the current alpha value
+     */
+    originalAlpha?: number;
+    /**
+     * Original tint value to restore after flash
+     * If not provided, uses the current tint value
+     */
+    originalTint?: number;
+    /**
+     * Callback function called when flash starts
+     */
+    onStart?: () => void;
+    /**
+     * Callback function called when flash completes
+     */
+    onComplete?: () => void;
+}
+
+/**
+ * Flash directive that animates a display object's alpha and/or tint when a trigger is activated.
+ * Creates a flash effect by rapidly changing opacity or color.
+ * 
+ * @example
+ * ```typescript
+ * // Basic usage with trigger
+ * const flashTrigger = trigger();
+ * 
+ * onMount(element) {
+ *   // Element will flash when trigger is activated
+ *   element.props.flash = { trigger: flashTrigger };
+ * }
+ * 
+ * // Trigger the flash
+ * flashTrigger.start();
+ * ```
+ */
+export class Flash extends Directive {
+    private elementRef: Element<Container> | null = null;
+    private progressSignal: AnimatedSignal<number> | null = null;
+    private flashSubscription: any = null;
+    private alphaEffect: Subscription | null = null;
+    private tintEffect: Subscription | null = null;
+    private originalAlpha: number = 1;
+    private originalTint: number = 0xffffff;
+    private currentFlashConfig: {
+        type: FlashType;
+        duration: number;
+        cycles: number;
+        flashAlpha: number;
+        flashTint: number;
+    } | null = null;
+
+    /**
+     * Initializes the flash directive
+     * @param element - The element to attach the flash effect to
+     */
+    onInit(element: Element<Container>) {
+        this.elementRef = element;
+    }
+
+    /**
+     * Mounts the flash directive and sets up trigger listener
+     * @param element - The element being mounted
+     */
+    onMount(element: Element<Container>) {
+        const instance = element.componentInstance;
+        if (!instance) return;
+
+        const flashProps = this.flashProps;
+        
+        // Check if trigger is provided
+        if (!flashProps.trigger || !isTrigger(flashProps.trigger)) {
+            return;
+        }
+
+        // Store original values once at mount time
+        // Only set if not already stored (to preserve values from first mount)
+        if (this.originalAlpha === 1 && !flashProps.originalAlpha) {
+            this.originalAlpha = instance.alpha ?? 1;
+        } else if (flashProps.originalAlpha !== undefined) {
+            this.originalAlpha = flashProps.originalAlpha;
+        }
+        
+        const currentTint = (instance as any).tint;
+        if (this.originalTint === 0xffffff && !flashProps.originalTint) {
+            this.originalTint = (isSignal(currentTint) ? currentTint() : currentTint) ?? 0xffffff;
+        } else if (flashProps.originalTint !== undefined) {
+            this.originalTint = flashProps.originalTint;
+        }
+
+        // Listen to trigger activation
+        this.flashSubscription = on(flashProps.trigger, async (data) => {
+            await this.performFlash(data);
+        });
+    }
+
+    /**
+     * Gets the flash props with default values
+     * @returns FlashProps with defaults applied
+     */
+    get flashProps(): FlashProps {
+        const flash = this.elementRef?.props.flash;
+        return useProps(flash?.value ?? flash, {
+            type: 'alpha',
+            duration: 300,
+            cycles: 1,
+            alpha: 0.3,
+            tint: 0xffffff,
+        });
+    }
+
+    /**
+     * Performs the flash animation using animatedSignal
+     * @param data - Optional data passed from the trigger that can override default options
+     */
+    private async performFlash(data?: any): Promise<void> {
+        if (!this.elementRef?.componentInstance) return;
+
+        const instance = this.elementRef.componentInstance;
+        const flashProps = this.flashProps;
+        
+        // Use data from trigger to override defaults if provided
+        const type = data?.type ?? (typeof flashProps.type === 'function' ? flashProps.type() : flashProps.type);
+        const duration = data?.duration ?? (typeof flashProps.duration === 'function' ? flashProps.duration() : flashProps.duration);
+        const cycles = data?.cycles ?? (typeof flashProps.cycles === 'function' ? flashProps.cycles() : flashProps.cycles);
+        const flashAlpha = data?.alpha ?? (typeof flashProps.alpha === 'function' ? flashProps.alpha() : flashProps.alpha);
+        const flashTint = data?.tint ?? (typeof flashProps.tint === 'function' ? flashProps.tint() : flashProps.tint);
+
+        // Stop any existing animation first
+        if (this.progressSignal) {
+            // Stop the animation immediately
+            this.progressSignal.set(0, { duration: 0 });
+        }
+
+        // Clean up effects BEFORE restoring values
+        // This prevents effects from continuing to update values after we restore
+        if (this.alphaEffect) {
+            this.alphaEffect.unsubscribe();
+            this.alphaEffect = null;
+        }
+        if (this.tintEffect) {
+            this.tintEffect.unsubscribe();
+            this.tintEffect = null;
+        }
+
+        // Always restore to original values immediately after stopping effects
+        // This ensures that if a new flash starts before the previous one completes,
+        // we restore to the true original values, not the intermediate animation values
+        instance.alpha = this.originalAlpha;
+        const currentTint = (instance as any).tint;
+        if (currentTint !== undefined) {
+            // Ensure originalTint is a primitive value, not a signal
+            const tintValue = typeof this.originalTint === 'number' ? this.originalTint : 0xffffff;
+            // Handle both signal and primitive tint
+            if (isSignal(currentTint)) {
+                currentTint.set(tintValue);
+            } else {
+                (instance as any).tint = tintValue;
+            }
+        }
+
+        // Call onStart callback
+        flashProps.onStart?.();
+
+        // Store current flash configuration for use in effect
+        this.currentFlashConfig = {
+            type,
+            duration,
+            cycles,
+            flashAlpha,
+            flashTint,
+        };
+
+        // Create or recreate progress signal for flash animation
+        // Note: We already stopped the previous animation above, so we can reuse the signal
+        if (!this.progressSignal) {
+            this.progressSignal = animatedSignal(0, {
+                duration: duration,
+                ease: (t) => t, // Linear ease
+            });
+        }
+        // Reset to 0 immediately without animation to start fresh
+        this.progressSignal.set(0, { duration: 0 });
+        // Wait a bit to ensure the reset is complete before starting new animation
+        await new Promise(resolve => setTimeout(resolve, 0));
+
+        // Create effect to update alpha based on progress
+        if (type === 'alpha' || type === 'both') {
+            this.alphaEffect = effect(() => {
+                if (!instance || !this.progressSignal || !this.currentFlashConfig) return;
+
+                const progress = this.progressSignal();
+                const config = this.currentFlashConfig;
+                
+                // Calculate flash value based on cycles
+                // Each cycle goes from 0 to 1, so we use modulo to repeat
+                const cycleProgress = (progress * config.cycles) % 1;
+                
+                // Create flash effect: fade to flashAlpha then back to original
+                // For each cycle, we flash twice (on/off)
+                const flashPhase = cycleProgress < 0.5 
+                    ? cycleProgress * 2  // Fade to flashAlpha (0 to 1)
+                    : 1 - ((cycleProgress - 0.5) * 2); // Fade back to original (1 to 0)
+                
+                // Interpolate between original and flash alpha
+                const currentAlpha = this.originalAlpha + (config.flashAlpha - this.originalAlpha) * flashPhase;
+                instance.alpha = currentAlpha;
+            }).subscription;
+        }
+
+        // Create effect to update tint based on progress
+        if (type === 'tint' || type === 'both') {
+            this.tintEffect = effect(() => {
+                if (!instance || !this.progressSignal || !this.currentFlashConfig) return;
+                
+                // Get current tint value - handle both signal and primitive
+                const currentTint = (instance as any).tint;
+                if (currentTint === undefined) return;
+                
+                // Check if tint is a signal
+                const tintIsSignal = isSignal(currentTint);
+                
+                const progress = this.progressSignal();
+                const config = this.currentFlashConfig;
+                
+                // Calculate flash value based on cycles
+                const cycleProgress = (progress * config.cycles) % 1;
+                
+                // Create flash effect: change to flashTint then back to original
+                const flashPhase = cycleProgress < 0.5 
+                    ? cycleProgress * 2  // Change to flashTint (0 to 1)
+                    : 1 - ((cycleProgress - 0.5) * 2); // Change back to original (1 to 0)
+                
+                // Interpolate between original and flash tint
+                // Simple linear interpolation for RGB values
+                const r1 = (this.originalTint >> 16) & 0xff;
+                const g1 = (this.originalTint >> 8) & 0xff;
+                const b1 = this.originalTint & 0xff;
+                
+                const r2 = (config.flashTint >> 16) & 0xff;
+                const g2 = (config.flashTint >> 8) & 0xff;
+                const b2 = config.flashTint & 0xff;
+                
+                const r = Math.round(r1 + (r2 - r1) * flashPhase);
+                const g = Math.round(g1 + (g2 - g1) * flashPhase);
+                const b = Math.round(b1 + (b2 - b1) * flashPhase);
+                
+                const newTintValue = (r << 16) | (g << 8) | b;
+                
+                // Handle both signal and primitive tint
+                if (tintIsSignal) {
+                    currentTint.set(newTintValue);
+                } else {
+                    (instance as any).tint = newTintValue;
+                }
+            }).subscription;
+        }
+
+        // Start animation and wait for completion
+        await this.progressSignal.set(1, {
+            duration: duration,
+        });
+
+        // Animation completed - clean up and call callbacks
+        // Restore original values
+        if (instance) {
+            instance.alpha = this.originalAlpha;
+            const currentTint = (instance as any).tint;
+            if (currentTint !== undefined) {
+                // Ensure originalTint is a primitive value, not a signal
+                const tintValue = typeof this.originalTint === 'number' ? this.originalTint : 0xffffff;
+                // Handle both signal and primitive tint
+                if (isSignal(currentTint)) {
+                    currentTint.set(tintValue);
+                } else {
+                    (instance as any).tint = tintValue;
+                }
+            }
+        }
+        
+        // Clean up effects
+        if (this.alphaEffect) {
+            this.alphaEffect.unsubscribe();
+            this.alphaEffect = null;
+        }
+        if (this.tintEffect) {
+            this.tintEffect.unsubscribe();
+            this.tintEffect = null;
+        }
+        
+        // Clear flash config
+        this.currentFlashConfig = null;
+        
+        // Call onComplete callback
+        flashProps.onComplete?.();
+    }
+
+    /**
+     * Updates the flash 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 flash directive
+     */
+    onDestroy() {
+        // Stop any running animation by resetting progress
+        if (this.progressSignal) {
+            this.progressSignal.set(0, { duration: 0 });
+            this.progressSignal = null;
+        }
+
+        // Clean up effects
+        if (this.alphaEffect) {
+            this.alphaEffect.unsubscribe();
+            this.alphaEffect = null;
+        }
+        if (this.tintEffect) {
+            this.tintEffect.unsubscribe();
+            this.tintEffect = null;
+        }
+
+        // Clear flash config
+        this.currentFlashConfig = null;
+
+        // Restore original values
+        if (this.elementRef?.componentInstance) {
+            const instance = this.elementRef.componentInstance;
+            instance.alpha = this.originalAlpha;
+            const currentTint = (instance as any).tint;
+            if (currentTint !== undefined) {
+                // Ensure originalTint is a primitive value, not a signal
+                const tintValue = typeof this.originalTint === 'number' ? this.originalTint : 0xffffff;
+                // Handle both signal and primitive tint
+                if (isSignal(currentTint)) {
+                    currentTint.set(tintValue);
+                } else {
+                    (instance as any).tint = tintValue;
+                }
+            }
+        }
+
+        // Clean up subscription
+        if (this.flashSubscription) {
+            this.flashSubscription = null;
+        }
+
+        this.elementRef = null;
+    }
+}
+
+registerDirective('flash', Flash);
+