@vpmedia/phaser 1.117.0 → 1.119.0

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

package/src/phaser/display/webgl/renderer.ts

@@ -71,7 +71,7 @@ export class WebGLRenderer {
     this.height = game.height;
     this.view = game.canvas;
     this._contextOptions = {
-      alpha: game.config.transparent,
+      alpha: Boolean(game.config.transparent),
       depth: false,
       antialias: game.config.antialias,
       premultipliedAlpha: game.config.transparent && game.config.transparent !== 'notMultiplied',