@caperjs/core 0.1.0

package/src/display/ParticleContainer.ts

@@ -0,0 +1,107 @@
+import { DestroyOptions, ParticleContainerOptions, ParticleContainer as PIXIParticleContainer, Ticker } from 'pixi.js';
+
+import { Application } from '../core/Application';
+import { Signal } from '../signals';
+import type { AppTypeOverrides, Size } from '../utils';
+import { bindAllMethods } from '../utils';
+
+/**
+ * Configuration for the Container class.
+ */
+export interface ParticleContainerConfig extends ParticleContainerOptions {
+  autoUpdate: boolean;
+  priority: number;
+}
+
+export const ParticleContainerConfigKeys: (keyof ParticleContainerConfig)[] = ['autoUpdate', 'priority'];
+
+const defaultConfig: ParticleContainerConfig = { autoUpdate: true, priority: 0 };
+
+export interface IParticleContainer {
+  app: AppTypeOverrides['App'];
+
+  onDestroy: Signal<() => void>;
+
+  destroy(options?: DestroyOptions): void;
+
+  added(): Promise<void> | void;
+
+  update(ticker?: Ticker | number): void;
+}
+
+/**
+ * The Container class extends the _Container class (which includes the Animated and Factory mixins) and implements the IContainer interface.
+ * It represents a container for PIXI.js display objects.
+ */
+export class ParticleContainer extends PIXIParticleContainer implements IParticleContainer {
+  onDestroy: Signal<() => void> = new Signal();
+  __caper_method_binding_root = true;
+  private __config: ParticleContainerConfig;
+
+  /**
+   * The constructor for the Container class.
+   * @param config - The configuration for the container.
+   */
+  constructor(config: Partial<ParticleContainerConfig> = {}) {
+    super(config);
+    this.__config = { ...defaultConfig, ...config };
+    // Bind all methods of this class to the current instance.
+    bindAllMethods(this);
+    // Add an event listener for the 'added' event.
+    this.on('added', this._added);
+    this.on('removed', this._removed);
+  }
+
+  /**
+   * Get the application instance.
+   */
+  public get app(): AppTypeOverrides['App'] {
+    return Application.getInstance() as AppTypeOverrides['App'];
+  }
+  /**
+   * Update the container. This method is meant to be overridden by subclasses.
+   * @param ticker
+   */
+  public update(ticker?: Ticker | number) {
+    void ticker;
+  }
+
+  /**
+   * Resize the container. This method is meant to be overridden by subclasses.
+   * @param size
+   */
+  public resize(size?: Size) {
+    void size;
+  }
+
+  /**
+   * This method is called when the container is added to the stage. It is meant to be overridden by subclasses.
+   */
+  public added() {}
+
+  destroy(options?: DestroyOptions): void {
+    if (this.__config.autoUpdate) {
+      this.app.ticker.remove(this.update, this);
+    }
+    this.onDestroy.emit();
+    super.destroy(options);
+  }
+
+  public removed() {}
+  /**
+   * This method is called when the container is added to the stage. It sets up auto-resizing and auto-updating if enabled.
+   */
+  private _added() {
+    if (this.__config.autoUpdate) {
+      this.app.ticker.add(this.update, this, this.__config.priority);
+    }
+    this.added();
+  }
+
+  private _removed() {
+    if (this.__config.autoUpdate) {
+      this.app.ticker.remove(this.update, this);
+    }
+    this.removed();
+  }
+}

package/src/display/Scene.ts

