@caperjs/core 0.1.0

package/src/mixins/factory/registry.ts

@@ -0,0 +1,61 @@
+/**
+ * Runtime registry for `this.add.entity(id, props)` lookups.
+ *
+ * The Vite plugin's entity discovery emits a `virtual:caper-entities` module
+ * with static imports by default (`defaultDynamic: false` in
+ * `discoverLocalClassFiles`). The `caper-runtime` virtual module pulls that
+ * list onto `globalThis.Caper.entityList` before the Application starts, so
+ * by the time any scene fires `initialize()` and calls `this.add.entity`,
+ * the list is in place.
+ *
+ * This registry is populated lazily on first lookup — no explicit bootstrap
+ * step needed. Entities declared with `defineEntity({ dynamic: true })` have
+ * an async `module` function and are skipped: the sync factory API can't
+ * wait for them. That's an intentional tradeoff — if a project needs code-
+ * split entities, they use `add.existing(new Foo(...), props)` with a
+ * manual lazy import instead.
+ */
+
+type EntityConstructor = new (props?: unknown) => unknown;
+
+type EntityListItem = {
+  id: string;
+  active?: boolean;
+  module?: EntityConstructor | (() => Promise<unknown>);
+};
+
+let registry: Map<string, EntityConstructor> | null = null;
+
+function ensureRegistry(): Map<string, EntityConstructor> {
+  if (registry) return registry;
+  registry = new Map();
+  const list: EntityListItem[] =
+    (globalThis as unknown as { Caper?: { get?: (key: string) => unknown } }).Caper?.get?.(
+      'entityList',
+    ) as EntityListItem[] | undefined ?? [];
+  for (const item of list) {
+    if (item.active === false) continue;
+    if (typeof item.module === 'function' && item.module.prototype) {
+      registry.set(item.id, item.module as EntityConstructor);
+    }
+    // Dynamic (arrow-function) modules have no prototype — skipped, since
+    // `this.add.entity` is sync and can't await a dynamic import.
+  }
+  return registry;
+}
+
+export function getEntityCtor(id: string): EntityConstructor | undefined {
+  return ensureRegistry().get(id);
+}
+
+export function getRegisteredEntityIds(): string[] {
+  return [...ensureRegistry().keys()];
+}
+
+/**
+ * Reset the registry. Test-only — production code should rely on the lazy
+ * initialization from `globalThis.Caper.entityList`.
+ */
+export function _resetEntityRegistry(): void {
+  registry = null;
+}

package/src/mixins/factory/schema.ts

