@vpmedia/phaser 1.117.0 → 1.119.0

package/src/phaser/core/loader.ts

@@ -8,6 +8,37 @@ import { Signal } from './signal.js';
 
 const TEXTURE_ATLAS_JSON_HASH = 1;
 
+/**
+ * What a completed load carries. Which member applies is decided by the file's type, so the
+ * completion handlers narrow before handing it to the cache.
+ */
+/** One entry in a pack manifest: the arguments for the loader call it stands for. */
+export type PackEntry = {
+  type: string;
+  key: string;
+  url?: string;
+  overwrite?: boolean;
+  frameWidth?: number;
+  frameHeight?: number;
+  frameMax?: number;
+  margin?: number;
+  spacing?: number;
+  urls?: string[] | string;
+  autoDecode?: boolean;
+  textureURL?: string;
+  atlasURL?: string;
+  atlasData?: unknown;
+  audioURL?: string;
+  jsonURL?: string;
+  jsonData?: unknown;
+  fontDataURL?: string;
+  xSpacing?: number;
+  ySpacing?: number;
+  format?: unknown;
+};
+
+export type LoaderFileData = HTMLImageElement | XMLDocument | ArrayBuffer | string | Record<string, unknown> | null;
+
 /** An audio source, either a plain URL or a URL paired with its format. */
 export type AudioSource = string | { uri: string; type?: string };
 