@@ -0,0 +1,305 @@
+import { Ticker } from 'pixi.js';
+import { PauseConfig } from '../core';
+import { type AppTypeOverrides, type AssetTypeOverrides, Size } from '../utils';
+import type { IContainer } from './Container';
+import { Container } from './Container';
+
+type AppScenes = AppTypeOverrides['Scenes'];
+
+type SceneAssetsToLoad = {
+  assets?: (string | { alias: string; src: string | string[] })[];
+  bundles?: AssetTypeOverrides['Bundles'] | AssetTypeOverrides['Bundles'][];
+};
+
+export type SceneAssets = {
+  preload?: SceneAssetsToLoad;
+  background?: SceneAssetsToLoad;
+  autoUnload?: boolean;
+};
+
+export type ScenePlugins = AppTypeOverrides['Plugins'][];
+
+export type SceneDebug = {
+  label?: string;
+  group?: string;
+  order?: number;
+};
+
+export type SceneConfig = {
+  id?: string;
+  dynamic?: boolean;
+  active?: boolean;
+  assets?: SceneAssets;
+  plugins?: ScenePlugins;
+  debug?: SceneDebug;
+};
+
+export interface IScene extends IContainer {
+  id: AppScenes;
+  label?: string;
+  assets?: SceneAssets;
+  autoUnloadAssets?: boolean;
+
+  enter(): Promise<any>;
+
+  exit(): Promise<any>;
+
+  initialize(): Promise<void> | void;
+
+  start(): Promise<void> | void;
+
+  onPause(config: PauseConfig): void;
+
+  onResume(config: PauseConfig): void;
+}
+
+export interface SceneListItem {
+  id: string;
+  path: string;
+  scene: () => Promise<new () => IScene> | IScene;
+  debug?: {
+    label?: string;
+    group?: string;
+  };
+  assets?: SceneAssets;
+  plugins?: ScenePlugins;
+  autoUnloadAssets: boolean;
+}
+
+/**
+ * Base class for all scenes in a Caper app. A scene is a self-contained
+ * unit of game state and display — start screen, level, menu, etc.
+ *
+ * **Lifecycle order** (per scene load):
+ *
+ *   1. `constructor` — instantiated by the SceneManager. Don't reference
+ *      `this.app` here; it's not yet attached to the stage.
+ *   2. **Assets load** — anything declared in `assets.preload.bundles` is
+ *      fetched before `initialize` runs. Background bundles are kicked
+ *      off in parallel and may complete after.
+ *   3. `initialize()` — build the display tree. The scene is on the stage
+ *      but not yet animated in. Safe to use `this.app`, `this.add.*`,
+ *      and any preloaded asset.
+ *   4. `enter()` — animate the scene in. Override to return a promise /
+ *      tween / timeline; the manager awaits it before calling `start`.
+ *   5. `start()` — fired after `enter` resolves. Begin per-frame work,
+ *      timers, signal connections, gameplay loops.
+ *   6. `update(ticker)` — called every frame while the scene is active.
+ *      Read `ticker.deltaMS` for frame timing.
+ *   7. `resize(size)` — called on viewport resize. Re-layout here.
+ *   8. `onPause(config)` / `onResume(config)` — called when the app pauses
+ *      or resumes. Use to halt/restart non-display work (audio, network).
+ *   9. `exit()` — animate the scene out. Awaited before `destroy`.
+ *  10. `destroy()` — tear down. The base implementation removes the
+ *      ticker callback and destroys all children — call `super.destroy()`.
+ *
+ * Scenes are **discovered automatically** by the Vite plugin walking
+ * `src/scenes/`. Annotate the file with `defineScene({ id, assets })`
+ * (or individual `export const id` / `export const assets`) to give the
+ * scene a stable id and declare its asset bundles.
+ *
+ * @example
+ * ```ts
+ * import { defineScene, Scene } from '@caperjs/core';
+ *
+ * export const scene = defineScene({
+ *   id: 'menu',
+ *   assets: { preload: { bundles: ['ui'] } },
+ * });
+ *
+ * export default class MenuScene extends Scene {
+ *   initialize() {
+ *     this.add.text({ text: 'Play', anchor: 0.5 });
+ *   }
+ *   start() {
+ *     // begin gameplay loop
+ *   }
+ *   destroy() {
+ *     super.destroy();
+ *   }
+ * }
+ * ```
+ */
+export class Scene<Props = void> extends Container implements IScene {
+  public readonly id: string;
+  public autoUnloadAssets: boolean = false;
+
+  /**
+   * Runtime props passed via `app.scenes.load(id, props)`. Populated by
+   * `SceneManagerPlugin._createCurrentScene` after construction and before
+   * `initialize()` runs, so scene authors can read them safely from any
+   * lifecycle hook.
+   *
+   * Subclasses declare the shape via the generic parameter:
+   *
+   * @example
+   * ```ts
+   * class LevelScene extends Scene<{ levelId: number; difficulty: 'easy' | 'hard' }> {
+   *   async start() {
+   *     const { levelId } = this.props;
+   *   }
+   * }
+   * ```
+   *
+   * For scenes that don't need props, use the default `Scene<void>` (no
+   * generic parameter) — `app.scenes.load('menu')` takes no second arg.
+   */
+  public props!: Props;
+
+  protected _animationContext: string;
+  public get animationContext(): string {
+    return this._animationContext ?? `__scene_${this.id}`;
+  }
+  public set animationContext(value: string) {
+    this._animationContext = value;
+  }
+
+  constructor() {
+    super({ autoResize: true, autoUpdate: true, priority: 'highest' });
+  }
+
+  /**
+   * The assets to load for the scene
+   * @private
+   * @type {AssetLoadingOptions}
+   * @example
+   * ```ts
+   * assets: {
+   *  preload: {
+   *  assets: ['path/to/asset.png'],
+   *  bundles: ['bundle1', 'bundle2'],
+   *  },
+   *  background: {
+   *   assets: ['path/to/asset.png'],
+   *   bundles: ['bundle1', 'bundle2'],
+   *   },
+   * }
+   * ```
+   */
+  private _assets: SceneAssets;
+
+  get assets(): SceneAssets {
+    return this._assets;
+  }
+
+  set assets(value: SceneAssets) {
+    this._assets = value;
+  }
+
+  /**
+   * Build the scene's display tree. Called once after preload assets
+   * have loaded and the scene has been added to the stage, but **before**
+   * `enter()` animates it in. Safe to use `this.app`, `this.add.*`, and
+   * any asset declared in `assets.preload`.
+   *
+   * Override to construct sprites, text, containers, layouts. Don't put
+   * gameplay loops here — that's `start()`.
+   *
+   * Can be sync or async; the manager awaits the return value before
+   * calling `enter`.
+   */
+  public initialize(): Promise<void> | void;
+
+  public async initialize(): Promise<void> {}
+
+  /**
+   * Animate the scene in. Called after `initialize()` resolves. The
+   * manager awaits the returned promise before calling `start()`, so
+   * return a tween / timeline / promise to gate the entry on it.
+   *
+   * Default implementation resolves immediately (no animation).
+   *
+   * @returns A promise that resolves when the entry animation completes.
+   */
+  public enter(): Promise<any> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Animate the scene out. Called when the SceneManager is unloading
+   * this scene. Awaited before `destroy()` runs.
+   *
+   * Default implementation resolves immediately (no animation).
+   *
+   * @returns A promise that resolves when the exit animation completes.
+   */
+  public exit(): Promise<any> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Begin per-frame work. Called once after `enter()` resolves; this is
+   * where gameplay loops, timers, signal connections, and any work that
+   * shouldn't start until the scene is fully visible should live.
+   *
+   * Override to start tickers, subscribe to input, kick off gameplay.
+   * Don't build the display tree here — that's `initialize()`.
+   *
+   * Can be sync or async.
+   */
+  public start(): Promise<void> | void;
+
+  public async start(): Promise<void> {}
+
+  /**
+   * Per-frame update hook. Called every tick while the scene is active,
+   * after `start()` has resolved. Use `ticker.deltaMS` for time-based
+   * motion that's framerate-independent.
+   *
+   * The base implementation is a no-op; override to drive game logic.
+   * The base `destroy()` removes this from the ticker — call
+   * `super.destroy()` if you override destroy.
+   *
+   * @param ticker The Pixi ticker; provides `deltaMS`, `deltaTime`, etc.
+   */
+  public update(ticker?: Ticker) {
+    void ticker;
+  }
+
+  /**
+   * Re-layout on viewport resize. Called whenever the host element /
+   * window size changes. Use to reposition or rescale display elements
+   * relative to the new viewport size.
+   *
+   * @param size New viewport dimensions.
+   * @override
+   */
+  public resize(size?: Size): void {
+    void size;
+  }
+
+  /**
+   * Tear down the scene. The base implementation removes this scene
+   * from the ticker (so `update` stops firing) and destroys all child
+   * display objects. **Always call `super.destroy()`** if you override
+   * — otherwise the ticker callback leaks.
+   *
+   * Override to clean up listeners, signal connections, timers, network
+   * subscriptions, or anything else not handled by Pixi's destroy.
+   */
+  public destroy() {
+    this.app.ticker.remove(this.update);
+    super.destroy({ children: true });
+  }
+
+  /**
+   * Called when the application is paused. Use to halt non-display
+   * work — audio, network polling, gameplay timers. Display state
+   * stays on screen; only logic should pause.
+   *
+   * @param config Pause options (e.g. which subsystems to pause).
+   */
+  public onPause(config: PauseConfig): void {
+    void config;
+  }
+
+  /**
+   * Called when the application resumes from a pause. Use to restart
+   * whatever was halted in `onPause`.
+   *
+   * @param config Resume options.
+   */
+  public onResume(config: PauseConfig): void {
+    void config;
+  }
+}