@@ -0,0 +1,153 @@
+// Import from source files directly (not via the `../../utils` barrel) so
+// the test runtime doesn't transitively pull in display/Container → the
+// Factory mixin chain → const.ts. That cycle is fine for bundled builds
+// but breaks vitest module evaluation when the test imports from here.
+import { omitKeys } from '../../utils/object';
+import {
+  resolveAnchor,
+  resolvePivot,
+  resolvePosition,
+  resolveScale,
+  resolveUnknownKeys,
+} from './utils';
+
+/**
+ * Common prop resolvers the schema helper can apply after constructing an
+ * instance. Each entry corresponds to one of the `resolveXxx` utilities and
+ * reads its inputs from the raw props object — so `'position'` consumes
+ * `{ position, x, y }`, `'scale'` consumes `{ scale, scaleX, scaleY }`,
+ * etc.
+ */
+export type FactoryApply = 'position' | 'scale' | 'pivot' | 'anchor';
+
+/**
+ * Schema describing a single factory method. Owned by the method's entry in
+ * `defaultFactoryMethods`; `buildFactoryMethod` consumes it to produce a
+ * typed `(props?: Props) => Instance` function with the standard
+ * resolve-position / resolve-scale / resolve-pivot / resolve-anchor
+ * post-construct pipeline and an automatic unknown-keys passthrough.
+ *
+ * The point of pushing every method through this shape is to collapse the
+ * copy-paste construction boilerplate in [const.ts](./const.ts): each
+ * method becomes (a) `build` — the bespoke constructor call that may
+ * reshape the props before handing them to Pixi — and (b) a list of which
+ * common resolvers to run. Everything else (unknowns passthrough, optional
+ * props guard, etc.) is centralized.
+ */
+export interface FactorySchema<Props, Instance> {
+  /**
+   * Bespoke construction. Receives the raw Caper-shaped props (possibly
+   * undefined) and returns a new instance. Any reshaping Caper does for DX
+   * — Sprite's `{asset, sheet}` → texture resolution, Text's top-level
+   * style flattening, Container's config/extras split — lives here.
+   */
+  build: (props: Props | undefined) => Instance;
+
+  /**
+   * Which common resolvers to run on the instance after `build` returns.
+   * Defaults to `['position', 'scale', 'pivot']` when omitted — the lowest
+   * common denominator that every display object supports. Classes with an
+   * `anchor` field (Sprite, Text, AnimatedSprite, Spine) opt in to
+   * `'anchor'` explicitly.
+   */
+  applies?: readonly FactoryApply[];
+
+  /**
+   * Keys the `build` callback already consumed — excluded from the
+   * unknown-keys passthrough so Caper doesn't try to set them on the
+   * instance a second time. For example, Sprite's schema excludes `asset`
+   * and `sheet` (consumed by `resolveTexture`), Text's schema excludes
+   * `text`, `roundPixels`, `resolution`, `style`, `anchor`, and `pivot`.
+   */
+  exclude?: readonly string[];
+}
+
+const DEFAULT_APPLIES: readonly FactoryApply[] = ['position', 'scale', 'pivot'];
+
+/**
+ * Keys automatically excluded from the unknown-keys passthrough because
+ * they're either consumed by a resolver listed in `applies` or are a
+ * shorthand alias for one that is. Listed here so individual schemas don't
+ * have to re-declare them.
+ */
+const RESOLVER_KEYS: readonly string[] = [
+  'position',
+  'x',
+  'y',
+  'scale',
+  'scaleX',
+  'scaleY',
+  'pivot',
+  'anchor',
+];
+
+/**
+ * Build a typed factory method from a schema. The return type preserves
+ * the `(props?: Props) => Instance` shape TypeScript uses to drive
+ * autocomplete on `this.add.*({...})` call sites.
+ *
+ * Behavior mirrors the hand-written factory method pattern:
+ *  1. Call `schema.build(props)` to get the instance.
+ *  2. If props were passed, apply each resolver in `schema.applies`
+ *     (position / scale / pivot / anchor).
+ *  3. Forward any remaining keys to `resolveUnknownKeys` for the common
+ *     pass-through surface (`alpha`, `visible`, `label`, `eventMode`, etc.)
+ *     minus any keys the `build` callback already consumed.
+ *
+ * @example
+ * ```ts
+ * sprite: buildFactoryMethod<Partial<SpriteProps>, Sprite>({
+ *   build: (props) => new Sprite(props ? resolveTexture(props) : undefined),
+ *   applies: ['position', 'scale', 'pivot', 'anchor'],
+ *   exclude: ['asset', 'sheet'],
+ * }),
+ * ```
+ */
+export function buildFactoryMethod<Props, Instance>(
+  schema: FactorySchema<Props, Instance>,
+): (props?: Props) => Instance {
+  const applies = schema.applies ?? DEFAULT_APPLIES;
+  const applyPosition = applies.includes('position');
+  const applyScale = applies.includes('scale');
+  const applyPivot = applies.includes('pivot');
+  const applyAnchor = applies.includes('anchor');
+  const excludeKeys = [...RESOLVER_KEYS, ...(schema.exclude ?? [])];
+
+  return (props?: Props): Instance => {
+    const instance = schema.build(props);
+    if (props === undefined || props === null) return instance;
+
+    // Post-construct resolvers. Each reads from the raw props object so the
+    // schema doesn't have to pre-extract them.
+    const rawProps = props as unknown as Record<string, unknown>;
+    if (applyPosition) {
+      resolvePosition(
+        { position: rawProps.position as never, x: rawProps.x as never, y: rawProps.y as never },
+        instance as unknown as object,
+      );
+    }
+    if (applyScale) {
+      resolveScale(
+        {
+          scale: rawProps.scale as never,
+          scaleX: rawProps.scaleX as never,
+          scaleY: rawProps.scaleY as never,
+        },
+        instance as unknown as object,
+      );
+    }
+    if (applyPivot) {
+      resolvePivot(rawProps.pivot as never, instance as unknown as object);
+    }
+    if (applyAnchor) {
+      resolveAnchor(rawProps.anchor as never, instance as unknown as object);
+    }
+
+    // Forward any remaining keys via the passthrough. Excludes the keys
+    // already handled by the resolvers above plus anything the schema's
+    // `build` callback consumed.
+    const rest = omitKeys(excludeKeys, rawProps);
+    resolveUnknownKeys(rest, instance);
+    return instance;
+  };
+}

