@caperjs/core 0.1.0

package/src/core/interfaces/ICoreFunctions.ts

@@ -0,0 +1,86 @@
+import type { Container as PIXIContainer } from 'pixi.js';
+import type { IScene } from '../../display';
+import type {
+  ActionMap,
+  ActionSignal,
+  i18nTParams,
+  IFocusable,
+  IFocusLayer,
+  KeySignal,
+  LoadSceneConfig,
+} from '../../plugins';
+import { InputController } from '../../plugins';
+import type { IPopup } from '../../ui';
+
+import {
+  type AppTypeOverrides,
+  type PopupId,
+  type PopupInstance,
+  type PopupProps,
+  type SceneId,
+  type SceneLoadArgs,
+} from '../../utils';
+
+type AppContexts = AppTypeOverrides['Contexts'];
+type AppActions = AppTypeOverrides['Actions'];
+type AppScenes = AppTypeOverrides['Scenes'];
+
+export interface ICoreFunctions {
+  // FocusManagerPlugin
+  addFocusable(
+    focusable: IFocusable | IFocusable[],
+    layerId?: string | number | null | undefined,
+    isDefault?: boolean,
+  ): void;
+  removeFocusable(focusable: IFocusable | IFocusable[]): void;
+  setLayerOrder(layerIds: (string | number)[]): void;
+  addFocusLayer(layerId?: string | number, setAsCurrent?: boolean, focusables?: IFocusable | IFocusable[]): IFocusLayer;
+  removeFocusLayer(layerId?: string | number, removeTopLayerIfUndefined?: boolean): void;
+  setFocus(focusable: IFocusable): IFocusable;
+  setFocusLayer(layerId: string | number): void;
+  clearFocus(): void;
+  removeAllFocusLayers(): void;
+
+  // i18nPlugin
+  setLocale(localeId: string): void;
+  t(key: string, params?: i18nTParams, locale?: string): string;
+  translate(key: string, params?: i18nTParams, locale?: string): string;
+  // InputPlugin
+  isControllerActive(controller: InputController): boolean;
+  isGamepadActive(gamepad: Gamepad): boolean;
+
+  // ActionsPlugin;
+  getAction<T = any>(action: AppActions): ActionSignal<T>;
+  getActions(): ActionMap;
+  sendAction<T = any>(actionId: AppActions, data?: T): void;
+  setActionContext(context: AppContexts): string; // in Application.ts
+  actions<T = any>(action: AppActions): ActionSignal<T>; // in Application.ts
+
+  // KeyboardPlugin
+  onKeyDown(key?: string): KeySignal;
+  onKeyUp(key?: string): KeySignal;
+  isKeyDown(key: string): boolean;
+
+  // PopupManagerPlugin
+  showPopup<K extends PopupId>(id: K, config?: PopupProps<K>): Promise<PopupInstance<K> | undefined>;
+  hidePopup<T = any>(id: string | number, data?: T): Promise<IPopup<T> | undefined>;
+  removeAllPopups(animate?: boolean): void;
+
+  // SceneManagerPlugin
+  loadScene<K extends SceneId>(id: K, ...args: SceneLoadArgs<K>): Promise<void>;
+  loadScene(sceneIdOrLoadSceneConfig: LoadSceneConfig | AppScenes): Promise<void>;
+
+  // AssetsPlugin
+  loadAssets(assets: string | string[]): Promise<void>;
+  loadBundles(bundle: string | string[]): Promise<void>;
+  loadSceneAssets(scene: IScene, background?: boolean): Promise<void>;
+  unloadSceneAssets(scene: IScene): Promise<void>;
+  loadRequired(): Promise<void>;
+
+  // LookupPlugin
+  getChildAtPath(path: string): PIXIContainer | undefined;
+  getChildrenAtPaths(paths: string[]): PIXIContainer[];
+  getPathForChild(container: PIXIContainer): string;
+  getPathsForChildren(containers: PIXIContainer[]): string[];
+  getAllPaths(): string[];
+}