package/src/display/SceneTransition.ts

@@ -0,0 +1,108 @@
+import { Sprite, Ticker } from 'pixi.js';
+import { type Size } from '../utils';
+import { Container } from './Container';
+
+export interface ISceneTransition extends Container {
+  initialized: boolean;
+  progress: number;
+  active: boolean;
+  destroy(): void;
+  enter(): Promise<any> | void;
+  exit(): Promise<any> | void;
+  initialize(): void;
+}
+
+export class SceneTransition extends Container {
+  public initialized: boolean = false;
+  protected __background: Sprite;
+
+  private _active: boolean = false;
+
+  get active(): boolean {
+    return this._active;
+  }
+
+  set active(value: boolean) {
+    this._active = value;
+  }
+
+  private _progress: number;
+
+  get progress(): number {
+    return this._progress;
+  }
+
+  set progress(value: number) {
+    this._progress = value;
+  }
+
+  constructor(autoUpdate: boolean = false) {
+    super({ autoResize: true, autoUpdate: false, priority: -9999 });
+
+    if (autoUpdate) {
+      this.app.ticker.add(this._update);
+    }
+
+    this.addSignalConnection(
+      this.app.assets.onLoadStart.connect(this.handleLoadStart),
+      this.app.assets.onLoadProgress.connect(this.handleLoadProgress),
+      this.app.assets.onLoadProgress.connect(this.handleLoadComplete),
+    );
+  }
+
+  public initialize(): void;
+  public async initialize(): Promise<void> {
+    return Promise.resolve();
+  }
+
+  public resize(size: Size): void {
+    void size;
+  }
+
+  public destroy(): void {
+    this.app.ticker.remove(this._update);
+    this.initialized = false;
+    this._active = false;
+    this._progress = 0;
+    super.destroy();
+  }
+
+  /**
+   * Called to animate the scene in
+   * @returns {Promise<void>}
+   */
+  public enter(): void;
+  public async enter(): Promise<any> {
+    return Promise.resolve();
+  }
+
+  /**
+   * Called to animate the scene out
+   * @returns {Promise<void>}
+   */
+  public exit(): void;
+  public async exit(): Promise<any> {
+    return Promise.resolve();
+  }
+
+  protected handleLoadStart() {
+    // signifies the preloading phase has started for the new scene
+  }
+
+  protected handleLoadProgress(progress: number) {
+    // the preloading progress for the loading scene
+    this._progress = progress;
+  }
+
+  protected handleLoadComplete() {
+    // signifies the preloading phase is complete for the new scene
+  }
+
+  // check if initialized and active before calling update
+  // this way we're sure in the case of a Splash sccreen, all the assets are loaded and the scene is initialized
+  private _update(ticker: Ticker) {
+    if (this.active && this.initialized) {
+      this.update(ticker);
+    }
+  }
+}

