@vpmedia/phaser 1.116.0 → 1.118.0

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

@@ -0,0 +1,115 @@
+import { describe, expect, it } from 'vitest';
+import type { BaseTexture } from '../display/webgl/base_texture.js';
+import { bitmapFont, jsonBitmapFont, xmlBitmapFont } from './loader_parser.js';
+
+const baseTexture = { width: 256, height: 256 } as unknown as BaseTexture;
+
+const parseXml = (markup: string): XMLDocument => new DOMParser().parseFromString(markup, 'text/xml');
+
+const FONT_XML = `<?xml version="1.0"?>
+<font>
+  <info face="Arial" size="32" />
+  <common lineHeight="40" />
+  <chars>
+    <char id="65" x="0" y="0" width="20" height="30" xoffset="1" yoffset="2" xadvance="21" />
+    <char id="66" x="20" y="0" width="22" height="30" xoffset="0" yoffset="2" xadvance="23" />
+  </chars>
+  <kernings>
+    <kerning first="65" second="66" amount="-3" />
+  </kernings>
+</font>`;
+
+const FONT_JSON = {
+  font: {
+    info: { _face: 'Arial', _size: '32' },
+    common: { _lineHeight: '40' },
+    chars: {
+      char: [
+        { _id: '65', _x: '0', _y: '0', _width: '20', _height: '30', _xoffset: '1', _yoffset: '2', _xadvance: '21' },
+        { _id: '66', _x: '20', _y: '0', _width: '22', _height: '30', _xoffset: '0', _yoffset: '2', _xadvance: '23' },
+      ],
+    },
+    kernings: { kerning: [{ _first: '65', _second: '66', _amount: '-3' }] },
+  },
+};
+
+describe('bitmap font parsing', () => {
+  describe('xmlBitmapFont', () => {
+    it('reads the font metrics', () => {
+      const data = xmlBitmapFont(parseXml(FONT_XML), baseTexture, 0, 0);
+      expect(data.font).toBe('Arial');
+      expect(data.size).toBe(32);
+      expect(data.lineHeight).toBe(40);
+    });
+
+    it('reads every glyph, keyed by character code', () => {
+      const data = xmlBitmapFont(parseXml(FONT_XML), baseTexture, 0, 0);
+      expect(Object.keys(data.chars)).toStrictEqual(['65', '66']);
+      expect(data.chars[65]).toMatchObject({ x: 0, y: 0, width: 20, height: 30, xOffset: 1, yOffset: 2 });
+    });
+
+    it('adds the spacing arguments to advance and line height', () => {
+      const data = xmlBitmapFont(parseXml(FONT_XML), baseTexture, 5, 7);
+      expect(data.chars[65]?.xAdvance).toBe(26);
+      expect(data.lineHeight).toBe(47);
+    });
+
+    it('records kerning against the second character of the pair', () => {
+      const data = xmlBitmapFont(parseXml(FONT_XML), baseTexture, 0, 0);
+      expect(data.chars[66]?.kerning[65]).toBe(-3);
+    });
+
+    it('attaches a texture to every glyph', () => {
+      const data = xmlBitmapFont(parseXml(FONT_XML), baseTexture, 0, 0);
+      expect(data.chars[65]?.texture).toBeDefined();
+      expect(data.chars[66]?.texture).toBeDefined();
+    });
+
+    it('survives a font with no kerning table', () => {
+      const markup = FONT_XML.replace(/<kernings>[\s\S]*<\/kernings>/, '');
+      expect(() => xmlBitmapFont(parseXml(markup), baseTexture, 0, 0)).not.toThrow();
+    });
+
+    it('ignores kerning that names a character the font does not have', () => {
+      const markup = FONT_XML.replace('second="66"', 'second="999"');
+      const data = xmlBitmapFont(parseXml(markup), baseTexture, 0, 0);
+      expect(data.chars[66]?.kerning).toStrictEqual({});
+    });
+
+    it('falls back to an empty face when the info element is missing', () => {
+      const markup = FONT_XML.replace(/<info[^>]*\/>/, '');
+      expect(xmlBitmapFont(parseXml(markup), baseTexture, 0, 0).font).toBe('');
+    });
+  });
+
+  describe('jsonBitmapFont', () => {
+    it('reads the same metrics as the xml form', () => {
+      const data = jsonBitmapFont(FONT_JSON, baseTexture, 0, 0);
+      expect(data.font).toBe('Arial');
+      expect(data.size).toBe(32);
+      expect(data.lineHeight).toBe(40);
+    });
+
+    it('produces the same glyphs as the xml form', () => {
+      const fromJson = jsonBitmapFont(FONT_JSON, baseTexture, 0, 0);
+      const fromXml = xmlBitmapFont(parseXml(FONT_XML), baseTexture, 0, 0);
+      for (const code of [65, 66]) {
+        expect(fromJson.chars[code]).toMatchObject({
+          x: fromXml.chars[code]!.x,
+          width: fromXml.chars[code]!.width,
+          xAdvance: fromXml.chars[code]!.xAdvance,
+        });
+      }
+    });
+
+    it('records the same kerning as the xml form', () => {
+      expect(jsonBitmapFont(FONT_JSON, baseTexture, 0, 0).chars[66]?.kerning[65]).toBe(-3);
+    });
+  });
+
+  describe('bitmapFont', () => {
+    it('parses the xml form', () => {
+      expect(bitmapFont(parseXml(FONT_XML), baseTexture, 0, 0).font).toBe('Arial');
+    });
+  });
+});

