npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

spritenator

v1.0.0

Published

Smooth animations with dom elements and spritesheets.

Downloads

8

Readme

Spritenator

Spritenator

Spritenator is a micro lib that turns simple img element into sprite-sheet animations.

No dependencies, no jQuery, just plug and play! (pun intended)

Live example.

Install

Via bower:

bower install spritenator

Via npm

npm install spritenator

Or simply download the js files from /dist/ in this repo and include it in a script tag.

Usage Example

Lets start with a basic example.

To create a sprite, you first need to create an image element inside a div, and use your spritesheet as the image src:

<div id="sprite" style="width:100px; height:100px;">
    <img src="sprite.png">
</div>

Now to init the sprite:

// first define the different animations in the sprite-sheet (see file example/sprite.png for more info)
// note: steps goes from top-left corner to bottom right (starting with 0)
var animations = {
    "idle": Spritenator.animation({steps: [0,1,2,3,4,5,6,7,8,9], fps: 5}),
    "taunt": Spritenator.animation({steps: [10,11,12,13,14,15,16,17,18,19], fps: 12, next: "idle"}),
    "hop": Spritenator.animation({steps: [20,21,22,23,24,25,26,27,28,29], fps: 12}),
};

// init sprite on the div element
// note: the "{x: 10, y: 5}" param define the spritesheet size: 10 columns and 5 rows of animation steps. 
var elem = document.getElementById("sprite");
Spritenator.create(elem, {x: 10, y: 5}, animations);

Spritenator API

After seeing a simple example, lets dive into the API.

Spritenator.animation()

To create a new sprite you first need to define a dictionary with all the spritesheet animations. You use Spritenator.animation() to define each animation sequence.

For example:

var animations = {
    "some_anim": Spritenator.animation({steps: [0,1,2,3,4,5,6], fps: 5, loop: true}),
};

Will define a sprite with a single animation, "some_anim", that will play steps 0-6 in an endless loop with 5 frames per second.

The function Spritenator.animation() accept a single dictionary as param, with the following options:

steps

A list with the animation sequence steps. Every value in this list is a step index, counted from top-left corner.

delays

Optional list of extra delays, in milliseconds, to add to each animation step.

For example if you want the third step to halt for 1.5 seconds, you can set [0, 0, 1500] as delays (the two 0's in the beginning of the list is to skip step 1 and 2).

fps

Frames per seconds, determine the general animation speed (delays, if provided, are added on top of the basic speed).

loop

If true, this animation will play in loops (default to true). If false, animation will play once and stop.

next

Optional string or function to determine the next animation to play right after this one ends.

For example, you can define an animation sequence that will play once and then switch to an animation called "idle".

startDelay

Delay, in milliseconds, to add to first animation step.

endDelay

Delay, in milliseconds, to add to last animation step.

onStart

Function to call whenever animation sequence starts playing.

onEnd

Function to call whenever animation sequence ends.

Creating Sprites

Sprites are the most basic object of Spritenator. They attach to an existing div element and play animation sequences with it, using the internal img tag.

The function Spritenator.create() creates a new sprite instance. It requires the following params:

element

The div element to create the sprite from. Must be in the following format:

<div id="some-id" style="width:100px; height:100px;">
    <img src="sprite.png">
</div>

Where sprite.png is your spritesheet file. Note: the containing div must define sprite size.

sheetSize

A dictionary with x and y, representing the spritesheet size, eg how many columns and rows of animation steps it contains (note: spritesheets are assumed to have the same size for every animation step).

animations

The animations dictionary we defined above, using Spritenator.animation().

Retrieving existing sprites

After you create a sprite instance you can always get it back from the dom element, using Spritenator.get():

// assuming sprite was init on 'element' before.
var element = document.getElementById("my-id");
var sprite = Spritenator.get(element);

Sprite API

Once you create a new sprite instance, you can use the following sprite API:

play (name, forceReset, next)

Start playing an animation sequence.

  • name: the name of the animation to play (key from the animations dictionary).
  • forceReset: if true will restart animation even if already playing it.
  • next: can override the animation default 'next' param, and decide which animation to play after this sequence ends (can be a string or a callback).

reset function()

Reset current animation.

current()

Get the name of the animation currently playing.

destroy()

Destroy and cleanup this sprite. Note: image element will remain at its current state. If you need to remove the dom elements as well, its your responsibility.

speed [float]

Speed factor you can set to change the speed of all animations in sprite. For example, if you set

sprite.speed = 3.0;

All animations in sprite will play x3 times faster.

paused [boolean]

If true, animation will pause until set to false.

step (time)

This function will advance the animation by a given time factor (in milliseconds).

It is used internally and normally you should not use it, but it might become handy for some special effects.

What next

To learn more about Spritenator please see the Live Example, or you can explore the JavaScript file yourself (its really just one lightweight JS file).

License

Spritenator is distributed under the MIT license and is free for any personal and / or commercial use.