@caperjs/core 0.3.0 → 0.4.0

package/src/plugins/input/AbstractControls.ts

@@ -1,21 +1,116 @@
 import type { ControlsActionMap } from '../..';
-import { IApplication } from '../../core';
 import { Application } from '../../core/Application';
+import { WithSignals } from '../../mixins/signals';
+import { Logger } from '../../utils';
+import type { Action } from '../actions';
+import { buildDownMaps, buildUpMap, isInputActive, type SchemeSection } from './controlsCore';
 
-export class AbstractControls {
+/**
+ * Terminates the destroy chain — WithSignals' destroy() calls super.destroy().
+ * Also the binding root: `bindAllMethods` in an adapter binds everything down
+ * to here and stops, exactly like `Application` / `Plugin` / `Container`.
+ */
+class ControlsRoot {
+  private static readonly __caper_method_binding_root = true;
+
+  destroy(): void {}
+}
+
+/**
+ * Shared machinery for every controls adapter: scheme storage, context-gated
+ * down/up map building (rebuilt whenever the action context changes), the
+ * `isActionActive` query and the ticker hookup. Adapters supply the scheme
+ * sections, the "is this input down" predicates and the dispatch loop.
+ */
+export abstract class AbstractControls extends WithSignals(ControlsRoot) {
   protected scheme: any;
+  /** `+` combinations, longest first — the update loop relies on that order. */
+  protected combinations: string[][] = [];
+  protected combinationsMap: Map<string[], Action> = new Map();
+  protected activeDownInputs: Map<string, Action> = new Map();
+  protected activeUpInputs: Map<string, Action> = new Map();
+  private _warnedMissingActions: Set<string> = new Set();
 
-  get app(): IApplication {
+  get app() {
     return Application.getInstance();
   }
 
   initialize(scheme: Partial<ControlsActionMap>) {
     this.scheme = scheme;
+    this.addSignalConnection(this.app.signal.onActionContextChanged.connect(this._sortActions));
+    this._sortActions();
   }
 
-  /**
-   * Terminates the destroy chain — subclasses are built on WithSignals, whose destroy()
-   * calls super.destroy().
-   */
-  destroy(): void {}
+  public connect(): void {
+    this.app.ticker.add(this._update);
+  }
+
+  public destroy(): void {
+    this.app.ticker.remove(this._update);
+    super.destroy();
+  }
+
+  isActionActive(action: Action): boolean {
+    const input = this.scheme?.down?.[action] ?? null;
+    if (!input) {
+      return false;
+    }
+    if (Array.isArray(input)) {
+      return input.some((item: string) => this._isInputActive(item));
+    }
+    return this._isInputActive(input);
+  }
+
+  /** The `down` section of the adapter's scheme. */
+  protected get downSection(): SchemeSection | undefined {
+    return this.scheme?.down;
+  }
+
+  /** The `up` section of the adapter's scheme. */
+  protected get upSection(): SchemeSection | undefined {
+    return this.scheme?.up;
+  }
+
+  /** Prefix for scheme warnings — a field, so minification cannot rename it away. */
+  protected abstract readonly logLabel: string;
+
+  /** Whether a single input is currently down. */
+  protected abstract isInputDown(id: string): boolean;
+
+  /** Whether an input counts as down *as part of a combination*. */
+  protected isComboPartDown(id: string): boolean {
+    return this.isInputDown(id);
+  }
+
+  /** Dispatch actions for the current input state — added to the ticker by {@link connect}. */
+  protected abstract _update(): void;
+
+  protected _isInputActive(input: string): boolean {
+    return isInputActive(input, this.isInputDown, this.isComboPartDown);
+  }
+
+  /** Rebuild the down/up maps for the current action context. */
+  protected _sortActions(): void {
+    const actions = this.app.actionsPlugin.getActions();
+    const context = this.app.actionContext as string;
+
+    const { combinations, combinationsMap, singles } = buildDownMaps<Action>(
+      this.downSection,
+      actions,
+      context,
+      this._warnMissingAction,
+    );
+    this.combinations = combinations;
+    this.combinationsMap = combinationsMap;
+    this.activeDownInputs = singles;
+    this.activeUpInputs = buildUpMap<Action>(this.upSection, actions, context, this._warnMissingAction);
+  }
+
+  protected _warnMissingAction(key: string): void {
+    if (this._warnedMissingActions.has(key)) {
+      return;
+    }
+    this._warnedMissingActions.add(key);
+    Logger.warn(`${this.logLabel}: scheme references unknown action "${key}"`);
+  }
 }

package/src/plugins/input/Controls.test.ts

@@ -10,6 +10,7 @@ vi.mock('../../core/Application', () => ({
 }));
 
 import type { IButton } from '../../ui';
+import { Logger } from '../../utils';
 import { Controls } from './Controls';
 
 type FakeApp = {
@@ -35,6 +36,11 @@ function pressKey(key: string) {
   keyDown.emit({ event: { key }, key });
 }
 
+function releaseKey(key: string) {
+  app.keyboard.keysDown.delete(key);
+  keyUp.emit({ event: { key }, key });
+}
+
 function makeButton(id: string): IButton {
   return {
     id,
@@ -132,6 +138,56 @@ describe('Controls with an unmapped action in the scheme', () => {
   });
 });
 
+describe('Controls up maps', () => {
+  it('dispatches a keyboard up action that is in context', () => {
+    const controls = new Controls();
+    controls.initialize({ keyboard: { up: { jump: 'A' } } } as any);
+    controls.connect();
+
+    pressKey('A');
+    releaseKey('A');
+
+    expect(app.action).toHaveBeenCalledWith('jump', { combination: false, inputState: 'up', key: 'A' });
+  });
+
+  it('does not dispatch a keyboard up action that is out of context', () => {
+    actions.pause = { context: 'menu', input: [] };
+
+    const controls = new Controls();
+    controls.initialize({ keyboard: { up: { pause: 'A' } } } as any);
+    controls.connect();
+
+    pressKey('A');
+    releaseKey('A');
+
+    expect(app.action).not.toHaveBeenCalled();
+  });
+
+  it('warns once for an unknown action in the keyboard up map', () => {
+    const warn = vi.spyOn(Logger, 'warn').mockImplementation(() => undefined);
+
+    const controls = new Controls();
+    controls.initialize({ keyboard: { up: { not_an_action: 'A' } } } as any);
+    controls.connect();
+
+    expect(warn).toHaveBeenCalledTimes(1);
+    warn.mockRestore();
+  });
+
+  it('dispatches a virtual up action declared as an array', () => {
+    const controls = new Controls();
+    controls.initialize({ touch: { up: { jump: ['btn-a'] } } } as any);
+    controls.connect();
+
+    const button = makeButton('btn-a');
+    controls.virtual.addButton(button);
+    button.onDown.emit();
+    button.onUp.emit();
+
+    expect(app.action).toHaveBeenCalledWith('jump', { combination: false, inputState: 'up', button: 'btn-a' });
+  });
+});
+
 describe('VirtualControls.removeButton', () => {
   it('stops a removed button from driving action state', () => {
     const controls = new Controls();

package/src/plugins/input/InputPlugin.ts

@@ -70,11 +70,11 @@ export class InputPlugin extends Plugin<InputManagerOptions> implements IInputPl
 
     app.stage.eventMode = 'static';
     this._canvas = app.canvas as HTMLCanvasElement;
-    this._canvas.addEventListener('pointerdown', this._onPointerDown);
-    this._canvas.addEventListener('pointermove', this._onPointerMove);
-    window.addEventListener('keydown', this._onKeyDown);
-    window.addEventListener('gamepadconnected', this._onGamepadConnected);
-    window.addEventListener('gamepaddisconnected', this._onGamepadDisconnected);
+    this.listen(this._canvas, 'pointerdown', this._onPointerDown as EventListener);
+    this.listen(this._canvas, 'pointermove', this._onPointerMove as EventListener);
+    this.listen(window, 'keydown', this._onKeyDown);
+    this.listen(window, 'gamepadconnected', this._onGamepadConnected as EventListener);
+    this.listen(window, 'gamepaddisconnected', this._onGamepadDisconnected as EventListener);
 
     if (this._options.controls) {
       this.controls.initialize(this._options.controls);
@@ -88,15 +88,7 @@ export class InputPlugin extends Plugin<InputManagerOptions> implements IInputPl
   }
 
   destroy(): void {
-    // unregister all event listeners
-    if (this._canvas) {
-      this._canvas.removeEventListener('pointerdown', this._onPointerDown);
-      this._canvas.removeEventListener('pointermove', this._onPointerMove);
-      this._canvas = null;
-    }
-    window.removeEventListener('keydown', this._onKeyDown);
-    window.removeEventListener('gamepadconnected', this._onGamepadConnected);
-    window.removeEventListener('gamepaddisconnected', this._onGamepadDisconnected);
+    this._canvas = null;
 
     this.controls.destroy();
 

package/src/plugins/input/controlsCore.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { buildDownMaps, buildUpMap, contextAllows, evaluateCombinations, isInputActive } from './controlsCore';
+
+const anywhere = { context: '*' as const };
+
+describe('contextAllows', () => {
+  it("allows every context for '*'", () => {
+    expect(contextAllows('*', 'default')).toBe(true);
+    expect(contextAllows('*', 'menu')).toBe(true);
+  });
+
+  it('matches a string context exactly', () => {
+    expect(contextAllows('menu', 'menu')).toBe(true);
+    expect(contextAllows('menu', 'game')).toBe(false);
+  });
+
+  it('does not treat a substring as a match', () => {
+    expect(contextAllows('game_over', 'game')).toBe(false);
+  });
+
+  it('matches any member of an array context', () => {
+    expect(contextAllows(['menu', 'game'], 'game')).toBe(true);
+    expect(contextAllows(['menu', 'game'], 'pause')).toBe(false);
+  });
+});
+
+describe('buildDownMaps', () => {
+  it('splits singles from combinations and sorts combinations longest first', () => {
+    const { combinations, combinationsMap, singles } = buildDownMaps(
+      { jump: 'A', special: ['B+C', 'D+E+F'] },
+      { jump: anywhere, special: anywhere },
+      'default',
+      vi.fn(),
+    );
+
+    expect([...singles]).toEqual([['A', 'jump']]);
+    expect(combinations).toEqual([
+      ['D', 'E', 'F'],
+      ['B', 'C'],
+    ]);
+    expect(combinationsMap.get(combinations[0])).toBe('special');
+    expect(combinationsMap.get(combinations[1])).toBe('special');
+  });
+
+  it('skips actions that are out of context', () => {
+    const { singles } = buildDownMaps(
+      { jump: 'A', pause: 'B' },
+      { jump: anywhere, pause: { context: 'menu' } },
+      'default',
+      vi.fn(),
+    );
+
+    expect([...singles]).toEqual([['A', 'jump']]);
+  });
+
+  it('warns once per unknown action and skips it', () => {
+    const warn = vi.fn();
+    const { singles } = buildDownMaps({ nope: ['A', 'B'] }, {}, 'default', warn);
+
+    expect(singles.size).toBe(0);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn).toHaveBeenCalledWith('nope');
+  });
+
+  it('handles a missing section', () => {
+    const { combinations, singles } = buildDownMaps(undefined, {}, 'default', vi.fn());
+
+    expect(combinations).toEqual([]);
+    expect(singles.size).toBe(0);
+  });
+});
+
+describe('buildUpMap', () => {
+  it('normalizes a single input and an array of inputs', () => {
+    const map = buildUpMap({ jump: 'A', pause: ['B', 'C'] }, { jump: anywhere, pause: anywhere }, 'default', vi.fn());
+
+    expect([...map]).toEqual([
+      ['A', 'jump'],
+      ['B', 'pause'],
+      ['C', 'pause'],
+    ]);
+  });
+
+  it('skips out-of-context actions and warns once for unknown ones', () => {
+    const warn = vi.fn();
+    const map = buildUpMap(
+      { jump: 'A', pause: 'B', nope: 'C' },
+      { jump: anywhere, pause: { context: 'menu' } },
+      'default',
+      warn,
+    );
+
+    expect([...map]).toEqual([['A', 'jump']]);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn).toHaveBeenCalledWith('nope');
+  });
+});
+
+describe('isInputActive', () => {
+  it('uses the down predicate for a single input', () => {
+    const isDown = (id: string) => id === 'A';
+
+    expect(isInputActive('A', isDown)).toBe(true);
+    expect(isInputActive('B', isDown)).toBe(false);
+  });
+
+  it('requires every part of a combination', () => {
+    const down = new Set(['A', 'B']);
+    const isDown = (id: string) => down.has(id);
+
+    expect(isInputActive('A+B', isDown)).toBe(true);
+    expect(isInputActive('A+C', isDown)).toBe(false);
+  });
+
+  it('uses the combination predicate for combination parts only', () => {
+    const isDown = (id: string) => id === 'A';
+    const isComboPartDown = (id: string) => id === 'A' || id === 'joystick_up';
+
+    expect(isInputActive('A+joystick_up', isDown, isComboPartDown)).toBe(true);
+    expect(isInputActive('joystick_up', isDown, isComboPartDown)).toBe(false);
+  });
+});
+
+describe('evaluateCombinations', () => {
+  it('fires a combination whose inputs are all down and eliminates its inputs', () => {
+    const combinations = [['A', 'B']];
+    const { fired, eliminated } = evaluateCombinations(combinations, (id) => id === 'A' || id === 'B');
+
+    expect(fired).toEqual([['A', 'B']]);
+    expect([...eliminated]).toEqual(['A', 'B']);
+  });
+
+  it('does not fire a combination that shares an input with an already fired one', () => {
+    const combinations = [
+      ['A', 'B', 'C'],
+      ['A', 'B'],
+    ];
+    const down = new Set(['A', 'B', 'C']);
+    const { fired } = evaluateCombinations(combinations, (id) => down.has(id));
+
+    expect(fired).toEqual([['A', 'B', 'C']]);
+  });
+
+  it('fires nothing when no combination is fully down', () => {
+    const { fired, eliminated } = evaluateCombinations([['A', 'B']], (id) => id === 'A');
+
+    expect(fired).toEqual([]);
+    expect(eliminated.size).toBe(0);
+  });
+});

package/src/plugins/input/controlsCore.ts

@@ -0,0 +1,162 @@
+/**
+ * Pure scheme processing shared by every controls adapter — context gating,
+ * down/up map building and combination elimination. No caper/Pixi imports so
+ * it stays trivially unit-testable, and so keyboard and virtual input can not
+ * drift apart again.
+ *
+ * `A` is the adapter's action-id type; ids are plain object keys at runtime.
+ */
+
+/** One `down` / `up` / `joystick` block of a controls scheme. */
+export interface SchemeSection {
+  [actionId: string]: string | string[] | undefined;
+}
+
+/** The part of a registered action this module cares about. */
+export interface ActionLike {
+  context: string | string[];
+}
+
+/** The down-map trio: combinations (longest first), their action lookup, and single inputs. */
+export interface DownMaps<A = string> {
+  combinations: string[][];
+  combinationsMap: Map<string[], A>;
+  singles: Map<string, A>;
+}
+
+/**
+ * Whether an action registered for `actionContext` may fire in `current`.
+ * Matching is exact — a string context is compared with `===`, never with
+ * `includes`, so `'game_over'` does not swallow `'game'`.
+ */
+export function contextAllows(actionContext: string | string[], current: string): boolean {
+  if (actionContext === '*') {
+    return true;
+  }
+  if (Array.isArray(actionContext)) {
+    return actionContext.includes(current);
+  }
+  return actionContext === current;
+}
+
+/**
+ * Build the down maps for a scheme section. Unknown actions are reported to
+ * `warn` (once per action) and skipped; out-of-context actions are skipped
+ * silently. Combinations are sorted largest first so the elimination pass in
+ * {@link evaluateCombinations} prefers the most specific match.
+ */
+export function buildDownMaps<A = string>(
+  section: SchemeSection | undefined,
+  actions: Record<string, ActionLike | undefined>,
+  currentContext: string,
+  warn: (actionId: string) => void,
+): DownMaps<A> {
+  const combinations: string[][] = [];
+  const combinationsMap = new Map<string[], A>();
+  const singles = new Map<string, A>();
+
+  forEachInput<A>(section, actions, currentContext, warn, (key, input) => {
+    if (input.includes('+')) {
+      const combo = input.split('+');
+      combinations.push(combo);
+      combinationsMap.set(combo, key);
+    } else {
+      singles.set(input, key);
+    }
+  });
+
+  // sort them from the largest to smallest
+  combinations.sort((a, b) => b.length - a.length);
+
+  return { combinations, combinationsMap, singles };
+}
+
+/**
+ * Build the up map for a scheme section — same gating and warning rules as
+ * {@link buildDownMaps}, but every input is a single value.
+ */
+export function buildUpMap<A = string>(
+  section: SchemeSection | undefined,
+  actions: Record<string, ActionLike | undefined>,
+  currentContext: string,
+  warn: (actionId: string) => void,
+): Map<string, A> {
+  const map = new Map<string, A>();
+  forEachInput<A>(section, actions, currentContext, warn, (key, input) => {
+    map.set(input, key);
+  });
+  return map;
+}
+
+/**
+ * Whether an input is active: a single input is tested with `isDown`, a `+`
+ * separated combination requires every part to satisfy `isComboPartDown`
+ * (which defaults to `isDown` — the virtual adapter uses the split to let a
+ * joystick direction take part in a combination but not stand alone).
+ */
+export function isInputActive(
+  input: string,
+  isDown: (id: string) => boolean,
+  isComboPartDown: (id: string) => boolean = isDown,
+): boolean {
+  if (input.includes('+')) {
+    return input.split('+').every((id) => isComboPartDown(id));
+  }
+  return isDown(input);
+}
+
+/**
+ * Walk combinations (already sorted largest first) and fire each one whose
+ * inputs are all down and none of which a longer combination already claimed.
+ * Returns the fired combinations plus the claimed inputs, so the caller can
+ * skip them when dispatching single inputs.
+ */
+export function evaluateCombinations(
+  combinations: string[][],
+  isDown: (id: string) => boolean,
+): { fired: string[][]; eliminated: Set<string> } {
+  const fired: string[][] = [];
+  const eliminated = new Set<string>();
+
+  for (let i = 0; i < combinations.length; i++) {
+    const combination = combinations[i];
+    if (combination.some((id) => eliminated.has(id))) {
+      continue;
+    }
+    if (combination.every((id) => isDown(id))) {
+      combination.forEach((id) => eliminated.add(id));
+      fired.push(combination);
+    }
+  }
+
+  return { fired, eliminated };
+}
+
+/** Shared scheme walk: resolve the action, gate it, normalize its inputs. */
+function forEachInput<A>(
+  section: SchemeSection | undefined,
+  actions: Record<string, ActionLike | undefined>,
+  currentContext: string,
+  warn: (actionId: string) => void,
+  visit: (actionId: A, input: string) => void,
+): void {
+  if (!section) {
+    return;
+  }
+  Object.keys(section).forEach((key) => {
+    const action = actions[key];
+    if (!action) {
+      warn(key);
+      return;
+    }
+    if (!contextAllows(action.context, currentContext)) {
+      return;
+    }
+    const input = section[key];
+    if (!input) {
+      return;
+    }
+    const inputs = Array.isArray(input) ? input : [input];
+    inputs.forEach((inputString) => visit(key as unknown as A, inputString));
+  });
+}

package/src/plugins/input/keyboard/KeyboardControls.ts

@@ -0,0 +1,84 @@
+import { bindAllMethods } from '../../../utils';
+import { normalizeKey, type KeyboardEventDetail } from '../../KeyboardPlugin';
+import { AbstractControls } from '../AbstractControls';
+import { evaluateCombinations } from '../controlsCore';
+import type { ControlsActionMap, KeyboardControlsMap } from '../types';
+
+export class KeyboardControls extends AbstractControls {
+  protected scheme: Partial<KeyboardControlsMap>;
+  protected readonly logLabel = 'KeyboardControls';
+  private _singleDownKeys: Set<string> = new Set();
+
+  constructor() {
+    super();
+    bindAllMethods(this);
+  }
+
+  public initialize(scheme: Partial<KeyboardControlsMap>): void {
+    super.initialize(scheme as Partial<ControlsActionMap>);
+  }
+
+  public connect() {
+    this.addSignalConnection(
+      this.app.keyboard.onKeyDown().connect(this._handleKeyDown),
+      this.app.keyboard.onKeyUp().connect(this._handleKeyUp),
+    );
+
+    super.connect();
+  }
+
+  protected isInputDown(id: string): boolean {
+    return this._singleDownKeys.has(id);
+  }
+
+  private _handleKeyDown(detail: KeyboardEventDetail): void {
+    const key = normalizeKey(detail.event.key);
+    this._singleDownKeys.add(key);
+  }
+
+  private _handleKeyUp(detail: KeyboardEventDetail): void {
+    const key = normalizeKey(detail.event.key);
+    this._singleDownKeys.delete(key);
+
+    const action = this.activeUpInputs.get(key);
+    if (action) {
+      this.app.action(action, { combination: false, inputState: 'up', key });
+    }
+  }
+
+  protected _update() {
+    if (!this.app.keyboard) {
+      return;
+    }
+    const keysDown = this.app.keyboard.keysDown;
+    if (keysDown.size === 0) {
+      return;
+    }
+
+    // this.combinations is already sorted from largest to smallest
+    const { fired, eliminated } = evaluateCombinations(this.combinations, (key) => keysDown.has(key));
+    fired.forEach((combination) => {
+      const action = this.combinationsMap.get(combination);
+      if (action) {
+        this.app.action(action, {
+          key: combination,
+          combination: true,
+          inputState: 'down',
+        });
+      }
+    });
+
+    // order doesn't matter here
+    this._singleDownKeys.forEach((key) => {
+      if (eliminated.has(key)) {
+        return;
+      }
+      if (keysDown.has(key)) {
+        const action = this.activeDownInputs.get(key);
+        if (action) {
+          this.app.action(action, { key, combination: false, inputState: 'down' });
+        }
+      }
+    });
+  }
+}

package/src/plugins/input/keyboard/index.ts

@@ -1,2 +1,2 @@
 export * from './interfaces';
-export * from './KeyboardContols';
+export * from './KeyboardControls';