Logo sprites from A Platformer in the Forest

PIXI Animator

pixi-animator provides a simple API to create animations from PIXI Sprites

Table of Contents

• Installation
• Guide
• API
  • AnimationClip
  • Animator
    • add
    • remove
    • play
    • stop
    • update
• Tests

Installation

To install pixi-animator through npm, simply use the following command:

$ npm install pixi-animator

Guide

To use pixi-animator, you'll need to import Animator and AnimationClip like so:

import {
    Animator,
    AnimationClip
} from 'pixi-animator';

Next we make sure to set up the Animator (and we'll set up the PIXI app here):

const app = new PIXI.Application({ width: 300, height: 300, backgroundColor: 0x1099bb });
document.body.appendChild(app.view);

const animator = new Animator();

When an instance of the Animator is created, it also creates an empty sprite. This empty sprite is used to display the animation by switching it's texture to the frame that we're supposed to show. You have to take this sprite and add it to whatever group you want. This is also where you should adjust any properties like position or scale:

app.stage.addChild(animator.animation);

Next, the Animator needs to update the animation so you need to put its update method in your game loop like so:

app.ticker.add(() => animator.update());

Next you'll want to lod your images and make them into sprites and create animation clips from them. Animation clips take the following arguments:

param	type	description	default
key	string	A unique key that is used to reference the AnimationClip in the Animator
length	number	The amount of time, in milliseconds, that the animation should take to get from the first sprite to the last.
sprites	Array<PIXI.Sprite>	The sprites that make up the animation.
timeline	Array<Array>	The timeline is used by the Animator to know when to stop displaying a sprite and move on to the next sprite.
loop	boolean	Indicates whether the animation should play on a loop or not.	false

// Get your images however you wish, for me I'm using gingerale to do so.
const sprites = [...]; // Array of sprites.

// Create a looping walk animation from the first 4 frames of the spritesheet.
// A breakdown of the timeline is as follows:
// Play frame 0 until 101ms.
// Play frame 1 until 201ms.
// Play frame 2 until 301ms.
// Play from 3 until the end.
const walk = new AnimationClip('walk', 400, sprites.slice(0, 4), [
    [100, 0],
    [200, 1],
    [300, 2],
    [400, 3],
], true);

// Add the animation to the Animator.
animator.add(walk);

// Play the walk animation.
animator.play('walk');

API

The API is split up into two parts, the AnimationClip and the Animator.

AnimationClip

AnimationClip defines the structure of an animation to pass to the Animator.

param	type	description	default
key	string	A unique key that is used to reference the AnimationClip in the Animator
length	number	The amount of time, in milliseconds, that the animation should take to get from the first sprite to the last.
sprites	Array<PIXI.Sprite>	The sprites that make up the animation.
timeline	Array<Array>	The timeline is used by the Animator to know when to stop displaying a sprite and move on to the next sprite.
loop	boolean	Indicates whether the animation should play on a loop or not.	false

Example:

// Creating a looping 
// Create a looping walk animation from the first 4 frames of the spritesheet.
// A breakdown of the timeline is as follows:
// Play frame 0 until 101ms.
// Play frame 1 until 201ms.
// Play frame 2 until 301ms.
// Play from 3 until the end.
const walk = new AnimationClip('walk', 400, spritesForAnimation, [
    [100, 0],
    [200, 1],
    [300, 2],
    [400, 3],
], true);

The AnimationClip has no other properties or methods, it is just used by the Animator to have a structured set of animations.

Animator

The Animator is used to manage animations and their properties.

add

Adds an AnimationClip to the Animator.

param	type	description	default
animationClip	AnimationClip	The AnimationClip to add to the Animator.
overwrite	boolean	Indicates whether the AnimationClip should replace an existing AnimationClip with the same key.

Example:

// Creating a looping 
// Create a looping walk animation from the first 4 frames of the spritesheet.
// A breakdown of the timeline is as follows:
// Play frame 0 until 101ms.
// Play frame 1 until 201ms.
// Play frame 2 until 301ms.
// Play from 3 until the end.
const walk = new AnimationClip('walk', 400, spritesForAnimation, [
    [100, 0],
    [200, 1],
    [300, 2],
    [400, 3],
], true);

animator.add(walk);

remove

Removes an AnimationClip from the Animator by its key.

param	type	description	default
key	string	The key of the AnimationClip to remove from the Animator

Example:

animator.remove('walk');

play

Plays the AnimationClip with the specified key.

param	type	description	default
key	string	The key of the AnimationClip to play

Example:

animation.play('walk');

stop

Stops playing the AnimationClip that is currently playing.

param	type	description	default
reset	boolean	If set to true, the AnimationClip will be reverted to its first frame. Otherwise, the AnimationClip will stop on the frame that it ended on.	false

Example:

// Stopping the animation on its current frame.
animator.stop();

// Stopping the animation and resetting it back to the first frame.
animator.stop(true);

update

Updates the animation to show the correct frame that the AnimationClip is on. This needs to be called during the game loop for smooth animations.

Example:

// Adding the `update` method to PIXI's ticker.
app.ticker.add(() => animator.update());

// Using `RequestAnimationFrame`.
function update() {
    animator.update();

    requestAnimationFrame(update);
}
update();

Tests

The tests for pixi-animator are browser based so to run them you will first need to start the local testing server like so:

$ npm run test

then you will need to navigate to https://localhost:3000 in your browser to run all of the available tests.

License

MIT