@caperjs/core 0.1.0

package/src/plugins/WebEventsPlugin.ts

@@ -0,0 +1,132 @@
+import { Application } from '../core/Application';
+import { Signal } from '../signals';
+import type { Size } from '../utils';
+import { bindAllMethods, debounce, getOrientation, type Orientation } from '../utils';
+import type { IPlugin } from './Plugin';
+import { Plugin } from './Plugin';
+
+export interface IWebEventsPlugin extends IPlugin {
+  onResize: Signal<(size: { width: number; height: number }) => void>;
+  onVisibilityChanged: Signal<(visible: boolean) => void>;
+  onOrientationChanged: Signal<
+    ({ orientation, screenOrientation }: { orientation: Orientation; screenOrientation: ScreenOrientation }) => void
+  >;
+}
+
+/**
+ * Maintains a list of callbacks for specific web events and invokes callbacks when event occurs.
+ */
+export class WebEventsPlugin extends Plugin implements IWebEventsPlugin {
+  public readonly id = 'webEvents';
+
+  // signals
+  public onResize: Signal<(size: Size) => void> = new Signal<(size: Size) => void>();
+  public onVisibilityChanged: Signal<(visible: boolean) => void> = new Signal<(visible: boolean) => void>();
+  public onOrientationChanged: Signal<
+    ({ orientation, screenOrientation }: { orientation: Orientation; screenOrientation: ScreenOrientation }) => void
+  > = new Signal<
+    ({ orientation, screenOrientation }: { orientation: Orientation; screenOrientation: ScreenOrientation }) => void
+  >();
+  private _debouncedEmitVisibility = debounce((value: boolean) => {
+    this.onVisibilityChanged.emit(value);
+  }, 1);
+
+  /**
+   * Creates callback arrays and registers to web events.
+   */
+  constructor() {
+    super();
+    bindAllMethods(this);
+  }
+
+  get app(): Application {
+    return Application.getInstance();
+  }
+
+  public initialize(): void {
+    document.addEventListener('visibilitychange', this._onVisibilityChanged, false);
+    window.addEventListener('pagehide', this._onPageHide, false);
+    window.addEventListener('pageshow', this._onPageShow, false);
+    window.addEventListener('resize', this._onResize);
+    document.addEventListener('fullscreenchange', this._onResize);
+    window.addEventListener('orientationchange', this._onOrientationChanged);
+  }
+
+  public destroy() {
+    document.removeEventListener('visibilitychange', this._onVisibilityChanged, false);
+    window.removeEventListener('resize', this._onResize);
+    document.removeEventListener('fullscreenchange', this._onResize);
+    window.removeEventListener('pagehide', this._onPageHide, false);
+    window.removeEventListener('pageshow', this._onPageShow, false);
+  }
+
+  protected getCoreSignals(): string[] {
+    return ['onVisibilityChanged', 'onOrientationChanged'];
+  }
+
+  /**
+   * Called when the browser visibility changes. Passes the `hidden` flag of the document to all callbacks.
+   */
+  private _onVisibilityChanged(): void {
+    this._emitVisibilityChanged(!document.hidden);
+  }
+
+  /**
+   * Called when the browser resizes.
+   */
+  private _onResize(): void {
+    const el = this.app.renderer.canvas?.parentElement;
+    let screenWidth = window.innerWidth;
+    let screenHeight = window.innerHeight;
+    if (el && el?.getBoundingClientRect()) {
+      screenWidth = el.offsetWidth;
+      screenHeight = el.offsetHeight;
+    }
+    this.onResize.emit({ width: screenWidth, height: screenHeight });
+  }
+
+  /**
+   * Called when the page is hidden.
+   * Some browsers (like Safari) don't support the `visibilitychange` event, so we also listen for `pagehide`.
+   * We're just mimicking the `visibilitychange` event here.
+   */
+  private _onPageHide() {
+    this._emitVisibilityChanged(false);
+  }
+
+  /**
+   * Called when the page is shown.
+   * Some browsers (like Safari) don't support the `visibilitychange` event, so we also listen for `pageshow`.
+   * We're just mimicking the `visibilitychange` event here.
+   * @private
+   */
+  private _onPageShow() {
+    this._emitVisibilityChanged(true);
+    this._onResize();
+  }
+
+  private _emitVisibilityChanged(value: boolean) {
+    this._debouncedEmitVisibility(value);
+  }
+
+  private _onOrientationChanged(e: any) {
+    let orientation: Orientation | null = null;
+    const screenOrientation = e?.target?.screen?.orientation;
+    const screenOrientationType = screenOrientation?.type;
+
+    if (screenOrientationType) {
+      if (screenOrientationType.includes('landscape')) {
+        orientation = 'landscape';
+      } else {
+        orientation = 'portrait';
+      }
+      this.onOrientationChanged.emit({ orientation, screenOrientation });
+      return;
+    }
+
+    setTimeout(() => {
+      orientation = getOrientation();
+      this.onOrientationChanged.emit({ orientation, screenOrientation });
+    }, 10);
+  }
+}

