@caperjs/core 0.1.0

package/src/plugins/focus/FocusOutliner.ts

@@ -0,0 +1,111 @@
+import { Bounds, Container, DestroyOptions, Graphics, Point, PointLike } from 'pixi.js';
+import { Application } from '../../core/Application';
+import { bindAllMethods, resolvePointLike } from '../../utils';
+import type { IFocusable } from './FocusManagerPlugin';
+
+export type FocusOutlinerConfig = {
+  color: number;
+  shape: 'rectangle' | 'rounded rectangle';
+  lineWidth?: number;
+  radius?: number;
+};
+
+export interface IFocusOutliner {
+  position: PointLike;
+  focusBounds: Bounds;
+
+  draw(focusTarget: IFocusable): void;
+
+  clear(): void;
+
+  destroy(args?: DestroyOptions): void;
+
+  setFocusTarget(focusTarget: IFocusable): void;
+
+  clearFocusTarget(): void;
+
+  updatePosition(): void;
+}
+
+export class FocusOutliner extends Container implements IFocusOutliner {
+  focusBounds: Bounds;
+  focusTarget: IFocusable | null;
+  protected _config: FocusOutlinerConfig;
+  protected _graphics: Graphics;
+
+  constructor(config?: Partial<FocusOutlinerConfig>) {
+    super();
+    bindAllMethods(this);
+    this._config = {
+      color: 0x00ffff,
+      shape: 'rounded rectangle',
+      radius: 8,
+      lineWidth: 2,
+      ...config,
+    };
+    this._graphics = new Graphics();
+    this.addChild(this._graphics);
+  }
+
+  public draw(focusTarget: IFocusable): void {
+    this.clear();
+    this.setFocusTarget(focusTarget);
+    if (!this.focusTarget) {
+      return;
+    }
+
+    this._graphics.strokeStyle = { width: this._config.lineWidth, color: this._config.color, alpha: 1 };
+    if (this._config.shape === 'rectangle') {
+      this._graphics.rect(0, 0, this.focusBounds.width, this.focusBounds.height);
+    } else {
+      this._graphics.roundRect(0, 0, this.focusBounds.width, this.focusBounds.height, this._config.radius);
+    }
+    this._graphics.stroke();
+  }
+
+  public clear(): void {
+    if (this._graphics) {
+      this._graphics.clear();
+    }
+    this.clearFocusTarget();
+  }
+
+  public destroy(options?: DestroyOptions) {
+    this.clear();
+    this._graphics.destroy();
+    super.destroy(options);
+  }
+
+  public setFocusTarget(focusTarget: IFocusable) {
+    if (focusTarget) {
+      this.focusTarget = focusTarget;
+      this.focusBounds = this.focusTarget.getFocusArea().clone();
+      Application.getInstance().ticker.add(this.updatePosition);
+    }
+  }
+
+  public clearFocusTarget() {
+    this.focusTarget = null;
+    Application.getInstance().ticker.remove(this.updatePosition);
+  }
+
+  public updatePosition() {
+    if (!this.focusTarget || !this.parent) {
+      return;
+    }
+    let pos;
+    if (this.focusTarget.layout && this.focusTarget.parent) {
+      const pt = new Point(this.focusTarget.layout.realX, this.focusTarget.layout.realY);
+      pos = this.parent.toLocal(this.focusTarget.parent.toGlobal(pt));
+    } else {
+      pos = this.parent.toLocal(this.focusTarget.getGlobalPosition());
+    }
+    const focusPos = this.focusTarget.getFocusPosition();
+    if (focusPos) {
+      const fp = resolvePointLike(focusPos);
+      pos.x += fp.x;
+      pos.y += fp.y;
+    }
+    this.position.set(pos.x, pos.y);
+  }
+}

package/src/plugins/focus/index.ts

@@ -0,0 +1,2 @@
+export * from './FocusOutliner';
+export * from './FocusManagerPlugin';

package/src/plugins/i18nPlugin.ts