package/src/mixins/factory/ui-registry.ts

@@ -0,0 +1,54 @@
+/**
+ * Runtime registry for `this.add.ui(id, props)` lookups.
+ *
+ * Mirrors the entity registry pattern exactly. The Vite plugin's UI
+ * discovery emits a `virtual:caper-uis` module with static imports by
+ * default (`defaultDynamic: false`). The `caper-runtime` virtual module
+ * pulls that list onto `globalThis.Caper.uiList` before the Application
+ * starts.
+ *
+ * Populated lazily on first lookup — no explicit bootstrap step needed.
+ */
+
+type UIConstructor = new (props?: unknown) => unknown;
+
+type UIListItem = {
+  id: string;
+  active?: boolean;
+  module?: UIConstructor | (() => Promise<unknown>);
+};
+
+let registry: Map<string, UIConstructor> | null = null;
+
+function ensureRegistry(): Map<string, UIConstructor> {
+  if (registry) return registry;
+  registry = new Map();
+  const list: UIListItem[] =
+    (globalThis as unknown as { Caper?: { get?: (key: string) => unknown } }).Caper?.get?.(
+      'uiList',
+    ) as UIListItem[] | undefined ?? [];
+  for (const item of list) {
+    if (item.active === false) continue;
+    if (typeof item.module === 'function' && item.module.prototype) {
+      registry.set(item.id, item.module as UIConstructor);
+    }
+    // Dynamic (arrow-function) modules have no prototype — skipped, since
+    // `this.add.ui` is sync and can't await a dynamic import.
+  }
+  return registry;
+}
+
+export function getUICtor(id: string): UIConstructor | undefined {
+  return ensureRegistry().get(id);
+}
+
+export function getRegisteredUIIds(): string[] {
+  return [...ensureRegistry().keys()];
+}
+
+/**
+ * Reset the registry. Test-only.
+ */
+export function _resetUIRegistry(): void {
+  registry = null;
+}

package/src/mixins/factory/utils.ts