package/src/core/interfaces/ICoreSignals.ts

@@ -0,0 +1,77 @@
+import type {
+  BreakpointChangeDetail,
+  ChannelMutedDetail,
+  ChannelVolumeDetail,
+  FocusChangeDetail,
+  IAudioInstance,
+  KeyboardEventDetail,
+  PopupSignalDetail,
+  SoundDetail,
+} from '../../plugins';
+import { ActionContext } from '../../plugins';
+import { Signal } from '../../signals';
+import type { DataChangeSignalDetail } from '../../plugins/DataAdapter';
+import type { Orientation, Size } from '../../utils';
+
+export interface ICoreSignals {
+  // Application;
+  onResize: Signal<(size: Size) => void>;
+  // AudioManager;
+  onSoundStarted: Signal<(detail: SoundDetail) => void>;
+  onSoundEnded: Signal<(detail: SoundDetail) => void>;
+  onMuted: Signal<(muted: boolean) => void>;
+  onMasterVolumeChanged: Signal<(volume: number) => void>;
+  onChannelVolumeChanged: Signal<(detail: ChannelVolumeDetail) => void>;
+  onChannelMuted: Signal<(detail: ChannelMutedDetail) => void>;
+  // VoiceOverPlugin;
+  onVoiceOverStart: Signal<(instance: IAudioInstance) => void>;
+  onVoiceOverPaused: Signal<(instance: IAudioInstance) => void>;
+  onVoiceOverComplete: Signal<(instance: IAudioInstance) => void>;
+  onVoiceOverResumed: Signal<(instance: IAudioInstance) => void>;
+  onVoiceOverStopped: Signal<(instance?: IAudioInstance) => void>;
+  // FocusManager;
+  onFocusManagerActivated: Signal<() => void>;
+  onFocusManagerDeactivated: Signal<() => void>;
+  onFocusLayerChange: Signal<(currentLayerId: string | number) => void>;
+  onFocusChange: Signal<(detail: FocusChangeDetail) => void>;
+  // i18nPlugin;
+  onLocaleChanged: Signal<(locale: string) => void>;
+  // actionsPlugin;
+  onActionContextChanged: Signal<(context: string | ActionContext) => void>;
+  // InputManager;
+  onGamepadConnected: Signal<(gamepad: Gamepad) => void>;
+  onGamepadDisconnected: Signal<(gamepad: Gamepad) => void>;
+  onControllerActivated: Signal<(controller: string) => void>;
+  onControllerDeactivated: Signal<(controller: string) => void>;
+  // KeyboardManager;
+  onGlobalKeyDown: Signal<(detail: KeyboardEventDetail) => void>;
+  onGlobalKeyUp: Signal<(detail: KeyboardEventDetail) => void>;
+  // PopupManager;
+  onShowPopup: Signal<(detail: PopupSignalDetail) => void>;
+  onHidePopup: Signal<(detail: PopupSignalDetail) => void>;
+  onPopupChanged: Signal<(detail: PopupSignalDetail) => void>;
+  // SceneManager;
+  onSceneChangeStart: Signal<(detail: { exiting: string | null; entering: string }) => void>;
+  onSceneChangeComplete: Signal<(detail: { current: string }) => void>;
+  // WebEventsManager;
+  onOrientationChanged: Signal<
+    ({ orientation, screenOrientation }: { orientation: Orientation; screenOrientation: ScreenOrientation }) => void
+  >;
+  onVisibilityChanged: Signal<(visible: boolean) => void>;
+  // AssetPlugin
+  onLoadProgress: Signal<(progress: number) => void>;
+  onLoadComplete: Signal<() => void>;
+  onError: Signal<(error: Error) => void>;
+
+  onBackgroundLoadStart: Signal<() => void>;
+  onBackgroundAssetsLoaded: Signal<(assets: string[]) => void>;
+  onBackgroundBundlesLoaded: Signal<(bundles: string[]) => void>;
+
+  onLoadRequiredStart: Signal<() => void>;
+  onLoadRequiredProgress: Signal<(progress: number) => void>;
+  onLoadRequiredComplete: Signal<() => void>;
+  // DataAdapter;
+  onDataChange: Signal<(detail: DataChangeSignalDetail) => void>;
+  // BreakpointPlugin;
+  onBreakpointChanged: Signal<(detail: BreakpointChangeDetail) => void>;
+}