package/src/plugins/actions/ActionsPlugin.ts

@@ -0,0 +1,113 @@
+import { Action, ActionContext, ActionDetail, ActionMap, ActionSignal } from '.';
+import { IApplication } from '../../core';
+import { Signal } from '../../signals';
+import { Logger } from '../../utils';
+import { IPlugin, Plugin } from '../Plugin';
+
+export interface IActionsPlugin<C extends ActionContext = ActionContext> extends IPlugin {
+  context: C;
+  onActionContextChanged: Signal<(context: C) => void>;
+  onActionDispatched: Signal<(detail: ActionDetail) => void>;
+  initialize(options: Partial<IActionsPluginOptions>, app: IApplication): void;
+  getAction<TActionData = any>(action: Action | string): ActionSignal<TActionData>;
+  getActions(): ActionMap;
+  sendAction<TActionData = any>(actionId: Action | string, data?: TActionData): void;
+  setActionContext(context: C): string;
+  debug: boolean;
+}
+
+export interface IActionsPluginOptions {
+  actions: Partial<ActionMap>;
+}
+
+export class ActionsPlugin extends Plugin<IActionsPluginOptions> implements IActionsPlugin {
+  public readonly id = 'actions';
+  // signals
+  public onActionContextChanged: Signal<(context: string | ActionContext) => void> = new Signal<
+    (context: string | ActionContext) => void
+  >();
+  // emitted after an allowed action is dispatched (not for dropped out-of-context actions)
+  public onActionDispatched: Signal<(detail: ActionDetail) => void> = new Signal<(detail: ActionDetail) => void>();
+
+  // private properties
+  private _context: ActionContext = 'default';
+  private _signals: Map<string | number, ActionSignal> = new Map();
+  private _actions: Partial<ActionMap> = {};
+  private _debug: boolean = false;
+  set debug(debug: boolean) {
+    this._debug = debug;
+  }
+  get debug(): boolean {
+    return this._debug;
+  }
+
+  // getter / setter
+  get context(): string | ActionContext {
+    return this._context;
+  }
+
+  set context(context: string | ActionContext) {
+    if (this._context === context) {
+      return;
+    }
+    this._context = context;
+    this.onActionContextChanged.emit(context);
+  }
+
+  initialize(_options: Partial<IActionsPluginOptions>, app: IApplication): void {
+    this._actions = app?.config?.actions ? app.config.actions || {} : {};
+  }
+
+  getAction<TActionData = any>(action: Action | string): ActionSignal<TActionData> {
+    if (!this._signals.has(action)) {
+      this._signals.set(action, new Signal<(actionDetail: ActionDetail<TActionData>) => void>());
+    }
+    return this._signals.get(action)!;
+  }
+
+  getActions(): ActionMap {
+    return this._actions as ActionMap;
+  }
+
+  sendAction<TActionData = any>(actionId: Action | string, data?: TActionData): void {
+    // check if action is defined
+    if (!this._actions[actionId]) {
+      if (this._debug) {
+        Logger.warn(`Action ${actionId} is not defined`);
+      }
+      return;
+    }
+
+    // check if action is allowed for current context
+    // send action if allowed
+    if (
+      this._actions[actionId]?.context === '*' ||
+      this._actions[actionId]?.context === this.context ||
+      this._actions[actionId]?.context?.includes(this.context)
+    ) {
+      const detail: ActionDetail<TActionData> = { id: actionId, context: this.context, data };
+      this.getAction<TActionData>(actionId).emit(detail);
+      // notify automation / observers of the dispatched (allowed) action
+      this.onActionDispatched.emit(detail);
+      return;
+    }
+
+    // the action wasn't allowed
+    if (this._debug) {
+      Logger.warn(`Action ${actionId} is not allowed for context ${this.context}`);
+    }
+  }
+
+  setActionContext(context: string | ActionContext): string {
+    this.context = context;
+    return this.context;
+  }
+
+  protected getCoreFunctions(): string[] {
+    return ['getAction', 'sendAction', 'setActionContext', 'getActions'];
+  }
+
+  protected getCoreSignals(): string[] {
+    return ['onActionContextChanged', 'onActionDispatched'];
+  }
+}

