@vpmedia/phaser 1.95.0 → 1.96.0

package/src/phaser/core/sound.js

@@ -2,12 +2,12 @@ import { Signal } from './signal.js';
 
 export class Sound {
   /**
-   * TBD.
-   * @param {import('./game.js').Game} game - TBD.
-   * @param {string} key - TBD.
-   * @param {number} volume - TBD.
-   * @param {boolean} loop - TBD.
-   * @param {boolean} connect - TBD.
+   * Creates a new Sound instance.
+   * @param {import('./game.js').Game} game - Reference to the Phaser Game instance.
+   * @param {string} key - The key of the sound to play.
+   * @param {number} volume - The initial volume level (0.0 to 1.0).
+   * @param {boolean} loop - Whether the sound should loop.
+   * @param {boolean} connect - Whether to connect to the master gain node.
    */
   constructor(game, key, volume = 1, loop = false, connect = null) {
     // TODO
@@ -81,8 +81,8 @@ export class Sound {
   }
 
   /**
-   * TBD.
-   * @param {string} key - TBD.
+   * Callback when a sound has been unlocked.
+   * @param {string} key - The key of the sound that was unlocked.
    */
   soundHasUnlocked(key) {
     if (key === this.key) {
@@ -92,12 +92,12 @@ export class Sound {
   }
 
   /**
-   * TBD.
-   * @param {string} name - TBD.
-   * @param {number} start - TBD.
-   * @param {number} duration - TBD.
-   * @param {number} volume - TBD.
-   * @param {boolean} loop - TBD.
+   * Adds a marker to the sound.
+   * @param {string} name - The name of the marker.
+   * @param {number} start - The start time (in seconds) of the marker.
+   * @param {number} duration - The duration (in seconds) of the marker.
+   * @param {number} volume - The volume level (0.0 to 1.0) of the marker.
+   * @param {boolean} loop - Whether the marker should loop.
    */
   addMarker(name, start, duration = 1, volume = 1, loop = false) {
     this.markers[name] = {
@@ -112,15 +112,15 @@ export class Sound {
   }
 
   /**
-   * TBD.
-   * @param {string} name - TBD.
+   * Removes a marker from the sound.
+   * @param {string} name - The name of the marker to remove.
    */
   removeMarker(name) {
     delete this.markers[name];
   }
 
   /**
-   * TBD.
+   * Handler for when the sound ends.
    */
   onEndedHandler() {
     this._sound.onended = null;
@@ -154,7 +154,7 @@ export class Sound {
   }
 
   /**
-   * TBD.
+   * Updates the sound state.
    */
   update() {
     if (!this.game.cache.checkSoundKey(this.key)) {
@@ -191,22 +191,22 @@ export class Sound {
   }
 
   /**
-   * TBD.
-   * @param {number} volume - TBD.
-   * @returns {Sound} TBD.
+   * Plays the sound at full volume in a loop.
+   * @param {number} volume - The volume level (0.0 to 1.0) to play at.
+   * @returns {Sound} This Sound instance for chaining.
    */
   loopFull(volume) {
     return this.play(null, 0, volume, true);
   }
 
   /**
-   * TBD.
-   * @param {string} marker - TBD.
-   * @param {number} position - TBD.
-   * @param {number} volume - TBD.
-   * @param {boolean} loop - TBD.
-   * @param {boolean} forceRestart - TBD.
-   * @returns {Sound} TBD.
+   * Plays the sound, optionally using a marker.
+   * @param {string} marker - The name of the marker to play, or null/undefined to play the entire sound.
+   * @param {number} position - The position (in seconds) to start playing from.
+   * @param {number} volume - The volume level (0.0 to 1.0) to play at.
+   * @param {boolean} loop - Whether the sound should loop.
+   * @param {boolean} forceRestart - Whether to force restarting the sound even if it's already playing.
+   * @returns {Sound} This Sound instance for chaining.
    */
   play(marker, position, volume, loop, forceRestart = true) {
     if (marker === undefined || marker === false || marker === null) {
@@ -323,18 +323,18 @@ export class Sound {
   }
 
   /**
-   * TBD.
-   * @param {string} marker - TBD.
-   * @param {number} position - TBD.
-   * @param {number} volume - TBD.
-   * @param {boolean} loop - TBD.
+   * Restarts the sound, optionally using a marker.
+   * @param {string} marker - The name of the marker to play, or empty string to play the entire sound.
+   * @param {number} position - The position (in seconds) to start playing from.
+   * @param {number} volume - The volume level (0.0 to 1.0) to play at.
+   * @param {boolean} loop - Whether the sound should loop.
    */
   restart(marker = '', position = 0, volume = 1, loop = false) {
     this.play(marker, position, volume, loop, true);
   }
 
   /**
-   * TBD.
+   * Pauses the sound.
    */
   pause() {
     if (this.isPlaying && this._sound) {
@@ -348,7 +348,7 @@ export class Sound {
   }
 
   /**
-   * TBD.
+   * Resumes the sound.
    */
   resume() {
     if (this.paused && this._sound) {
@@ -380,7 +380,7 @@ export class Sound {
   }
 
   /**
-   * TBD.
+   * Stops the sound.
    */
   stop() {
     if (this.isPlaying && this._sound) {
@@ -411,10 +411,10 @@ export class Sound {
   }
 
   /**
-   * TBD.
-   * @param {number} duration - TBD.
-   * @param {boolean} loop - TBD.
-   * @param {string} marker - TBD.
+   * Fades in the sound to full volume.
+   * @param {number} duration - The fade-in duration (in milliseconds).
+   * @param {boolean} loop - Whether the sound should loop.
+   * @param {string} marker - The name of the marker to fade in, or empty string to use current marker.
    */
   fadeIn(duration, loop = false, marker = this.currentMarker) {
     if (this.paused) {
@@ -425,17 +425,17 @@ export class Sound {
   }
 
   /**
-   * TBD.
-   * @param {number} duration - TBD.
+   * Fades out the sound to silence.
+   * @param {number} duration - The fade-out duration (in milliseconds).
    */
   fadeOut(duration) {
     this.fadeTo(duration, 0);
   }
 
   /**
-   * TBD.
-   * @param {number} duration - TBD.
-   * @param {number} volume - TBD.
+   * Fades the sound to a specific volume level.
+   * @param {number} duration - The fade duration (in milliseconds).
+   * @param {number} volume - The target volume level (0.0 to 1.0).
    */
   fadeTo(duration = 100, volume = 0) {
     if (!this.isPlaying || this.paused || volume === this.volume) {
@@ -446,7 +446,7 @@ export class Sound {
   }
 
   /**
-   * TBD.
+   * Callback when fade completes.
    */
   fadeComplete() {
     this.onFadeComplete.dispatch(this, this.volume);
@@ -456,8 +456,8 @@ export class Sound {
   }
 
   /**
-   * TBD.
-   * @param {boolean} remove - TBD.
+   * Destroys the sound and cleans up resources.
+   * @param {boolean} remove - Whether to remove the sound from the SoundManager.
    */
   destroy(remove = true) {
     this._markedToDelete = true;
@@ -482,15 +482,15 @@ export class Sound {
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Gets the muted state of the sound.
+   * @returns {boolean} True if the sound is muted, false otherwise.
    */
   get mute() {
     return this._muted || this.game.sound.mute;
   }
 
   /**
-   * TBD.
+   * Sets the muted state of the sound.
    */
   set mute(value) {
     value = value || false;
@@ -509,15 +509,15 @@ export class Sound {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the volume of the sound.
+   * @returns {number} The volume level (0.0 to 1.0).
    */
   get volume() {
     return this._volume;
   }
 
   /**
-   * TBD.
+   * Sets the volume of the sound.
    */
   set volume(value) {
     if (this._muted) {

package/src/phaser/core/sound_manager.js

@@ -13,8 +13,8 @@ import { SoundSprite } from './sound_sprite.js';
 
 export class SoundManager {
   /**
-   * TBD.
-   * @param {import('./game.js').Game} game - TBD.
+   * Creates a new SoundManager instance.
+   * @param {import('./game.js').Game} game - Reference to the Phaser Game instance.
    */
   constructor(game) {
     this.game = game;
@@ -40,7 +40,7 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
+   * Initializes the sound manager and sets up audio context.
    */
   boot() {
     const setAudioDisabledState = () => {
@@ -98,7 +98,7 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
+   * Handles page lifecycle changes for audio management.
    */
   onPageLifecycleChange = () => {
     if (!document.hidden) {
@@ -107,7 +107,7 @@ export class SoundManager {
   };
 
   /**
-   * TBD.
+   * Handles audio context state changes.
    */
   onContextStateChange = () => {
     this.game.logger.info('onContextStateChange', {
@@ -118,7 +118,7 @@ export class SoundManager {
   };
 
   /**
-   * TBD.
+   * Checks if audio unlock handlers need to be added or removed.
    */
   checkUnlockHandlers = () => {
     this.game.logger.info('checkUnlockHandlers', {
@@ -133,7 +133,7 @@ export class SoundManager {
   };
 
   /**
-   * TBD.
+   * Adds event listeners to unlock audio context.
    */
   addUnlockHandlers = () => {
     this.isLocked = true;
@@ -147,7 +147,7 @@ export class SoundManager {
   };
 
   /**
-   * TBD.
+   * Removes event listeners that unlock audio context.
    */
   removeUnlockHandlers = () => {
     this.isLocked = false;
@@ -161,8 +161,8 @@ export class SoundManager {
   };
 
   /**
-   * TBD.
-   * @param {Event} event - TBD.
+   * Handles unlock events to resume audio context.
+   * @param {Event} event - The DOM event that triggered the unlock.
    */
   onUnlockEvent = (event) => {
     const initialState = this.context.state;
@@ -205,7 +205,7 @@ export class SoundManager {
   };
 
   /**
-   * TBD.
+   * Stops all sounds in the manager.
    */
   stopAll() {
     if (this.noAudio) {
@@ -219,7 +219,7 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
+   * Pauses all sounds in the manager.
    */
   pauseAll() {
     if (this.noAudio) {
@@ -233,7 +233,7 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
+   * Resumes all sounds in the manager.
    */
   resumeAll() {
     if (this.noAudio) {
@@ -247,8 +247,8 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
-   * @param {string} key - TBD.
+   * Decodes an audio file for playback.
+   * @param {string} key - The key of the sound to decode.
    */
   decode(key) {
     const soundData = this.game.cache.getSoundData(key);
@@ -274,10 +274,10 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
-   * @param {Sound[]|string[]} files - TBD.
-   * @param {Function} callback - TBD.
-   * @param {object} callbackContext - TBD.
+   * Sets up a callback to be called when audio files are decoded.
+   * @param {Sound[]|string[]} files - The sound files or keys to wait for.
+   * @param {Function} callback - The callback function to call when all files are decoded.
+   * @param {object} callbackContext - The context in which to call the callback.
    */
   setDecodedCallback(files, callback, callbackContext) {
     if (typeof files === 'string') {
@@ -306,7 +306,7 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
+   * Updates the sound manager state.
    */
   update() {
     if (this.noAudio) {
@@ -332,12 +332,12 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
-   * @param {string} key - TBD.
-   * @param {number} volume - TBD.
-   * @param {boolean} loop - TBD.
-   * @param {boolean} connect - TBD.
-   * @returns {Sound} TBD.
+   * Adds a new sound to the manager.
+   * @param {string} key - The key of the sound to add.
+   * @param {number} volume - The initial volume level (0.0 to 1.0).
+   * @param {boolean} loop - Whether the sound should loop.
+   * @param {boolean} connect - Whether to connect to the master gain node.
+   * @returns {Sound} The created Sound object.
    */
   add(key, volume = 1, loop = false, connect = this.connectToMaster) {
     const sound = new Sound(this.game, key, volume, loop, connect);
@@ -346,18 +346,18 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
-   * @param {string} key - TBD.
-   * @returns {SoundSprite} TBD.
+   * Adds a new sound sprite to the manager.
+   * @param {string} key - The key of the sound sprite to add.
+   * @returns {SoundSprite} The created SoundSprite object.
    */
   addSprite(key) {
     return new SoundSprite(this.game, key);
   }
 
   /**
-   * TBD.
-   * @param {Sound | null | undefined} sound - TBD.
-   * @returns {boolean} TBD.
+   * Removes a sound from the manager.
+   * @param {Sound | null | undefined} sound - The sound object to remove.
+   * @returns {boolean} True if the sound was removed, false otherwise.
    */
   remove(sound) {
     let i = this._sounds.length;
@@ -373,9 +373,9 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
-   * @param {string} key - TBD.
-   * @returns {number} TBD.
+   * Removes all sounds with a specific key from the manager.
+   * @param {string} key - The key of sounds to remove.
+   * @returns {number} The number of sounds removed.
    */
   removeByKey(key) {
     let i = this._sounds.length;
@@ -392,11 +392,11 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
-   * @param {string} key - TBD.
-   * @param {number} volume - TBD.
-   * @param {boolean} loop - TBD.
-   * @returns {Sound} TBD.
+   * Plays a sound by key.
+   * @param {string} key - The key of the sound to play.
+   * @param {number} volume - The volume level (0.0 to 1.0).
+   * @param {boolean} loop - Whether the sound should loop.
+   * @returns {Sound} The created Sound object, or null if audio is disabled.
    */
   play(key, volume = 1, loop = false) {
     if (this.noAudio) {
@@ -408,7 +408,7 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
+   * Mutes all sounds in the manager.
    */
   setMute() {
     if (this._muted) {
@@ -423,7 +423,7 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
+   * Unmutes all sounds in the manager.
    */
   unsetMute() {
     if (!this._muted || this._codeMuted) {
@@ -437,7 +437,7 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
+   * Destroys the sound manager and cleans up resources.
    */
   destroy() {
     this.stopAll();
@@ -454,15 +454,15 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Gets the muted state of the sound manager.
+   * @returns {boolean} True if the manager is muted, false otherwise.
    */
   get mute() {
     return this._muted;
   }
 
   /**
-   * TBD.
+   * Sets the muted state of the sound manager.
    */
   set mute(value) {
     if (value || false) {
@@ -481,15 +481,15 @@ export class SoundManager {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the volume level of the sound manager.
+   * @returns {number} The volume level (0.0 to 1.0).
    */
   get volume() {
     return this._volume;
   }
 
   /**
-   * TBD.
+   * Sets the volume level of the sound manager.
    */
   set volume(value) {
     if (value < 0) {

package/src/phaser/core/stage.js

@@ -6,8 +6,8 @@ import { SCALE_LINEAR, SCALE_NEAREST } from './const.js';
 
 export class Stage extends DisplayObject {
   /**
-   * TBD.
-   * @param {import('./game.js').Game} game - TBD.
+   * Creates a new Stage instance.
+   * @param {import('./game.js').Game} game - The game instance.
    */
   constructor(game) {
     super(game);
@@ -32,8 +32,8 @@ export class Stage extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @param {number} color - TBD.
+   * Sets the background color of the stage.
+   * @param {number} color - The color to set as the background.
    */
   setBackgroundColor(color) {
     if (this.game.config.transparent) {
@@ -48,7 +48,7 @@ export class Stage extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Initializes the stage after game creation.
    */
   boot() {
     setUserSelect(this.game.canvas, 'none');
@@ -56,7 +56,7 @@ export class Stage extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Pre-updates the stage and its children.
    */
   preUpdate() {
     this.currentRenderOrderID = 0;
@@ -67,7 +67,7 @@ export class Stage extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Updates the stage and its children.
    */
   update() {
     let i = this.children.length;
@@ -78,7 +78,7 @@ export class Stage extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Post-updates the stage and its children.
    */
   postUpdate() {
     for (let i = 0; i < this.children.length; i += 1) {
@@ -88,7 +88,7 @@ export class Stage extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Updates the stage's transformation matrix.
    */
   updateTransform() {
     this.worldAlpha = 1;
@@ -98,7 +98,7 @@ export class Stage extends DisplayObject {
   }
 
   /**
-   * TBD.
+   * Destroys the stage and cleans up resources.
    */
   destroy() {
     this.exists = false;
@@ -108,30 +108,30 @@ export class Stage extends DisplayObject {
   }
 
   /**
-   * TBD.
-   * @returns {number} TBD.
+   * Gets the background color of the stage.
+   * @returns {number} The background color.
    */
   get backgroundColor() {
     return this._bgColor.color;
   }
 
   /**
-   * TBD.
+   * Sets the background color of the stage.
    */
   set backgroundColor(value) {
     this.setBackgroundColor(value);
   }
 
   /**
-   * TBD.
-   * @returns {boolean} TBD.
+   * Gets whether texture smoothing is enabled.
+   * @returns {boolean} True if texture smoothing is enabled, false otherwise.
    */
   get smoothed() {
     return window.PhaserRegistry.TEXTURE_SCALE_MODE === SCALE_LINEAR;
   }
 
   /**
-   * TBD.
+   * Sets whether texture smoothing is enabled.
    */
   set smoothed(value) {
     window.PhaserRegistry.TEXTURE_SCALE_MODE = value ? SCALE_LINEAR : SCALE_NEAREST;