@vpmedia/phaser 1.94.0 → 1.96.0

package/CHANGELOG.md

@@ -1,3 +1,44 @@
+## [1.96.0] - 2025-12-17
+
+### 💼 Other
+
+- *(deps)* Bump dependency versions
+
+### 📚 Documentation
+
+- Improve jsdocs
+- Improve jsdoc comments
+- Improve jsdoc comments
+- Improve jsdoc comments
+- Improve jsdoc comments
+- Improve jsdoc comments
+- Improve jsdoc comments
+- Improve jsdoc comments
+- Regenerated types
+- Improve jsdoc comments
+- Improve jsdoc comments
+- Improved jsdoc comments
+- Improve jsdoc comments
+- Improve jsdoc comments
+- Improve jsdoc comments
+- Improve jsdoc comments
+
+### ⚙️ Miscellaneous Tasks
+
+- Release
+- *(release)* V1.96.0
+## [1.95.0] - 2025-12-16
+
+### 💼 Other
+
+- *(deps)* Bump dependency versions
+- *(deps)* Bump dependency versions
+
+### ⚙️ Miscellaneous Tasks
+
+- Release
+- Improve type checking
+- *(release)* V1.95.0
 ## [1.94.0] - 2025-12-11
 
 ### ⚙️ Miscellaneous Tasks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vpmedia/phaser",
-  "version": "1.94.0",
+  "version": "1.96.0",
   "description": "@vpmedia/phaser is the modern ECMAScript port of the popular Phaser game engine v2.6.2",
   "author": "Andras Csizmadia <andras@vpmedia.hu> (www.vpmedia.hu)",
   "license": "MIT",
