@vpmedia/phaser 1.117.0 → 1.118.0

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();
     }
   }
 }

package/src/phaser/display/bitmap_text.test.ts

@@ -0,0 +1,212 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+import { SCALE_LINEAR } from '../core/const.js';
+import { getRegistry } from '../core/registry.js';
+import { Rectangle } from '../geom/rectangle.js';
+import { BaseTexture } from './webgl/base_texture.js';
+import { Texture } from './webgl/texture.js';
+import type { BitmapFontCacheEntry } from '../core/cache.js';
+import type { Game } from '../core/game.js';
+import type { BitmapFontData } from '../core/loader_parser.js';
+import { BitmapText } from './bitmap_text.js';
+
+getRegistry().TEXTURE_SCALE_MODE = SCALE_LINEAR;
+
+const createBaseTexture = (): BaseTexture => {
+  const base = new BaseTexture(null);
+  base.hasLoaded = true;
+  base.width = 256;
+  base.height = 256;
+  return base;
+};
+
+const atlas = createBaseTexture();
+
+const glyph = (code: number, width: number): [number, BitmapFontData['chars'][number]] => [
+  code,
+  {
+    x: 0,
+    y: 0,
+    width,
+    height: 10,
+    xOffset: 0,
+    yOffset: 0,
+    xAdvance: width,
+    kerning: {},
+    texture: new Texture(atlas, new Rectangle(0, 0, width, 10)),
+  },
+];
+
+const FONT: BitmapFontData = {
+  font: 'test',
+  size: 10,
+  lineHeight: 12,
+  chars: Object.fromEntries([
+    glyph(32, 5), // space
+    glyph(65, 10), // A
+    glyph(66, 10), // B
+  ]),
+};
+
+const createGame = (font: BitmapFontData | null = FONT): Game =>
+  ({
+    cache: {
+      getBitmapFont: (): BitmapFontCacheEntry | null =>
+        font === null ? null : ({ url: '', data: null, font, base: {} } as unknown as BitmapFontCacheEntry),
+    },
+    stage: { currentRenderOrderID: 0 },
+  }) as unknown as Game;
+
+const createText = (text: string, size = 10): BitmapText => new BitmapText(createGame(), 0, 0, 'test', text, size);
+
+describe('BitmapText', () => {
+  beforeEach(() => {
+    getRegistry().CACHE_MISSING_IMAGE = new Texture(atlas, new Rectangle(0, 0, 1, 1));
+  });
+
+  describe('updateText', () => {
+    it('measures a single line from the glyph advances', () => {
+      const bitmapText = createText('AB');
+      expect(bitmapText.textWidth).toBe(20);
+      expect(bitmapText.textHeight).toBe(12);
+    });
+
+    it('scales the metrics with the font size', () => {
+      const bitmapText = createText('AB', 20);
+      expect(bitmapText.textWidth).toBe(40);
+      expect(bitmapText.textHeight).toBe(24);
+    });
+
+    it('splits on a newline and takes the widest line as the width', () => {
+      const bitmapText = createText('AB\nA');
+      expect(bitmapText.textWidth).toBe(20);
+      expect(bitmapText.textHeight).toBe(24);
+    });
+
+    it('creates one glyph sprite per character', () => {
+      expect(createText('AB')._glyphs).toHaveLength(2);
+    });
+
+    it('reuses the glyph pool when the text shrinks', () => {
+      const bitmapText = createText('AB');
+      const pooled = bitmapText._glyphs;
+      bitmapText.text = 'A';
+      expect(bitmapText._glyphs).toBe(pooled);
+      expect(bitmapText._glyphs).toHaveLength(2);
+      expect(bitmapText.children).toHaveLength(1);
+    });
+
+    it('drops the glyphs that left the display list when purged', () => {
+      const bitmapText = createText('AB');
+      bitmapText.text = 'A';
+      expect(bitmapText.purgeGlyphs()).toBe(1);
+      expect(bitmapText._glyphs).toHaveLength(1);
+    });
+
+    it('lays out an empty string as a single empty line', () => {
+      const bitmapText = createText('');
+      expect(bitmapText.textWidth).toBe(0);
+      expect(bitmapText.textHeight).toBe(12);
+      expect(bitmapText._glyphs).toHaveLength(0);
+    });
+
+    it('does nothing when the font is not in the cache', () => {
+      const bitmapText = new BitmapText(createGame(null), 0, 0, 'missing', 'AB');
+      expect(bitmapText.textWidth).toBe(0);
+      expect(bitmapText._glyphs).toHaveLength(0);
+    });
+  });
+
+  describe('scanLine', () => {
+    it('reports the whole text when nothing forces a wrap', () => {
+      const line = createText('AB').scanLine(FONT, 1, 'AB');
+      expect(line).toMatchObject({ width: 20, text: 'AB', end: true, chars: [0, 10] });
+    });
+
+    it('stops at a newline and reports the line as unfinished', () => {
+      const line = createText('AB').scanLine(FONT, 1, 'AB\nA');
+      expect(line.text).toBe('AB');
+      expect(line.end).toBe(false);
+    });
+
+    it('wraps at the last space once maxWidth is exceeded', () => {
+      const bitmapText = createText('A A');
+      bitmapText.maxWidth = 20;
+      expect(bitmapText.scanLine(FONT, 1, 'A A').text).toBe('A');
+    });
+
+    it('substitutes a space for a character the font does not carry', () => {
+      const line = createText('A').scanLine(FONT, 1, 'Z');
+      expect(line.width).toBe(5);
+    });
+
+    it('skips a character the font cannot even substitute for', () => {
+      const spaceless: BitmapFontData = { ...FONT, chars: Object.fromEntries([glyph(65, 10)]) };
+      expect(createText('A').scanLine(spaceless, 1, 'AZ').width).toBe(10);
+    });
+  });
+
+  describe('cleanText', () => {
+    it('drops characters the font does not carry', () => {
+      expect(createText('A').cleanText('AZB')).toBe('AB');
+    });
+
+    it('replaces them with the given stand-in', () => {
+      expect(createText('A').cleanText('AZB', '?')).toBe('A?B');
+    });
+
+    it('keeps line breaks', () => {
+      expect(createText('A').cleanText('A\nB')).toBe('A\nB');
+    });
+  });
+
+  describe('properties', () => {
+    it('re-lays out when the alignment changes', () => {
+      const bitmapText = createText('A\nAB');
+      bitmapText.align = 'right';
+      expect(bitmapText.align).toBe('right');
+      expect(bitmapText._glyphs[0]?.position.x).toBe(10);
+    });
+
+    it('ignores an alignment it does not know', () => {
+      const bitmapText = createText('A');
+      bitmapText.align = 'sideways';
+      expect(bitmapText.align).toBe('left');
+    });
+
+    it('coerces a string font size', () => {
+      const bitmapText = createText('A');
+      bitmapText.fontSize = '20';
+      expect(bitmapText.fontSize).toBe(20);
+    });
+
+    it('ignores a font size of zero or less', () => {
+      const bitmapText = createText('A');
+      bitmapText.fontSize = -5;
+      expect(bitmapText.fontSize).toBe(10);
+    });
+
+    it('renders the tint as a padded hex string', () => {
+      const bitmapText = createText('A');
+      bitmapText.tint = 0x00ff00;
+      expect(bitmapText.fill).toBe('#00FF00');
+    });
+
+    it('reads a hex string back into the tint', () => {
+      const bitmapText = createText('A');
+      bitmapText.fill = '#FF0000';
+      expect(bitmapText.tint).toBe(0xff0000);
+    });
+
+    it('trims the font key before looking it up', () => {
+      const bitmapText = createText('A');
+      bitmapText.font = '  other  ';
+      expect(bitmapText.font).toBe('other');
+    });
+
+    it('stringifies whatever the text is set to', () => {
+      const bitmapText = createText('A');
+      bitmapText.text = 65;
+      expect(bitmapText.text).toBe('65');
+    });
+  });
+});