package/src/plugins/actions/constants.ts

@@ -0,0 +1,45 @@
+import { Action } from '../..';
+
+export const DefaultActionContexts = {
+  default: 'default',
+  menu: 'menu',
+  pause: 'pause',
+  popup: 'popup',
+  game: 'game',
+};
+
+export const DefaultActionContextsArray = ['default', 'menu', 'pause', 'popup', 'game'];
+
+export const DefaultActions: Action[] = [
+  'up',
+  'down',
+  'left',
+  'right',
+  'action',
+  'pause',
+  'unpause',
+  'start',
+  'select',
+  'menu',
+  'back',
+  'next',
+];
+
+export const defaultActionsList = {
+  action: { context: '*' },
+  back: { context: ['menu', 'default', 'popup'] },
+  next: { context: ['menu', 'default', 'popup'] },
+  select: { context: ['menu', 'default', 'popup'] },
+  menu: { context: ['default'] },
+  down: { context: ['menu', 'default', 'popup'] },
+  up: { context: ['menu', 'default', 'popup'] },
+  left: { context: ['menu', 'default', 'popup'] },
+  right: { context: '*' },
+  pause: { context: '*' },
+  unpause: { context: '*' },
+  start: { context: '*' },
+};
+
+export const DefaultButtonIds = {
+  __default_do_not_use__: '__default_do_not_use__',
+};

package/src/plugins/actions/index.ts

@@ -0,0 +1,4 @@
+export * from './ActionsPlugin';
+export * from './constants';
+export * from './methods';
+export * from './types';

package/src/plugins/actions/methods.ts

@@ -0,0 +1,28 @@
+import { DefaultActionContextsArray, defaultActionsList } from './constants';
+import { type UserActions, type UserButtons, type UserContexts } from './types';
+
+/**
+ * Define the contexts for the actions.
+ * @param contexts - The contexts to define.
+ * @default ['default', 'game', 'menu', 'pause', 'popup', 'default']
+ * @returns {ActionContext[]}
+ */
+
+export function defineContexts<C extends UserContexts = UserContexts>(contexts?: C): C {
+  return contexts ?? (DefaultActionContextsArray as unknown as C);
+}
+
+export function defineActions<C extends UserContexts = UserContexts, U extends UserActions = UserActions<C>>(
+  contexts: C,
+  actions: U,
+  useDefaultActions: boolean = true,
+): U {
+  if (useDefaultActions) {
+    actions = { ...defaultActionsList, ...actions };
+  }
+  return actions;
+}
+
+export function defineButtons<B extends UserButtons = UserButtons>(buttons?: B): B {
+  return buttons || ([] as unknown as B);
+}

package/src/plugins/actions/types.ts

@@ -0,0 +1,47 @@
+import { Signal } from '../../signals';
+import { DefaultActionContexts, DefaultButtonIds } from './constants';
+
+export type ActionContext = keyof typeof DefaultActionContexts | (string & {});
+
+export type Action =
+  | 'up'
+  | 'down'
+  | 'left'
+  | 'right'
+  | 'action'
+  | 'next'
+  | 'back'
+  | 'pause'
+  | 'unpause'
+  | 'start'
+  | 'select'
+  | 'menu'
+  | ((string | number) & {});
+
+export type ActionDetail<T = any> = {
+  id: string | number;
+  context: string | ActionContext;
+  data?: T;
+};
+export type ActionSignal<TActionData = any> = Signal<(detail: ActionDetail<TActionData>) => void>;
+export type ActionsList = (Action | (string & {}))[];
+export type ActionKey = Action | (string & {});
+
+export type ActionMap<C extends UserContexts = UserContexts> = {
+  [K in ActionKey]: ActionDefinition<C>;
+};
+
+export type UserActions<C extends UserContexts = UserContexts> = Partial<ActionMap<C>>;
+
+export type ExtractContext<C extends readonly ActionContext[]> = C[number];
+export type UserContexts = ActionContext[];
+
+export interface ActionDefinition<C extends UserContexts = UserContexts> {
+  context: ExtractContext<C> | ExtractContext<C>[] | '*' | (string & {});
+}
+
+export type UserButton = keyof typeof DefaultButtonIds | (string & {});
+
+export type UserButtons = UserButton[];
+
+export type ExtractButtonId<B extends UserButtons> = B[number];

