@caperjs/core 0.2.4 → 0.4.0

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

@@ -0,0 +1,205 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { Signal } from '../../signals';
+
+// Controls → KeyboardControls / VirtualControls reach for the Application singleton.
+const mocks = vi.hoisted(() => ({ app: null as any }));
+
+vi.mock('../../core/Application', () => ({
+  Application: { getInstance: () => mocks.app },
+}));
+
+import type { IButton } from '../../ui';
+import { Logger } from '../../utils';
+import { Controls } from './Controls';
+
+type FakeApp = {
+  ticker: { add: ReturnType<typeof vi.fn>; remove: ReturnType<typeof vi.fn> };
+  actionContext: string;
+  actionsPlugin: { getActions: () => Record<string, { context: string; input: string[] }> };
+  signal: { onActionContextChanged: Signal<() => void> };
+  keyboard: {
+    keysDown: Set<string>;
+    onKeyDown: () => Signal<(detail: any) => void>;
+    onKeyUp: () => Signal<(detail: any) => void>;
+  };
+  action: ReturnType<typeof vi.fn>;
+};
+
+let app: FakeApp;
+let keyDown: Signal<(detail: any) => void>;
+let keyUp: Signal<(detail: any) => void>;
+let actions: Record<string, { context: string; input: string[] }>;
+
+function pressKey(key: string) {
+  app.keyboard.keysDown.add(key);
+  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,
+    onDown: new Signal<() => void>(),
+    onUp: new Signal<() => void>(),
+    onUpOutside: new Signal<() => void>(),
+    onDestroy: new Signal<() => void>(),
+  } as unknown as IButton;
+}
+
+beforeEach(() => {
+  keyDown = new Signal();
+  keyUp = new Signal();
+  actions = {
+    move_left: { context: '*', input: [] },
+    jump: { context: '*', input: [] },
+  };
+  app = {
+    ticker: { add: vi.fn(), remove: vi.fn() },
+    actionContext: 'default',
+    actionsPlugin: { getActions: () => actions },
+    signal: { onActionContextChanged: new Signal<() => void>() },
+    keyboard: {
+      keysDown: new Set<string>(),
+      onKeyDown: () => keyDown,
+      onKeyUp: () => keyUp,
+    },
+    action: vi.fn(),
+  };
+  mocks.app = app;
+});
+
+describe('Controls teardown', () => {
+  it('destroys configured control schemes without throwing and removes ticker callbacks', () => {
+    const controls = new Controls();
+    controls.initialize({
+      keyboard: { down: { move_left: 'A' } },
+      touch: { down: { jump: 'btn-a' } },
+    } as any);
+    controls.connect();
+
+    expect(app.ticker.add).toHaveBeenCalledTimes(2);
+    expect(() => controls.destroy()).not.toThrow();
+    expect(app.ticker.remove).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe('Controls combinations', () => {
+  it('reports a keyboard combination active when both keys are down', () => {
+    const controls = new Controls();
+    controls.initialize({ keyboard: { down: { move_left: ['A+B'] } } } as any);
+    controls.connect();
+
+    expect(controls.isActionActive('move_left')).toBe(false);
+
+    pressKey('A');
+    expect(controls.isActionActive('move_left')).toBe(false);
+
+    pressKey('B');
+    expect(controls.isActionActive('move_left')).toBe(true);
+  });
+
+  it('reports a virtual button combination active when both buttons are down', () => {
+    const controls = new Controls();
+    controls.initialize({ touch: { down: { jump: ['btn-a+btn-b'] } } } as any);
+    controls.connect();
+
+    const a = makeButton('btn-a');
+    const b = makeButton('btn-b');
+    controls.virtual.addButton(a);
+    controls.virtual.addButton(b);
+
+    a.onDown.emit();
+    expect(controls.isActionActive('jump')).toBe(false);
+
+    b.onDown.emit();
+    expect(controls.isActionActive('jump')).toBe(true);
+  });
+});
+
+describe('Controls with an unmapped action in the scheme', () => {
+  it('does not throw on initialize or on an action context change', () => {
+    const controls = new Controls();
+
+    expect(() =>
+      controls.initialize({
+        keyboard: { down: { not_an_action: 'A' } },
+        touch: { down: { not_an_action: 'btn-a' }, up: { also_not_an_action: 'btn-b' } },
+      } as any),
+    ).not.toThrow();
+
+    controls.connect();
+
+    expect(() => app.signal.onActionContextChanged.emit()).not.toThrow();
+  });
+});
+
+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();
+    controls.initialize({ touch: { down: { jump: 'btn-a' } } } as any);
+    controls.connect();
+
+    const button = makeButton('btn-a');
+    controls.virtual.addButton(button);
+    controls.virtual.removeButton(button);
+
+    button.onDown.emit();
+
+    expect(controls.isActionActive('jump')).toBe(false);
+  });
+});

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';

package/src/plugins/input/touch/VirtualControls.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest';
+
+// VirtualControls reaches the app through Application.getInstance(). Stub it.
+// The stub app is filled in after the imports (getInstance is only called lazily).
+const holder = vi.hoisted(() => ({ app: null as any }));
+vi.mock('../../../core/Application', () => ({
+  Application: { getInstance: () => holder.app },
+}));
+
+import { Signal } from '../../../signals';
+import { VirtualControls } from './VirtualControls';
+
+describe('VirtualControls', () => {
+  it('stops reacting to action context changes after destroy', () => {
+    const onActionContextChanged = new Signal<(context: string) => void>();
+    holder.app = {
+      signal: { onActionContextChanged },
+      ticker: { add: vi.fn(), remove: vi.fn() },
+      actionsPlugin: { getActions: () => ({}) },
+      actionContext: 'default',
+    };
+
+    const controls = new VirtualControls();
+    const sortActions = vi.fn();
+    (controls as any)._sortActions = sortActions;
+
+    controls.initialize({});
+    const callsAfterInit = sortActions.mock.calls.length;
+
+    onActionContextChanged.emit('menu');
+    expect(sortActions).toHaveBeenCalledTimes(callsAfterInit + 1);
+
+    controls.destroy();
+
+    onActionContextChanged.emit('game');
+    expect(sortActions).toHaveBeenCalledTimes(callsAfterInit + 1);
+  });
+});