@@ -21,7 +52,7 @@ export type LoaderFile = {
   path: string;
   url: string | AudioSource[];
   syncPoint: boolean;
-  data: any;
+  data: LoaderFileData;
   loading: boolean;
   loaded: boolean;
   error: boolean;
@@ -311,7 +342,7 @@ export class Loader {
       url,
       path: this.path,
       syncPoint: true,
-      data: null as unknown,
+      data: null as LoaderFileData,
       loading: false,
       loaded: false,
       error: false,
@@ -321,7 +352,7 @@ export class Loader {
       if (typeof data === 'string') {
         data = JSON.parse(data);
       }
-      pack.data = data ?? {};
+      pack.data = (data ?? {}) as LoaderFileData;
       pack.loaded = true;
     }
     for (let i = 0; i < this._fileList.length + 1; i += 1) {
@@ -755,52 +786,53 @@ export class Loader {
    * @param {object} pack - The pack file object to process.
    */
   public processPack(pack: LoaderFile): void {
-    const packData = pack.data[pack.key];
+    const manifest = (pack.data ?? {}) as Record<string, unknown>;
+    const packData = manifest[pack.key] as { files?: unknown[] } | unknown[] | undefined;
     if (!packData) {
       this.game.logger.warn('Missing loader pack key', { key: pack.key });
       return;
     }
-    const packDataCompat = Array.isArray(packData) ? packData : packData.files;
+    const packDataCompat = (Array.isArray(packData) ? packData : (packData.files ?? [])) as PackEntry[];
     for (const file of packDataCompat) {
       switch (file.type) {
         case 'image': {
-          this.image(file.key, file.url, file.overwrite);
+          this.image(file.key, file.url ?? file.key, file.overwrite);
           break;
         }
         case 'text': {
-          this.text(file.key, file.url, file.overwrite);
+          this.text(file.key, file.url ?? file.key, file.overwrite);
           break;
         }
         case 'json': {
-          this.json(file.key, file.url, file.overwrite);
+          this.json(file.key, file.url ?? file.key, file.overwrite);
           break;
         }
         case 'xml': {
-          this.xml(file.key, file.url, file.overwrite);
+          this.xml(file.key, file.url ?? file.key, file.overwrite);
           break;
         }
         case 'spritesheet': {
           this.spritesheet(
             file.key,
-            file.url,
-            file.frameWidth,
-            file.frameHeight,
-            file.frameMax,
+            file.url ?? file.key,
+            file.frameWidth ?? 0,
+            file.frameHeight ?? 0,
+            file.frameMax ?? -1,
             file.margin,
             file.spacing
           );
           break;
         }
         case 'audio': {
-          this.audio(file.key, file.urls ?? file.url);
+          this.audio(file.key, file.urls ?? file.url ?? file.key);
           break;
         }
         case 'audiosprite': {
-          this.audioSprite(file.key, file.urls ?? file.url, file.jsonURL, file.jsonData);
+          this.audioSprite(file.key, String(file.urls ?? file.url ?? file.key), file.jsonURL ?? '', file.jsonData);
           break;
         }
         case 'audioSprite': {
-          this.audioSprite(file.key, file.audioURL, file.jsonURL, file.jsonData);
+          this.audioSprite(file.key, file.audioURL ?? file.key, file.jsonURL ?? '', file.jsonData);
           break;
         }
         case 'bitmapFont': {
@@ -815,7 +847,7 @@ export class Loader {
           break;
         }
         case 'atlas': {
-          this.atlas(file.key, file.textureURL, file.atlasURL, file.atlasData, TEXTURE_ATLAS_JSON_HASH);
+          this.atlas(file.key, file.textureURL ?? file.key, file.atlasURL, file.atlasData, TEXTURE_ATLAS_JSON_HASH);
           break;
         }
       }
@@ -898,31 +930,37 @@ export class Loader {
   public loadImageTag(file: LoaderFile): void {
     this.log('loadImageTag', file);
     const scope = this;
-    file.data = new globalThis.Image();
-    file.data.name = file.key;
-    if (this.crossOrigin) {
-      file.data.crossOrigin = this.crossOrigin;
+    const image = new globalThis.Image();
+    file.data = image;
+    image.name = file.key;
+    if (typeof this.crossOrigin === 'string' && this.crossOrigin) {
+      image.crossOrigin = this.crossOrigin;
     }
-    file.data.onload = (): void => {
-      if (file.data.onload) {
-        file.data.onload = null;
-        file.data.onerror = null;
+    image.onload = (): void => {
+      if (image.onload) {
+        image.onload = null;
+        image.onerror = null;
         scope.fileComplete(file);
       }
     };
-    file.data.onerror = (): void => {
+    image.onerror = (): void => {
       if (scope.isUseRetry && (!file.numRetry || file.numRetry < scope.maxRetry)) {
         setTimeout((): void => {
           file.numRetry = !file.numRetry ? 1 : (file.numRetry += 1);
           scope.loadImageTag(file);
         }, 1000);
-      } else if (file.data.onload) {
-        file.data.onload = null;
-        file.data.onerror = null;
+      } else if (image.onload) {
+        image.onload = null;
+        image.onerror = null;
         scope.fileError(file);
       }
     };
-    file.data.src = this.transformUrl(file.url, file);
+    const src = this.transformUrl(file.url, file);
+    if (src === false) {
+      this.fileError(file, null, 'Could not resolve the file URL');
+      return;
+    }
+    image.src = src;
   }
 
   /**
@@ -1091,14 +1129,14 @@ export class Loader {
         break;
       }
       case 'image': {
-        this.cache.addImage(file.key, url, file.data);
+        this.cache.addImage(file.key, url, file.data as HTMLImageElement);
         break;
       }
       case 'spritesheet': {
         this.cache.addSpriteSheet(
           file.key,
           url,
-          file.data,
+          file.data as HTMLImageElement,
           file.frameWidth ?? 0,
           file.frameHeight ?? 0,
           file.frameMax ?? -1,
@@ -1109,7 +1147,7 @@ export class Loader {
       }
       case 'textureatlas': {
         if (file.atlasURL == null) {
-          this.cache.addTextureAtlas(file.key, url, file.data, file.atlasData);
+          this.cache.addTextureAtlas(file.key, url, file.data as HTMLImageElement, file.atlasData);
         } else {
           loadNext = false;
           if (file.format === TEXTURE_ATLAS_JSON_HASH) {
@@ -1125,7 +1163,7 @@ export class Loader {
           this.cache.addBitmapFont(
             file.key,
             url,
-            file.data,
+            file.data as HTMLImageElement,
             file.atlasData,
             file.atlasType ?? 'xml',
             file.xSpacing ?? 0,
@@ -1159,16 +1197,18 @@ export class Loader {
         break;
       }
       case 'audio': {
-        file.data = response.response;
-        this.cache.addSound(file.key, url, file.data);
+        const audio = response.response as ArrayBuffer;
+        file.data = audio;
+        this.cache.addSound(file.key, url, audio);
         if (file.autoDecode) {
           this.game.sound.decode(file.key);
         }
         break;
       }
       case 'text': {
-        file.data = response.responseText;
-        this.cache.addText(file.key, url, file.data);
+        const { responseText } = response;
+        file.data = responseText;
+        this.cache.addText(file.key, url, responseText);
         break;
       }
       default: {
@@ -1193,7 +1233,7 @@ export class Loader {
       this.cache.addBitmapFont(
         file.key,
         url,
-        file.data,
+        file.data as HTMLImageElement,
         data,
         file.atlasType ?? 'json',
         file.xSpacing ?? 0,
@@ -1202,7 +1242,7 @@ export class Loader {
     } else if (file.type === 'json') {
       this.cache.addJSON(file.key, url, data);
     } else {
-      this.cache.addTextureAtlas(file.key, url, file.data, data);
+      this.cache.addTextureAtlas(file.key, url, file.data as HTMLImageElement, data);
     }
     this.asyncComplete(file);
   }
@@ -1235,14 +1275,14 @@ export class Loader {
       this.cache.addBitmapFont(
         file.key,
         url,
-        file.data,
+        file.data as HTMLImageElement,
         xml,
         file.atlasType ?? 'xml',
         file.xSpacing ?? 0,
         file.ySpacing ?? 0
       );
     } else if (file.type === 'textureatlas') {
-      this.cache.addTextureAtlas(file.key, url, file.data, xml);
+      this.cache.addTextureAtlas(file.key, url, file.data as HTMLImageElement, xml);
     } else if (file.type === 'xml') {
       this.cache.addXML(file.key, url, xml);
     }

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): void => {
-    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,13 +103,13 @@ 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,

package/src/phaser/core/scene.ts

@@ -1,6 +1,8 @@
+import type { Game } from './game.js';
+
 export class Scene {
-  public game: any = null;
-  public key: any = '';
+  public game: Game | null = null;
+  public key = '';
   /**
    * Creates a new Scene instance.
    */