@@ -23,27 +23,27 @@
   "types": "./types/index.d.ts",
   "type": "module",
   "dependencies": {
-    "@vpmedia/simplify": "^1.46.0",
+    "@vpmedia/simplify": "^1.52.0",
     "uuid": "^13.0.0"
   },
   "devDependencies": {
     "@commitlint/cli": "^20.2.0",
     "@commitlint/config-conventional": "^20.2.0",
-    "@eslint/js": "^9.39.1",
-    "@types/node": "^24.10.1",
-    "@vitest/coverage-v8": "^4.0.15",
-    "eslint": "^9.39.1",
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^4.0.16",
+    "eslint": "^9.39.2",
     "eslint-plugin-jsdoc": "^61.5.0",
-    "eslint-plugin-oxlint": "^1.32.0",
+    "eslint-plugin-oxlint": "^1.33.0",
     "eslint-plugin-unicorn": "^62.0.0",
     "globals": "^16.5.0",
     "jsdom": "^27.3.0",
-    "oxlint": "^1.32.0",
-    "oxlint-tsgolint": "^0.8.4",
+    "oxlint": "^1.33.0",
+    "oxlint-tsgolint": "^0.9.1",
     "prettier": "^3.7.4",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.49.0",
-    "vitest": "^4.0.15"
+    "typescript-eslint": "^8.50.0",
+    "vitest": "^4.0.16"
   },
   "browserslist": [
     "> 0.5%",

package/src/phaser/core/animation.js

@@ -2,37 +2,55 @@ import { Signal } from './signal.js';
 
 export class Animation {
   /**
-   * TBD.
-   * @param {import('./game.js').Game} game - TBD.
-   * @param {import('../display/image.js').Image} parent - TBD.
-   * @param {string} name - TBD.
-   * @param {import('./frame_data.js').FrameData} frameData - TBD.
-   * @param {string[]|number[]} frames - TBD.
-   * @param {number} frameRate - TBD.
-   * @param {boolean} loop - TBD.
+   * Creates a new Animation instance.
+   * @param {import('./game.js').Game} game - The game instance this animation belongs to.
+   * @param {import('../display/image.js').Image} parent - The Image object that owns this animation.
+   * @param {string} name - The unique name of this animation.
+   * @param {import('./frame_data.js').FrameData} frameData - The FrameData object that contains the frames for this animation.
+   * @param {string[]|number[]} frames - An array of frame identifiers (names or indices) to use in this animation.
+   * @param {number} frameRate - The frame rate at which this animation should play (frames per second).
+   * @param {boolean} loop - Whether the animation should loop when it completes.
    */
   constructor(game, parent, name, frameData, frames, frameRate, loop = false) {
+    /** @type {import('./game.js').Game} */
     this.game = game;
     this._parent = parent;
+    /** @type {import('./frame_data.js').FrameData} */
     this._frameData = frameData;
+    /** @type {string} */
     this.name = name;
     this._frames = [];
     this._frames = this._frames.concat(frames);
+    /** @type {number} */
     this.delay = 1000 / frameRate;
+    /** @type {boolean} */
     this.loop = loop;
+    /** @type {number} */
     this.loopCount = 0;
+    /** @type {boolean} */
     this.isFinished = false;
+    /** @type {boolean} */
     this.isPlaying = false;
+    /** @type {boolean} */
     this.isPaused = false;
+    /** @type {number} */
     this._pauseStartTime = 0;
+    /** @type {number} */
     this._frameIndex = 0;
+    /** @type {number} */
     this._frameDiff = 0;
+    /** @type {number} */
     this._frameSkip = 1;
     this.currentFrame = this._frameData.getFrame(this._frames[this._frameIndex]);
+    /** @type {Signal} */
     this.onStart = new Signal();
+    /** @type {Signal} */
     this.onUpdate = null;
+    /** @type {Signal} */
     this.onComplete = new Signal();
+    /** @type {Signal} */
     this.onLoop = new Signal();
+    /** @type {boolean} */
     this.isReversed = false;
     //  Set-up some event listeners
     this.game.onPause.add(this.onPause, this);
@@ -40,10 +58,10 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @param {number} frameRate - TBD.
-   * @param {boolean} loop - TBD.
-   * @returns {Animation} TBD.
+   * Plays this animation.
+   * @param {number} frameRate - The new frame rate to use for this animation (if null, uses the original frame rate).
+   * @param {boolean} loop - Whether to loop this animation (if null, uses the original loop setting).
+   * @returns {Animation} This Animation instance for chaining.
    */
   play(frameRate = null, loop = null) {
     if (typeof frameRate === 'number') {
@@ -70,7 +88,7 @@ export class Animation {
   }
 
   /**
-   * TBD.
+   * Restarts this animation from the beginning.
    */
   restart() {
     this.isPlaying = true;
@@ -88,8 +106,8 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @returns {Animation} TBD.
+   * Reverses the direction of this animation.
+   * @returns {Animation} This Animation instance for chaining.
    */
   reverse() {
     this.reversed = !this.reversed;
@@ -97,8 +115,8 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @returns {Animation} TBD.
+   * Reverses the animation direction once, then returns to normal direction.
+   * @returns {Animation} This Animation instance for chaining.
    */
   reverseOnce() {
     this.onComplete.addOnce(this.reverse, this);
@@ -106,9 +124,9 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @param {string|number} frameId - TBD.
-   * @param {boolean} useLocalFrameIndex - TBD.
+   * Sets the current frame of this animation.
+   * @param {string|number} frameId - The identifier (name or index) of the frame to set.
+   * @param {boolean} useLocalFrameIndex - If true, treats frameId as an index into the local frames array.
    */
   setFrame(frameId, useLocalFrameIndex = false) {
     let frameIndex;
@@ -140,9 +158,9 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @param {boolean} resetFrame - TBD.
-   * @param {boolean} dispatchComplete - TBD.
+   * Stops this animation.
+   * @param {boolean} resetFrame - If true, resets to the first frame.
+   * @param {boolean} dispatchComplete - If true, dispatches the onComplete signal.
    */
   stop(resetFrame = false, dispatchComplete = false) {
     this.isPlaying = false;
@@ -161,7 +179,7 @@ export class Animation {
   }
 
   /**
-   * TBD.
+   * Called when the game is paused.
    */
   onPause() {
     if (this.isPlaying) {
@@ -170,7 +188,7 @@ export class Animation {
   }
 
   /**
-   * TBD.
+   * Called when the game is resumed.
    */
   onResume() {
     if (this.isPlaying) {
@@ -179,8 +197,8 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Updates this animation.
+   * @returns {boolean} True if the animation was updated, false otherwise.
    */
   update() {
     if (this.isPaused) {
@@ -238,10 +256,10 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @param {boolean} signalUpdate - TBD.
-   * @param {boolean} fromPlay - TBD.
-   * @returns {boolean} TBD.
+   * Updates the current frame of this animation.
+   * @param {boolean} signalUpdate - Whether to signal the update event.
+   * @param {boolean} fromPlay - Whether this call is from play().
+   * @returns {boolean} True if the frame was updated, false otherwise.
    */
   updateCurrentFrame(signalUpdate, fromPlay = false) {
     if (!this._frameData || !this.currentFrame) {
@@ -263,8 +281,8 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @param {number} quantity - TBD.
+   * Advances the animation to the next frame(s).
+   * @param {number} quantity - The number of frames to advance by.
    */
   next(quantity = 1) {
     let frame = this._frameIndex + quantity;
@@ -282,8 +300,8 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @param {number} quantity - TBD.
+   * Moves the animation to the previous frame(s).
+   * @param {number} quantity - The number of frames to move back by.
    */
   previous(quantity = 1) {
     let frame = this._frameIndex - quantity;
@@ -301,8 +319,8 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @param {import('./frame_data.js').FrameData} frameData - TBD.
+   * Updates the frame data used by this animation.
+   * @param {import('./frame_data.js').FrameData} frameData - The new FrameData object to use.
    */
   updateFrameData(frameData) {
     this._frameData = frameData;
@@ -312,7 +330,7 @@ export class Animation {
   }
 
   /**
-   * TBD.
+   * Destroys this animation and cleans up resources.
    */
   destroy() {
     if (!this._frameData) {
@@ -336,7 +354,7 @@ export class Animation {
   }
 
   /**
-   * TBD.
+   * Completes this animation, setting it to the final frame.
    */
   complete() {
     this._frameIndex = this._frames.length - 1;
@@ -349,15 +367,16 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Gets whether this animation is currently paused.
+   * @returns {boolean} True if the animation is paused, false otherwise.
    */
   get paused() {
     return this.isPaused;
   }
 
   /**
-   * TBD.
+   * Sets whether this animation is currently paused.
+   * @param {boolean} value - True to pause the animation, false to resume it.
    */
   set paused(value) {
     this.isPaused = value;
@@ -369,31 +388,32 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Gets whether this animation is currently reversed.
+   * @returns {boolean} True if the animation is reversed, false otherwise.
    */
   get reversed() {
     return this.isReversed;
   }
 
   /**
-   * TBD.
+   * Sets whether this animation is currently reversed.
+   * @param {boolean} value - True to reverse the animation, false to normal direction.
    */
   set reversed(value) {
     this.isReversed = value;
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the total number of frames in this animation.
+   * @returns {number} The total number of frames.
    */
   get frameTotal() {
     return this._frames.length;
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the current frame index.
+   * @returns {number} The current frame index.
    */
   get frame() {
     if (this.currentFrame !== null) {
@@ -403,7 +423,8 @@ export class Animation {
   }
 
   /**
-   * TBD.
+   * Sets the current frame index.
+   * @param {number} value - The new frame index to set.
    */
   set frame(value) {
     this.currentFrame = this._frameData.getFrame(this._frames[value]);
@@ -417,15 +438,16 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the current animation speed (frame rate).
+   * @returns {number} The frame rate in frames per second.
    */
   get speed() {
     return 1000 / this.delay;
   }
 
   /**
-   * TBD.
+   * Sets the animation speed (frame rate).
+   * @param {number} value - The new frame rate in frames per second.
    */
   set speed(value) {
     if (value > 0) {
@@ -434,15 +456,16 @@ export class Animation {
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Gets whether the update signal is enabled.
+   * @returns {boolean} True if the update signal is enabled, false otherwise.
    */
   get enableUpdate() {
     return this.onUpdate !== null;
   }
 
   /**
-   * TBD.
+   * Sets whether the update signal is enabled.
+   * @param {boolean} value - True to enable the update signal, false to disable it.
    */
   set enableUpdate(value) {
     if (value && this.onUpdate === null) {

package/src/phaser/core/animation_manager.js

@@ -3,8 +3,8 @@ import { ENGINE_ERROR_CANNOT_SET_FRAME, ENGINE_ERROR_CANNOT_SET_FRAME_NAME } fro
 
 export class AnimationManager {
   /**
-   * TBD.
-   * @param {import('../display/image.js').Image} sprite - TBD.
+   * Creates a new AnimationManager instance.
+   * @param {import('../display/image.js').Image} sprite - Reference to the parent Sprite.
    */
   constructor(sprite) {
     this.sprite = sprite;
@@ -24,7 +24,7 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
+   * Destroys the AnimationManager and cleans up resources.
    */
   destroy() {
     const keys = Object.keys(this._anims);
@@ -41,10 +41,10 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
-   * @param {import('./frame_data.js').FrameData} frameData - TBD.
-   * @param {string|number} frame - TBD.
-   * @returns {boolean} TBD.
+   * Loads frame data into the AnimationManager.
+   * @param {import('./frame_data.js').FrameData} frameData - The FrameData to load.
+   * @param {string|number} frame - The frame index or name to set as current.
+   * @returns {boolean} True if the frame data was loaded successfully, false otherwise.
    */
   loadFrameData(frameData, frame) {
     if (!frameData) {
@@ -71,10 +71,10 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
-   * @param {import('./frame_data.js').FrameData} frameData - TBD.
-   * @param {string|number} frame - TBD.
-   * @returns {boolean} TBD.
+   * Copies frame data into the AnimationManager.
+   * @param {import('./frame_data.js').FrameData} frameData - The FrameData to copy.
+   * @param {string|number} frame - The frame index or name to set as current.
+   * @returns {boolean} True if the frame data was copied successfully, false otherwise.
    */
   copyFrameData(frameData, frame) {
     this._frameData = frameData.clone();
@@ -98,13 +98,13 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
-   * @param {string} name - TBD.
-   * @param {number[] | string[] | null | undefined} frameList - TBD.
-   * @param {number} frameRate - TBD.
-   * @param {boolean} loop - TBD.
-   * @param {boolean | undefined} useNumericIndex - TBD.
-   * @returns {Animation} TBD.
+   * Adds a new animation to the AnimationManager.
+   * @param {string} name - The name of the animation.
+   * @param {number[] | string[] | null | undefined} frameList - The list of frames to include in the animation.
+   * @param {number} frameRate - The frame rate of the animation (frames per second).
+   * @param {boolean} loop - Whether the animation should loop.
+   * @param {boolean | undefined} useNumericIndex - Whether to treat frameList as numeric indices.
+   * @returns {Animation} The created Animation object.
    */
   add(name, frameList, frameRate = 60, loop = false, useNumericIndex = undefined) {
     const frames = frameList || [];
@@ -135,10 +135,10 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
-   * @param {string[] | number[]} frames - TBD.
-   * @param {boolean} useNumericIndex - TBD.
-   * @returns {boolean} TBD.
+   * Validates a list of frames against the current frame data.
+   * @param {string[] | number[]} frames - The list of frames to validate.
+   * @param {boolean} useNumericIndex - Whether to treat frameList as numeric indices.
+   * @returns {boolean} True if all frames are valid, false otherwise.
    */
   validateFrames(frames, useNumericIndex = false) {
     for (let i = 0; i < frames.length; i += 1) {
@@ -154,11 +154,11 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
-   * @param {string} name - TBD.
-   * @param {number} frameRate - TBD.
-   * @param {boolean} loop - TBD.
-   * @returns {Animation} TBD.
+   * Plays an animation by name.
+   * @param {string} name - The name of the animation to play.
+   * @param {number} frameRate - The frame rate (frames per second) to play at, or null to use the animation's default.
+   * @param {boolean} loop - Whether the animation should loop, or null to use the animation's default.
+   * @returns {Animation} The Animation object that was played, or null if not found.
    */
   play(name, frameRate = null, loop = null) {
     if (this._anims[name]) {
@@ -181,9 +181,9 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
-   * @param {string} name - TBD.
-   * @param {boolean} resetFrame - TBD.
+   * Stops an animation by name.
+   * @param {string} name - The name of the animation to stop, or null to stop the current animation.
+   * @param {boolean} resetFrame - Whether to reset the frame to the first frame of the animation.
    */
   stop(name = null, resetFrame = false) {
     if (this.currentAnim && (typeof name !== 'string' || name === this.currentAnim.name)) {
@@ -192,8 +192,8 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Updates the animation manager state.
+   * @returns {boolean} True if an animation was updated, false otherwise.
    */
   update() {
     if (this.updateIfVisible && !this.sprite.visible) {
@@ -207,8 +207,8 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
-   * @param {number} quantity - TBD.
+   * Advances the current animation by a specified number of frames.
+   * @param {number} quantity - The number of frames to advance by.
    */
   next(quantity) {
     if (this.currentAnim) {
@@ -218,8 +218,8 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
-   * @param {number} quantity - TBD.
+   * Moves the current animation back by a specified number of frames.
+   * @param {number} quantity - The number of frames to move back by.
    */
   previous(quantity) {
     if (this.currentAnim) {
@@ -229,9 +229,9 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
-   * @param {string} name - TBD.
-   * @returns {Animation} TBD.
+   * Gets an animation by name.
+   * @param {string} name - The name of the animation to retrieve.
+   * @returns {Animation} The Animation object, or null if not found.
    */
   getAnimation(name) {
     if (name && this._anims[name]) {
@@ -241,7 +241,7 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
+   * Refreshes the current frame texture (not implemented).
    */
   refreshFrame() {
     // TODO
@@ -250,39 +250,39 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
-   * @returns {import('./frame_data.js').FrameData} TBD.
+   * Gets the frame data used by this AnimationManager.
+   * @returns {import('./frame_data.js').FrameData} The FrameData object.
    */
   get frameData() {
     return this._frameData;
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the total number of frames in the frame data.
+   * @returns {number} The total number of frames.
    */
   get frameTotal() {
     return this._frameData.total;
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Gets the paused state of the current animation.
+   * @returns {boolean} True if the current animation is paused, false otherwise.
    */
   get paused() {
     return this.currentAnim.isPaused;
   }
 
   /**
-   * TBD.
+   * Sets the paused state of the current animation.
    */
   set paused(value) {
     this.currentAnim.paused = value;
   }
 
   /**
-   * TBD.
-   * @returns {string} TBD.
+   * Gets the name of the current animation.
+   * @returns {string} The name of the current animation, or null if no animation is active.
    */
   get name() {
     if (this.currentAnim) {
@@ -292,8 +292,8 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the current frame index.
+   * @returns {number} The current frame index.
    */
   get frame() {
     if (this.currentFrame) {
@@ -303,7 +303,7 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
+   * Sets the current frame index.
    */
   set frame(value) {
     if (typeof value === 'number' && this._frameData && this._frameData.getFrame(value) !== null) {
@@ -319,8 +319,8 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
-   * @returns {string} TBD.
+   * Gets the current frame name.
+   * @returns {string} The current frame name, or null if no frame is set.
    */
   get frameName() {
     if (this.currentFrame) {
@@ -330,7 +330,7 @@ export class AnimationManager {
   }
 
   /**
-   * TBD.
+   * Sets the current frame by name.
    */
   set frameName(value) {
     if (typeof value === 'string' && this._frameData && this._frameData.getFrameByName(value) !== null) {