@vpmedia/phaser 1.123.0 → 1.125.0

package/src/phaser/core/tween.ts

@@ -6,6 +6,7 @@ import { TweenData } from './tween_data.js';
 import type { Game } from './game.js';
 import type { TweenManager } from './tween_manager.js';
 import type { AppliedCallback, Callback, EasingFunction, InterpolationFunction } from './callback.js';
+import type { TweenValues } from './tween_data.js';
 
 export class Tween {
   public game!: Game;
@@ -23,7 +24,7 @@ export class Tween {
   public onComplete!: Signal;
   public isRunning!: boolean;
   public current!: number;
-  public properties!: any;
+  public properties!: TweenValues;
   public chainedTween!: Tween | null;
   public isPaused!: boolean;
   public _onUpdateCallback!: Callback | null;
@@ -92,7 +93,7 @@ export class Tween {
    * @returns {Tween} This Tween object for chaining.
    */
   public to(
-    properties: any,
+    properties: TweenValues,
     duration = 1000,
     ease: string | EasingFunction = 'Linear',
     autoStart = false,
@@ -100,13 +101,11 @@ export class Tween {
     repeat = 0,
     yoyo = false
   ): this {
-    if (typeof ease === 'string' && this.manager.easeMap[ease]) {
-      ease = this.manager.easeMap[ease]!;
-    }
+    const easing = this.resolveEasing(ease);
     if (this.isRunning) {
       return this;
     }
-    this.timeline.push(new TweenData(this).to(properties, duration, ease, delay, repeat, yoyo));
+    this.timeline.push(new TweenData(this).to(properties, duration, easing, delay, repeat, yoyo));
     if (autoStart) {
       this.start();
     }
@@ -125,7 +124,7 @@ export class Tween {
    * @returns {Tween} This Tween object for chaining.
    */
   public from(
-    properties: any,
+    properties: TweenValues,
     duration = 1000,
     ease: string | EasingFunction = 'Linear',
     autoStart = false,
@@ -133,14 +132,11 @@ export class Tween {
     repeat = 0,
     yoyo = false
   ): this {
-    if (typeof ease === 'string' && this.manager.easeMap[ease]) {
-      ease = this.manager.easeMap[ease]!;
-    }
     if (this.isRunning) {
       this.game.logger.warn('Tween.from cannot be called after Tween.start');
       return this;
     }
-    this.timeline.push(new TweenData(this).from(properties, duration, ease, delay, repeat, yoyo));
+    this.timeline.push(new TweenData(this).from(properties, duration, this.resolveEasing(ease), delay, repeat, yoyo));
     if (autoStart) {
       this.start();
     }
@@ -161,12 +157,9 @@ export class Tween {
       //  Build our master property list with the starting values
       const keys = Object.keys(tweenData.vEnd);
       for (const property of keys) {
-        const targetProperties = this.target as unknown as Record<string, number>;
-        this.properties[property] = targetProperties[property] ?? 0;
-        if (!Array.isArray(this.properties[property])) {
-          //  Ensures we're using numbers, not strings
-          this.properties[property] *= 1;
-        }
+        const targetProperties = this.target as unknown as Record<string, number | string | undefined>;
+        //  Ensures we're using numbers, not strings
+        this.properties[property] = Number(targetProperties[property] ?? 0);
       }
     }
     for (const tweenData of this.timeline) {
@@ -174,10 +167,7 @@ export class Tween {
     }
     this.manager.add(this);
     this.isRunning = true;
-    if (index < 0 || index > this.timeline.length - 1) {
-      index = 0;
-    }
-    this.current = index;
+    this.current = index < 0 || index > this.timeline.length - 1 ? 0 : index;
     this.timeline[this.current]!.start();
     return this;
   }
@@ -209,7 +199,7 @@ export class Tween {
    * @param {number} index - The index in the timeline to update.
    * @returns {Tween} This Tween object for chaining.
    */
-  public updateTweenData(property: string, value: any, index = 0): this {
+  public updateTweenData(property: string, value: unknown, index = 0): this {
     if (this.timeline.length === 0) {
       return this;
     }
@@ -283,11 +273,21 @@ export class Tween {
    * @param {number} index - The index in the timeline to apply easing to.
    * @returns {Tween} This Tween object for chaining.
    */
-  public easing(ease: string | EasingFunction, index: number): this {
-    if (typeof ease === 'string' && this.manager.easeMap[ease]) {
-      ease = this.manager.easeMap[ease]!;
+  public resolveEasing(ease: string | EasingFunction): EasingFunction {
+    if (typeof ease !== 'string') {
+      return ease;
     }
-    return this.updateTweenData('easingFunction', ease, index);
+    return this.manager.easeMap[ease] ?? this.manager.easeMap['Linear']!;
+  }
+
+  /**
+   * Sets the easing function for a tween in the timeline.
+   * @param {string | Function} ease - The easing function or its name.
+   * @param {number} index - The index of the tween in the timeline.
+   * @returns {Tween} This Tween object for chaining.
+   */
+  public easing(ease: string | EasingFunction, index: number): this {
+    return this.updateTweenData('easingFunction', this.resolveEasing(ease), index);
   }
 
   /**
@@ -401,7 +401,7 @@ export class Tween {
    * @returns {boolean} True if the tween should continue running, false if it's complete.
    */
   public update(time: number): boolean {
-    if (this.pendingDelete || !this.target) {
+    if (this.pendingDelete || !(this.target as TweenTarget | undefined)) {
       return false;
     }
     if (this.isPaused) {
@@ -484,7 +484,7 @@ export class Tween {
    * @param {object[]} data - The array to store the generated data in.
    * @returns {object[]} The populated data array.
    */
-  public generateData(frameRate = 60, data: any[] = []) {
+  public generateData(frameRate = 60, data: Record<string, number>[] = []): Record<string, number>[] | null {
     if (this.game === null || this.target === null) {
       return null;
     }
@@ -493,21 +493,19 @@ export class Tween {
       //  Build our master property list with the starting values
       const keys = Object.keys(tweenData.vEnd);
       for (const property of keys) {
-        const targetProperties = this.target as unknown as Record<string, number>;
-        this.properties[property] = targetProperties[property] ?? 0;
-        if (!Array.isArray(this.properties[property])) {
-          //  Ensures we're using numbers, not strings
-          this.properties[property] *= 1;
-        }
+        const targetProperties = this.target as unknown as Record<string, number | string | undefined>;
+        //  Ensures we're using numbers, not strings
+        this.properties[property] = Number(targetProperties[property] ?? 0);
       }
     }
     for (const tweenData of this.timeline) {
       tweenData.loadValues();
     }
+    const frames = [...data];
     for (const tweenData of this.timeline) {
-      data = [...data, ...tweenData.generateData(frameRate)];
+      frames.push(...tweenData.generateData(frameRate));
     }
-    return data;
+    return frames;
   }
 
   /**

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

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest';
+import { TWEEN_COMPLETE, TWEEN_RUNNING } from './const.js';
+import { Signal } from './signal.js';
+import { Tween } from './tween.js';
+import { TweenManager } from './tween_manager.js';
+import type { Game } from './game.js';
+
+const createGame = (): Game =>
+  ({
+    time: { time: 0, elapsedMS: 0 },
+    logger: { warn: (): void => undefined },
+    onPause: new Signal(),
+    onResume: new Signal(),
+  }) as unknown as Game;
+
+const createTween = (target: Record<string, number>): { game: Game; tween: Tween } => {
+  const game = createGame();
+  const manager = new TweenManager(game);
+  return { game, tween: new Tween(target, game, manager) };
+};
+
+const advance = (game: Game, tween: Tween, ms: number): void => {
+  game.time.time += ms;
+  game.time.elapsedMS = ms;
+  tween.update(game.time.time);
+};
+
+describe('TweenData', (): void => {
+  describe('resolveEasing', (): void => {
+    it('takes a function as-is', (): void => {
+      const { tween } = createTween({ x: 0 });
+      const ease = (k: number): number => k * k;
+      expect(tween.resolveEasing(ease)).toBe(ease);
+    });
+
+    it('looks a named curve up in the manager', (): void => {
+      const { tween } = createTween({ x: 0 });
+      expect(tween.resolveEasing('Quad.easeIn')).toBe(tween.manager.easeMap['Quad.easeIn']);
+    });
+
+    it('falls back to linear for a name the manager does not know', (): void => {
+      const { tween } = createTween({ x: 0 });
+      expect(tween.resolveEasing('No.Such.Curve')).toBe(tween.manager.easeMap['Linear']);
+    });
+  });
+
+  describe('to', (): void => {
+    it('drives a numeric property from its start value to the end value', (): void => {
+      const target = { x: 0 };
+      const { game, tween } = createTween(target);
+      tween.to({ x: 100 }, 100, 'Linear', true);
+      advance(game, tween, 50);
+      expect(target.x).toBeCloseTo(50);
+      advance(game, tween, 50);
+      expect(target.x).toBeCloseTo(100);
+    });
+
+    it('reads a relative end value against the start', (): void => {
+      const target = { x: 20 };
+      const { game, tween } = createTween(target);
+      tween.to({ x: '+10' }, 100, 'Linear', true);
+      advance(game, tween, 100);
+      expect(target.x).toBeCloseTo(30);
+    });
+
+    it('interpolates through a list of waypoints', (): void => {
+      const target = { x: 0 };
+      const { game, tween } = createTween(target);
+      tween.to({ x: [0, 50, 100] }, 100, 'Linear', true);
+      advance(game, tween, 100);
+      expect(target.x).toBeCloseTo(100);
+    });
+
+    // An empty waypoint list has nothing to interpolate between, so the property goes to NaN.
+    it('survives an empty waypoint list', (): void => {
+      const target = { x: 7 };
+      const { game, tween } = createTween(target);
+      tween.to({ x: [] }, 100, 'Linear', true);
+      expect((): void => {
+        advance(game, tween, 100);
+      }).not.toThrow();
+    });
+
+    it('reports the tween running until the duration has passed', (): void => {
+      const target = { x: 0 };
+      const { game, tween } = createTween(target);
+      tween.to({ x: 10 }, 100, 'Linear', true);
+      game.time.time += 50;
+      game.time.elapsedMS = 50;
+      expect(tween.timeline[0]?.update(game.time.time)).toBe(TWEEN_RUNNING);
+      game.time.time += 100;
+      game.time.elapsedMS = 100;
+      expect(tween.timeline[0]?.update(game.time.time)).toBe(TWEEN_COMPLETE);
+    });
+  });
+
+  describe('from', (): void => {
+    it('starts at the given value and lands on the target original', (): void => {
+      const target = { x: 100 };
+      const { game, tween } = createTween(target);
+      tween.from({ x: 0 }, 100, 'Linear', true);
+      advance(game, tween, 0);
+      expect(target.x).toBeCloseTo(0);
+      advance(game, tween, 100);
+      expect(target.x).toBeCloseTo(100);
+    });
+  });
+
+  describe('generateData', (): void => {
+    it('produces one frame of values per step', (): void => {
+      const { tween } = createTween({ x: 0 });
+      tween.to({ x: 100 }, 100, 'Linear');
+      tween.start();
+      const data = tween.generateData(10) ?? [];
+      expect(data.length).toBeGreaterThan(0);
+      expect(data.at(-1)?.['x']).toBeCloseTo(100);
+    });
+  });
+});

package/src/phaser/core/tween_data.ts

@@ -2,15 +2,18 @@ import type { Game } from './game.js';
 import * as MathUtils from '../util/math.js';
 import { TWEEN_COMPLETE, TWEEN_LOOPED, TWEEN_PENDING, TWEEN_RUNNING } from './const.js';
 import type { Tween } from './tween.js';
-import type { InterpolationFunction } from './callback.js';
+import type { EasingFunction, InterpolationFunction } from './callback.js';
+
+/** The properties a tween drives, each holding either a single target or a list of waypoints. */
+export type TweenValues = Record<string, number | number[] | string>;
 
 export class TweenData {
   public parent!: Tween;
   public game!: Game;
-  public vStart!: Record<string, any>;
-  public vStartCache!: Record<string, any>;
-  public vEnd!: Record<string, any>;
-  public vEndCache!: Record<string, any>;
+  public vStart!: TweenValues;
+  public vStartCache!: TweenValues;
+  public vEnd!: TweenValues;
+  public vEndCache!: TweenValues;
   public duration!: number;
   public percent!: number;
   public value!: number;
@@ -71,7 +74,14 @@ export class TweenData {
    * @param {boolean} yoyo - Whether to reverse the tween on each repeat.
    * @returns {TweenData} This TweenData object for chaining.
    */
-  public to(properties: any, duration: number, ease: any, delay: number, repeat: number, yoyo: boolean): this {
+  public to(
+    properties: TweenValues,
+    duration: number,
+    ease: EasingFunction,
+    delay: number,
+    repeat: number,
+    yoyo: boolean
+  ): this {
     this.vEnd = properties;
     this.duration = duration;
     this.easingFunction = ease;
@@ -92,7 +102,14 @@ export class TweenData {
    * @param {boolean} yoyo - Whether to reverse the tween on each repeat.
    * @returns {TweenData} This TweenData object for chaining.
    */
-  public from(properties: any, duration: number, ease: any, delay: number, repeat: number, yoyo: boolean): this {
+  public from(
+    properties: TweenValues,
+    duration: number,
+    ease: EasingFunction,
+    delay: number,
+    repeat: number,
+    yoyo: boolean
+  ): this {
     this.vEnd = properties;
     this.duration = duration;
     this.easingFunction = ease;
@@ -115,9 +132,9 @@ export class TweenData {
       //  Reverse them all and instant set them
       const keys = Object.keys(this.vStartCache);
       for (const property of keys) {
-        this.vStart[property] = this.vEndCache[property];
-        this.vEnd[property] = this.vStartCache[property];
-        (this.parent.target as unknown as Record<string, any>)[property] = this.vStart[property];
+        this.vStart[property] = this.vEndCache[property]!;
+        this.vEnd[property] = this.vStartCache[property]!;
+        (this.parent.target as unknown as Record<string, unknown>)[property] = this.vStart[property];
       }
     }
     this.value = 0;
@@ -134,29 +151,27 @@ export class TweenData {
     const keys = Object.keys(this.parent.properties);
     for (const property of keys) {
       //  Load the property from the parent object
-      this.vStart[property] = this.parent.properties[property];
+      const start = this.parent.properties[property]!;
+      this.vStart[property] = start;
       //  Check if an Array was provided as property value
-      if (Array.isArray(this.vEnd[property])) {
-        if (this.vEnd[property].length === 0) {
-          // an empty end array leaves the property untouched for this step
-        } else if (this.percent === 0) {
-          //  Put the start value at the beginning of the array
-          //  but we only want to do this once, if the Tween hasn't run before
-          this.vEnd[property] = [this.vStart[property], ...this.vEnd[property]];
-        }
+      const end = this.vEnd[property];
+      if (Array.isArray(end) && end.length > 0 && this.percent === 0) {
+        //  Put the start value at the beginning of the array
+        //  but we only want to do this once, if the Tween hasn't run before
+        this.vEnd[property] = [Number(start), ...end];
       }
-      if (this.vEnd[property] !== undefined) {
-        if (typeof this.vEnd[property] === 'string') {
+      if (end === undefined) {
+        //  Null tween
+        this.vEnd[property] = start;
+      } else {
+        if (typeof end === 'string') {
           //  Parses relative end values with start as base (e.g.: +10, -3)
-          this.vEnd[property] = this.vStart[property] + Number(this.vEnd[property]);
+          this.vEnd[property] = Number(start) + Number(end);
         }
-        this.parent.properties[property] = this.vEnd[property];
-      } else {
-        //  Null tween
-        this.vEnd[property] = this.vStart[property];
+        this.parent.properties[property] = this.vEnd[property]!;
       }
-      this.vStartCache[property] = this.vStart[property];
-      this.vEndCache[property] = this.vEnd[property];
+      this.vStartCache[property] = this.vStart[property]!;
+      this.vEndCache[property] = this.vEnd[property]!;
     }
     return this;
   }
@@ -189,11 +204,11 @@ export class TweenData {
     this.value = this.easingFunction(this.percent);
     const keys = Object.keys(this.vEnd);
     for (const property of keys) {
-      const start = this.vStart[property];
       const end = this.vEnd[property];
-      (this.parent.target as unknown as Record<string, any>)[property] = Array.isArray(end)
+      const start = Number(this.vStart[property]);
+      (this.parent.target as unknown as Record<string, unknown>)[property] = Array.isArray(end)
         ? this.interpolationFunction.call(this.interpolationContext, end, this.value)
-        : start + (end - start) * this.value;
+        : start + (Number(end) - start) * this.value;
     }
     if ((!this.parent.reverse && this.percent === 1) || (this.parent.reverse && this.percent === 0)) {
       return this.repeat();
@@ -224,11 +239,11 @@ export class TweenData {
       const blob: Record<string, number> = {};
       const keys = Object.keys(this.vEnd);
       for (const property of keys) {
-        const start = this.vStart[property];
         const end = this.vEnd[property];
+        const start = Number(this.vStart[property]);
         blob[property] = Array.isArray(end)
           ? this.interpolationFunction(end, this.value)
-          : start + (end - start) * this.value;
+          : start + (Number(end) - start) * this.value;
       }
       data.push(blob);
       if ((!this.parent.reverse && this.percent === 1) || (this.parent.reverse && this.percent === 0)) {
@@ -253,8 +268,8 @@ export class TweenData {
         //  Restore the properties
         const keys = Object.keys(this.vStartCache);
         for (const property of keys) {
-          this.vStart[property] = this.vStartCache[property];
-          this.vEnd[property] = this.vEndCache[property];
+          this.vStart[property] = this.vStartCache[property]!;
+          this.vEnd[property] = this.vEndCache[property]!;
         }
         this.inReverse = false;
         return TWEEN_COMPLETE;
@@ -267,15 +282,15 @@ export class TweenData {
       //  If inReverse we're going from vEnd to vStartCache
       const keys = Object.keys(this.vStartCache);
       for (const property of keys) {
-        this.vStart[property] = this.vEndCache[property];
-        this.vEnd[property] = this.vStartCache[property];
+        this.vStart[property] = this.vEndCache[property]!;
+        this.vEnd[property] = this.vStartCache[property]!;
       }
     } else {
       //  If not inReverse we're just repopulating the cache again
       const keys = Object.keys(this.vStartCache);
       for (const property of keys) {
-        this.vStart[property] = this.vStartCache[property];
-        this.vEnd[property] = this.vEndCache[property];
+        this.vStart[property] = this.vStartCache[property]!;
+        this.vEnd[property] = this.vEndCache[property]!;
       }
       //  -1 means repeat forever, otherwise decrement the repeatCounter
       //  We only decrement this counter if the tween isn't doing a yoyo, as that doesn't count towards the repeat total

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

@@ -82,22 +82,22 @@ const EXPECTED: Record<string, number[]> = {
   ],
 };
 
-describe('tween_easing', () => {
-  it.each(Object.keys(EXPECTED))('%s matches its reference curve', (name) => {
+describe('tween_easing', (): void => {
+  it.each(Object.keys(EXPECTED))('%s matches its reference curve', (name): void => {
     const fn = (Easing as unknown as Record<string, (k: number) => number>)[name]!;
-    const actual = SAMPLE_POINTS.map((k) => fn(k));
+    const actual = SAMPLE_POINTS.map((k): number => fn(k));
     for (const [index, value] of actual.entries()) {
       expect(value).toBeCloseTo(EXPECTED[name]![index]!, 12);
     }
   });
 
-  it.each(Object.keys(EXPECTED))('%s is anchored at both ends', (name) => {
+  it.each(Object.keys(EXPECTED))('%s is anchored at both ends', (name): void => {
     const fn = (Easing as unknown as Record<string, (k: number) => number>)[name]!;
     expect(fn(0)).toBeCloseTo(0, 12);
     expect(fn(1)).toBeCloseTo(1, 12);
   });
 
-  it.each(Object.keys(EXPECTED))('%s does not mutate beyond its return value', (name) => {
+  it.each(Object.keys(EXPECTED))('%s does not mutate beyond its return value', (name): void => {
     const fn = (Easing as unknown as Record<string, (k: number) => number>)[name]!;
     for (const k of SAMPLE_POINTS) {
       expect(fn(k)).toBe(fn(k));

package/src/phaser/core/tween_manager.ts

@@ -106,7 +106,7 @@ export class TweenManager {
    * Get all tweens managed by this manager.
    * @returns {Tween[]} An array of all active tweens.
    */
-  public getAll() {
+  public getAll(): Tween[] {
     return this._tweens;
   }
 
@@ -128,7 +128,7 @@ export class TweenManager {
    */
   public removeFrom(obj: TweenTarget, children: object[] | null = null): void {
     if (Array.isArray(obj)) {
-      for (const entry of obj) {
+      for (const entry of obj as object[]) {
         this.removeFrom(entry);
       }
       return;