@skewedaspect/sage 0.3.0

package/src/managers/binding.ts

@@ -0,0 +1,729 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Binding Manager
+//----------------------------------------------------------------------------------------------------------------------
+
+import { GameEventBus } from '../classes/eventBus.ts';
+
+// Interfaces
+import { type Binding, type BindingDefinition, type Context, bindingTypes } from '../interfaces/binding.ts';
+import type {
+    DeviceValueReader,
+    DeviceValueReaderDefinition,
+    InputDevice,
+    InputState,
+} from '../interfaces/input.ts';
+import type { LoggerInterface } from '../interfaces/logger.ts';
+import type { Action } from '../interfaces/action.ts';
+
+// Bindings
+import { TriggerBinding } from '../classes/bindings/trigger.ts';
+import { ToggleBinding } from '../classes/bindings/toggle.ts';
+import { ValueBinding } from '../classes/bindings/value.ts';
+
+// Value Readers
+import { KeyboardValueReader } from '../classes/input/readers/keyboard.ts';
+import { MouseValueReader } from '../classes/input/readers/mouse.ts';
+import { GamepadValueReader } from '../classes/input/readers/gamepad.ts';
+
+// Utils
+import { LoggingUtility, SAGELogger } from '../utils/logger.ts';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Configuration object structure for binding manager
+ */
+export interface BindingConfiguration
+{
+    /** All registered actions */
+    actions : Action[];
+
+    /** All registered bindings */
+    bindings : BindingDefinition[];
+
+    /** All registered contexts */
+    contexts : {
+        name : string;
+        exclusive : boolean;
+        active : boolean;
+    }[];
+}
+
+/* eslint-disable no-continue */
+
+/**
+ * Manages input bindings and actions for the game
+ */
+export class BindingManager
+{
+    /** Map of device IDs to their bindings */
+    private _bindings = new Map<string, Binding[]>();
+
+    /** Map of action names to their action definitions */
+    private _actions = new Map<string, Action>();
+
+    /** Map of all registered contexts by name for O(1) lookup */
+    private _contexts = new Map<string, Context>();
+
+    /**
+     * Set of all active contexts (both exclusive and non-exclusive)
+     */
+    private _activeContexts = new Set<string>();
+
+    /** Event bus for handling game events */
+    private _eventBus : GameEventBus;
+
+    /** Logger instance */
+    private _log : LoggerInterface;
+
+    /**
+     * Creates an instance of BindingManager.
+     *
+     * @param eventBus - The game event bus to publish events to
+     * @param logger - The logging utility to use
+     */
+    constructor(eventBus : GameEventBus, logger ?: LoggingUtility)
+    {
+        this._eventBus = eventBus;
+
+        // Bind to input events
+        this._eventBus.subscribe<{ device : InputDevice, state : InputState }>('input:changed', (event) =>
+        {
+            if(event.payload)
+            {
+                this.$handleInput(event.payload.device, event.payload.state);
+            }
+        });
+
+        this._log = logger?.getLogger('BindingManager') || new SAGELogger('BindingManager');
+        this._log.debug('BindingManager initialized');
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Private Methods
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Checks if a binding's context is currently active
+     *
+     * @param binding - The binding to check
+     * @returns True if binding's context is active or has no context
+     */
+    private _isBindingContextActive(binding : Binding) : boolean
+    {
+        // If no context is specified, binding is always active regardless of active contexts
+        if(!binding.context)
+        {
+            return true;
+        }
+
+        // Otherwise check if the binding's specific context is active
+        return this._activeContexts.has(binding.context);
+    }
+
+    /**
+     * Get a context by name, creating it if it doesn't exist
+     *
+     * @param contextName - The name of the context to get or create
+     * @param exclusive - Whether the context is exclusive (only used if creating)
+     * @returns The context object
+     */
+    private _getOrCreateContext(contextName : string, exclusive = true) : Context
+    {
+        let context = this._contexts.get(contextName);
+
+        if(!context)
+        {
+            context = {
+                name: contextName,
+                exclusive,
+            };
+
+            this._contexts.set(contextName, context);
+            this._log.debug(`Auto-created context "${ contextName }" (exclusive: ${ exclusive })`);
+        }
+
+        return context;
+    }
+
+    /**
+     * Deactivate all exclusive contexts except the specified one
+     *
+     * @param exceptContextName - Name of context to not deactivate
+     * @returns Array of deactivated context names
+     */
+    private _deactivateExclusiveContexts(exceptContextName ?: string) : string[]
+    {
+        const deactivatedContexts : string[] = [];
+
+        // Find all active exclusive contexts
+        for(const contextName of this._activeContexts)
+        {
+            // Skip the context we want to keep
+            if(contextName === exceptContextName)
+            {
+                continue;
+            }
+
+            const context = this._contexts.get(contextName);
+
+            // If this is an exclusive context, deactivate it
+            if(context?.exclusive)
+            {
+                this._activeContexts.delete(contextName);
+                deactivatedContexts.push(contextName);
+            }
+        }
+
+        return deactivatedContexts;
+    }
+
+    /**
+     * Create a binding from a binding definition
+     *
+     * @param definition - The binding definition to create a binding from
+     * @returns A new binding instance or null if the type is not supported
+     */
+    private _createBindingFromDefinition(definition : BindingDefinition) : Binding | null
+    {
+        // Get the full action object from the action name
+        const action = this._actions.get(definition.action);
+
+        // If the action doesn't exist, log a warning and return null
+        if(!action)
+        {
+            this._log.warn(`Cannot create binding: Action "${ definition.action }" not found.`);
+            return null;
+        }
+
+        // Extract deviceID and create reader from the input definition
+        const { deviceID, ...readerDef } = definition.input;
+        
+        switch (definition.type)
+        {
+            case 'trigger': {
+                // Create the binding with the device value reader based on definition's source
+                return new TriggerBinding(
+                    action,
+                    deviceID,
+                    this._createInputSourceFromDefinition(readerDef),
+                    {
+                        ...(definition.options || {}),
+                        context: definition.context,
+                    }
+                );
+            }
+
+            case 'toggle': {
+                // Create the binding with the device value reader based on definition's source
+                return new ToggleBinding(
+                    action,
+                    deviceID,
+                    this._createInputSourceFromDefinition(readerDef),
+                    {
+                        ...(definition.options || {}),
+                        context: definition.context,
+                    }
+                );
+            }
+
+            case 'value': {
+                // Create the binding with the device value reader based on definition's source
+                return new ValueBinding(
+                    action,
+                    deviceID,
+                    this._createInputSourceFromDefinition(readerDef),
+                    {
+                        ...(definition.options || {}),
+                        context: definition.context,
+                    }
+                );
+            }
+
+            default:
+                this._log.error(`Binding type not implemented: ${ (definition as any).type }`);
+                return null;
+        }
+    }
+
+    /**
+     * Create a device value reader from a definition object
+     *
+     * @param definition - The device value reader definition
+     * @returns A new device value reader instance
+     * @throws Error if the reader type is not supported
+     */
+    private _createInputSourceFromDefinition(definition : DeviceValueReaderDefinition) : DeviceValueReader
+    {
+        // Create reader based on device type
+        switch (definition.type)
+        {
+            case 'keyboard':
+                return new KeyboardValueReader(
+                    definition.sourceKey,
+                    definition.options
+                );
+
+            case 'mouse':
+            {
+                // Check if sourceType is valid
+                const sourceType = definition.sourceType;
+                if(!(sourceType === 'button' || sourceType === 'position' || sourceType === 'wheel'))
+                {
+                    throw new Error(`Invalid mouse source type: ${ sourceType }`);
+                }
+
+                return new MouseValueReader(
+                    sourceType,
+                    definition.sourceKey
+                );
+            }
+
+            case 'gamepad':
+            {
+                // Check if sourceType is valid
+                const sourceType = definition.sourceType;
+                if(!(sourceType === 'button' || sourceType === 'axis'))
+                {
+                    throw new Error(`Invalid gamepad source type: ${ sourceType }`);
+                }
+                return new GamepadValueReader(
+                    sourceType,
+                    definition.sourceKey,
+                    definition.options
+                );
+            }
+
+            default:
+                throw new Error(`Unsupported input source type: ${ (definition as any).type }`);
+        }
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Internal API
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Handle input from a device and process all relevant bindings
+     *
+     * @param device - The input device
+     * @param state - Current input state
+     */
+    public $handleInput(device : InputDevice, state : InputState) : void
+    {
+        const bindings = this._bindings.get(device.id);
+        if(!bindings || bindings.length === 0)
+        {
+            return;
+        }
+
+        if(this._activeContexts.size === 0 && bindings.some((binding) => binding.context))
+        {
+            return;
+        }
+
+        for(const binding of bindings)
+        {
+            if(!this._isBindingContextActive(binding))
+            {
+                continue;
+            }
+
+            binding.process(state, this._eventBus);
+        }
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Action Management API
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Registers an action
+     *
+     * @param action - The action to register
+     * @throws Error if action is already registered
+     */
+    public registerAction(action : Action) : void
+    {
+        this._log.debug(`Registering action "${ action.name }"`);
+
+        if(this._actions.has(action.name))
+        {
+            const errorMsg = `Action "${ action.name }" already registered.`;
+            this._log.error(errorMsg);
+            throw new Error(errorMsg);
+        }
+
+        this._actions.set(action.name, action);
+        this._log.debug(`Action "${ action.name }" registered successfully`);
+    }
+
+    /**
+     * Gets an action by name
+     *
+     * @param actionName - The name of the action to get
+     * @returns The action or null if not found
+     */
+    public getAction(actionName : string) : Action | null
+    {
+        this._log.trace(`Getting action "${ actionName }"`);
+
+        const action = this._actions.get(actionName) ?? null;
+        if(!action)
+        {
+            this._log.debug(`Action "${ actionName }" not found`);
+        }
+
+        return action;
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Context Management API
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Registers a context with specific options
+     *
+     * @param contextName - The name of the context to register
+     * @param exclusive - Whether the context is exclusive (default: true)
+     * @returns The registered context
+     */
+    public registerContext(contextName : string, exclusive = true) : Context
+    {
+        const context = this._getOrCreateContext(contextName, exclusive);
+
+        // Update context's exclusivity if it already exists
+        if(context.exclusive !== exclusive)
+        {
+            context.exclusive = exclusive;
+            this._log.info(`Updated context "${ contextName }" exclusivity: ${ exclusive }`);
+        }
+
+        return context;
+    }
+
+    /**
+     * Activates a context, enabling all bindings associated with it.
+     * If the context is exclusive, all other exclusive contexts will be deactivated.
+     *
+     * @param contextName - The name of the context to activate
+     */
+    public activateContext(contextName : string) : void
+    {
+        // Get or create context
+        const context = this._getOrCreateContext(contextName);
+
+        // Get the context's exclusivity setting
+        const isExclusive = context.exclusive;
+
+        this._log.debug(`Activating context "${ contextName }" (exclusive: ${ isExclusive })`);
+
+        // If already active, nothing to do unless we're making an exclusive activation
+        const isAlreadyActive = this._activeContexts.has(contextName);
+
+        if(isExclusive)
+        {
+            // Deactivate all other exclusive contexts
+            const deactivated = this._deactivateExclusiveContexts(contextName);
+
+            if(deactivated.length > 0)
+            {
+                this._log.info(`Deactivated exclusive contexts: ${ deactivated.join(', ') }`);
+            }
+        }
+
+        // Add to active contexts if not already there
+        if(!isAlreadyActive)
+        {
+            this._activeContexts.add(contextName);
+            this._log.info(`Context "${ contextName }" activated${ isExclusive ? ' as exclusive' : '' }`);
+        }
+    }
+
+    /**
+     * Deactivates a context, disabling all bindings associated with it
+     *
+     * @param contextName - The name of the context to deactivate
+     */
+    public deactivateContext(contextName : string) : void
+    {
+        this._log.debug(`Deactivating context "${ contextName }"`);
+
+        if(this._activeContexts.has(contextName))
+        {
+            this._activeContexts.delete(contextName);
+            this._log.info(`Context "${ contextName }" deactivated`);
+        }
+        else
+        {
+            this._log.debug(`Context "${ contextName }" was not active`);
+        }
+    }
+
+    /**
+     * Returns a list of all active contexts
+     *
+     * @returns Array of active context names
+     */
+    public getActiveContexts() : string[]
+    {
+        return [ ...this._activeContexts ];
+    }
+
+    /**
+     * Returns whether a context is active
+     *
+     * @param contextName - The context to check
+     * @returns True if the context is active
+     */
+    public isContextActive(contextName : string) : boolean
+    {
+        return this._activeContexts.has(contextName);
+    }
+
+    /**
+     * Gets a context by name
+     *
+     * @param contextName - The context name to get
+     * @returns The context or null if not found
+     */
+    public getContext(contextName : string) : Context | null
+    {
+        return this._contexts.get(contextName) || null;
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Binding Management API
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Register a binding for an input device
+     *
+     * @param binding - The binding to register
+     * @throws Error if binding type is invalid
+     */
+    public $registerBinding(binding : Binding) : void
+    {
+        if(!bindingTypes.includes(binding.type))
+        {
+            throw new Error(`Invalid binding type: ${ binding.type }`);
+        }
+
+        // If binding has a context but context isn't registered yet, register it with default settings
+        if(binding.context && !this._contexts.has(binding.context))
+        {
+            this.registerContext(binding.context);
+        }
+
+        // Initialize device bindings array if it doesn't exist
+        if(!this._bindings.has(binding.deviceID))
+        {
+            this._bindings.set(binding.deviceID, []);
+        }
+
+        // Add the binding
+        this._bindings.get(binding.deviceID)?.push(binding);
+        this._log.debug(`Registered ${ binding.type } binding for "${ binding.action.name }" in context `
+            + `"${ binding.context || null }"`);
+    }
+
+    /**
+     * Register a binding using a binding definition object
+     *
+     * @param definition - The binding definition to register
+     */
+    public registerBinding(definition : BindingDefinition) : void
+    {
+        const binding = this._createBindingFromDefinition(definition);
+
+        if(binding)
+        {
+            this.$registerBinding(binding);
+        }
+        else
+        {
+            this._log.error(`Failed to create binding for action "${ definition.action }" with type `
+                + `"${ definition.type }"`);
+        }
+    }
+
+    /**
+     * Unregister all bindings for an action within a context
+     *
+     * @param actionName - The name of the action
+     * @param context - The context to unregister from (defaults to null)
+     */
+    public unregisterBindings(actionName : string, context : string | null = null) : void
+    {
+        this._log.debug(`Unregistering all bindings for action "${ actionName }" in context "${ context }"`);
+
+        let bindingsRemoved = 0;
+
+        // Iterate through all devices and their bindings
+        for(const [ deviceId, deviceBindings ] of this._bindings.entries())
+        {
+            const newBindings = deviceBindings.filter((binding) =>
+            {
+                const bindingContext = binding.context || null;
+                const shouldKeep = binding.action.name !== actionName || bindingContext !== context;
+                if(!shouldKeep)
+                {
+                    bindingsRemoved++;
+                }
+                return shouldKeep;
+            });
+
+            // Only update the map if we actually removed something
+            if(newBindings.length !== deviceBindings.length)
+            {
+                this._bindings.set(deviceId, newBindings);
+            }
+        }
+
+        this._log.info(`Removed ${ bindingsRemoved } bindings for action "${ actionName }" in context "${ context }"`);
+    }
+
+    /**
+     * Gets all bindings for a specific action
+     *
+     * @param actionName - The name of the action
+     * @param context - The context to get bindings from (optional)
+     * @returns Array of bindings that match the criteria
+     */
+    public getBindingsForAction(actionName : string, context ?: string | null) : Binding[]
+    {
+        const result : Binding[] = [];
+
+        for(const deviceBindings of this._bindings.values())
+        {
+            for(const binding of deviceBindings)
+            {
+                const bindingContext = binding.context || null;
+                if(binding.action.name === actionName)
+                {
+                    // If context specified, only include bindings from that context
+                    if(!context || bindingContext === context)
+                    {
+                        result.push(binding);
+                    }
+                }
+            }
+        }
+
+        return result;
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Configuration Management API
+    //------------------------------------------------------------------------------------------------------------------
+
+    /**
+     * Exports the current configuration to a serializable object
+     *
+     * @returns A BindingConfiguration object representing the current state
+     */
+    public exportConfiguration() : BindingConfiguration
+    {
+        this._log.debug('Exporting binding configuration');
+
+        // Export all registered actions
+        const actions = [ ...this._actions.values() ].map((action) =>
+        {
+            // Ensure we include all analog action properties when exporting
+            if(action.type === 'analog')
+            {
+                return {
+                    name: action.name,
+                    type: action.type,
+                    minValue: action.minValue ?? 0,
+                    maxValue: action.maxValue ?? 1,
+                };
+            }
+            return action;
+        });
+
+        // Export all registered bindings using their toJSON methods
+        const bindings : BindingDefinition[] = [];
+
+        // Iterate through all device bindings
+        for(const deviceBindings of this._bindings.values())
+        {
+            for(const binding of deviceBindings)
+            {
+                // Let the binding serialize itself to the BindingDefinition format
+                bindings.push(binding.toJSON());
+            }
+        }
+
+        // Export all contexts with their active state
+        const contexts = [ ...this._contexts.values() ].map((context) => ({
+            name: context.name,
+            exclusive: context.exclusive,
+            active: this._activeContexts.has(context.name),
+        }));
+
+        this._log.info(`Configuration exported: ${ actions.length } actions, ${ bindings.length } bindings, `
+            + `${ contexts.length } contexts`);
+
+        return {
+            actions,
+            bindings,
+            contexts,
+        };
+    }
+
+    /**
+     * Imports a configuration from an object
+     *
+     * @param config - The configuration to import
+     */
+    public importConfiguration(config : BindingConfiguration) : void
+    {
+        this._log.debug('Importing binding configuration');
+
+        // Clear existing configuration
+        this._bindings.clear();
+        this._actions.clear();
+        this._contexts.clear();
+        this._activeContexts.clear();
+
+        // Import actions
+        for(const action of config.actions)
+        {
+            this.registerAction(action);
+        }
+
+        // Import contexts first so they exist before bindings reference them
+        for(const contextData of config.contexts)
+        {
+            this.registerContext(contextData.name, contextData.exclusive);
+
+            // Activate contexts that were active
+            if(contextData.active)
+            {
+                this.activateContext(contextData.name);
+            }
+        }
+
+        // Import bindings
+        for(const bindingDef of config.bindings)
+        {
+            try
+            {
+                this.registerBinding(bindingDef);
+            }
+            catch (err : unknown)
+            {
+                if(err instanceof Error)
+                {
+                    this._log.error(`Failed to import binding for action "${ bindingDef.action }": ${ err.message }`);
+                }
+            }
+        }
+
+        this._log.info(`Configuration imported: ${ config.actions.length } actions, `
+            + `${ config.bindings.length } bindings, ${ config.contexts.length } contexts`);
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------