package/src/plugins/audio/AudioChannel.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it, vi } from 'vitest';
+import { AudioChannel } from './AudioChannel';
+import { AudioInstance } from './AudioInstance';
+import { IAudioManagerPlugin } from './AudioManagerPlugin';
+
+function createManager(overrides: Record<string, unknown> = {}) {
+  return {
+    muted: false,
+    masterVolume: 1,
+    onChannelMuted: { emit: vi.fn() },
+    onChannelVolumeChanged: { emit: vi.fn() },
+    app: { ticker: { addOnce: (fn: () => void) => fn() } },
+    ...overrides,
+  } as unknown as IAudioManagerPlugin;
+}
+
+function createMedia() {
+  return {
+    volume: 1,
+    muted: false,
+    paused: false,
+    on: vi.fn(),
+    off: vi.fn(),
+    play: vi.fn(),
+    stop: vi.fn(),
+  };
+}
+
+describe('AudioChannel', () => {
+  it('mutes every concurrent instance of the same alias', () => {
+    const manager = createManager();
+    const channel = new AudioChannel('sfx', manager);
+
+    const instance1 = channel.add('boom', new AudioInstance('boom', channel, manager));
+    const media1 = createMedia();
+    instance1.media = media1 as never;
+
+    const instance2 = channel.add('boom', new AudioInstance('boom', channel, manager));
+    const media2 = createMedia();
+    instance2.media = media2 as never;
+
+    channel.muted = true;
+
+    expect(media1.muted).toBe(true);
+    expect(media2.muted).toBe(true);
+  });
+
+  it('removeInstance drops just that instance; removing an unknown instance/id is a no-op', () => {
+    const manager = createManager();
+    const channel = new AudioChannel('sfx', manager);
+
+    const instance1 = channel.add('boom', new AudioInstance('boom', channel, manager));
+    const instance2 = channel.add('boom', new AudioInstance('boom', channel, manager));
+
+    channel.removeInstance(instance1);
+    expect(channel.instances).toEqual([instance2]);
+
+    const untracked = new AudioInstance('boom', channel, manager);
+    expect(() => channel.removeInstance(untracked)).not.toThrow();
+    expect(channel.instances).toEqual([instance2]);
+
+    expect(channel.remove('does-not-exist')).toBeUndefined();
+    expect(channel.instances).toEqual([instance2]);
+  });
+
+  it('folds channel mute into effective volume and restores it on unmute', () => {
+    const manager = createManager();
+    const channel = new AudioChannel('sfx', manager);
+    channel.volume = 0.5;
+
+    const instance = channel.add('boom', new AudioInstance('boom', channel, manager));
+    const media = createMedia();
+    instance.media = media as never;
+
+    channel.muted = true;
+    instance.volume = 0.8;
+    expect(media.volume).toBe(0);
+
+    channel.muted = false;
+    expect(media.volume).toBeCloseTo(0.8 * 0.5 * 1);
+  });
+
+  it('remove(id) stops all instances tracked under that alias', () => {
+    const manager = createManager();
+    const channel = new AudioChannel('sfx', manager);
+
+    const instance1 = channel.add('boom', new AudioInstance('boom', channel, manager));
+    const media1 = createMedia();
+    instance1.media = media1 as never;
+
+    const instance2 = channel.add('boom', new AudioInstance('boom', channel, manager));
+    const media2 = createMedia();
+    instance2.media = media2 as never;
+
+    channel.remove('boom');
+
+    expect(media1.stop).toHaveBeenCalled();
+    expect(media2.stop).toHaveBeenCalled();
+    expect(channel.instances).toEqual([]);
+  });
+});

package/src/plugins/audio/AudioChannel.ts

