@vpmedia/phaser 1.95.0 → 1.97.0

package/src/phaser/core/loader_parser.js

@@ -2,10 +2,10 @@ import { Texture } from '../display/webgl/texture.js';
 import { Rectangle } from '../geom/rectangle.js';
 
 /**
- * TBD.
- * @param {import('../display/webgl/base_texture.js').BaseTexture} baseTexture - TBD.
- * @param {object} bitmapFontData - TBD.
- * @returns {object} TBD.
+ * Finalizes bitmap font data by attaching textures to characters.
+ * @param {import('../display/webgl/base_texture.js').BaseTexture} baseTexture - The base texture for the font.
+ * @param {object} bitmapFontData - The bitmap font data to finalize.
+ * @returns {object} The finalized bitmap font data.
  */
 export const finalizeBitmapFont = (baseTexture, bitmapFontData) => {
   Object.keys(bitmapFontData.chars).forEach((charCode) => {
@@ -16,12 +16,12 @@ export const finalizeBitmapFont = (baseTexture, bitmapFontData) => {
 };
 
 /**
- * TBD.
- * @param {object} xml - TBD.
- * @param {import('../display/webgl/base_texture.js').BaseTexture} baseTexture - TBD.
- * @param {number} xSpacing - TBD.
- * @param {number} ySpacing - TBD.
- * @returns {object} TBD.
+ * Parses XML bitmap font data.
+ * @param {object} xml - The XML document containing the bitmap font data.
+ * @param {import('../display/webgl/base_texture.js').BaseTexture} baseTexture - The base texture for the font.
+ * @param {number} xSpacing - Horizontal spacing between characters.
+ * @param {number} ySpacing - Vertical spacing between characters.
+ * @returns {object} The parsed bitmap font data.
  */
 export const xmlBitmapFont = (xml, baseTexture, xSpacing, ySpacing) => {
   const data = {};
@@ -56,24 +56,24 @@ export const xmlBitmapFont = (xml, baseTexture, xSpacing, ySpacing) => {
 };
 
 /**
- * TBD.
- * @param {object} xml - TBD.
- * @param {import('../display/webgl/base_texture.js').BaseTexture} baseTexture - TBD.
- * @param {number} xSpacing - TBD.
- * @param {number} ySpacing - TBD.
- * @returns {object} TBD.
+ * Parses XML bitmap font data (alias for xmlBitmapFont).
+ * @param {object} xml - The XML document containing the bitmap font data.
+ * @param {import('../display/webgl/base_texture.js').BaseTexture} baseTexture - The base texture for the font.
+ * @param {number} xSpacing - Horizontal spacing between characters.
+ * @param {number} ySpacing - Vertical spacing between characters.
+ * @returns {object} The parsed bitmap font data.
  */
 export const bitmapFont = (xml, baseTexture, xSpacing, ySpacing) => {
   return xmlBitmapFont(xml, baseTexture, xSpacing, ySpacing);
 };
 
 /**
- * TBD.
- * @param {object} json - TBD.
- * @param {import('../display/webgl/base_texture.js').BaseTexture} baseTexture - TBD.
- * @param {number} xSpacing - TBD.
- * @param {number} ySpacing - TBD.
- * @returns {object} TBD.
+ * Parses JSON bitmap font data.
+ * @param {object} json - The JSON object containing the bitmap font data.
+ * @param {import('../display/webgl/base_texture.js').BaseTexture} baseTexture - The base texture for the font.
+ * @param {number} xSpacing - Horizontal spacing between characters.
+ * @param {number} ySpacing - Vertical spacing between characters.
+ * @returns {object} The parsed bitmap font data.
  */
 export const jsonBitmapFont = (json, baseTexture, xSpacing, ySpacing) => {
   const data = {

package/src/phaser/core/raf.js

@@ -24,7 +24,7 @@ export class RequestAnimationFrame {
 
   /**
    * Performs an animation frame request.
-   * @param {number} rafTime - TBD.
+   * @param {number} rafTime - The timestamp provided by the browser's animation frame.
    */
   update = (rafTime) => {
     this.game.update(rafTime);

package/src/phaser/core/scene.js

@@ -1,6 +1,6 @@
 export class Scene {
   /**
-   * TBD.
+   * Creates a new Scene instance.
    */
   constructor() {
     this.game = null;
@@ -8,51 +8,57 @@ export class Scene {
   }
 
   /**
-   * TBD.
+   * Initialize the scene.
+   * This method is called before preload() and create().
    */
   init() {
     // inherit
   }
 
   /**
-   * TBD.
+   * Load assets for the scene.
+   * This method is called after init() and before create().
    */
   preload() {
     // inherit
   }
 
   /**
-   * TBD.
+   * Create the scene.
+   * This method is called after preload() and is where you create your game objects.
    */
   create() {
     // inherit
   }
 
   /**
-   * TBD.
+   * Update the scene.
+   * This method is called every frame while the scene is active.
    */
   update() {
     // inherit
   }
 
   /**
-   * TBD.
-   * @param {number} width - TBD.
-   * @param {number} height - TBD.
+   * Handle scene resize.
+   * @param {number} width - The new width of the scene.
+   * @param {number} height - The new height of the scene.
    */
   resize(width, height) {
     // inherit
   }
 
   /**
-   * TBD.
+   * Update the scene while paused.
+   * This method is called every frame while the scene is paused.
    */
   pauseUpdate() {
     // inherit
   }
 
   /**
-   * TBD.
+   * Shutdown the scene.
+   * This method is called when the scene is about to be destroyed.
    */
   shutdown() {
     // inherit

package/src/phaser/core/scene_manager.js

@@ -2,9 +2,9 @@ import { Scene } from './scene.js';
 
 export class SceneManager {
   /**
-   * TBD.
-   * @param {import('./game.js').Game} game - TBD.
-   * @param {string} pendingState - TBD.
+   * Creates a new SceneManager instance.
+   * @param {import('./game.js').Game} game - The game instance this manager belongs to.
+   * @param {string} pendingState - The state to load when the game boots.
    */
   constructor(game, pendingState) {
     this.game = game;
@@ -28,7 +28,8 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
+   * Initialize the scene manager.
+   * This method is called when the game boots and sets up the initial state.
    */
   boot() {
     if (this._pendingState !== null && typeof this._pendingState !== 'string') {
@@ -37,11 +38,11 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
-   * @param {string} key - TBD.
-   * @param {object} state - TBD.
-   * @param {boolean} autoStart - TBD.
-   * @returns {Scene|object} TBD.
+   * Add a new scene state to the manager.
+   * @param {string} key - The unique key for this state.
+   * @param {object} state - The scene state to add.
+   * @param {boolean} autoStart - Whether to start this state immediately.
+   * @returns {Scene|object} The created scene or state object.
    */
   add(key, state, autoStart = false) {
     let newState = null;
@@ -65,8 +66,8 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
-   * @param {string} key - TBD.
+   * Remove a scene state from the manager.
+   * @param {string} key - The unique key for the state to remove.
    */
   remove(key) {
     if (this.current === key) {
@@ -83,11 +84,11 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
-   * @param {string} key - TBD.
-   * @param {boolean} clearWorld - TBD.
-   * @param {boolean} clearCache - TBD.
-   * @param {...any} args - TBD.
+   * Start a scene state.
+   * @param {string} key - The unique key for the state to start.
+   * @param {boolean} clearWorld - Whether to clear the world before starting.
+   * @param {boolean} clearCache - Whether to clear the cache before starting.
+   * @param {...any} args - Additional arguments to pass to the state.
    */
   start(key, clearWorld = true, clearCache = false, ...args) {
     if (this.checkState(key)) {
@@ -102,10 +103,10 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
-   * @param {boolean} clearWorld - TBD.
-   * @param {boolean} clearCache - TBD.
-   * @param {...any} args - TBD.
+   * Restart the current scene state.
+   * @param {boolean} clearWorld - Whether to clear the world before restarting.
+   * @param {boolean} clearCache - Whether to clear the cache before restarting.
+   * @param {...any} args - Additional arguments to pass to the state.
    */
   restart(clearWorld = true, clearCache = false, ...args) {
     this._pendingState = this.current;
@@ -117,7 +118,8 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
+   * Pre-update the scene manager.
+   * This method is called before the game loop updates.
    */
   preUpdate() {
     if (this._pendingState && this.game.isBooted) {
@@ -151,7 +153,8 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
+   * Clear the current scene state.
+   * This method is called when switching scenes to clean up the previous scene.
    */
   clearCurrentState() {
     if (this.current) {
@@ -172,9 +175,9 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
-   * @param {string} key - TBD.
-   * @returns {boolean} TBD.
+   * Check if a scene state exists.
+   * @param {string} key - The unique key for the state to check.
+   * @returns {boolean} True if the scene exists, false otherwise.
    */
   checkState(key) {
     if (this.states[key]) {
@@ -187,8 +190,8 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
-   * @param {string} key - TBD.
+   * Link a scene state to the manager.
+   * @param {string} key - The unique key for the state to link.
    */
   link(key) {
     this.states[key].game = this.game;
@@ -196,8 +199,8 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
-   * @param {string} key - TBD.
+   * Unlink a scene state from the manager.
+   * @param {string} key - The unique key for the state to unlink.
    */
   unlink(key) {
     if (this.states[key]) {
@@ -206,8 +209,8 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
-   * @param {string} key - TBD.
+   * Set the current scene state.
+   * @param {string} key - The unique key for the state to set as current.
    */
   setCurrentState(key) {
     this.callbackContext = this.states[key];
@@ -230,15 +233,16 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
-   * @returns {Scene} TBD.
+   * Get the current scene state.
+   * @returns {Scene} The current scene state.
    */
   getCurrentState() {
     return this.states[this.current];
   }
 
   /**
-   * TBD.
+   * Handle loading completion.
+   * This method is called when scene loading is complete.
    */
   loadComplete() {
     if (this._created === false && this.onCreateCallback) {
@@ -250,7 +254,8 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
+   * Update the scene manager.
+   * This method is called every frame while the game is running.
    */
   update() {
     if (this._created && this.onUpdateCallback) {
@@ -259,7 +264,8 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
+   * Pause the scene manager updates.
+   * This method is called when the game is paused.
    */
   pauseUpdate() {
     if (this._created && this.onPauseUpdateCallback) {
@@ -268,9 +274,9 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
-   * @param {number} width - TBD.
-   * @param {number} height - TBD.
+   * Handle scene resize.
+   * @param {number} width - The new width of the scene.
+   * @param {number} height - The new height of the scene.
    */
   resize(width, height) {
     if (this.onResizeCallback) {
@@ -279,7 +285,8 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
+   * Destroy the scene manager.
+   * This method is called when the scene manager is about to be destroyed.
    */
   destroy() {
     this._clearWorld = true;
@@ -299,15 +306,16 @@ export class SceneManager {
   }
 
   /**
-   * TBD.
+   * Dummy function for callbacks.
+   * This is a placeholder function used when no callback is defined.
    */
   dummy() {
     // pass
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Get whether the scene has been created.
+   * @returns {boolean} True if the scene has been created, false otherwise.
    */
   get created() {
     return this._created;

package/src/phaser/core/signal.js

@@ -2,7 +2,8 @@ import { SignalBinding } from './signal_binding.js';
 
 export class Signal {
   /**
-   * TBD.
+   * Creates a new Signal instance.
+   * A Signal is a simple event system that allows you to dispatch events and listen for them.
    */
   constructor() {
     this._bindings = null;
@@ -14,10 +15,10 @@ export class Signal {
   }
 
   /**
-   * TBD.
-   * @param {Function} listener - TBD.
-   * @param {string} fnName - TBD.
-   * @throws {Error}
+   * Validates that a listener is a function.
+   * @param {Function} listener - The listener to validate.
+   * @param {string} fnName - The name of the function this validation is for.
+   * @throws {Error} If the listener is not a function.
    */
   validateListener(listener, fnName) {
     if (typeof listener !== 'function') {
@@ -28,14 +29,14 @@ export class Signal {
   }
 
   /**
-   * TBD.
-   * @param {Function} listener - TBD.
-   * @param {boolean} isOnce - TBD.
-   * @param {object} listenerContext - TBD.
-   * @param {number} priority - TBD.
-   * @param {...any} args - TBD.
-   * @returns {SignalBinding} TBD.
-   * @throws {Error}
+   * Register a new listener with the signal.
+   * @param {Function} listener - The function to call when the signal is dispatched.
+   * @param {boolean} isOnce - Whether the listener should only be called once.
+   * @param {object} listenerContext - The context to apply when calling the listener.
+   * @param {number} priority - The priority of this listener (higher numbers execute first).
+   * @param {...any} args - Additional arguments to pass to the listener.
+   * @returns {SignalBinding} The binding for this listener.
+   * @throws {Error} If the listener is already registered with a different once setting.
    */
   _registerListener(listener, isOnce = false, listenerContext = null, priority = 0, args = null) {
     const prevIndex = this._indexOfListener(listener, listenerContext);
@@ -60,8 +61,8 @@ export class Signal {
   }
 
   /**
-   * TBD.
-   * @param {SignalBinding} binding - TBD.
+   * Add a binding to the list of listeners.
+   * @param {SignalBinding} binding - The binding to add.
    */
   _addBinding(binding) {
     if (!this._bindings) {
@@ -76,10 +77,10 @@ export class Signal {
   }
 
   /**
-   * TBD.
-   * @param {Function} listener - TBD.
-   * @param {object} context - TBD.
-   * @returns {number} TBD.
+   * Find the index of a listener in the bindings array.
+   * @param {Function} listener - The listener to find.
+   * @param {object} context - The context of the listener.
+   * @returns {number} The index of the listener in the bindings array, or -1 if not found.
    */
   _indexOfListener(listener, context = null) {
     if (!this._bindings) {
@@ -98,22 +99,22 @@ export class Signal {
   }
 
   /**
-   * TBD.
-   * @param {Function} listener - TBD.
-   * @param {object} context - TBD.
-   * @returns {boolean} TBD.
+   * Check if a listener is registered with the signal.
+   * @param {Function} listener - The listener to check.
+   * @param {object} context - The context of the listener.
+   * @returns {boolean} True if the listener is registered, false otherwise.
    */
   has(listener, context = null) {
     return this._indexOfListener(listener, context) !== -1;
   }
 
   /**
-   * TBD.
-   * @param {Function} listener - TBD.
-   * @param {object} listenerContext - TBD.
-   * @param {number} priority - TBD.
-   * @param {...any} args - TBD.
-   * @returns {SignalBinding} TBD.
+   * Add a listener that will be called every time the signal is dispatched.
+   * @param {Function} listener - The function to call when the signal is dispatched.
+   * @param {object} listenerContext - The context to apply when calling the listener.
+   * @param {number} priority - The priority of this listener (higher numbers execute first).
+   * @param {...any} args - Additional arguments to pass to the listener.
+   * @returns {SignalBinding} The binding for this listener.
    */
   add(listener, listenerContext = null, priority = 0, ...args) {
     this.validateListener(listener, 'add');
@@ -121,12 +122,12 @@ export class Signal {
   }
 
   /**
-   * TBD.
-   * @param {Function} listener - TBD.
-   * @param {object} listenerContext - TBD.
-   * @param {number} priority - TBD.
-   * @param {...any} args - TBD.
-   * @returns {SignalBinding} TBD.
+   * Add a listener that will be called only once when the signal is dispatched.
+   * @param {Function} listener - The function to call when the signal is dispatched.
+   * @param {object} listenerContext - The context to apply when calling the listener.
+   * @param {number} priority - The priority of this listener (higher numbers execute first).
+   * @param {...any} args - Additional arguments to pass to the listener.
+   * @returns {SignalBinding} The binding for this listener.
    */
   addOnce(listener, listenerContext = null, priority = 0, ...args) {
     this.validateListener(listener, 'addOnce');
@@ -134,10 +135,10 @@ export class Signal {
   }
 
   /**
-   * TBD.
-   * @param {Function} listener - TBD.
-   * @param {object} context - TBD.
-   * @returns {Function} TBD.
+   * Remove a listener from the signal.
+   * @param {Function} listener - The listener to remove.
+   * @param {object} context - The context of the listener.
+   * @returns {Function} The removed listener function.
    */
   remove(listener, context = null) {
     this.validateListener(listener, 'remove');
@@ -151,8 +152,8 @@ export class Signal {
   }
 
   /**
-   * TBD.
-   * @param {object} context - TBD.
+   * Remove all listeners from the signal, or only those in a specific context.
+   * @param {object} context - The context to filter listeners by, or null to remove all.
    */
   removeAll(context = null) {
     if (!this._bindings) {
@@ -176,23 +177,24 @@ export class Signal {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Get the number of listeners registered with the signal.
+   * @returns {number} The number of registered listeners.
    */
   getNumListeners() {
     return this._bindings ? this._bindings.length : 0;
   }
 
   /**
-   * TBD.
+   * Stop the signal from propagating to other listeners.
+   * This method prevents any remaining listeners from being called.
    */
   halt() {
     this._shouldPropagate = false;
   }
 
   /**
-   * TBD.
-   * @param {...any} args - TBD.
+   * Dispatch the signal to all registered listeners.
+   * @param {...any} args - Arguments to pass to the listeners.
    */
   dispatch(...args) {
     if (!this.active || !this._bindings) {
@@ -219,7 +221,8 @@ export class Signal {
   }
 
   /**
-   * TBD.
+   * Clear any previously memorized arguments.
+   * This removes the stored arguments from a previous dispatch.
    */
   forget() {
     if (this._prevParams) {
@@ -228,7 +231,8 @@ export class Signal {
   }
 
   /**
-   * TBD.
+   * Dispose of the signal and clean up all resources.
+   * This method removes all listeners and clears internal state.
    */
   dispose() {
     this.removeAll();
@@ -237,16 +241,16 @@ export class Signal {
   }
 
   /**
-   * TBD.
-   * @returns {string} TBD.
+   * Get a string representation of the signal.
+   * @returns {string} A string representation of the signal.
    */
   toString() {
     return `[Signal active:${this.active} numListeners:${this.getNumListeners()}]`;
   }
 
   /**
-   * TBD.
-   * @returns {Function} TBD.
+   * Get a bound version of the dispatch function.
+   * @returns {Function} A function that will dispatch the signal with the correct context.
    */
   get boundDispatch() {
     const _this = this;
@@ -255,4 +259,16 @@ export class Signal {
     }
     return this._boundDispatch;
   }
+
+  /**
+   * Promisify the Signal.
+   * @returns {Promise<any>} The resolved result.
+   */
+  toPromise() {
+    return new Promise((resolve) => {
+      this.addOnce((...args) => {
+        resolve(args.length <= 1 ? args[0] : args);
+      }, this);
+    });
+  }
 }

package/src/phaser/core/signal.test.js

@@ -0,0 +1,37 @@
+import { expect } from 'vitest';
+import { Signal } from './signal.js';
+
+describe('Signal', () => {
+  describe('core', () => {
+    it('', () => {
+      const signal = new Signal();
+      const listener = (arg) => {
+        expect(arg).toBe(1);
+      };
+      const listenerOnce = (arg) => {
+        expect(arg).toBe(1);
+      };
+      signal.add(listener);
+      expect(signal.getNumListeners()).toBe(1);
+      signal.addOnce(listenerOnce);
+      expect(signal.getNumListeners()).toBe(2);
+      signal.dispatch(1);
+      expect(signal.getNumListeners()).toBe(1);
+      signal.remove(listener);
+      expect(signal.has(listener)).toBe(false);
+      expect(signal.getNumListeners()).toBe(0);
+      expect(signal.has(() => null)).toBe(false);
+    });
+
+    it('async', async () => {
+      const signal = new Signal();
+      const promise = signal.toPromise();
+      expect(signal.getNumListeners()).toBe(1);
+      setTimeout(() => {
+        signal.dispatch(1);
+      }, 10);
+      const result = await promise;
+      expect(result).toBe(1);
+    });
+  });
+});