package/src/phaser/display/bitmap_text.ts

@@ -2,7 +2,18 @@ import { BITMAP_TEXT, SCALE_LINEAR, SCALE_NEAREST } from '../core/const.js';
 import { Point } from '../geom/point.js';
 import { DisplayObject } from './display_object.js';
 import { Image } from './image.js';
+import type { BitmapFontCacheEntry } from '../core/cache.js';
 import type { Game } from '../core/game.js';
+import type { BitmapFontData } from '../core/loader_parser.js';
+
+/** One measured line of bitmap text: its width, its content and where each glyph starts. */
+export type BitmapTextLine = {
+  width: number;
+  text: string;
+  end: boolean;
+  chars: number[];
+  y: number;
+};
 
 export class BitmapText extends DisplayObject {
   declare public type: number;
@@ -14,7 +25,7 @@ export class BitmapText extends DisplayObject {
   public _glyphs!: Image[];
   public _maxWidth!: number;
   public _text!: string;
-  public _data!: any;
+  public _data!: BitmapFontCacheEntry | null;
   public _font!: string;
   public _fontSize!: number;
   public _align!: string;
@@ -97,14 +108,14 @@ export class BitmapText extends DisplayObject {
    * @param {string} text - The text to scan.
    * @returns {{width: number, text: string, end: boolean, chars: number[]}} An object containing the width, processed text, end status, and character positions.
    */
-  public scanLine(data: any, scale: number, text: string) {
+  public scanLine(data: BitmapFontData, scale: number, text: string): Omit<BitmapTextLine, 'y'> {
     let x = 0;
     let w = 0;
     let lastSpace = -1;
     let wrappedWidth = 0;
     let prevCharCode = null;
     const maxWidth = this._maxWidth > 0 ? this._maxWidth : null;
-    const chars = [];
+    const chars: number[] = [];
     //  Let's scan the text and work out if any of the lines are > maxWidth
     let end = true;
     for (let i = 0; i < text.length; i += 1) {
@@ -126,15 +137,18 @@ export class BitmapText extends DisplayObject {
         charCode = 32;
         charData = data.chars[charCode];
       }
+      if (charData === undefined) {
+        continue;
+      }
       //  Adjust for kerning from previous character to this one
-      const kerning = prevCharCode && charData.kerning[prevCharCode] ? charData.kerning[prevCharCode] : 0;
+      const kerning = (prevCharCode === null ? 0 : charData.kerning[prevCharCode]) ?? 0;
       //  Record the last space in the string and the current width
       if (/(\s)/.test(text.charAt(i))) {
         lastSpace = i;
         wrappedWidth = w;
       }
       //  What will the line width be if we add this character to it?
-      c = (kerning + charData.texture.width + charData.xOffset) * scale;
+      c = (kerning + (charData.texture?.width ?? 0) + charData.xOffset) * scale;
       //  Do we need to line-wrap?
       if (maxWidth && w + c >= maxWidth && lastSpace > -1) {
         //  The last space was at "lastSpace" which was "i - lastSpace" characters ago
@@ -165,7 +179,7 @@ export class BitmapText extends DisplayObject {
    * @returns {string} The cleaned text.
    */
   public cleanText(text: string, replace = ''): string {
-    const data = this._data.font;
+    const data = this._data?.font;
     if (!data) {
       return '';
     }
@@ -190,26 +204,26 @@ export class BitmapText extends DisplayObject {
    * Updates the internal text rendering based on current properties and content.
    */
   public updateText(): void {
-    const data = this._data.font;
+    const data = this._data?.font;
     if (!data) {
       return;
     }
-    let text: any = this.text;
+    let text = this.text;
     const scale = this._fontSize / data.size;
-    const lines = [];
+    const lines: BitmapTextLine[] = [];
     let y = 0;
     this.textWidth = 0;
-    let line: any = { end: text.length === 0 };
+    let end = false;
     do {
-      line = this.scanLine(data, scale, text);
-      line.y = y;
+      const line: BitmapTextLine = { ...this.scanLine(data, scale, text), y };
       lines.push(line);
       if (line.width > this.textWidth) {
         this.textWidth = line.width;
       }
       y += data.lineHeight * scale;
       text = text.slice(line.text.length + 1);
-    } while (line.end === false);
+      end = line.end;
+    } while (!end);
     this.textHeight = y;
     let t = 0;
     let align = 0;
@@ -228,6 +242,9 @@ export class BitmapText extends DisplayObject {
           charCode = 32;
           charData = data.chars[charCode];
         }
+        if (charData?.texture === undefined) {
+          continue;
+        }
         let g = this._glyphs[t];
         if (g) {
           // Sprite already exists in the glyphs pool, so we'll reuse it for this letter
@@ -235,10 +252,10 @@ export class BitmapText extends DisplayObject {
         } else {
           // We need a new sprite as the pool is empty or exhausted
           g = new Image(this.game, 0, 0, charData.texture);
-          g.name = currentLine.text[c];
+          g.name = currentLine.text[c] ?? '';
           this._glyphs.push(g);
         }
-        g.position.x = currentLine.chars[c] + align - ax;
+        g.position.x = (currentLine.chars[c] ?? 0) + align - ax;
         g.position.y = currentLine.y + charData.yOffset * scale - ay;
         g.scale.setTo(scale, scale);
         g.tint = this.tint;
@@ -398,10 +415,10 @@ export class BitmapText extends DisplayObject {
    * Sets the font size of this bitmap text.
    * @param {number} value - The new font size to use.
    */
-  public set fontSize(value: any) {
-    value = Math.trunc(Number(value));
-    if (value !== this._fontSize && value > 0) {
-      this._fontSize = value;
+  public set fontSize(value: number | string) {
+    const size = Math.trunc(Number(value));
+    if (size !== this._fontSize && size > 0) {
+      this._fontSize = size;
       this.updateText();
     }
   }
@@ -450,7 +467,7 @@ export class BitmapText extends DisplayObject {
    * @returns {boolean} True if smoothing is enabled, false otherwise.
    */
   public get smoothed(): boolean {
-    return !this._data.base.scaleMode;
+    return !this._data?.base.scaleMode;
   }
 
   /**
@@ -458,10 +475,8 @@ export class BitmapText extends DisplayObject {
    * @param {boolean} value - Whether to enable smoothing (true) or not (false).
    */
   public set smoothed(value: boolean) {
-    if (value) {
-      this._data.base.scaleMode = SCALE_LINEAR;
-    } else {
-      this._data.base.scaleMode = SCALE_NEAREST;
+    if (this._data) {
+      this._data.base.scaleMode = value ? SCALE_LINEAR : SCALE_NEAREST;
     }
   }
 }