package/src/core/interfaces/IStorageCapability.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { isStorageCapable } from './IStorageCapability';
+
+describe('isStorageCapable', () => {
+  it('accepts objects with save + load functions', () => {
+    expect(isStorageCapable({ save() {}, load() {} })).toBe(true);
+  });
+
+  it('rejects objects missing save', () => {
+    expect(isStorageCapable({ load() {} })).toBe(false);
+  });
+
+  it('rejects objects missing load', () => {
+    expect(isStorageCapable({ save() {} })).toBe(false);
+  });
+
+  it('rejects non-function save/load', () => {
+    expect(isStorageCapable({ save: true, load: true })).toBe(false);
+  });
+
+  it('rejects null / undefined / primitives', () => {
+    expect(isStorageCapable(null)).toBe(false);
+    expect(isStorageCapable(undefined)).toBe(false);
+    expect(isStorageCapable('x')).toBe(false);
+    expect(isStorageCapable(42)).toBe(false);
+  });
+});

package/src/core/interfaces/IStorageCapability.ts

@@ -0,0 +1,26 @@
+/**
+ * Marker interface for plugins that can act as a key/value store.
+ *
+ * Any plugin whose instance has `save` and `load` methods is considered
+ * storage-capable and will be reachable via `app.store.getAdapter(id)` /
+ * `app.store.save(id, ...)` / `app.store.load(id, ...)`.
+ *
+ * Implementations are free to interpret `key` and the variadic tail however
+ * they like — e.g. Firebase treats `key` as a collection name.
+ */
+export interface IStorageCapability<TSaveResult = any, TLoadResult = any> {
+  save(key: string, data: any, ...rest: any[]): Promise<TSaveResult> | TSaveResult;
+  load(key: string, ...rest: any[]): Promise<TLoadResult | undefined> | TLoadResult | undefined;
+}
+
+/**
+ * Duck-typed guard. No base class, no inheritance — any plugin that defines
+ * `save` and `load` qualifies.
+ */
+export function isStorageCapable(plugin: unknown): plugin is IStorageCapability {
+  return (
+    !!plugin &&
+    typeof (plugin as IStorageCapability).save === 'function' &&
+    typeof (plugin as IStorageCapability).load === 'function'
+  );
+}

package/src/core/interfaces/index.ts

@@ -0,0 +1,6 @@
+export type { ICoreFunctions } from './ICoreFunctions';
+export type { ICoreSignals } from './ICoreSignals';
+export type { IApplicationOptions } from './IApplicationOptions';
+export type { IApplication } from './IApplication';
+export { isStorageCapable } from './IStorageCapability';
+export type { IStorageCapability } from './IStorageCapability';

package/src/core/registries.ts

@@ -0,0 +1,7 @@
+import type { ICoreFunctions, ICoreSignals } from './interfaces';
+
+// @ts-expect-error - we don't know what the keys are, so we can't type them
+export const coreSignalRegistry: { [K in keyof ICoreSignals]: ICoreSignals[K] } = {};
+
+// @ts-expect-error - we don't know what the keys are, so we can't type them
+export const coreFunctionRegistry: { [K in keyof ICoreFunctions]: ICoreFunctions[K] } = {};

package/src/core/types.ts

