Merge branch 'main' into feature/1860-action-vector-overload

CHANGELOG.md

@@ -48,6 +48,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 
 - Actions `moveTo()`, `moveBy()`, `easeTo()`, `scaleTo()`, and `scaleBy()` now have vector overloads
+- `Animation.fromSpriteSheet` will now log a warning if an index into the `SpriteSheet` is invalid ([#1856](https://github.com/excaliburjs/Excalibur/issues/1856))
 - `new ImageSource()` will now log a warning if an image type isn't fully supported. ([#1855](https://github.com/excaliburjs/Excalibur/issues/1855))
 - `Timer.start()` to explicitly start timers, and `Timer.stop()` to stop timers and "rewind" them.
 - `Timer.timeToNextAction` will return the milliseconds until the next action callback

src/engine/Graphics/Animation.ts

@@ -3,6 +3,7 @@ import { clamp } from '../Util/Util';
 import { ExcaliburGraphicsContext } from './Context/ExcaliburGraphicsContext';
 import { EventDispatcher } from '../EventDispatcher';
 import { SpriteSheet } from './SpriteSheet';
+import { Logger } from '../Util/Log';
 
 export interface HasTick {
   /**
@@ -52,6 +53,7 @@ export type AnimationEvents = {
 };
 
 export class Animation extends Graphic implements HasTick {
+  private static _LOGGER = Logger.getInstance();
   public events = new EventDispatcher<any>(this); // TODO replace with new Emitter
   public frames: Frame[] = [];
   public strategy: AnimationStrategy = AnimationStrategy.Loop;
@@ -91,6 +93,13 @@ export class Animation extends Graphic implements HasTick {
     duration: number,
     strategy: AnimationStrategy = AnimationStrategy.Loop
   ): Animation {
+    const maxIndex = spriteSheet.sprites.length - 1;
+    const invalidIndices = frameIndices.filter((index) => index < 0 || index > maxIndex);
+    if (invalidIndices.length) {
+      Animation._LOGGER.warn(
+        `Indices into SpriteSheet were provided that don\'t exist: ${invalidIndices.join(',')} no frame will be shown`
+      );
+    }
     return new Animation({
       frames: spriteSheet.sprites
         .filter((_, index) => frameIndices.indexOf(index) > -1)

src/spec/GraphicsAnimationSpec.ts

@@ -70,6 +70,31 @@ describe('A Graphics Animation', () => {
     expect(anim.frames.length).toBe(4);
   });
 
+  it('warns if constructed with invalid indices', () => {
+    const sourceImage = new ex.Graphics.ImageSource('some/image.png');
+    const ss = ex.Graphics.SpriteSheet.fromGrid({
+      image: sourceImage,
+      grid: {
+        spriteWidth: 10,
+        spriteHeight: 10,
+        rows: 10,
+        columns: 10
+      }
+    });
+    const logger = ex.Logger.getInstance();
+    spyOn(logger, 'warn');
+    const invalidIndices = [-1, -2, 101, 102];
+    const anim = ex.Graphics.Animation.fromSpriteSheet(ss, invalidIndices, 100, ex.Graphics.AnimationStrategy.Freeze);
+
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+    expect(logger.warn).toHaveBeenCalledOnceWith(
+      `Indices into SpriteSheet were provided that don\'t exist: ${invalidIndices.join(',')} no frame will be shown`
+    );
+    expect(anim.strategy).toBe(ex.Graphics.AnimationStrategy.Freeze);
+    // expect(anim.frames[0].duration).toBe(100);
+    expect(anim.frames.length).toBe(0);
+  });
+
   it('is playing and looping by default', () => {
     const rect = new ex.Graphics.Rectangle({
       width: 100,