@caperjs/core 0.1.0

package/src/plugins/SceneManagerPlugin.ts

@@ -0,0 +1,669 @@
+import { Container } from 'pixi.js';
+import type { IApplication, PauseConfig } from '../core';
+import { Application } from '../core/Application';
+import type { IScene, ISceneTransition, SceneTransition } from '../display';
+import { Signal } from '../signals';
+import {
+  type AppTypeOverrides,
+  AssetTypes,
+  bindAllMethods,
+  BundleTypes,
+  Constructor,
+  createQueue,
+  getDynamicModuleFromImportListItem,
+  isDev,
+  Queue,
+  type SceneId,
+  SceneImportList,
+  SceneImportListItem,
+  type SceneLoadArgs,
+} from '../utils';
+import { triggerViteError } from '../utils/vite';
+import type { IPlugin } from './Plugin';
+import { Plugin } from './Plugin';
+
+export type AppScenes = AppTypeOverrides['Scenes'];
+
+export interface ISceneManagerPlugin extends IPlugin {
+  isFirstScene: boolean;
+  onSceneChangeStart: Signal<(detail: { exiting: string | null; entering: string }) => void>;
+  onSceneChangeComplete: Signal<(detail: { current: string }) => void>;
+  view: Container;
+  list: SceneImportList<IScene>;
+  splash: { view: ISceneTransition | null; hideWhen: SplashHideWhen; zOrder: SplashZOrder };
+  transition?: ISceneTransition;
+  currentScene: IScene;
+  readonly ids: AppScenes[];
+  readonly defaultScene: string;
+  readonly debugGroupsList: any[];
+
+  setDefaultLoadMethod(method: LoadSceneMethod): void;
+
+  loadDefaultScene(): Promise<void>;
+
+  /** Typed overload — enforces `props` required when `Scene<Props>` declares a non-void generic. */
+  loadScene<K extends SceneId>(id: K, ...args: SceneLoadArgs<K>): Promise<void>;
+  loadScene(sceneIdOrLoadSceneConfig: LoadSceneConfig | AppScenes): Promise<void>;
+
+  getSceneFromHash(): string | null;
+}
+
+export type LoadSceneMethod =
+  | 'immediate'
+  | 'exitEnter'
+  | 'enterExit'
+  | 'enterBehind'
+  | 'transitionExitEnter'
+  | 'exitTransitionEnter';
+
+export type SplashHideWhen = 'firstSceneEnter' | 'requiredAssetsLoaded';
+export type SplashZOrder = 'top' | 'bottom';
+
+export type SplashOptions = {
+  view: ISceneTransition | typeof SceneTransition | null;
+  zOrder: SplashZOrder;
+  hideWhen: SplashHideWhen;
+  preload?: {
+    assets?: AssetTypes;
+    bundles?: BundleTypes;
+  };
+};
+
+export type LoadSceneConfig = {
+  id: AppScenes;
+  method?: LoadSceneMethod;
+};
+
+const defaultSplashOptions: SplashOptions = {
+  view: null,
+  hideWhen: 'firstSceneEnter',
+  zOrder: 'top',
+  preload: {
+    assets: [],
+    bundles: [],
+  },
+};
+
+export class SceneManagerPlugin extends Plugin implements ISceneManagerPlugin {
+  public readonly id: string = 'scenes';
+  public onSceneChangeStart: Signal<(detail: { exiting: string | null; entering: string }) => void> = new Signal<
+    (detail: { exiting: string | null; entering: string }) => void
+  >();
+  public onSceneChangeComplete: Signal<(detail: { current: string }) => void> = new Signal<
+    (detail: { current: string }) => void
+  >();
+  public splash: {
+    view: ISceneTransition | null;
+    hideWhen: SplashHideWhen;
+    zOrder: SplashZOrder;
+    preload?: { assets?: AssetTypes; bundles?: BundleTypes };
+  };
+  public transition?: ISceneTransition;
+  // view container - gets added to the stage
+  public view: Container = new Container();
+  // maybe the user wants the enter animation to be different for the first scene
+  public isFirstScene: boolean = true;
+
+  // scene management
+  public list: SceneImportList<IScene> = [];
+  public groupOrder: string[] = [];
+  public currentScene: IScene;
+  public defaultScene: string;
+  public debugGroupsList: any[] = [];
+  private _sceneModules: Map<string, Constructor<IScene>> = new Map();
+  /** Props for the pending `loadScene(id, props)` call, assigned onto the new scene before `initialize()` runs. */
+  private _pendingLoadProps: unknown = undefined;
+  //
+  private _lastScene: IScene | null = null;
+  private _queue: Queue<any> | null;
+  private _defaultLoadMethod: LoadSceneMethod = 'immediate';
+  private _currentSceneId: string;
+  // debug
+  private _debugVisible: boolean = false;
+  private _debugMenu: HTMLDivElement;
+  private _useHash: boolean = false;
+
+  // debug
+  private _sceneSelect: HTMLSelectElement;
+
+  constructor() {
+    super();
+    bindAllMethods(this);
+  }
+
+  get ids(): string[] {
+    return this.list.map((s) => s.id);
+  }
+
+  public setDefaultLoadMethod(method: LoadSceneMethod) {
+    this._defaultLoadMethod = method;
+  }
+
+  public destroy(): void {}
+
+  public async initialize(_options: any, app: IApplication): Promise<void> {
+    this._debugVisible =
+      this.app.config?.showSceneDebugMenu === true || (isDev && this.app.config?.showSceneDebugMenu !== false);
+    this._useHash = app.config?.useHash === true || this._debugVisible;
+    this.view.sortableChildren = true;
+    const sceneList: SceneImportListItem<IScene>[] = Caper.get('sceneList') || [];
+    this.list = sceneList.filter((scene) => scene.active !== false);
+    this.groupOrder = app.config?.sceneGroupOrder || [];
+
+    if (this._debugVisible || this._useHash) {
+      this.defaultScene = this.getSceneFromHash() || '';
+    }
+    if (!this.splash) {
+      this.splash = { view: null, hideWhen: 'firstSceneEnter', zOrder: 'top' };
+      const splash = { ...defaultSplashOptions, ...(app.config?.splash ?? {}) };
+      if (splash.view) {
+        this.splash.view =
+          typeof splash.view === 'function' ? new (splash.view as Constructor<ISceneTransition>)() : splash.view;
+      }
+      this.splash.preload = splash.preload;
+    }
+
+    this.defaultScene = this.defaultScene || app.config?.defaultScene || this.list?.[0]?.id;
+    if (!this.transition && app.config?.sceneTransition) {
+      this.transition =
+        typeof app.config.sceneTransition === 'function'
+          ? new (app.config.sceneTransition as Constructor<ISceneTransition>)()
+          : app.config.sceneTransition;
+    }
+    this._defaultLoadMethod = app.config.defaultSceneLoadMethod || 'immediate';
+
+    if (this._debugVisible) {
+      this._createDebugMenu();
+    }
+    if (this._useHash) {
+      this._listenForHashChange();
+    }
+
+    this.app.onPause.connect(this._onPause, 'highest');
+    this.app.onResume.connect(this._onResume, 'highest');
+
+    return Promise.resolve(undefined);
+  }
+
+  private _onPause(config: PauseConfig) {
+    this.currentScene.onPause(config);
+  }
+
+  private _onResume(config: PauseConfig) {
+    this.currentScene.onResume(config);
+  }
+
+  public async loadDefaultScene(): Promise<void> {
+    if (this.splash) {
+      await this._showSplash();
+    }
+    await this.app.assets.loadRequired();
+    if (this.splash.hideWhen === 'requiredAssetsLoaded') {
+      await this._hideSplash();
+    }
+    return this.loadScene(this.defaultScene);
+  }
+
+  public async loadScene<K extends SceneId>(id: K, ...args: SceneLoadArgs<K>): Promise<void>;
+  public async loadScene(sceneIdOrLoadSceneConfig: LoadSceneConfig | string): Promise<void>;
+
+  public async loadScene(
+    sceneIdOrLoadSceneConfig: LoadSceneConfig | string,
+    props?: unknown,
+  ): Promise<void> {
+    this._pendingLoadProps = props;
+    if (this._queue) {
+      // An in-flight load is interrupted by the new request: cancel the queue,
+      // tear down the mid-transition scene, and proceed with the new load.
+      this._queue.cancel();
+      this._queue = null;
+      if (this.currentScene) {
+        this._lastScene = this.currentScene;
+        this.currentScene.destroy();
+      }
+    }
+
+    this._lastScene = null;
+    const newSceneId =
+      typeof sceneIdOrLoadSceneConfig === 'string' ? sceneIdOrLoadSceneConfig : sceneIdOrLoadSceneConfig.id;
+
+    const method =
+      typeof sceneIdOrLoadSceneConfig === 'string'
+        ? this._defaultLoadMethod
+        : sceneIdOrLoadSceneConfig?.method || this._defaultLoadMethod;
+
+    if (this.currentScene) {
+      this._lastScene = this.currentScene;
+    }
+
+    // check if the scene item exists
+    const sceneItem = this.list.find((scene) => scene.id === newSceneId);
+    if (!sceneItem) {
+      triggerViteError({ message: `Scene item not found for id ${newSceneId}` });
+      throw new Error(`Scene item not found  for id ${newSceneId}`);
+    }
+
+    if (sceneItem?.plugins?.length) {
+      for (const plugin of sceneItem.plugins) {
+        const pluginListItem = this.app.getUnloadedPlugin(plugin);
+        if (pluginListItem) {
+          await this.app.loadPlugin(pluginListItem);
+        }
+      }
+    }
+
+    this._currentSceneId = newSceneId;
+
+    // found a scene item
+    this._queue = createQueue(this._createCurrentScene);
+
+    // Scene bundle loading currently happens inside `_loadCurrentScene` via
+    // `app.assets.loadSceneAssets`, not as discrete queue steps. Queue-level
+    // asset loading + per-step progress reporting is tracked as a Phase 5 DX
+    // improvement (see plan/fork-plan.md §7 — scene-level progress + typed
+    // route map) rather than a blocking TODO here.
+    switch (method) {
+      case 'exitEnter':
+        this._queue.add(
+          this._exitLastScene,
+          this._destroyLastScene,
+          this._unloadLastScene,
+          this._loadCurrentScene,
+          this._initializeCurrentScene,
+          this._addCurrentScene,
+          this._enterCurrentScene,
+          this._startCurrentScene,
+        );
+        break;
+      case 'enterExit':
+        this._queue.add(
+          this._loadCurrentScene,
+          this._initializeCurrentScene,
+          this._addCurrentScene,
+          this._enterCurrentScene,
+          this._startCurrentScene,
+          this._destroyLastScene,
+          this._unloadLastScene,
+        );
+        break;
+      case 'enterBehind':
+        this._queue.add(
+          this._loadCurrentScene,
+          this._initializeCurrentScene,
+          this._addCurrentSceneBehind,
+          this._enterCurrentScene,
+          this._exitLastScene,
+          this._destroyLastScene,
+          this._unloadLastScene,
+          this._startCurrentScene,
+        );
+        break;
+      case 'transitionExitEnter':
+        this._queue.add(
+          this._showTransition,
+          this._exitLastScene,
+          this._destroyLastScene,
+          this._unloadLastScene,
+          this._loadCurrentScene,
+          this._initializeCurrentScene,
+          this._addCurrentScene,
+          this._hideTransition,
+          this._enterCurrentScene,
+          this._startCurrentScene,
+        );
+        break;
+      case 'exitTransitionEnter':
+        this._queue.add(
+          this._exitLastScene,
+          this._showTransition,
+          this._destroyLastScene,
+          this._unloadLastScene,
+          this._loadCurrentScene,
+          this._initializeCurrentScene,
+          this._addCurrentScene,
+          this._hideTransition,
+          this._enterCurrentScene,
+          this._startCurrentScene,
+        );
+        break;
+      case 'immediate':
+      default:
+        this._queue.add(
+          this._destroyLastScene,
+          this._unloadLastScene,
+          this._loadCurrentScene,
+          this._initializeCurrentScene,
+          this._addCurrentScene,
+          this._enterCurrentScene,
+          this._startCurrentScene,
+        );
+        break;
+    }
+
+    this._queue.add(this._queueComplete);
+    this._queue.start();
+  }
+
+  public getSceneFromHash(): string | null {
+    let hash = window?.location?.hash;
+    if (hash) {
+      hash = hash.replace('#', '');
+      if (hash.length > 0) {
+        for (let i = 0; i < this.list.length; i++) {
+          if (this.list[i]?.id?.toLowerCase() === hash.toLowerCase()) {
+            return this.list[i].id;
+          }
+        }
+      }
+    }
+    return null;
+  }
+
+  protected getCoreSignals(): string[] {
+    return ['onSceneChangeStart', 'onSceneChangeComplete'];
+  }
+
+  protected getCoreFunctions(): string[] {
+    return ['loadScene'];
+  }
+
+  private _listenForHashChange() {
+    window.addEventListener('hashchange', () => {
+      const sceneId = this.getSceneFromHash();
+      if (sceneId) {
+        void this.loadScene(sceneId);
+      }
+    });
+  }
+
+  private async _createCurrentScene() {
+    const sceneItem = this.list.find((scene) => scene.id === this._currentSceneId)!;
+    let SceneClass: Constructor<IScene> | undefined = undefined;
+
+    if (this._sceneModules.has(this._currentSceneId)) {
+      SceneClass = this._sceneModules.get(this._currentSceneId);
+    } else {
+      const module = await getDynamicModuleFromImportListItem(sceneItem);
+      if (!module) {
+        throw new Error(`Couldn't load ${this._currentSceneId}"`);
+      }
+
+      if ((module as any)[this._currentSceneId]) {
+        SceneClass = (module as any)[this._currentSceneId];
+      } else {
+        SceneClass = module;
+      }
+
+      if (SceneClass) {
+        this._sceneModules.set(this._currentSceneId, SceneClass);
+      }
+    }
+
+    if (!SceneClass) {
+      throw new Error(`Couldn't load ${this._currentSceneId}"`);
+    }
+
+    this.currentScene = new SceneClass();
+    this.currentScene.id = this._currentSceneId;
+    // Thread the pending load-call props onto the scene. Scenes that don't
+    // declare a generic (default `Scene<void>`) just get `undefined`; scenes
+    // that declare one read them via `this.props` inside `initialize()`.
+    (this.currentScene as unknown as { props: unknown }).props = this._pendingLoadProps;
+    this._pendingLoadProps = undefined;
+    if (sceneItem?.assets) {
+      this.currentScene.assets = sceneItem.assets;
+    }
+    if (sceneItem.autoUnloadAssets !== undefined) {
+      this.currentScene.autoUnloadAssets = sceneItem.autoUnloadAssets;
+    }
+
+    this.currentScene.label = sceneItem.debugLabel || sceneItem.id;
+
+    this.onSceneChangeStart.emit({ exiting: this._lastScene?.id || null, entering: this.currentScene.id });
+  }
+
+  private _queueComplete() {
+    if (this.isFirstScene) {
+      // background required assets
+      this.app.assets.loadBackground();
+    }
+    this.isFirstScene = false;
+
+    // load any background assets for the current scene
+    void this.app.assets.loadSceneAssets(this.currentScene, true);
+
+    this._lastScene = null;
+    this.onSceneChangeComplete.emit({ current: this.currentScene.id });
+    this._queue = null;
+    return Promise.resolve();
+  }
+
+  private async _destroyLastScene(): Promise<void> {
+    if (!this._lastScene) {
+      return Promise.resolve();
+    }
+    this.view.removeChild(this._lastScene as any);
+    this._lastScene.destroy();
+    return Promise.resolve();
+  }
+
+  private async _exitLastScene(): Promise<void> {
+    if (!this._lastScene) {
+      return Promise.resolve();
+    }
+    await this._lastScene.exit();
+    return Promise.resolve();
+  }
+
+  private async _loadCurrentScene(): Promise<any> {
+    await this.app.assets.loadSceneAssets(this.currentScene);
+  }
+
+  private async _unloadLastScene(): Promise<any> {
+    if (this._lastScene && this._lastScene.autoUnloadAssets) {
+      return this.app.assets.unloadSceneAssets(this._lastScene);
+    }
+    return Promise.resolve();
+  }
+
+  private async _initializeCurrentScene(): Promise<void> {
+    await this.currentScene.initialize();
+    // wait one tick so everything in the scene has had a chance to render before triggering the resize
+    this.app.ticker.addOnce(() => {
+      this.currentScene.resize(this.app.size);
+    });
+
+    return Promise.resolve();
+  }
+
+  private _addCurrentScene(): Promise<void> {
+    this.view.addChild(this.currentScene as any);
+    return Promise.resolve();
+  }
+
+  private _addCurrentSceneBehind(): Promise<void> {
+    this.view.addChildAt(this.currentScene as any, 0);
+    return Promise.resolve();
+  }
+
+  private async _enterCurrentScene(): Promise<void> {
+    await this.currentScene.enter();
+    if (this.isFirstScene && this.splash.hideWhen === 'firstSceneEnter') {
+      await this._hideSplash();
+    }
+    return Promise.resolve();
+  }
+
+  private async _startCurrentScene(): Promise<void> {
+    void this.currentScene.start();
+    return Promise.resolve();
+  }
+
+  private async _showTransition(): Promise<void> {
+    if (this.isFirstScene) {
+      return Promise.resolve();
+    }
+    if (this.transition) {
+      if (!this.transition.initialized) {
+        await this.transition.initialize();
+        this.transition.initialized = true;
+      }
+      this.transition.active = true;
+      this.transition.renderable = true;
+      this.transition.visible = true;
+      this.transition.progress = 0;
+      await this.transition.enter();
+    }
+  }
+
+  private async _hideTransition(): Promise<void> {
+    if (this.isFirstScene) {
+      return Promise.resolve();
+    }
+    if (this.transition) {
+      await this.transition.exit();
+      this.transition.progress = 0;
+      this.transition.visible = false;
+      this.transition.renderable = false;
+      this.transition.active = false;
+    }
+  }
+
+  private async _showSplash() {
+    if (this.splash.preload) {
+      if (this.splash.preload.assets) {
+        await this.app.assets.loadAssets(this.splash.preload.assets, false);
+      }
+      if (this.splash.preload.bundles) {
+        await this.app.assets.loadBundles(this.splash.preload.bundles, false);
+      }
+    }
+    if (this.splash.view) {
+      await this.splash.view.initialize();
+      this.splash.view.resize(this.app.size);
+      this.splash.view.active = true;
+      this.splash.view.initialized = true;
+      await this.splash.view.enter();
+    }
+  }
+
+  private async _hideSplash(): Promise<void> {
+    if (this.splash.view) {
+      await this.splash.view?.exit();
+      this.splash.view.active = false;
+      this.splash.view.destroy();
+      this.splash.view.parent?.removeChild(this.splash.view);
+      this.splash.view = null;
+    }
+  }
+
+  private _createDebugMenu() {
+    this._debugMenu = document.createElement('div');
+    this._debugMenu.id = 'scene-debug';
+    this._debugMenu.style.cssText =
+      'position: absolute; bottom: 0; left:0; width:48px; height:48px; z-index: 1000; background-color:rgba(0,0,0,0.8); color:white; border-top-right-radius:8px;';
+    const icon = document.createElement('i');
+    icon.style.cssText =
+      'cursor:pointer; position:absolute;width:100%; font-style:normal; font-size:20px; top:50%; left:50%; transform:translate(-50%, -50%); text-align:center; pointer-events:none';
+    icon.innerHTML = '🎬';
+    this._debugMenu.appendChild(icon);
+
+    (Application.containerElement || document.body).appendChild(this._debugMenu);
+
+    this._sceneSelect = document.createElement('select');
+    this._sceneSelect.style.cssText =
+      'padding:0; border-radius:5px; opacity:0; width:48px; height:48px; cursor:pointer';
+    this._sceneSelect.value = this.defaultScene || '';
+
+    const defaultOption = document.createElement('option');
+    defaultOption.value = '';
+    defaultOption.innerHTML = 'Select a scene';
+    defaultOption.setAttribute('disabled', 'disabled');
+    this._sceneSelect.appendChild(defaultOption);
+
+    // create option groups
+    const groups = new Map<string, HTMLOptGroupElement>();
+    const groupsList: any[] = [];
+
+    this.list.forEach((item) => {
+      if (item.debugGroup) {
+        if (!groups.has(item.debugGroup)) {
+          const group = document.createElement('optgroup');
+          group.label = item.debugGroup;
+          groups.set(item.debugGroup, group);
+          groupsList.push(group);
+          // this._sceneSelect.appendChild(group);
+        }
+      }
+    });
+
+    if (groups.size > 0) {
+      const nogroups = this.list.filter((item) => !item.debugGroup);
+
+      if (nogroups.length) {
+        const group = document.createElement('optgroup');
+        group.label = 'Other';
+        groups.set('Other', group);
+        this._sceneSelect.appendChild(group);
+        nogroups.forEach((item) => {
+          item.debugGroup = 'Other';
+        });
+        groupsList.push(group);
+      }
+    }
+
+    this.debugGroupsList = groupsList;
+
+    this.list.sort((a, b) => {
+      return a.debugOrder! - b.debugOrder!;
+    });
+
+    this.list.forEach((value) => {
+      const option = document.createElement('option');
+      option.value = value.id;
+      option.innerHTML = value?.debugLabel || value.id;
+      if (value.id === this.defaultScene) {
+        option.selected = true;
+      }
+      if (value.debugGroup) {
+        groups.get(value.debugGroup)?.appendChild(option);
+      } else {
+        this._sceneSelect.appendChild(option);
+      }
+    });
+
+    // add groups in order
+    groupsList.sort((a, b) => {
+      return this.groupOrder.indexOf(a.label) - this.groupOrder.indexOf(b.label);
+    });
+
+    groupsList.forEach((group) => {
+      this._sceneSelect.appendChild(group);
+    });
+
+    this._debugMenu.appendChild(this._sceneSelect);
+
+    this._debugMenu.addEventListener('change', (e: Event) => {
+      if (this._queue) {
+        e.preventDefault();
+        return;
+      }
+      const target = e.target as HTMLSelectElement;
+      const sceneId = target.value;
+      if (sceneId) {
+        window.location.hash = sceneId.toLowerCase();
+      }
+    });
+
+    this.onSceneChangeStart.connect(this._disableDebugMenu);
+    this.onSceneChangeComplete.connect(this._enableDebugMenu);
+  }
+
+  private _enableDebugMenu() {
+    this._debugMenu?.querySelector('select')?.removeAttribute('disabled');
+  }
+
+  private _disableDebugMenu() {
+    this._debugMenu?.querySelector('select')?.setAttribute('disabled', 'disabled');
+  }
+}

package/src/plugins/StatsPlugin.ts

@@ -0,0 +1,24 @@
+import { Ticker, UPDATE_PRIORITY } from 'pixi.js';
+import Stats from 'stats.js';
+import { Application } from '../core/Application';
+import { Plugin } from './Plugin';
+
+export class StatsPlugin extends Plugin {
+  public readonly id = 'StatsPlugin';
+  public stats: Stats;
+
+  public async initialize() {
+    this.stats = new Stats();
+    this.stats.dom.id = 'stats';
+
+    Application.containerElement?.appendChild(this.stats.dom);
+
+    this.stats.dom.style.position = 'absolute';
+    this.stats.dom.style.top = 'auto';
+    this.stats.dom.style.bottom = '0';
+    this.stats.dom.style.right = '0';
+    this.stats.dom.style.left = 'auto';
+
+    Ticker.shared.add(this.stats.update, this.stats, UPDATE_PRIORITY.UTILITY);
+  }
+}