package/src/phaser/core/loader_parser.ts

@@ -2,17 +2,37 @@ import { Texture } from '../display/webgl/texture.js';
 import { Rectangle } from '../geom/rectangle.js';
 import type { BaseTexture } from '../display/webgl/base_texture.js';
 
+/** One glyph in a bitmap font, as parsed from the font descriptor. */
+export type BitmapFontChar = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  xOffset: number;
+  yOffset: number;
+  xAdvance: number;
+  kerning: Record<number, number>;
+  texture?: Texture;
+};
+
+/** A parsed bitmap font: its metrics and the glyphs it can draw. */
+export type BitmapFontData = {
+  font: string;
+  size: number;
+  lineHeight: number;
+  chars: Record<number, BitmapFontChar>;
+};
+
 /**
  * Finalizes bitmap font data by attaching textures to characters.
  * @param {BaseTexture} baseTexture - The base texture for the font.
  * @param {object} bitmapFontData - The bitmap font data to finalize.
  * @returns {object} The finalized bitmap font data.
  */
-export const finalizeBitmapFont = (baseTexture: BaseTexture, bitmapFontData: any) => {
-  Object.keys(bitmapFontData.chars).forEach((charCode) => {
-    const letter = bitmapFontData.chars[charCode];
+export const finalizeBitmapFont = (baseTexture: BaseTexture, bitmapFontData: BitmapFontData): BitmapFontData => {
+  for (const letter of Object.values(bitmapFontData.chars)) {
     letter.texture = new Texture(baseTexture, new Rectangle(letter.x, letter.y, letter.width, letter.height));
-  });
+  }
   return bitmapFontData;
 };
 
@@ -24,34 +44,38 @@ export const finalizeBitmapFont = (baseTexture: BaseTexture, bitmapFontData: any
  * @param {number} ySpacing - Vertical spacing between characters.
  * @returns {object} The parsed bitmap font data.
  */
-export const xmlBitmapFont = (xml: any, baseTexture: BaseTexture, xSpacing: number, ySpacing: number) => {
-  const data: any = {};
+export const xmlBitmapFont = (
+  xml: XMLDocument,
+  baseTexture: BaseTexture,
+  xSpacing: number,
+  ySpacing: number
+): BitmapFontData => {
   const info = xml.querySelectorAll('info')[0];
   const common = xml.querySelectorAll('common')[0];
-  data.font = info.getAttribute('face');
-  data.size = Math.trunc(Number(info.getAttribute('size')));
-  data.lineHeight = Math.trunc(Number(common.getAttribute('lineHeight'))) + ySpacing;
-  data.chars = {};
-  const letters = xml.querySelectorAll('char');
-  for (let i = 0; i < letters.length; i += 1) {
-    const charCode = Math.trunc(Number(letters[i].getAttribute('id')));
-    data.chars[charCode] = {
-      x: Math.trunc(Number(letters[i].getAttribute('x'))),
-      y: Math.trunc(Number(letters[i].getAttribute('y'))),
-      width: Math.trunc(Number(letters[i].getAttribute('width'))),
-      height: Math.trunc(Number(letters[i].getAttribute('height'))),
-      xOffset: Math.trunc(Number(letters[i].getAttribute('xoffset'))),
-      yOffset: Math.trunc(Number(letters[i].getAttribute('yoffset'))),
-      xAdvance: Math.trunc(Number(letters[i].getAttribute('xadvance'))) + xSpacing,
+  const attr = (element: Element | undefined, name: string): number => Math.trunc(Number(element?.getAttribute(name)));
+  const data: BitmapFontData = {
+    font: info?.getAttribute('face') ?? '',
+    size: attr(info, 'size'),
+    lineHeight: attr(common, 'lineHeight') + ySpacing,
+    chars: {},
+  };
+  for (const letter of xml.querySelectorAll('char')) {
+    data.chars[attr(letter, 'id')] = {
+      x: attr(letter, 'x'),
+      y: attr(letter, 'y'),
+      width: attr(letter, 'width'),
+      height: attr(letter, 'height'),
+      xOffset: attr(letter, 'xoffset'),
+      yOffset: attr(letter, 'yoffset'),
+      xAdvance: attr(letter, 'xadvance') + xSpacing,
       kerning: {},
     };
   }
-  const kernings = xml.querySelectorAll('kerning');
-  for (let i = 0; i < kernings.length; i += 1) {
-    const first = Math.trunc(Number(kernings[i].getAttribute('first')));
-    const second = Math.trunc(Number(kernings[i].getAttribute('second')));
-    const amount = Math.trunc(Number(kernings[i].getAttribute('amount')));
-    data.chars[second].kerning[first] = amount;
+  for (const kerning of xml.querySelectorAll('kerning')) {
+    const char = data.chars[attr(kerning, 'second')];
+    if (char) {
+      char.kerning[attr(kerning, 'first')] = attr(kerning, 'amount');
+    }
   }
   return finalizeBitmapFont(baseTexture, data);
 };
@@ -64,8 +88,12 @@ export const xmlBitmapFont = (xml: any, baseTexture: BaseTexture, xSpacing: numb
  * @param {number} ySpacing - Vertical spacing between characters.
  * @returns {object} The parsed bitmap font data.
  */
-export const bitmapFont = (xml: any, baseTexture: BaseTexture, xSpacing: number, ySpacing: number) =>
-  xmlBitmapFont(xml, baseTexture, xSpacing, ySpacing);
+export const bitmapFont = (
+  xml: XMLDocument,
+  baseTexture: BaseTexture,
+  xSpacing: number,
+  ySpacing: number
+): BitmapFontData => xmlBitmapFont(xml, baseTexture, xSpacing, ySpacing);
 
 /**
  * Parses JSON bitmap font data.
@@ -75,19 +103,19 @@ export const bitmapFont = (xml: any, baseTexture: BaseTexture, xSpacing: number,
  * @param {number} ySpacing - Vertical spacing between characters.
  * @returns {object} The parsed bitmap font data.
  */
-export const jsonBitmapFont = (json: any, baseTexture: BaseTexture, xSpacing: number, ySpacing: number) => {
-  const data: {
-    font: string;
-    size: number;
-    lineHeight: number;
-    chars: Record<number, { kerning: Record<number, number>; [key: string]: unknown }>;
-  } = {
+export const jsonBitmapFont = (
+  json: any,
+  baseTexture: BaseTexture,
+  xSpacing: number,
+  ySpacing: number
+): BitmapFontData => {
+  const data: BitmapFontData = {
     font: json.font.info._face,
     size: Math.trunc(Number(json.font.info._size)),
     lineHeight: Math.trunc(Number(json.font.common._lineHeight)) + ySpacing,
     chars: {},
   };
-  json.font.chars.char.forEach((letter: Record<string, string>) => {
+  json.font.chars.char.forEach((letter: Record<string, string>): void => {
     const charCode = Math.trunc(Number(letter['_id']));
     data.chars[charCode] = {
       x: Math.trunc(Number(letter['_x'])),
@@ -101,7 +129,7 @@ export const jsonBitmapFont = (json: any, baseTexture: BaseTexture, xSpacing: nu
     };
   });
   if (json.font.kernings && json.font.kernings.kerning) {
-    json.font.kernings.kerning.forEach((kerning: Record<string, string>) => {
+    json.font.kernings.kerning.forEach((kerning: Record<string, string>): void => {
       const char = data.chars[Math.trunc(Number(kerning['_second']))];
       if (char) {
         char.kerning[Math.trunc(Number(kerning['_first']))] = Math.trunc(Number(kerning['_amount']));

package/src/phaser/core/raf.ts

@@ -15,14 +15,14 @@ export class RequestAnimationFrame {
   /**
    * Starts an animation frame request.
    */
-  public start = () => {
+  public start = (): void => {
     this.rafId = requestAnimationFrame(this.update);
   };
 
   /**
    * Cancels an animation frame request.
    */
-  public stop = () => {
+  public stop = (): void => {
     cancelAnimationFrame(this.rafId);
   };
 
@@ -30,7 +30,7 @@ export class RequestAnimationFrame {
    * Performs an animation frame request.
    * @param {number} rafTime - The timestamp provided by the browser's animation frame.
    */
-  public update = (rafTime: number) => {
+  public update = (rafTime: number): void => {
     this.game.update(rafTime);
     this.rafId = requestAnimationFrame(this.update);
   };