Animate Sprite

Demo - codepen

animate-sprite is a lightweight library (6kb minified) which allows to animate a sequence of frames that looks like 3d. It supports playing full animation sequence, rotate an image by the mouse and touch, autoplay, loop, reverse and exposes an API to programmatically control the animation.

To use it you should export animation from your 3d app as a series of frames and combine them in one image file (sprite).

• Installation
• Usage
• Options
• Methods
• Events
• Browser support
• License

Installation

Browser script tag

Add with CDN link:

<script src="https://unpkg.com/@its2easy/animate-sprite"></script>

Or download minified version from repository and include in html:

<script src="animate-sprite.min.js"></script>

npm

npm i @its2easy/animate-sprite --save

Usage

Create an element with background

<div id="sprite" style="background-image: url('images/sprite.jpg')"></div>

Initialize with options

var element = document.getElementById('sprite');
var sprite = animateSprite.init(element,
    {
            width: 800, /* required */
            height: 450, /* required */
            cols: 10,
            frames: 90, /* required */
            fps: 60,
            loop: true,
            draggable: true
    }
);
sprite.play();

Or with inline options

<div id="sprite" 
    style="background-image: url('images/sprite.jpg')"
    data-width="700"
    data-heigth="400"
    data-frames="60"
></div>

var element = document.getElementById('sprite');
var sprite = animateSprite.init(element);
sprite.play();

Inline options have higher priority

Usage with bundlers

import { init as spriteInit } from '@its2easy/animate-sprite';
let sprite = spriteInit(element, options);

If ES modules are supported - untranspiled es6 code will be imported, you should add it your build process. Example for webpack:

rules: [
    {
        test: /\.js$/,
        exclude: /node_modules(?!(\/|\\)@its2easy)/,
        use: {
            loader: 'babel-loader',
        }
    }
]

or

rules: [
    {
        // basic js rule
        test: /\.js$/,
        exclude: /node_modules/,
        use: {
            loader: 'babel-loader',
        }
    },
    {
        // additional rule
        test: /\.js$/,
        include: /node_modules(\/|\\)@its2easy/,
        use: {
            loader: 'babel-loader',
    }
]

Responsive behavior

By default, you don't have to specify block sizes in css. Element with the sprite will take all available width and set its height based on width/height ratio from configuration options. To limit the size add max-width to the sprite. You can also explicitly set width, but it will no longer adapt to the container width (on small screens this can be changed with width: auto inside media query).

On page load sprite block will have 0px height, to prevent this you can manually add height style (and maybe backgroud-size), it will be overwritten after initialization.

Options

If multiple time options (frameTime, duration or fps) are set at the same time, frameTime has higher priority, then duration, then fps.

Methods

Methods can be chained sprite.setReverse(true).play()

init

Initializes and returns an instance of a sprite.

parameters

• element : NodeElement - dom element
• options : Object - configuration options

play

Starts animation

stop

Stops animation

toggle

Toggle between play and stop

prev

Animate to the previous frame

next

Animate to the next frame

reset

Stop animation and move to the first frame

setFrame

Set frame (without animation)

parameters

• frame : Number - Frame number

sprite.setFrame(35);

setReverse

Change the direction of the animation

parameters

• reverse : Bool - true to reverse, false to normal direction

sprite.setReverse(true);

setOption

It sets one of the allowed options (frameTime, duration, fps) on the fly

parameters

• option : String - Option name
• value : Number - New value

sprite.setOption('frameTime', 40);

destroy

Destroy sprite instance

getCurrentFrame

Returns current frame number

isAnimating

Returns true if sprite is animating, else false

Events

sprite:last-frame

fires after the last frame is set

sprite:first-frame

fires after the first frame is set (when reverse is true)

Don't fire with draggable rotation

var element = document.getElementById('sprite');
element.addEventListener('sprite:last-frame', function () {
    console.log('last frame');
})

Browser support

It supports browsers that have more than 1% usage and not dead

• latest versions of Chrome, android Chrome, Firefox
• Safari 13+,
• iOS Safari 12.2+,
• Edge 18+
• some rare browsers

License

Animate Sprite is provided under the MIT License