@@ -0,0 +1,130 @@
+import { Assets, Graphics, Sprite, Spritesheet, Texture } from 'pixi.js';
+import { Logger, PointLike, resolvePointLike } from '../../utils';
+
+import { Application } from '../../core/Application';
+import { PositionProps, ScaleProps, TextureProps } from './props';
+
+let errorTexture: Texture | undefined;
+
+export function resolveUnknownKeys(props: any, entity: any) {
+  for (const key in props) {
+    try {
+      (entity as any)[key] = props[key];
+    } catch (e) {
+      Logger.warn(`Error setting property ${key}`, e);
+    }
+  }
+}
+
+export function getErrorTexture() {
+  if (!errorTexture) {
+    const gfx = new Graphics();
+    gfx.rect(0, 0, 100, 100);
+    gfx.fill({ color: 0xff0000 });
+    gfx.stroke({ color: 0xffffff, width: 1, alignment: 0 });
+    // draw an X across the rectangle
+    gfx.moveTo(0, 0);
+    gfx.lineTo(100, 100);
+    gfx.moveTo(100, 0);
+    gfx.lineTo(0, 100);
+    gfx.stroke({ color: 0xffffff, width: 2, alignment: 0.5 });
+    errorTexture = Application.getInstance().renderer.generateTexture(gfx);
+    gfx.destroy();
+  }
+  return errorTexture;
+}
+
+export function resolveTexture(props?: Partial<TextureProps>): Texture {
+  let texture: Texture | undefined;
+  const asset = props?.asset;
+  const assetAsString = asset as string;
+  const sheet = props?.sheet;
+  if (asset instanceof Texture) {
+    texture = asset;
+  } else if (!sheet || sheet?.length === 0) {
+    if (Assets.cache.has(assetAsString)) {
+      texture = Assets.get(assetAsString)!;
+    } else if (Assets.get(assetAsString)) {
+      texture = Assets.get(assetAsString).texture!;
+    } else {
+      Logger.error('Asset "' + asset + '" not loaded into Pixi cache');
+      texture = getErrorTexture();
+      //throw new Error('Asset "' + asset + '" not loaded into Pixi cache');
+    }
+  } else {
+    if (!Assets.get(sheet)) {
+      // throw new Error('Spritesheet "' + sheet + '" not loaded into Pixi cache');
+      Logger.error('Spritesheet "' + sheet + '" not loaded into Pixi cache');
+      return getErrorTexture();
+    } else {
+      const spriteSheet: Spritesheet = Assets.get(sheet) as Spritesheet;
+      const textures = spriteSheet.textures;
+      if (textures !== undefined) {
+        // eslint-disable-next-line no-prototype-builtins
+        if (textures.hasOwnProperty(assetAsString)) {
+          texture = textures[assetAsString];
+        } else if (spriteSheet.linkedSheets !== undefined && spriteSheet.linkedSheets.length > 0) {
+          for (const linkedSheet of spriteSheet.linkedSheets) {
+            // eslint-disable-next-line no-prototype-builtins
+            if (linkedSheet.textures !== undefined && linkedSheet.textures.hasOwnProperty(assetAsString)) {
+              texture = linkedSheet.textures[assetAsString];
+              break;
+            }
+          }
+          if (texture === undefined) {
+            Logger.error(
+              'Asset "' + asset + '" not found inside spritesheet "' + asset + "' or any of its linked sheets",
+            );
+            texture = getErrorTexture();
+          }
+        } else {
+          Logger.error('Asset "' + asset + '" not found inside spritesheet "' + sheet + "'");
+          texture = getErrorTexture();
+        }
+      } else {
+        Logger.error('Spritesheet "' + sheet + '" loaded but textures arent?!');
+        texture = getErrorTexture();
+      }
+    }
+  }
+  return texture || new Sprite().texture;
+}
+
+export function resolvePosition(props: Partial<PositionProps>, entity: any) {
+  const pos = resolvePointLike(props.position, false, props.x, props.y);
+  entity.x = pos.x;
+  entity.y = pos.y;
+}
+
+export function resolveScale(props: Partial<ScaleProps>, entity: any) {
+  if (!props) {
+    return;
+  }
+  if (props.scale === undefined) {
+    if (props.scaleX === undefined && props.scaleY === undefined) {
+      return;
+    }
+    if (props.scaleX === undefined) {
+      props.scaleX = 1;
+    }
+    if (props.scaleY === undefined) {
+      props.scaleY = 1;
+    }
+  }
+  const scale = resolvePointLike(props.scale, false, props.scaleX, props.scaleY);
+  entity.scale.set(scale.x, scale.y);
+}
+
+export function resolveAnchor(anchor: PointLike | undefined, entity: any) {
+  if (anchor !== undefined) {
+    const anchorPoint = resolvePointLike(anchor);
+    entity.anchor.set(anchorPoint.x, anchorPoint.y);
+  }
+}
+
+export function resolvePivot(pivot: PointLike | undefined, entity: any) {
+  if (pivot !== undefined) {
+    const pivotPoint = resolvePointLike(pivot);
+    entity.pivot.set(pivotPoint.x, pivotPoint.y);
+  }
+}

package/src/mixins/focus.ts