@@ -0,0 +1,13 @@
+import type { WithRequiredProps } from '../utils';
+import { IApplicationOptions } from './interfaces';
+
+export type AppConfig = WithRequiredProps<IApplicationOptions, 'id'>;
+
+export type PauseConfig = {
+  pauseAudio?: boolean;
+  pauseAnimations?: boolean;
+  pauseTimers?: boolean;
+  pauseTicker?: boolean;
+  pauseOther?: any[];
+  clearOnResume?: boolean;
+};

package/src/display/AnimatedSprite.ts

@@ -0,0 +1,227 @@
+import { AnimatedSprite as PIXIAnimatedSprite, Texture, Ticker } from 'pixi.js';
+import { AnimatedSpriteProps, resolveTexture } from '../mixins';
+import { Signal } from '../signals';
+import {
+  bindAllMethods,
+  getFirstMapEntry,
+  getLastMapEntry,
+  getNextMapEntry,
+  getPreviousMapEntry,
+  getZeroPaddedNumber,
+  type SpritesheetAsset,
+} from '../utils';
+
+export class AnimatedSprite extends PIXIAnimatedSprite {
+  onAnimationChange: Signal<(currentAnimation: string) => void> = new Signal();
+  onAnimationStart: Signal<() => void> = new Signal();
+  onAnimationStop: Signal<() => void> = new Signal();
+  onAnimationLoop: Signal<() => void> = new Signal();
+  onAnimationComplete: Signal<() => void> = new Signal();
+  onAnimationFrameChange: Signal<() => void> = new Signal();
+  public defaultTexturePrefix: string = '';
+  public defaultSheet: string | undefined;
+  public defaultAnimation: string;
+  public defaultAnimationSpeed: number;
+  public defaultZeroPad: number | undefined;
+  public autoPlay: boolean;
+  public currentAnimation: string;
+  protected _animations: Map<string, Texture[]>;
+
+  constructor(protected config?: Partial<AnimatedSpriteProps>) {
+    // get default animation
+    const animations = config?.animations ?? {};
+    const defaultAnimationName = config?.animation ?? Object.keys(animations)[0];
+    const defaultAnimation = animations[defaultAnimationName as string];
+    const defaultSheet = config?.sheet;
+    const defaultTexturePrefix = config?.texturePrefix || '';
+    const defaultZeroPad = config?.zeroPad;
+    const defaultStartIndex = config?.startIndex ?? 0;
+
+    super(
+      AnimatedSprite.generateTexturesFromProps(
+        defaultAnimationName,
+        defaultAnimation,
+        defaultTexturePrefix,
+        defaultSheet,
+        defaultZeroPad,
+        defaultStartIndex,
+      ),
+      config?.autoUpdate !== false,
+    );
+    bindAllMethods(this);
+    this.defaultSheet = defaultSheet;
+    this.defaultTexturePrefix = defaultTexturePrefix;
+    this.defaultZeroPad = defaultZeroPad;
+    this._generateAnimations();
+    this.currentAnimation = this.defaultAnimation = defaultAnimationName;
+    this.autoPlay = config?.autoPlay ?? true;
+    this.loop = config?.loop ?? true;
+    this.updateAnchor = config?.updateAnchor ?? false;
+    this.animationSpeed = this.defaultAnimationSpeed = config?.animationSpeed ?? 1;
+    this.on('added', this._added);
+  }
+
+  protected _paused: boolean = false;
+
+  get paused(): boolean {
+    return this._paused;
+  }
+
+  set paused(value: boolean) {
+    this._paused = value;
+  }
+
+  get speed(): number {
+    return this.animationSpeed;
+  }
+
+  set speed(value: number) {
+    this.animationSpeed = this.defaultAnimationSpeed = value;
+  }
+
+  protected _isReversed: boolean = false;
+
+  get isReversed(): boolean {
+    return this._isReversed;
+  }
+
+  static generateTexturesFromProps(
+    animationName: string,
+    props?: Partial<AnimatedSpriteProps>,
+    defaultTexturePrefix = '',
+    defaultSheet: SpritesheetAsset | undefined = undefined,
+    defaultZeroPad?: number,
+    defaultStartIndex?: number,
+  ): Texture[] {
+    const textures: Texture[] = [];
+    let asset = '';
+    const sheet = props?.sheet ?? defaultSheet;
+    if (props?.numFrames > 1) {
+      const idx = props?.startIndex ?? defaultStartIndex ?? 0;
+      for (let i = idx; i < idx + props?.numFrames; i++) {
+        asset = `${defaultTexturePrefix}${props?.texturePrefix ?? animationName}${getZeroPaddedNumber(i, props?.zeroPad ?? defaultZeroPad)}`;
+        textures.push(
+          resolveTexture({
+            asset,
+            sheet,
+          }),
+        );
+      }
+    } else {
+      asset = `${defaultTexturePrefix}${props?.texturePrefix ?? animationName}`;
+      textures.push(
+        resolveTexture({
+          asset,
+          sheet,
+        }),
+      );
+    }
+    return textures;
+  }
+
+  reverse() {
+    this._isReversed = !this._isReversed;
+    if (this._isReversed) {
+      this.setAnimation(`${this.currentAnimation}_reverse`);
+    } else {
+      this.setAnimation(this.currentAnimation.split('_reverse')[0]);
+    }
+  }
+
+  setAnimation(animationName: string, autoPlay: boolean = true) {
+    if (!this._animations.has(animationName)) {
+      throw new Error(`Animation ${animationName} does not exist`);
+    }
+    this.textures = this._animations.get(animationName) as Texture[];
+    this.currentAnimation = animationName;
+    const animSpeed = this.config?.animations?.[animationName.split('_reverse')[0]]?.animationSpeed;
+    if (animSpeed) {
+      this.animationSpeed = animSpeed;
+    } else {
+      this.animationSpeed = this.defaultAnimationSpeed;
+    }
+    this.onAnimationChange.emit(animationName);
+    if (autoPlay) {
+      this.play();
+    }
+  }
+
+  play() {
+    super.play();
+    this.onAnimationStart?.emit();
+  }
+
+  stop() {
+    super.stop();
+    this.onAnimationStop?.emit();
+  }
+
+  nextAnimation() {
+    const entry = getNextMapEntry(this._animations, this.currentAnimation) ?? getFirstMapEntry(this._animations);
+    if (entry) {
+      this.setAnimation(entry[0]);
+    }
+  }
+
+  previousAnimation() {
+    const entry = getPreviousMapEntry(this._animations, this.currentAnimation) ?? getLastMapEntry(this._animations);
+    if (entry) {
+      this.setAnimation(entry[0]);
+    }
+  }
+
+  update(ticker: Ticker) {
+    if (this._paused) {
+      return;
+    }
+    super.update(ticker);
+  }
+
+  private _generateAnimations() {
+    this._animations = new Map();
+    const animations = this.config?.animations ?? {};
+    if (animations) {
+      for (const [key, value] of Object.entries(animations)) {
+        this._animations.set(
+          key,
+          AnimatedSprite.generateTexturesFromProps(
+            key,
+            value,
+            this.defaultTexturePrefix,
+            this.defaultSheet,
+            this.defaultZeroPad,
+          ),
+        );
+      }
+      if (this.config?.reversible) {
+        for (const [key, value] of Object.entries(animations)) {
+          const textures = AnimatedSprite.generateTexturesFromProps(
+            key,
+            value,
+            this.defaultTexturePrefix,
+            this.defaultSheet,
+            this.defaultZeroPad,
+          );
+          textures.reverse();
+          this._animations.set(`${key}_reverse`, textures);
+        }
+      }
+    }
+  }
+
+  private _added() {
+    this.onLoop = () => {
+      this.onAnimationLoop.emit();
+    };
+    this.onComplete = () => {
+      this.onAnimationComplete.emit();
+    };
+    this.onFrameChange = () => {
+      this.onAnimationFrameChange.emit();
+    };
+
+    if (this.autoPlay) {
+      this.play();
+    }
+  }
+}