@@ -0,0 +1,284 @@
+import { Assets } from 'pixi.js';
+import { Signal } from '../signals';
+import type { AppTypeOverrides, ImportListItem, ImportListItemModule } from '../utils';
+import { getDynamicModuleFromImportListItem, Logger } from '../utils';
+import type { IPlugin } from './Plugin';
+import { Plugin } from './Plugin';
+
+/**
+ * Flattened dot-path keys for the project's reference locale (e.g. 'foo',
+ * 'obj.nested'). Generated from `src/locales/<reference>.ts` by the Vite
+ * plugin. Falls back to `string` when no locales are discovered.
+ *
+ * `(string & {})` preserves autocomplete for known keys while still
+ * accepting dynamic strings like `t(\`errors.\${code}\`)`.
+ */
+export type LocaleKey = AppTypeOverrides extends { LocaleKeys: infer K extends string }
+  ? K | (string & {})
+  : string;
+
+/**
+ * Type definition for i18n dictionary.
+ */
+export type i18nDict = Record<string, any>;
+
+/**
+ * Type definition for i18n translation parameters.
+ */
+export type i18nTParams = { variant?: number | 'random' } & Record<string, any>;
+
+/**
+ * Type definition for i18n import list item.
+ */
+type i18nImportListItem<T> = {
+  id: string;
+  namedExport?: string;
+  options?: any;
+  module?: ImportListItemModule<T>;
+} & {
+  json?: string;
+};
+
+/**
+ * Type definition for i18n options.
+ */
+export type i18nOptions = {
+  defaultLocale: string;
+  locales: string[];
+  loadAll: boolean;
+  files: i18nImportListItem<i18nDict>[];
+};
+
+/**
+ * Default options for i18n module.
+ */
+const defaultOptions: i18nOptions = {
+  defaultLocale: 'en',
+  locales: ['en'],
+  loadAll: false,
+  files: [],
+};
+
+/**
+ * Interface for i18n module.
+ */
+export interface Ii18nPlugin extends IPlugin {
+  readonly locale: string;
+  readonly locales: string[];
+  onLocaleChanged: Signal<(locale: string) => void>;
+
+  setLocale(localeId: string): Promise<string>;
+
+  loadLocale(localeId: string): Promise<void>;
+
+  t(key: LocaleKey, params?: i18nTParams, locale?: string): string;
+
+  parse(input: string, locale?: string): string;
+}
+
+/**
+ * Resolves a dot-path (e.g. `'obj.nested.value'`) against a dictionary
+ * object. Returns `undefined` if any segment is missing or if a non-object
+ * is traversed mid-path.
+ */
+function resolveLocalePath(dict: i18nDict, key: string): unknown {
+  if (key in dict) return dict[key];
+  if (!key.includes('.')) return undefined;
+  let cur: unknown = dict;
+  for (const segment of key.split('.')) {
+    if (cur && typeof cur === 'object' && segment in (cur as Record<string, unknown>)) {
+      cur = (cur as Record<string, unknown>)[segment];
+    } else {
+      return undefined;
+    }
+  }
+  return cur;
+}
+
+/**
+ * i18n module class.
+ */
+export class i18nPlugin extends Plugin<i18nOptions> implements Ii18nPlugin {
+  public readonly id = 'i18n';
+  public onLocaleChanged: Signal<(locale: string) => void> = new Signal<(locale: string) => void>();
+
+  private _dicts: Record<string, i18nDict> = {};
+
+  private _locale: string;
+
+  /**
+   * Getter for locale.
+   */
+  get locale(): string {
+    return this._locale;
+  }
+
+  get locales(): string[] {
+    return this._options.locales;
+  }
+
+  /**
+   * Initializes the i18n module.
+   * sets the default locale and loads the locale files.
+   * @param app The application instance.
+   * @param options The i18n options.
+   * @returns Promise<void>
+   */
+  public async initialize(options: Partial<i18nOptions>): Promise<void> {
+    this._options = { ...defaultOptions, ...options };
+    this._locale = this._options.defaultLocale;
+    if (this._options.loadAll && this._options.files.length > 0) {
+      const files = this._options.files.filter((file) => this._options.locales.includes(file.id));
+      for (const file of files) {
+        await this.loadLocale(file.id);
+      }
+    } else if (this._options.files.length > 0) {
+      await this.loadLocale(this._locale);
+    }
+  }
+
+  /**
+   * Sets the locale.
+   * If the locale is not loaded, it will load it first.
+   * @param localeId The locale id to set.
+   * @returns Promise<string>
+   */
+
+  async setLocale(localeId: string) {
+    this._locale = localeId;
+    await this._loadAndSetLocale(localeId);
+    return this._locale;
+  }
+
+  /**
+   * Translates a key into a string.
+   * If the key is not found, it will return an empty string.
+   * If the key is found, it will replace any placeholders in the string with the values from the params object.
+   * If the key contains a variant, it will select a random variant if the variant param is set to 'random'.
+   * If the key contains a number variant, it will select the variant based on the variant param.
+   * @param key The key to translate.
+   * @param params The parameters to replace in the string.
+   * @param locale The locale to use for translation.
+   * @returns The translated string.
+   */
+
+  t(key: LocaleKey, params?: i18nTParams, locale: string = this._locale): string {
+    const dict = this._dicts[locale];
+    if (!dict) {
+      Logger.error(`i18n:: No dictionary loaded for current locale: ${locale}`);
+      return '';
+    }
+    // Dot-path resolution: `t('obj.nested')` walks the dict tree. Flat keys
+    // still work (including keys that literally contain dots, via the
+    // short-circuit in resolveLocalePath).
+    const resolved = resolveLocalePath(dict, key as string);
+    let str = typeof resolved === 'string' ? resolved : undefined;
+
+    if (!str) {
+      Logger.error(`i18n:: No result found for the key ${key} in the locale: ${this._locale}`);
+      return '';
+    }
+
+    if (params) {
+      if (typeof params.variant === 'number' || params.variant === 'random') {
+        const match = /\[(.*?)\]/.exec(str);
+        if (match) {
+          // Split the string by the "|" character to get an array of variations.
+          const items = match[1].split('|');
+
+          // Get the selected variant based on the "variation" param.
+          const num = params.variant === 'random' ? Math.floor(Math.random() * items.length) : params.variant;
+
+          // Replace the original string with the selected variant
+          str = str.replace(match[0], items[num]);
+        }
+      }
+
+      // Iterate over all params to replace placeholders in the string.
+      for (const f in params) {
+        // Create a regular expression to match the placeholder for the current param.
+        const re = new RegExp(`{${f}}`, 'g');
+
+        //Replace all occurences of the placeholder with the value of the param.
+        str = str.replace(re, String(params[f]));
+      }
+    }
+
+    /**
+     * Return the final translated string.
+     */
+    return str;
+  }
+
+  /**
+   * Translates a key into a string (alias for t)
+   * @param key The key to translate.
+   * @param params The parameters to replace in the string.
+   * @param locale The locale to use for translation.
+   * @returns The translated string.
+   */
+  translate(key: LocaleKey, params?: i18nTParams, locale: string = this._locale): string {
+    return this.t(key, params, locale);
+  }
+
+  /**
+   * Parses the input string and replaces anything in between {} braces, assuming it is a key in the dictionary.
+   * @param {string} input
+   * @param locale
+   * @returns {string}
+   */
+  parse(input: string, locale: string = this._locale): string {
+    const dict = this._dicts[locale];
+    if (!dict) {
+      Logger.error(`i18n:: No dictionary loaded for current locale: ${this._locale}`);
+      return '';
+    }
+    let str = input;
+    const matches = str.match(/{(.*?)}/g);
+    if (matches) {
+      matches.forEach((match) => {
+        const key = match.slice(1, -1);
+        if (dict[key]) {
+          str = str.replace(match, dict[key]);
+        }
+      });
+    }
+    return str;
+  }
+
+  /**
+   * Loads a locale.
+   * @param localeId The locale id to load.
+   * @returns Promise<void>
+   */
+  async loadLocale(localeId: string) {
+    const file = this._options.files.find((file) => localeId === file.id);
+    if (!file) {
+      Logger.error(`i18n:: Could not find locale file for ${localeId}`);
+      return;
+    }
+    this._dicts[localeId] = file.json
+      ? await Assets.load(file.json)
+      : await getDynamicModuleFromImportListItem(file as ImportListItem<i18nDict>);
+  }
+
+  protected getCoreFunctions(): string[] {
+    return ['t', 'translate', 'setLocale'];
+  }
+
+  protected getCoreSignals(): string[] {
+    return ['onLocaleChanged'];
+  }
+
+  /**
+   * Loads and sets a locale.
+   * If the locale is not loaded, it will load it first.
+   * @param localeId The locale id to load and set.
+   */
+  private async _loadAndSetLocale(localeId: string) {
+    if (!this._dicts[localeId]) {
+      await this.loadLocale(localeId);
+    }
+    this.onLocaleChanged.emit(localeId);
+  }
+}