@@ -0,0 +1,164 @@
+import { Logger } from '../../utils';
+import { IAudioInstance } from './AudioInstance';
+import { ChannelName, IAudioManagerPlugin } from './AudioManagerPlugin';
+
+export interface IAudioChannel {
+  name: string;
+  muted: boolean;
+  volume: number;
+  instances: IAudioInstance[];
+
+  add(id: string, instance: IAudioInstance): IAudioInstance;
+
+  get(id: string): IAudioInstance | undefined;
+
+  remove(id: string): IAudioInstance | undefined;
+
+  removeInstance(instance: IAudioInstance): void;
+
+  updateVolume(): void;
+
+  restore(): void;
+
+  destroy(): void;
+
+  pause(): void;
+
+  resume(): void;
+}
+
+export class AudioChannel<C extends ChannelName = ChannelName> {
+  private _sounds: Map<string, IAudioInstance[]> = new Map<string, IAudioInstance[]>();
+
+  constructor(
+    public name: C,
+    public manager: IAudioManagerPlugin<C>,
+  ) {
+    this.muted = this.manager.muted;
+  }
+
+  get instances(): IAudioInstance[] {
+    return Array.from(this._sounds.values()).flat();
+  }
+
+  private _muted: boolean = false;
+
+  get muted(): boolean {
+    return this._muted;
+  }
+
+  set muted(value: boolean) {
+    this._muted = value;
+    this.manager.onChannelMuted.emit({ channel: this, muted: value });
+    this._setMuted();
+  }
+
+  private _volume: number = 1.0;
+
+  get volume(): number {
+    return this._volume;
+  }
+
+  set volume(value: number) {
+    this._volume = value;
+    this.updateVolume();
+  }
+
+  add(id: string, instance: IAudioInstance): IAudioInstance {
+    const bucket = this._sounds.get(id);
+    if (bucket) {
+      bucket.push(instance);
+    } else {
+      this._sounds.set(id, [instance]);
+    }
+    return instance;
+  }
+
+  get(id: string): IAudioInstance | undefined {
+    const bucket = this._sounds.get(id);
+    return bucket ? bucket[bucket.length - 1] : undefined;
+  }
+
+  remove(id: string): IAudioInstance | undefined {
+    const bucket = this._sounds.get(id);
+    if (!bucket) {
+      return undefined;
+    }
+    const lastInstance = bucket[bucket.length - 1];
+    // destroy() -> stop() -> emits onEnd, whose handler may call
+    // removeInstance() and mutate `bucket` mid-iteration. Iterate a copy.
+    [...bucket].forEach((instance) => instance.destroy());
+    this._sounds.delete(id);
+    return lastInstance;
+  }
+
+  /**
+   * Removes a single instance from its alias bucket without stopping or
+   * destroying it, for use when an instance has naturally reached the end
+   * of its life. No-op if the instance is not currently tracked.
+   */
+  removeInstance(instance: IAudioInstance): void {
+    const bucket = this._sounds.get(instance.id);
+    if (!bucket) {
+      return;
+    }
+    const index = bucket.indexOf(instance);
+    if (index === -1) {
+      return;
+    }
+    bucket.splice(index, 1);
+    if (bucket.length === 0) {
+      this._sounds.delete(instance.id);
+    }
+  }
+
+  pause(): void {
+    this._sounds.forEach((bucket) => {
+      bucket.forEach((sound) => {
+        try {
+          sound.pause();
+        } catch (error) {
+          Logger.error('Error pausing sound', sound.id, error);
+        }
+      });
+    });
+  }
+
+  resume(): void {
+    this._sounds.forEach((bucket) => {
+      bucket.forEach((sound) => {
+        try {
+          sound.resume();
+        } catch (error) {
+          Logger.error('Error resuming sound', sound.id, error);
+        }
+      });
+    });
+  }
+
+  _setMuted(): void {
+    this._sounds.forEach((bucket) => {
+      bucket.forEach((sound) => {
+        sound.muted = this._muted;
+      });
+    });
+  }
+
+  updateVolume() {
+    this.manager.app.ticker.addOnce(() => {
+      this._sounds.forEach((bucket) => {
+        bucket.forEach((sound) => {
+          sound.updateVolume();
+        });
+      });
+      this.manager.onChannelVolumeChanged.emit({ channel: this, volume: this._volume });
+    });
+  }
+
+  restore() {
+    this.muted = this._muted;
+    this.volume = this._volume;
+  }
+
+  destroy() {}
+}