@@ -0,0 +1,124 @@
+import type { DestroyOptions, PointerEvents } from 'pixi.js';
+import { Container, FederatedEvent } from 'pixi.js';
+import type { Constructor, PointLike } from '../utils';
+
+import { Application } from '../core/Application';
+import type { IFocusable } from '../plugins';
+import { Signal } from '../signals';
+
+/**
+ * The Focusable function is a higher-order function that adds focus-related functionality to a given class.
+ *
+ * @param {TBase extends Constructor<Container>} Base - The base class to add focus functionality to.
+ *
+ * @returns {TBase & Constructor<IFocusable>} The modified class with focus functionality.
+ */
+export function Focusable<TBase extends Constructor<Container>>(Base: TBase): TBase & Constructor<IFocusable> {
+  return class extends Base implements IFocusable {
+    _accessibleDiv: HTMLElement;
+    isFocused = false;
+    isKeyDown = false;
+    focusEnabled = true;
+    tabIndex = 0;
+    // pixi accessibility options
+    accessible = false;
+    accessibleType: keyof HTMLElementTagNameMap | undefined = 'button';
+    accessibleTitle = 'Focusable';
+    accessibleHint = 'Press enter to focus';
+    accessiblePointerEvents: PointerEvents = 'auto';
+    accessibleChildren = true;
+    // signals
+    onFocus = new Signal<(focusable: IFocusable) => void>();
+    onFocusIn = new Signal<(focusable: IFocusable) => void>();
+    onFocusOut = new Signal<(focusable: IFocusable) => void>();
+    onBlur = new Signal<(focusable: IFocusable) => void>();
+
+    private _eventsDisabled: boolean = false;
+
+    constructor(...args: any[]) {
+      super(...args);
+      this.eventMode = 'static';
+      this.on('mouseover', this._onMouseOver);
+      this.on('mousedown', this._onMouseDown);
+      this.on('click', this._handleClick);
+      this.on('tap', this._handleClick);
+    }
+
+    get app() {
+      return Application.getInstance();
+    }
+
+    public destroy(options?: DestroyOptions): void {
+      this.off('mouseover', this._onMouseOver);
+      this.off('mousedown', this._onMouseDown);
+      this.off('click', this._handleClick);
+      this.off('tap', this._handleClick);
+      super.destroy(options);
+    }
+
+    public focusIn() {
+      if (this.app.focus.active) {
+        // @ts-expect-error Argument of type { type: string; } is not assignable to parameter of type FederatedPointerEvent
+        this.emit('pointerover', { type: 'pointerover' });
+      }
+    }
+
+    public blur() {
+      if (!this.isKeyDown) {
+        window.removeEventListener('keyup', this._handleKeyUp.bind(this));
+      }
+    }
+
+    public focusOut() {
+      if (!this.isKeyDown) {
+        window.removeEventListener('keyup', this._handleKeyUp.bind(this));
+      }
+      if (this.app.focus.active) {
+        // @ts-expect-error Argument of type { type: string; } is not assignable to parameter of type FederatedPointerEvent
+        this.emit('pointerout', { type: 'pointerout' });
+      }
+    }
+
+    public click() {}
+
+    public getFocusPosition() {
+      return null;
+    }
+
+    public getFocusArea() {
+      return this.getBounds();
+    }
+
+    public getFocusSize(): PointLike | null {
+      return [this.getFocusArea().width, this.getFocusArea().height];
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    protected _onMouseOver(_e: MouseEvent) {
+      this.app.focus.setFocus(this);
+    }
+
+    protected _onMouseDown(e: FederatedEvent) {
+      this._maybeEmit('pointerdown', e);
+    }
+
+    protected _handleClick(e: FederatedEvent) {
+      this._maybeEmit('click', e);
+      this.click();
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    protected _handleKeyUp(_e: KeyboardEvent) {}
+
+    private _maybeEmit(type: string, e: FederatedEvent) {
+      if (this._eventsDisabled || e.type) {
+        return;
+      }
+      this._eventsDisabled = true;
+      this.emit(type, { type });
+      this._eventsDisabled = false;
+    }
+  } as unknown as TBase & Constructor<IFocusable>;
+}
+
+Focusable.INITTED = false;

package/src/mixins/index.ts

@@ -0,0 +1,5 @@
+export * from './signals';
+export * from './animated';
+export * from './focus';
+export * from './interaction';
+export * from './factory';

package/src/mixins/interaction.ts

@@ -0,0 +1,74 @@
+import type { AllFederatedEventMap, DestroyOptions } from 'pixi.js';
+import { Container, FederatedEvent } from 'pixi.js';
+import { Signal } from '../signals';
+
+import { type Constructor } from '../utils';
+
+// gets all the event names from the PIXI event map
+type InteractionEventName = keyof AllFederatedEventMap;
+
+export type InteractionSignal = Signal<(event: FederatedEvent) => void>;
+
+/**
+ * Represents an interactive element.
+ */
+export interface IInteractive {
+  onInteraction: (eventName: InteractionEventName) => InteractionSignal;
+}
+
+/**
+ * Adds interactive functionality to a container.
+ *
+ * @param {Constructor<Container>} Base - The base container class.
+ * @returns {Constructor<IInteractive>} - The extended container class with interactive functionality.
+ */
+export function Interactive<TBase extends Constructor<Container>>(Base: TBase): TBase & Constructor<IInteractive> {
+  return class extends Base implements IInteractive {
+    private _signals: Map<InteractionEventName, InteractionSignal> = new Map();
+
+    constructor(...args: any[]) {
+      super(...args);
+      this._emitSignal = this._emitSignal.bind(this);
+      this.eventMode = 'static';
+    }
+
+    /**
+     * Handles interaction events and returns the corresponding signal.
+     *
+     * @param {InteractionEventName} eventName - The name of the interaction event.
+     * @return {InteractionSignal} The signal associated with the interaction event.
+     */
+    public onInteraction(eventName: InteractionEventName) {
+      if (!this._signals.has(eventName)) {
+        const signal = new Signal<(event: FederatedEvent) => void>();
+        this._signals.set(eventName, signal);
+        this.on(eventName, this._emitSignal);
+      }
+      return this._signals.get(eventName) as InteractionSignal;
+    }
+
+    public destroy(options: DestroyOptions): void {
+      for (const eventName of this._signals.keys()) {
+        this.off(eventName, this._emitSignal);
+      }
+      this._signals.clear();
+      super.destroy(options);
+    }
+
+    /**
+     * Emits a signal with the given event.
+     *
+     * @param {FederatedEvent} event - The event to emit.
+     *
+     * @return {void}
+     */
+    private _emitSignal(event: FederatedEvent) {
+      const signalName = event.type as InteractionEventName;
+      const signal = this._signals.get(signalName);
+
+      if (signal) {
+        signal.emit(event);
+      }
+    }
+  } as unknown as TBase & Constructor<IInteractive>;
+}

package/src/mixins/signals.ts

@@ -0,0 +1,49 @@
+import { DestroyOptions } from 'pixi.js';
+import { SignalConnection, SignalConnections } from '../signals';
+import type { Constructor } from '../utils';
+
+/**
+ * Interface for animated entities.
+ */
+export interface ISignalContainer {
+  signalConnections: SignalConnections;
+
+  destroy(options?: DestroyOptions): void;
+
+  addSignalConnection(...args: SignalConnection[]): void;
+  connectSignal(...args: SignalConnection[]): void;
+  connectAction(...args: SignalConnection[]): void;
+}
+
+export function WithSignals<TBase extends Constructor<any>>(Base: TBase): TBase & Constructor<ISignalContainer> {
+  return class extends Base implements ISignalContainer {
+    signalConnections: SignalConnections = new SignalConnections();
+
+    /**
+     * Add signal connections to the container.
+     * @param args - The signal connections to add.
+     */
+    public addSignalConnection(...args: SignalConnection[]) {
+      for (const connection of args) {
+        this.signalConnections.add(connection);
+      }
+    }
+
+    public connectSignal(...args: SignalConnection[]) {
+      for (const connection of args) {
+        this.signalConnections.add(connection);
+      }
+    }
+
+    public connectAction(...args: SignalConnection[]) {
+      for (const connection of args) {
+        this.signalConnections.add(connection);
+      }
+    }
+
+    destroy(options?: DestroyOptions): void {
+      this.signalConnections.disconnectAll();
+      super.destroy(options);
+    }
+  } as unknown as TBase & Constructor<ISignalContainer>;
+}