package/src/display/SpineAnimation.ts

@@ -0,0 +1,170 @@
+import { type AnimationStateListener, type Event, type TrackEntry } from '@esotericsoftware/spine-core';
+import { Application } from '../core/Application';
+import type { SpineProps } from '../mixins';
+import { Factory, WithSignals } from '../mixins';
+import { Signal } from '../signals';
+import { type AppTypeOverrides, bindAllMethods, Spine } from '../utils';
+
+const _SpineAnimation = WithSignals(Factory());
+
+export interface ISpineAnimation<ANames extends string = string> extends InstanceType<typeof _SpineAnimation> {
+  readonly spine: Spine;
+  readonly animationNames: ANames[];
+  readonly app: AppTypeOverrides['App'];
+  readonly onAnimationComplete: Signal<(entry: TrackEntry) => void>;
+  readonly onAnimationStart: Signal<(entry: TrackEntry) => void>;
+  readonly onAnimationInterrupt: Signal<(entry: TrackEntry) => void>;
+  readonly onAnimationDispose: Signal<(entry: TrackEntry) => void>;
+  readonly onAnimationEnd: Signal<(entry: TrackEntry) => void>;
+  readonly onAnimationEvent: Signal<(entry: TrackEntry, event: Event) => void>;
+  readonly onPaused: Signal<(entry: TrackEntry | null) => void>;
+  readonly onResumed: Signal<(entry: TrackEntry | null) => void>;
+  setAnimation(name: ANames, loop?: boolean, tracklndex?: number): void;
+  getCurrentAnimation(tracklndex?: number): ANames;
+  pause(): void;
+  resume(): void;
+  togglePause(): void;
+}
+
+export class SpineAnimation<ANames extends string = string> extends _SpineAnimation {
+  spine: Spine;
+  paused: boolean;
+
+  onAnimationComplete: Signal<(entry: TrackEntry) => void> = new Signal();
+  onAnimationStart: Signal<(entry: TrackEntry) => void> = new Signal();
+  onAnimationInterrupt: Signal<(entry: TrackEntry) => void> = new Signal();
+  onAnimationDispose: Signal<(entry: TrackEntry) => void> = new Signal();
+  onAnimationEnd: Signal<(entry: TrackEntry) => void> = new Signal();
+  onAnimationEvent: Signal<(entry: TrackEntry, event: Event) => void> = new Signal();
+
+  onPaused: Signal<(entry: TrackEntry | null) => void> = new Signal();
+  onResumed: Signal<(entry: TrackEntry | null) => void> = new Signal();
+
+  protected _stateListener: AnimationStateListener;
+
+  get app(): AppTypeOverrides['App'] {
+    return Application.getInstance();
+  }
+
+  get animationNames(): ANames[] {
+    return this.spine.state.data.skeletonData.animations.map((a) => a.name) as ANames[];
+  }
+
+  get currentEntry() {
+    return this.spine.state.getCurrent(0);
+  }
+
+  get elapsedAnimationTime() {
+    if (this.currentEntry) {
+      return this.currentEntry.trackTime;
+    }
+    return -1;
+  }
+
+  public constructor(props?: Partial<SpineProps>) {
+    super();
+    bindAllMethods(this);
+    let data = props?.data;
+    let spineData: { skeleton: string; atlas: string } | string = '';
+    if (typeof data === 'string') {
+      // get the spine data from cache
+      // check if '.json' is the last part of the asset string, and add it if not
+      let ext = data.slice(-5);
+      if (ext !== '.json' && ext !== '.skel') {
+        ext = '.json';
+      } else {
+        data = data.substring(0, data.length - 5);
+      }
+      spineData = { skeleton: data + ext, atlas: data + '.atlas' };
+    }
+    this.spine = (window as any).Spine.from(spineData);
+    this.add.existing(this.spine);
+
+    if (props) {
+      if (props.autoUpdate !== undefined) this.spine.autoUpdate = props.autoUpdate;
+      if (props.animationName) this.setAnimation(props.animationName as ANames, props.loop, props.trackIndex ?? 0);
+    }
+
+    this.addSignalConnection(this.app.actions('toggle_pause').connect(this.togglePause));
+
+    if (props?.paused) {
+      this.pause();
+    }
+
+    this._stateListener = {
+      start: this._handleAnimationStart,
+      interrupt: this._handleAnimationInterrupt,
+      dispose: this._handleAnimationDispose,
+      end: this._handleAnimationEnd,
+      event: this._handleAnimationEvent,
+      complete: this._handleAnimationComplete,
+    };
+
+    this.spine.state.addListener(this._stateListener);
+  }
+
+  destroy() {
+    this.spine.state.removeListener(this._stateListener);
+    super.destroy();
+  }
+
+  getCurrentAnimation(trackIndex: number = 0): ANames {
+    return (this.spine.state.getCurrent(trackIndex)?.animation?.name as ANames) || ('' as ANames);
+  }
+
+  setAnimation(name: ANames, loop = false, tracklndex: number = 0) {
+    this.spine.state.setAnimation(tracklndex, name, loop);
+  }
+
+  pause() {
+    this.paused = true;
+    this.spine.autoUpdate = false;
+
+    if (this.currentEntry) {
+      this.currentEntry.timeScale = 0;
+    }
+    this.onPaused.emit(this.currentEntry);
+  }
+
+  resume() {
+    this.paused = false;
+    this.spine.autoUpdate = true;
+    if (this.currentEntry) {
+      this.currentEntry.timeScale = 1;
+    }
+    this.onResumed.emit(this.currentEntry);
+  }
+
+  togglePause() {
+    if (this.paused) {
+      this.resume();
+    } else {
+      this.pause();
+    }
+  }
+
+  // protected methods
+  protected _handleAnimationComplete(entry: TrackEntry) {
+    this.onAnimationComplete.emit(entry);
+  }
+
+  protected _handleAnimationStart(entry: TrackEntry) {
+    this.onAnimationStart.emit(entry);
+  }
+
+  protected _handleAnimationInterrupt(entry: TrackEntry) {
+    this.onAnimationInterrupt.emit(entry);
+  }
+
+  protected _handleAnimationDispose(entry: TrackEntry) {
+    this.onAnimationDispose.emit(entry);
+  }
+
+  protected _handleAnimationEnd(entry: TrackEntry) {
+    this.onAnimationEnd.emit(entry);
+  }
+
+  protected _handleAnimationEvent(entry: TrackEntry, event: Event) {
+    this.onAnimationEvent.emit(entry, event);
+  }
+}

package/src/display/Svg.ts

@@ -0,0 +1,9 @@
+import { Assets, Graphics, GraphicsContext } from 'pixi.js';
+
+export class Svg extends Graphics {
+  constructor(ctx: string | GraphicsContext) {
+    super(typeof ctx === 'string' ? Assets.get(ctx) : ctx);
+    const bounds = this.getLocalBounds();
+    this.pivot.set((bounds.x + bounds.width) / 2, (bounds.y + bounds.height) / 2);
+  }
+}

package/src/display/index.ts

@@ -0,0 +1,11 @@
+// top level
+export * from './Container';
+export * from './Entity';
+export * from './ParticleContainer';
+export * from './Scene';
+export * from './SceneTransition';
+export * from './Svg';
+// utilities
+export * from './AnimatedSprite';
+export * from './Camera';
+export * from './SpineAnimation';