Wondering what’s next for npm?Check out our public roadmap! »

    pixi-animator
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.0 • Public • Published

    Logo sprites from A Platformer in the Forest

    PIXI Animator

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

    NPM version Known Vulnerabilities npm NPM downloads issues license Gitter

    Table of Contents

    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

    Install

    npm i pixi-animator

    DownloadsWeekly Downloads

    5

    Version

    0.2.0

    License

    MIT

    Unpacked Size

    3.22 MB

    Total Files

    27

    Last publish

    Collaborators

    • avatar