feat: [#1892] Animations should allow you to specify the total duration

CHANGELOG.md

@@ -10,7 +10,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 -
 ### Added
 
-- 
+- `ex.Animation` now support `totalDuration` that will calculate automatically each frame duration based on how many frames have.
+-
 ### Changed
 
 - Internal Actions implementation converted to ECS system and component, this is a backwards compatible change with v0.25.0

src/engine/Graphics/Animation.ts

@@ -62,6 +62,10 @@ export interface AnimationOptions {
    * Optionally specify a default frame duration in ms (Default is 1000)
    */
   frameDuration?: number;
+  /**
+   * Optionally specify a total duration of the animation in ms to calculate each frame's duration
+   */
+  totalDuration?: number;
   /**
    * Optionally specify the [[AnimationStrategy]] for the Animation
    */
@@ -101,8 +105,7 @@ export class Animation extends Graphic implements HasTick {
     super(options);
     this.frames = options.frames;
     this.strategy = options.strategy ?? this.strategy;
-    this.frameDuration = options.frameDuration ?? this.frameDuration;
-
+    this.frameDuration = options.totalDuration ? options.totalDuration / this.frames.length : options.frameDuration ?? this.frameDuration;
     this.goToFrame(0);
   }
 

src/spec/GraphicsAnimationSpec.ts

@@ -401,4 +401,35 @@ describe('A Graphics Animation', () => {
     anim.draw(ctx, 0, 0);
     await expectAsync(output).toEqualImage('src/spec/images/GraphicsAnimationSpec/frame-3.png');
   });
+
+  it('calculate automatically the frame duration based on the animation total duration', () => {
+
+    const rect = new ex.Rectangle({
+      width: 100,
+      height: 100,
+      color: ex.Color.Blue
+    });
+    const totalDuration = 1000;
+    const frames = [
+      {
+        graphic: rect
+      },
+      {
+        graphic: rect
+      }
+    ];
+    const expectedFrameDuration = totalDuration / frames.length;
+    const anim = new ex.Animation({
+      totalDuration,
+      frames: frames
+    });
+
+    expect(anim.frameDuration).toBe(expectedFrameDuration);
+    anim.play();
+    expect(anim.currentFrame).toBe(anim.frames[0]);
+    anim.tick(expectedFrameDuration, 0);
+    expect(anim.currentFrame).toBe(anim.frames[1]);
+    anim.tick(expectedFrameDuration, 2);
+    expect(anim.currentFrame).toBe(anim.frames[0]);
+  });
 });

src/stories/Animations.stories.ts

@@ -1,5 +1,5 @@
-import { Actor, Loader, Util } from '../engine';
-import { ImageSource, SpriteSheet, Animation, AnimationStrategy } from '../engine/Graphics';
+import { Actor, Color, Loader, Util } from '../engine';
+import { ImageSource, SpriteSheet, Animation, AnimationStrategy, Rectangle } from '../engine/Graphics';
 import { enumToControlSelectLabels, enumToControlSelectOptions, withEngine } from './utils';
 
 import animationSprite from './assets/animation.png';
@@ -10,8 +10,12 @@ export default {
 
 export const multipleFrames: Story = withEngine(async (game, { strategy }) => {
   const playerTexture = new ImageSource(animationSprite);
-
-  const player = new Actor({ x: game.currentScene.camera.x, y: game.currentScene.camera.y, width: 100, height: 30 });
+  const player = new Actor({
+    x: game.screen.center.x,
+    y: game.screen.center.y,
+    width: 100,
+    height: 30
+  });
   player.anchor.setTo(0.5, 0.5);
   const spritesheet = SpriteSheet.fromImageSource({
     image: playerTexture,
@@ -48,3 +52,89 @@ multipleFrames.argTypes = {
 multipleFrames.args = {
   strategy: AnimationStrategy.End
 };
+
+export const frameDuration: Story = withEngine(async (game, { duration }) => {
+  const size = 100;
+  const colors = [Color.Red, Color.Orange, Color.Yellow, Color.Green, Color.Cyan, Color.Blue, Color.Violet];
+  const player = new Actor({
+    x: game.screen.center.x,
+    y: game.screen.center.y,
+    width: size,
+    height: size
+  });
+  const animation = new Animation({
+    frameDuration: duration,
+    frames: colors.map((c) => ({
+      graphic: new Rectangle({
+        width: size,
+        height: size,
+        color: c
+      })
+    }))
+  });
+  player.graphics.add(animation);
+  game.currentScene.add(player);
+  await game.start();
+});
+frameDuration.story = {
+  parameters: {
+    notes: 'Should display 7 frames with a delay of 1s between them'
+  }
+};
+frameDuration.argTypes = {
+  duration: {
+    name: 'Frame Duration',
+    control: {
+      type: 'range',
+      min: 100,
+      max: 2000,
+      step: 100
+    }
+  }
+};
+frameDuration.args = {
+  duration: 1000
+};
+
+export const totalDuration: Story = withEngine(async (game, { duration }) => {
+  const size = 100;
+  const colors = [Color.Red, Color.Orange, Color.Yellow, Color.Green, Color.Cyan, Color.Blue, Color.Violet];
+  const player = new Actor({
+    x: game.screen.center.x,
+    y: game.screen.center.y,
+    width: size,
+    height: size
+  });
+  const animation = new Animation({
+    totalDuration: duration,
+    frames: colors.map((c) => ({
+      graphic: new Rectangle({
+        width: size,
+        height: size,
+        color: c
+      })
+    }))
+  });
+  player.graphics.add(animation);
+  game.currentScene.add(player);
+  await game.start();
+});
+totalDuration.story = {
+  parameters: {
+    notes: 'Should display 7 frames in 1s'
+  }
+};
+totalDuration.argTypes = {
+  duration: {
+    name: 'Total Duration',
+    control: {
+      type: 'range',
+      min: 100,
+      max: 2000,
+      step: 100
+    }
+  }
+};
+totalDuration.args = {
+  duration: 1000
+};