package/src/plugins/index.ts

@@ -0,0 +1,17 @@
+export * from './actions';
+export * from './AssetsPlugin';
+export * from './breakpoints';
+export * from './DataAdapter';
+export * from './audio';
+export * from './focus';
+export * from './FullScreenPlugin';
+export * from './i18nPlugin';
+export * from './input';
+export * from './KeyboardPlugin';
+export * from './LookupPlugin';
+export * from './Plugin';
+export * from './PopupManagerPlugin';
+export * from './ResizerPlugin';
+export * from './SceneManagerPlugin';
+export * from './TimerPlugin';
+export * from './WebEventsPlugin';

package/src/plugins/input/AbstractControls.ts

@@ -0,0 +1,15 @@
+import type { ControlsActionMap } from '../..';
+import { IApplication } from '../../core';
+import { Application } from '../../core/Application';
+
+export class AbstractControls {
+  protected scheme: any;
+
+  get app(): IApplication {
+    return Application.getInstance();
+  }
+
+  initialize(scheme: Partial<ControlsActionMap>) {
+    this.scheme = scheme;
+  }
+}

package/src/plugins/input/Controls.ts

@@ -0,0 +1,55 @@
+import { IApplication } from '../../core';
+import { Application } from '../../core/Application';
+import { bindAllMethods } from '../../utils';
+import { Action } from '../actions';
+import { IControls, UserControls } from './interfaces';
+import { KeyboardControls } from './keyboard';
+import { TouchControls } from './touch';
+
+export class Controls implements IControls {
+  keyboard: KeyboardControls;
+  touch: TouchControls;
+
+  constructor() {
+    bindAllMethods(this);
+  }
+
+  get app(): IApplication {
+    return Application.getInstance();
+  }
+
+  destroy() {
+    if (this.keyboard) {
+      this.keyboard.destroy();
+    }
+    if (this.touch) {
+      this.touch.destroy();
+    }
+  }
+
+  isActionActive(action: Action): boolean {
+    const isActive = this.keyboard?.isActionActive(action) || this.touch?.isActionActive(action) || false;
+    return isActive;
+  }
+
+  initialize(scheme: UserControls) {
+    if (scheme.keyboard) {
+      this.keyboard = new KeyboardControls();
+      this.keyboard.initialize(scheme.keyboard);
+    }
+
+    if (scheme.touch) {
+      this.touch = new TouchControls();
+      this.touch.initialize(scheme.touch);
+    }
+  }
+
+  public connect() {
+    if (this.keyboard) {
+      this.keyboard.connect();
+    }
+    if (this.touch) {
+      this.touch.connect();
+    }
+  }
+}

