canvasengine 2.0.0-beta.4 → 2.0.0-beta.41

package/src/directives/Controls.ts

@@ -0,0 +1,254 @@
+import { Directive, registerDirective } from "../engine/directive";
+import { Element, isElementFrozen } from "../engine/reactive";
+import { ControlsBase, Controls } from "./ControlsBase";
+import { KeyboardControls } from "./KeyboardControls";
+import { GamepadControls, GamepadConfig } from "./GamepadControls";
+import { JoystickControls, JoystickConfig } from "./JoystickControls";
+import { Signal, isSignal } from "@signe/reactive";
+import { Subscription } from "rxjs";
+
+/**
+ * Controls directive that coordinates keyboard, gamepad, and joystick input systems
+ * 
+ * This directive automatically activates keyboard, gamepad, and joystick controls when available.
+ * The gamepad is automatically enabled if joypad.js is detected in the environment.
+ * 
+ * All systems share the same control configuration and can work simultaneously.
+ * 
+ * @example
+ * ```html
+ * <Sprite 
+ *   image="path/to/image.png" 
+ *   controls={controlsConfig}
+ *   x={x}
+ *   y={y}
+ * />
+ * ```
+ */
+export class ControlsDirective extends Directive {
+    private keyboardControls: KeyboardControls | null = null;
+    private gamepadControls: GamepadControls | null = null;
+    private joystickControls: JoystickControls | null = null;
+    private freezeSubscription: Subscription | null = null;
+    private element: Element | null = null;
+
+    /**
+     * Initialize the controls directive
+     * Sets up keyboard, gamepad, and joystick controls if available
+     */
+    onInit(element: Element) {
+        this.element = element;
+        const value = element.props.controls?.value ?? element.props.controls;
+        if (!value) return;
+
+        // Initialize keyboard controls (always available)
+        this.keyboardControls = new KeyboardControls();
+        this.keyboardControls.setInputs(value as Controls);
+        this.keyboardControls.start();
+
+        // Initialize gamepad controls if gamepad config is present
+        // GamepadControls will handle joypad.js availability internally
+        const gamepadConfig = (value as Controls & { gamepad?: GamepadConfig }).gamepad;
+        if (gamepadConfig !== undefined && gamepadConfig.enabled !== false) {
+            this.gamepadControls = new GamepadControls();
+            this.gamepadControls.setInputs(value as Controls & { gamepad?: GamepadConfig });
+            this.gamepadControls.start();
+        }
+
+        // Initialize joystick controls if joystick config is present
+        const joystickConfig = (value as Controls & { joystick?: JoystickConfig }).joystick;
+        if (joystickConfig !== undefined && joystickConfig.enabled !== false) {
+            this.joystickControls = new JoystickControls();
+            this.joystickControls.setInputs(value as Controls & { joystick?: JoystickConfig });
+            this.joystickControls.start();
+        }
+
+        // Check initial freeze state
+        if (isElementFrozen(element)) {
+            this.stopInputs();
+        }
+
+        // Subscribe to freeze prop if it's a signal
+        const freezeProp = element.propObservables?.freeze ?? element.props?.freeze;
+        if (isSignal(freezeProp)) {
+            this.freezeSubscription = (freezeProp as Signal<boolean>).observable.subscribe((isFrozen) => {
+                if (isFrozen) {
+                    this.stopInputs();
+                } else {
+                    this.listenInputs();
+                }
+            });
+        }
+    }
+
+    /**
+     * Mount hook (no specific action needed)
+     */
+    onMount(element: Element) {}
+
+    /**
+     * Update controls configuration
+     * Updates both keyboard and gamepad controls
+     */
+    onUpdate(props: any, element: Element) {
+        const value = props.controls?.value ?? props.controls;
+        if (value) {
+            if (this.keyboardControls) {
+                this.keyboardControls.setInputs(value as Controls);
+            }
+
+            if (this.gamepadControls) {
+                this.gamepadControls.setInputs(value as Controls & { gamepad?: GamepadConfig });
+            }
+        }
+
+        // Handle freeze prop update
+        if (props.freeze !== undefined && this.element) {
+            if (isElementFrozen(this.element)) {
+                this.stopInputs();
+            } else {
+                this.listenInputs();
+            }
+        }
+    }
+
+    /**
+     * Cleanup and destroy all control systems
+     */
+    onDestroy(element: Element) {
+        if (this.freezeSubscription) {
+            this.freezeSubscription.unsubscribe();
+            this.freezeSubscription = null;
+        }
+
+        if (this.keyboardControls) {
+            this.keyboardControls.destroy();
+            this.keyboardControls = null;
+        }
+
+        if (this.gamepadControls) {
+            this.gamepadControls.destroy();
+            this.gamepadControls = null;
+        }
+
+        if (this.joystickControls) {
+            this.joystickControls.destroy();
+            this.joystickControls = null;
+        }
+
+        this.element = null;
+    }
+
+    /**
+     * Get a control by input name
+     * Delegates to keyboard controls (primary system)
+     * 
+     * @param inputName - Name of the input/key
+     * @returns BoundKey if found, undefined otherwise
+     */
+    getControl(inputName: string) {
+        return this.keyboardControls?.getControl(inputName);
+    }
+
+    /**
+     * Get all bound controls
+     * Delegates to keyboard controls (primary system)
+     * 
+     * @returns Object mapping input names to BoundKey objects
+     */
+    getControls() {
+        return this.keyboardControls?.getControls() || {};
+    }
+
+    /**
+     * Apply a control action programmatically
+     * Applies to both keyboard and gamepad if available
+     * 
+     * @param controlName - Name of the control
+     * @param isDown - Whether the control is pressed (true) or released (false)
+     * @param payload - Optional payload to pass to keyDown/keyUp callbacks (e.g., { power: 0.8 })
+     * @returns Promise that resolves when the action is complete
+     */
+    async applyControl(controlName: string | number, isDown?: boolean, payload?: any): Promise<void> {
+        if (this.keyboardControls) {
+            await this.keyboardControls.applyControl(controlName, isDown);
+        }
+        if (this.gamepadControls) {
+            await this.gamepadControls.applyControl(controlName, isDown, payload);
+        }
+        if (this.joystickControls) {
+            await this.joystickControls.applyControl(controlName, isDown, payload);
+        }
+    }
+
+    /**
+     * Stop listening to inputs
+     * Stops keyboard, gamepad, and joystick input processing
+     */
+    stopInputs() {
+        if (this.keyboardControls) {
+            this.keyboardControls.stopInputs();
+        }
+        if (this.gamepadControls) {
+            this.gamepadControls.stopInputs();
+        }
+        if (this.joystickControls) {
+            this.joystickControls.stopInputs();
+        }
+    }
+
+    /**
+     * Resume listening to inputs
+     * Resumes keyboard, gamepad, and joystick input processing
+     */
+    listenInputs() {
+        if (this.keyboardControls) {
+            this.keyboardControls.listenInputs();
+        }
+        if (this.gamepadControls) {
+            this.gamepadControls.listenInputs();
+        }
+        if (this.joystickControls) {
+            this.joystickControls.listenInputs();
+        }
+    }
+
+    /**
+     * Get the current controls configuration
+     * Returns keyboard controls options (both systems share the same config)
+     * 
+     * @returns The controls options object
+     */
+    get options(): Controls {
+        return this.keyboardControls?.options || {};
+    }
+
+    /**
+     * Get the keyboard controls instance
+     * 
+     * @returns KeyboardControls instance or null
+     */
+    get keyboard(): KeyboardControls | null {
+        return this.keyboardControls;
+    }
+
+    /**
+     * Get the gamepad controls instance
+     * 
+     * @returns GamepadControls instance or null
+     */
+    get gamepad(): GamepadControls | null {
+        return this.gamepadControls;
+    }
+
+    /**
+     * Get the joystick controls instance
+     * 
+     * @returns JoystickControls instance or null
+     */
+    get joystick(): JoystickControls | null {
+        return this.joystickControls;
+    }
+}
+
+registerDirective('controls', ControlsDirective);

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
+    }
+}