@vpmedia/phaser 1.117.0 → 1.119.0

package/src/phaser/core/scene_manager.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it, vi } from 'vitest';
+import { Scene } from './scene.js';
+import { SceneManager } from './scene_manager.js';
+import type { Game } from './game.js';
+import type { SceneState } from './scene_manager.js';
+
+const createGame = (isBooted = true): Game =>
+  ({
+    isBooted,
+    isKickStart: false,
+    world: { x: 0, y: 0, destroy: vi.fn() },
+    tweens: { removeAll: vi.fn() },
+    input: { reset: vi.fn() },
+    time: { removeAll: vi.fn() },
+    scale: { reset: vi.fn() },
+    cache: { destroy: vi.fn() },
+    load: { reset: vi.fn(), start: vi.fn(), totalQueuedFiles: (): number => 0, totalQueuedPacks: (): number => 0 },
+  }) as unknown as Game;
+
+const createManager = (pendingState: ConstructorParameters<typeof SceneManager>[1] = null): SceneManager =>
+  new SceneManager(createGame(), pendingState);
+
+describe('SceneManager', () => {
+  describe('add', () => {
+    it('takes a plain hook object and links the game onto it', () => {
+      const manager = createManager();
+      const state: SceneState = { create: vi.fn<() => void>() };
+      expect(manager.add('menu', state)).toBe(state);
+      expect(state.game).toBeDefined();
+    });
+
+    it('builds a state from a constructor', () => {
+      const manager = createManager();
+      class Menu extends Scene {}
+      expect(manager.add('menu', Menu)).toBeInstanceOf(Menu);
+    });
+
+    it('takes a scene instance as-is', () => {
+      const manager = createManager();
+      const scene = new Scene();
+      expect(manager.add('menu', scene)).toBe(scene);
+    });
+
+    it('queues the state when the game has not booted', () => {
+      const manager = new SceneManager(createGame(false), null);
+      manager.add('menu', { create: vi.fn<() => void>() }, true);
+      expect(manager._pendingState).toBe('menu');
+    });
+
+    it('starts the state right away once the game has booted', () => {
+      const manager = createManager();
+      manager.add('menu', { create: vi.fn<() => void>() }, true);
+      expect(manager._pendingState).toBe('menu');
+    });
+  });
+
+  describe('boot', () => {
+    it('registers a state given as an object under the default key', () => {
+      const manager = createManager({ create: vi.fn<() => void>() });
+      manager.boot();
+      expect(manager.states['default']).toBeDefined();
+    });
+
+    it('leaves a state given by key alone', () => {
+      const manager = createManager('menu');
+      manager.boot();
+      expect(manager.states['default']).toBeUndefined();
+    });
+  });
+
+  describe('checkState', () => {
+    it('accepts a state carrying any of the lifecycle hooks', () => {
+      const manager = createManager();
+      manager.add('menu', { update: vi.fn<() => void>() });
+      expect(manager.checkState('menu')).toBe(true);
+    });
+
+    it('rejects a state with no hooks at all', () => {
+      const manager = createManager();
+      manager.add('menu', {});
+      expect(manager.checkState('menu')).toBe(false);
+    });
+
+    it('rejects a key it does not hold', () => {
+      expect(createManager().checkState('nope')).toBe(false);
+    });
+  });
+
+  describe('setCurrentState', () => {
+    it('binds the hooks the state provides and leaves the rest null', () => {
+      const manager = createManager();
+      const create = vi.fn<() => void>();
+      manager.add('menu', { create });
+      manager.setCurrentState('menu');
+      expect(manager.current).toBe('menu');
+      expect(manager.onCreateCallback).toBe(create);
+      expect(manager.onUpdateCallback).toBeNull();
+      expect(manager.onPreloadCallback).toBeNull();
+    });
+
+    it('falls back to a no-op for init and shutdown', () => {
+      const manager = createManager();
+      manager.add('menu', {});
+      manager.setCurrentState('menu');
+      expect(manager.onInitCallback).toBe(manager.dummy);
+      expect(manager.onShutDownCallback).toBe(manager.dummy);
+    });
+
+    it('calls init with the arguments start was given', () => {
+      const manager = createManager();
+      const init = vi.fn<() => void>();
+      manager.add('menu', { init, update: vi.fn<() => void>() });
+      manager.start('menu', true, false, 'a', 1);
+      manager.setCurrentState('menu');
+      expect(init).toHaveBeenCalledWith('a', 1);
+    });
+
+    it('stamps the key onto the state', () => {
+      const manager = createManager();
+      const state: SceneState = { create: vi.fn<() => void>() };
+      manager.add('menu', state);
+      manager.setCurrentState('menu');
+      expect(state.key).toBe('menu');
+    });
+  });
+
+  describe('start', () => {
+    it('ignores a key with no lifecycle hooks', () => {
+      const manager = createManager();
+      manager.add('menu', {});
+      manager.start('menu');
+      expect(manager._pendingState).toBeNull();
+    });
+  });
+
+  describe('update', () => {
+    it('runs the update hook only once the scene has been created', () => {
+      const manager = createManager();
+      const update = vi.fn<() => void>();
+      manager.add('menu', { update });
+      manager.setCurrentState('menu');
+      manager.update();
+      expect(update).not.toHaveBeenCalled();
+      manager.loadComplete();
+      manager.update();
+      expect(update).toHaveBeenCalledTimes(1);
+    });
+
+    it('runs the create hook exactly once', () => {
+      const manager = createManager();
+      const create = vi.fn<() => void>();
+      manager.add('menu', { create });
+      manager.setCurrentState('menu');
+      manager.loadComplete();
+      manager.loadComplete();
+      expect(create).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('resize', () => {
+    it('passes the new size to the scene', () => {
+      const manager = createManager();
+      const resize = vi.fn<(width: number, height: number) => void>();
+      manager.add('menu', { resize });
+      manager.setCurrentState('menu');
+      manager.resize(320, 240);
+      expect(resize).toHaveBeenCalledWith(320, 240);
+    });
+  });
+
+  describe('remove', () => {
+    it('drops the state and unbinds its hooks when it is current', () => {
+      const manager = createManager();
+      manager.add('menu', { create: vi.fn<() => void>() });
+      manager.setCurrentState('menu');
+      manager.remove('menu');
+      expect(manager.states['menu']).toBeUndefined();
+      expect(manager.onCreateCallback).toBeNull();
+    });
+  });
+
+  describe('destroy', () => {
+    it('empties the manager', () => {
+      const manager = createManager();
+      manager.add('menu', { create: vi.fn<() => void>(), shutdown: vi.fn<() => void>() });
+      manager.setCurrentState('menu');
+      manager.destroy();
+      expect(manager.states).toStrictEqual({});
+      expect(manager.current).toBe('');
+      expect(manager._pendingState).toBeNull();
+    });
+  });
+});

package/src/phaser/core/scene_manager.ts

@@ -7,34 +7,47 @@ export type SceneHooks = {
   preload?: () => void;
   create?: () => void;
   update?: () => void;
+  render?: () => void;
   resize?: (width: number, height: number) => void;
   pauseUpdate?: () => void;
   shutdown?: () => void;
 };
 
+/** A scene once the manager holds it: its hooks plus the wiring the manager adds. */
+export type SceneState = SceneHooks & {
+  game?: Game | null;
+  key?: string;
+};
+
+/** What the manager accepts as a scene: an instance, a plain hook object, or a class to build one. */
+export type SceneDefinition = SceneState | (new (game: Game) => SceneState);
+
+/** A hook invoked with the scene as its receiver and the game as its argument. */
+type SceneCallback = (game: Game) => void;
+
 export class SceneManager {
   public game!: Game;
-  public states!: any;
-  public _pendingState!: any;
-  public _clearWorld!: any;
-  public _clearCache!: any;
-  public _created!: any;
-  public _args!: any;
+  public states!: Record<string, SceneState>;
+  public _pendingState!: SceneDefinition | string | null;
+  public _clearWorld!: boolean;
+  public _clearCache!: boolean;
+  public _created!: boolean;
+  public _args!: unknown[];
   public current!: string;
-  public onInitCallback!: any;
-  public onPreloadCallback!: any;
-  public onCreateCallback!: any;
-  public onUpdateCallback!: any;
-  public onResizeCallback!: any;
-  public onPauseUpdateCallback!: any;
-  public onShutDownCallback!: any;
-  public callbackContext!: SceneHooks;
+  public onInitCallback!: ((...args: unknown[]) => void) | null;
+  public onPreloadCallback!: SceneCallback | null;
+  public onCreateCallback!: SceneCallback | null;
+  public onUpdateCallback!: SceneCallback | null;
+  public onResizeCallback!: ((width: number, height: number) => void) | null;
+  public onPauseUpdateCallback!: SceneCallback | null;
+  public onShutDownCallback!: SceneCallback | null;
+  public callbackContext!: SceneState;
   /**
    * Creates a new SceneManager instance.
    * @param {Game} game - The game instance this manager belongs to.
    * @param {string} pendingState - The state to load when the game boots.
    */
-  public constructor(game: Game, pendingState: string) {
+  public constructor(game: Game, pendingState: SceneDefinition | string | null) {
     this.game = game;
     this.states = {};
     this._pendingState = null;
@@ -72,15 +85,15 @@ export class SceneManager {
    * @param {boolean} autoStart - Whether to start this state immediately.
    * @returns {Scene|object} The created scene or state object.
    */
-  public add(key: string, state: any, autoStart = false) {
-    let newState = null;
-    if (state instanceof Scene) {
-      newState = state;
-    } else if (typeof state === 'object') {
-      newState = state;
-      newState.game = this.game;
-    } else if (typeof state === 'function') {
+  public add(key: string, state: SceneDefinition, autoStart = false): SceneState {
+    let newState: SceneState;
+    if (typeof state === 'function') {
       newState = new state(this.game);
+    } else {
+      newState = state;
+      if (!(state instanceof Scene)) {
+        newState.game = this.game;
+      }
     }
     this.states[key] = newState;
     if (autoStart) {
@@ -149,7 +162,7 @@ export class SceneManager {
    * This method is called before the game loop updates.
    */
   public preUpdate(): void {
-    if (this._pendingState && this.game.isBooted) {
+    if (typeof this._pendingState === 'string' && this._pendingState && this.game.isBooted) {
       // var previousStateKey = this.current;
       //  Already got a state running?
       this.clearCurrentState();
@@ -207,11 +220,9 @@ export class SceneManager {
    * @returns {boolean} True if the scene exists, false otherwise.
    */
   public checkState(key: string): boolean {
-    if (this.states[key]) {
-      if (this.states[key].preload || this.states[key].create || this.states[key].update || this.states[key].render) {
-        return true;
-      }
-      return false;
+    const state = this.states[key];
+    if (state) {
+      return Boolean(state.preload ?? state.create ?? state.update ?? state.render);
     }
     return false;
   }
@@ -221,8 +232,11 @@ export class SceneManager {
    * @param {string} key - The unique key for the state to link.
    */
   public link(key: string): void {
-    this.states[key].game = this.game;
-    this.states[key].key = key;
+    const state = this.states[key];
+    if (state) {
+      state.game = this.game;
+      state.key = key;
+    }
   }
 
   /**
@@ -230,8 +244,9 @@ export class SceneManager {
    * @param {string} key - The unique key for the state to unlink.
    */
   public unlink(key: string): void {
-    if (this.states[key]) {
-      this.states[key].game = null;
+    const state = this.states[key];
+    if (state) {
+      state.game = null;
     }
   }
 
@@ -240,7 +255,7 @@ export class SceneManager {
    * @param {string} key - The unique key for the state to set as current.
    */
   public setCurrentState(key: string): void {
-    this.callbackContext = this.states[key];
+    this.callbackContext = this.states[key]!;
     this.link(key);
     //  Used when the state is set as being the current active state
     this.onInitCallback = this.callbackContext.init ?? this.dummy;
@@ -265,7 +280,7 @@ export class SceneManager {
    * @returns {T} The current scene state.
    */
   public getCurrentState<T = Partial<Scene>>(): T {
-    return this.states[this.current];
+    return this.states[this.current] as T;
   }
 
   /**
@@ -273,7 +288,7 @@ export class SceneManager {
    * This method is called when scene loading is complete.
    */
   public loadComplete(): void {
-    if (this._created === false && this.onCreateCallback) {
+    if (!this._created && this.onCreateCallback) {
       this._created = true;
       this.onCreateCallback.call(this.callbackContext, this.game);
     } else {

package/src/phaser/core/sound.ts

@@ -2,13 +2,24 @@ import { Signal } from './signal.js';
 import type { Game } from './game.js';
 import type { Tween } from './tween.js';
 
+/** A named span within a sound file. */
+export type SoundMarker = {
+  name: string;
+  start: number;
+  stop: number;
+  volume: number;
+  duration: number;
+  durationMS: number;
+  loop: boolean;
+};
+
 export class Sound {
-  public _paused!: any;
+  public _paused!: boolean;
   public game!: Game;
   public name!: string;
   public key!: string;
   public loop!: boolean;
-  public markers!: any;
+  public markers!: Record<string, SoundMarker>;
   public context!: AudioContext | null;
   public autoplay!: boolean;
   public totalDuration!: number;
@@ -124,8 +135,10 @@ export class Sound {
    */
   public soundHasUnlocked(key: string): void {
     if (key === this.key) {
-      this._sound = this.game.cache.getSoundData(this.key);
-      this.totalDuration = (this._sound as any).duration;
+      // Unlocking parks the decoded buffer in _sound; play() replaces it with a real source node.
+      const buffer = this.game.cache.getSoundData(this.key) as AudioBuffer;
+      this._sound = buffer as unknown as AudioBufferSourceNode;
+      this.totalDuration = buffer.duration;
     }
   }
 
@@ -246,7 +259,7 @@ export class Sound {
    * @param {boolean} forceRestart - Whether to force restarting the sound even if it's already playing.
    * @returns {Sound} This Sound instance for chaining.
    */
-  public play(marker: any = '', position: any = 0, volume: any = 1, loop: any = false, forceRestart = true): this {
+  public play(marker: string | false | null = '', position = 0, volume = 1, loop = false, forceRestart = true): this {
     if (marker === undefined || marker === false || marker === null) {
       marker = '';
     }
@@ -274,15 +287,16 @@ export class Sound {
       //  We should never play the entire thing
       return this;
     }
+    const markerData = marker === '' ? undefined : this.markers[marker];
     if (marker !== '') {
-      if (this.markers[marker]) {
+      if (markerData) {
         this.currentMarker = marker;
         //  Playing a marker? Then we default to the marker values
-        this.position = this.markers[marker].start;
-        this.volume = this.markers[marker].volume;
-        this.loop = this.markers[marker].loop;
-        this.duration = this.markers[marker].duration;
-        this.durationMS = this.markers[marker].durationMS;
+        this.position = markerData.start;
+        this.volume = markerData.volume;
+        this.loop = markerData.loop;
+        this.duration = markerData.duration;
+        this.durationMS = markerData.durationMS;
         if (volume !== undefined) {
           this.volume = volume;
         }
@@ -298,10 +312,8 @@ export class Sound {
         return this;
       }
     } else {
-      position = position ?? 0;
-      if (volume === undefined) {
-        volume = this._volume;
-      }
+      position ??= 0;
+      volume ??= this._volume;
       if (loop === undefined) {
         ({ loop } = this);
       }
@@ -323,7 +335,7 @@ export class Sound {
       } else {
         this._sound.connect(this.gainNode);
       }
-      this._buffer = this.game.cache.getSoundData(this.key);
+      this._buffer = this.game.cache.getSoundData(this.key) as AudioBuffer | null;
       this._sound.buffer = this._buffer;
       if (this.loop && marker === '') {
         this._sound.loop = true;
@@ -351,7 +363,7 @@ export class Sound {
       this.onPlay.dispatch(this);
     } else {
       this.pendingPlayback = true;
-      if (this.game.cache.getSound(this.key) && this.game.cache.getSound(this.key).isDecoding === false) {
+      if (this.game.cache.getSound(this.key)?.isDecoding === false) {
         this.game.sound.decode(this.key);
       }
     }

package/src/phaser/core/sound_manager.ts

@@ -272,7 +272,7 @@ export class SoundManager {
    */
   public decode(key: string): void {
     const soundData = this.game.cache.getSoundData(key);
-    if (!soundData) {
+    if (!(soundData instanceof ArrayBuffer)) {
       return;
     }
     if (this.game.cache.isSoundDecoded(key) === true) {

package/src/phaser/core/tween.ts

@@ -1,14 +1,14 @@
+import type { TweenTarget } from './tween_manager.js';
 import * as MathUtils from '../util/math.js';
 import { TWEEN_COMPLETE, TWEEN_LOOPED, TWEEN_PENDING, TWEEN_RUNNING } from './const.js';
 import { Signal } from './signal.js';
 import { TweenData } from './tween_data.js';
 import type { Game } from './game.js';
-import type { DisplayObject } from '../display/display_object.js';
 import type { TweenManager } from './tween_manager.js';
 
 export class Tween {
   public game!: Game;
-  public target!: DisplayObject;
+  public target!: TweenTarget;
   public manager!: TweenManager;
   public timeline!: TweenData[];
   public reverse!: boolean;
@@ -36,7 +36,7 @@ export class Tween {
    * @param {Game} game - Reference to the Phaser Game instance.
    * @param {TweenManager} manager - Reference to the Tween Manager.
    */
-  public constructor(target: DisplayObject, game: Game, manager: TweenManager) {
+  public constructor(target: TweenTarget, game: Game, manager: TweenManager) {
     this.game = game;
     this.target = target;
     /** @type {TweenManager} */
@@ -100,7 +100,7 @@ export class Tween {
     yoyo = false
   ): this {
     if (typeof ease === 'string' && this.manager.easeMap[ease]) {
-      ease = this.manager.easeMap[ease];
+      ease = this.manager.easeMap[ease]!;
     }
     if (this.isRunning) {
       return this;
@@ -133,7 +133,7 @@ export class Tween {
     yoyo = false
   ): this {
     if (typeof ease === 'string' && this.manager.easeMap[ease]) {
-      ease = this.manager.easeMap[ease];
+      ease = this.manager.easeMap[ease]!;
     }
     if (this.isRunning) {
       this.game.logger.warn('Tween.from cannot be called after Tween.start');
@@ -284,7 +284,7 @@ export class Tween {
    */
   public easing(ease: string | Function, index: number): this {
     if (typeof ease === 'string' && this.manager.easeMap[ease]) {
-      ease = this.manager.easeMap[ease];
+      ease = this.manager.easeMap[ease]!;
     }
     return this.updateTweenData('easingFunction', ease, index);
   }

package/src/phaser/core/tween_manager.ts

@@ -35,11 +35,14 @@ import {
   SinusoidalOut,
 } from './tween_easing.js';
 
+/** What a tween can be attached to: any object, or a list of them. */
+export type TweenTarget = object | object[];
+
 export class TweenManager {
   public game!: Game;
-  public _tweens!: any;
-  public _add!: any;
-  public easeMap!: any;
+  public _tweens!: Tween[];
+  public _add!: Tween[];
+  public easeMap!: Record<string, (k: number) => number>;
   /**
    * Creates a new TweenManager instance.
    * @param {Game} game - The game instance this manager belongs to.
@@ -112,8 +115,8 @@ export class TweenManager {
    * This method removes all active and pending tweens.
    */
   public removeAll(): void {
-    for (let i = 0; i < this._tweens.length; i += 1) {
-      this._tweens[i].pendingDelete = true;
+    for (const tween of this._tweens) {
+      tween.pendingDelete = true;
     }
     this._add = [];
   }
@@ -123,27 +126,28 @@ export class TweenManager {
    * @param {object} obj - The object to remove tweens from.
    * @param {object[]} children - Optional array of child objects to remove tweens from.
    */
-  public removeFrom(obj: any, children: any[] | null = null): void {
-    let i;
-    let len;
+  public removeFrom(obj: TweenTarget, children: object[] | null = null): void {
     if (Array.isArray(obj)) {
-      for (i = 0, len = obj.length; i < len; i += 1) {
-        this.removeFrom(obj[i]);
+      for (const entry of obj) {
+        this.removeFrom(entry);
       }
-    } else if (obj.type === GROUP && children) {
-      for (i = 0, len = obj.children.length; i < len; i += 1) {
-        this.removeFrom(obj.children[i]);
+      return;
+    }
+    const group = obj as { type?: number; children?: TweenTarget[] };
+    if (group.type === GROUP && children && group.children) {
+      for (const child of group.children) {
+        this.removeFrom(child);
       }
-    } else {
-      for (i = 0, len = this._tweens.length; i < len; i += 1) {
-        if (obj === this._tweens[i].target) {
-          this.remove(this._tweens[i]);
-        }
+      return;
+    }
+    for (const tween of this._tweens.slice()) {
+      if (obj === tween.target) {
+        this.remove(tween);
       }
-      for (i = 0, len = this._add.length; i < len; i += 1) {
-        if (obj === this._add[i].target) {
-          this.remove(this._add[i]);
-        }
+    }
+    for (const tween of this._add.slice()) {
+      if (obj === tween.target) {
+        this.remove(tween);
       }
     }
   }
@@ -162,7 +166,7 @@ export class TweenManager {
    * @param {object} object - The object to create a tween for.
    * @returns {Tween} The created Tween object.
    */
-  public create(object: any): Tween {
+  public create(object: TweenTarget): Tween {
     return new Tween(object, this.game, this);
   }
 
@@ -171,13 +175,16 @@ export class TweenManager {
    * @param {Tween | null | undefined} tween - The tween to remove.
    */
   public remove(tween: Tween | null | undefined): void {
+    if (!tween) {
+      return;
+    }
     let i = this._tweens.indexOf(tween);
     if (i !== -1) {
-      this._tweens[i].pendingDelete = true;
+      this._tweens[i]!.pendingDelete = true;
     } else {
       i = this._add.indexOf(tween);
       if (i !== -1) {
-        this._add[i].pendingDelete = true;
+        this._add[i]!.pendingDelete = true;
       }
     }
   }
@@ -194,7 +201,7 @@ export class TweenManager {
     }
     let i = 0;
     while (i < numTweens) {
-      if (this._tweens[i].update(this.game.time.time)) {
+      if (this._tweens[i]!.update(this.game.time.time)) {
         i += 1;
       } else {
         this._tweens.splice(i, 1);
@@ -215,7 +222,7 @@ export class TweenManager {
    * @returns {boolean} True if the object is being tweened, false otherwise.
    */
   public isTweening(object: unknown): boolean {
-    return (this._tweens as Tween[]).some((tween: Tween): boolean => tween.target === object);
+    return this._tweens.some((tween: Tween): boolean => tween.target === object);
   }
 
   /**
@@ -223,8 +230,8 @@ export class TweenManager {
    * This method pauses all active tweens.
    */
   public _pauseAll(): void {
-    for (let i = this._tweens.length - 1; i >= 0; i -= 1) {
-      this._tweens[i]._pause();
+    for (const tween of this._tweens) {
+      tween._pause();
     }
   }
 
@@ -233,8 +240,8 @@ export class TweenManager {
    * This method resumes all paused tweens.
    */
   public _resumeAll(): void {
-    for (let i = this._tweens.length - 1; i >= 0; i -= 1) {
-      this._tweens[i]._resume();
+    for (const tween of this._tweens) {
+      tween._resume();
     }
   }
 
@@ -243,8 +250,8 @@ export class TweenManager {
    * This method pauses all active tweens.
    */
   public pauseAll(): void {
-    for (let i = this._tweens.length - 1; i >= 0; i -= 1) {
-      this._tweens[i].pause();
+    for (const tween of this._tweens) {
+      tween.pause();
     }
   }
 
@@ -253,8 +260,8 @@ export class TweenManager {
    * This method resumes all paused tweens.
    */
   public resumeAll(): void {
-    for (let i = this._tweens.length - 1; i >= 0; i -= 1) {
-      this._tweens[i].resume(true);
+    for (const tween of this._tweens) {
+      tween.resume();
     }
   }
 }