package/src/plugins/input/InputPlugin.ts

@@ -0,0 +1,168 @@
+import type { ActionsList, IActionsPlugin } from '../actions';
+import { Action, DefaultActions } from '../actions';
+import { Controls } from './Controls';
+
+import { IApplication } from '../../core';
+import { Signal } from '../../signals';
+import type { IPlugin } from '../Plugin';
+import { Plugin } from '../Plugin';
+import { InputController, InputControllerTypes } from './constants';
+import { UserControls } from './interfaces';
+
+export type InputManagerOptions = {
+  actions?: ActionsList;
+  controls?: UserControls;
+};
+
+export interface IInputPlugin extends IPlugin<InputManagerOptions> {
+  readonly controls: Controls;
+  activeGamepads: Map<string, Gamepad>;
+  activeControllers: Set<string>;
+  options: InputManagerOptions;
+  onGamepadConnected: Signal<(gamepad: Gamepad) => void>;
+  onGamepadDisconnected: Signal<(gamepad: Gamepad) => void>;
+  onControllerActivated: Signal<(controller: string) => void>;
+  onControllerDeactivated: Signal<(controller: string) => void>;
+
+  isControllerActive(controller: InputController): boolean;
+
+  isGamepadActive(gamepad: Gamepad): boolean;
+
+  isActionActive(action: Action): boolean;
+}
+
+const defaultOptions = {
+  actions: DefaultActions,
+};
+
+export class InputPlugin extends Plugin<InputManagerOptions> implements IInputPlugin {
+  public readonly id = 'input';
+
+  // controls
+  public readonly controls = new Controls();
+
+  // properties
+  public activeGamepads = new Map<string, Gamepad>();
+  public activeControllers = new Set<string>([]);
+  // signals
+  public onGamepadConnected: Signal<(gamepad: Gamepad) => void> = new Signal<(gamepad: Gamepad) => void>();
+  public onGamepadDisconnected: Signal<(gamepad: Gamepad) => void> = new Signal<(gamepad: Gamepad) => void>();
+  public onControllerActivated: Signal<(controller: string) => void> = new Signal<(controller: string) => void>();
+  public onControllerDeactivated: Signal<(controller: string) => void> = new Signal<(controller: string) => void>();
+
+  isActionActive(action: Action): boolean {
+    return this.controls.isActionActive(action);
+  }
+
+  async initialize(options: Partial<InputManagerOptions> = defaultOptions, app: IApplication): Promise<void> {
+    this._options = { ...defaultOptions, ...options };
+
+    app.stage.eventMode = 'static';
+    app.stage.on('touchstart', this._onTouchStart);
+    app.stage.on('globalmousemove', this._onMouseMove);
+    window.addEventListener('keydown', this._onKeyDown);
+    window.addEventListener('gamepadconnected', this._onGamepadConnected);
+    window.addEventListener('gamepaddisconnected', this._onGamepadDisconnected);
+
+    if (this._options.controls) {
+      this.controls.initialize(this._options.controls);
+    }
+  }
+
+  public postInitialize(): void {
+    if (this.controls) {
+      this.controls.connect();
+    }
+  }
+
+  destroy(): void {
+    // unregister all event listeners
+    this.app.stage.off('touchstart', this._onTouchStart);
+    this.app.stage.off('globalmousemove', this._onMouseMove);
+    window.removeEventListener('keydown', this._onKeyDown);
+    window.removeEventListener('gamepadconnected', this._onGamepadConnected);
+    window.removeEventListener('gamepaddisconnected', this._onGamepadDisconnected);
+
+    super.destroy();
+  }
+
+  isControllerActive(controller: InputController): boolean {
+    return this.activeControllers.has(controller);
+  }
+
+  isGamepadActive(gamepad: Gamepad): boolean {
+    return this.activeGamepads.has(gamepad.id);
+  }
+
+  protected getCoreSignals(): string[] {
+    return ['onGamepadConnected', 'onGamepadDisconnected', 'onControllerActivated', 'onControllerDeactivated'];
+  }
+
+  private _activateController(inputController: string): void {
+    if (this.activeControllers.has(inputController)) {
+      return;
+    }
+    this.activeControllers.add(inputController);
+    // emit the controller activated signal
+    this.onControllerActivated.emit(inputController);
+  }
+
+  private _deactivateController(inputController: InputController): void {
+    const wasControllerActive = this.activeControllers.has(inputController);
+    if (!wasControllerActive) {
+      return;
+    }
+    this.activeControllers.delete(inputController);
+    // emit the controller deactivated signal
+    this.onControllerDeactivated.emit(inputController);
+  }
+
+  private _activateGamepad(gamepad: Gamepad): void {
+    this.activeGamepads.set(gamepad.id, gamepad);
+  }
+
+  private _deactivateGamepad(gamepadId: string): void {
+    this.activeGamepads.delete(gamepadId);
+  }
+
+  private _onTouchStart(): void {
+    this._activateController(InputControllerTypes.Touch);
+  }
+
+  private _onMouseMove(): void {
+    this._activateController(InputControllerTypes.Mouse);
+  }
+
+  private _onKeyDown(): void {
+    this._activateController(InputControllerTypes.Keyboard);
+  }
+
+  private _onGamepadConnected(event: GamepadEvent): void {
+    this._activateController(InputControllerTypes.GamePad);
+    // add the gamepad id just in case we need it (?)
+    this._activateController(event.gamepad.id);
+    this._activateGamepad(event.gamepad);
+    // emit the gamepad connected signal
+    this.onGamepadConnected.emit(event.gamepad);
+  }
+
+  private _onGamepadDisconnected(event: GamepadEvent): void {
+    // remove the gamepad
+    this._deactivateGamepad(event.gamepad.id);
+
+    // pause the game any time there is a controller disconnect
+    this.actionsPlugin.sendAction('pause');
+
+    // emit the gamepad disconnected signal
+    this.onGamepadDisconnected.emit(event.gamepad);
+
+    // check if all gamepads are disconnected
+    if (this.activeGamepads.size === 0) {
+      this._deactivateController(InputControllerTypes.GamePad);
+    }
+  }
+
+  get actionsPlugin(): IActionsPlugin {
+    return this.app.getPlugin('actions') as IActionsPlugin;
+  }
+}

package/src/plugins/input/constants.ts

@@ -0,0 +1,12 @@
+export enum InputControllerTypes {
+  Keyboard = 'keyboard',
+  GamePad = 'gamepad',
+  Mouse = 'mouse',
+  Touch = 'touch',
+}
+
+export type InputController =
+  | InputControllerTypes.Keyboard
+  | InputControllerTypes.GamePad
+  | InputControllerTypes.Mouse
+  | InputControllerTypes.Touch;

package/src/plugins/input/index.ts

@@ -0,0 +1,9 @@
+export * from './constants';
+export * from './Controls';
+export * from './InputPlugin';
+export * from './interfaces';
+export * from './keyboard';
+export * from './methods';
+export * from './touch';
+export * from './types';
+export * from './utils';