No Flash? No Problem!

Documentation

Spritely is a simple plugin with only two key methods, sprite() and pan() both of which simply animate the background-image css property of an element. The difference between the two is that a 'sprite' image contains two or more 'frames' of animation, whereas a 'pan' image contains a continuous image which pans left or right and then repeats. Typically, in either case, you would use a png file (with or without transparency) for this. You might wish to use a transparent gif for Internet Explorer 6, though it probably won't look as good. Your html elements must already be the correct size you want the sprite to appear, but the background image will typically be larger than the html element, and the spritely methods reposition the background image within the html element.

 

For documentation in languages other than English, please see Unoffical Documentation.

 

Please note: there is a problem with the current version of Mobile Safari on the iPad

On the iPad, using the pan() method may cause crashes in Mobile Safari. The issue does not just affect Spritely and is currently beyond our control - it appears to be caused by a bug in Mobile Safari where small adjustments to the background-position property in a short amount of time trigger a crash. A possible workaround is to use very low framerates (under 10 fps) or smaller background images (less than about 1000px wide). Mobile Safari on the iPhone seems not to be affected.

 

Quick start

If you're impatient to try out Spritely and want to see some self-contained working examples, you can download some sample 0.4 code as a zip file.

 

What's new in version 0.6?

Click here to see what's new in version 0.6

 

Animating an image with the 'sprite()' method

Here's a quick example to get you started... The following method animates one of the bird 'sprites' flying around this page. The 'sprite' is composed of three frames in a transparent png image, where each frame is side by side:


Now we simply need to create a div called 'bird', style it to exactly the correct size (180x180 pixels in this case), and animate it with the sprite() method. The two options we need to use are 'fps' (frames per second) and 'no_of_frames', e.g. three frames for the above image:

$('#bird').sprite({fps: 12, no_of_frames: 3});


To make the mouse attract the sprite when you click the screen, use this:

$('#bird').sprite({fps: 12, no_of_frames: 3}).activeOnClick().active();
$('body').flyToTap();


The active() method makes this sprite the active sprite on launch - otherwise a sprite with activeOnClick() becomes active only when you click it (or touch it using an iPhone/iPad).

The $('body').flyToTap() method watches for a click on the page at which point, after any current move is complete, the sprite moves to the clicked location. After a few second, if a random movement method has been applied (see below), it then moves away again.

To make the sprite move in a random way, within pixel constraints (speeds are in milliseconds), use this:

$('#bird')
.sprite({fps: 8, no_of_frames: 3})
.spRandom({
top: 70,
left: 100,
right: 200,
bottom: 340,
speed: 4000,
pause: 3000
});

 

Panning a background image with the 'pan()' method

Here's how you can 'pan' a background image, like the hills in the demo at the top of this page:

 

 

To make the background image pan continually to the left, create an html div element smaller than the image itself and use css to place your image as the background image, making sure you set the background image repeat to 'repeat-x', e.g. it repeats continuously in the horizontal axis.

Now animate it with spritely's 'pan()' method:

$('#trees').pan({fps: 30, speed: 2, dir: 'left'});


You can adjust the speed (pixels per frame) and frames per second independently of one another. Why? Because a lower speed will result in a smoother pan, however a higher frames per second may result in slower performance (especially on devices like iPhone). You'll need to experiment to get the right balance between smooth animation and page performance.

To layer background images over each other, simply place the html images below each other, or adjust the 'z-index' css property, then set the fps and speed properties to give the illusion of depth. A more distant background image should move more slowly (lower fps) than a close-up one.

 

What's new in version 0.6?

We're excited about version 0.6. Why? Because Spritely now has events!

Spritely 0.6 introduces the ability to call a function when a sprite reaches the first, last, or any other frame. Three new options are introduced for this: on_first_frame, on_last_frame and on_frame. This is extremely useful, because it means that you can change the 'state' of a sprite on any given frame, or stop the animation altogether.

 

Here's an example:

$('#sprite').sprite({
fps: 9,
no_of_frames: 24,
on_first_frame: function(obj) {
obj.spState(1); // change to state 1 (first row) on frame 1
},
on_last_frame: function(obj) {
obj.spStop(); // stop the animation on the last frame
},
on_frame: { // note - on_frame is an object not a function
8: function(obj) { // called on frame 8
obj.spState(2); // change to state 2 (row 2) on frame 8
},
16: function(obj) { // called on frame 16
obj.spState(3); // change to state 3 (row 3) on frame 16
}
}
});

Also new in 0.6:

You may now tell a sprite to start playing on a particular frame:

$('#sprite').sprite({fps: 9, no_of_frames: 24, start_at_frame: 8}); 

 

What was new in version 0.5?

New method: destroy()

Spritely 0.5 introduces the destroy() method. This resets an element entirely and removes all animation from it.

For example,

$('#balloons').destroy();

 

 

What was new in version 0.4?

Two new features are available in version 0.4:

Vertical Panning

The much awaited vertical panning is now available. This means you can specify 'up' or 'down' as directions when calling pan().

For example,

$('#balloons').pan({fps: 30, speed: 3, dir: 'up', depth: 70});

 

Animate sprites backwards

It is now possible to play a sprite in reverse (e.g. rewinding). This is achieved with the 'rewind' option. For example,

    $('#bird')
        .sprite({fps: 1, no_of_frames: 3, rewind: true})
        .spRandom({top: 50, bottom: 200, left: 300, right: 320})
        .isDraggable()
        .activeOnClick()
        .active();

 

 

Changing Frames Per Second

You can now change the frames per second with the fps() method:

 

$('#bird').fps(30);
$('#hills').fps(12);

 

Changing background speeds relative to their depth

Now that our backgrounds have a depth, we can easily change their speed, relative to each other with the $.spRelSpeed() method.

 

Move the slider in the above demo to see the affect depth has on speed of background objects, comparing it with this image:

 

Depth explained

 

To change the background speeds relatively, combine all backgrounds in a single jQuery selector and use the spRelSpeed() method:

 

$('#clouds, #hills').spRelSpeed(30);

 

... where the 'spRelSpeed' value is the amount of pixels to move, per frame, bearing in mind that it is relative to the item's depth. Thus spRelSpeed(30) applied to an object at depth 100 will move the object at 30 pixels per frame. Applied to an object at depth 50 the object will move at 15 pixels per frame. You can change frames per seconds separately - see above.

 

Changing background speed absolutely

The $.spSpeed() method allows you to change a background speed absolutely (this is equivalent to a depth of 100):

 

$('#hills').spSpeed(20); 

 

Once again, the speed value is the number of pixels to move, per frame.

 

Changing direction of background animations

The spChangeDir('left') or spChangeDir('right') methods may be used on a background animation to change direction left or right respectively:

 

$('#hills').spChangeDir('left'); // change background direction left (travel right!)
$('#hills').spChangeDir('right'); // change background direction right (travel left!)

 

Changing direction or 'state' of sprite animations

To change the direction of sprites, you need to use a different method, $.spState(), and you need a different image, with multiple rows of frames, one row for each state, as per the following example:

 

Two-state sprite image

 

The second row (flying backwards) represents the second 'state' of the sprite, and you therefore change its direction with:

 

$('#bird').spState(2); // fly backwards (row 2 of the sprite)
$('#bird').spState(1); // fly forwards (row 1 of the sprite)

 

Stopping and starting animations

To stop and start sprite and background animations, use the spStop(), spStart() and spToggle() methods:

 

$('#bird').spStop(); // stop a sprite or background animation at the current frame
$('#bird').spStop(true); // stop a sprite or background animation, returning to frame 1
$('#bird').spStart(); // start a sprite or background animation
$('#bird').spToggle(); // toggle a sprite or background animation on or off

 

Make a sprite draggable

The isDraggable() method will allow a sprite to be dragged to any point on the screen. There are also three parameters which can be used with this method; start, stop, and drag. These optional callbacks will fire at the start, end, or whilst you are dragging the item. See the example below:

$('#bird').isDraggable({
start: function() {
// Fade sprite to 70% opacity when at the start of the drag
$('#bird').fadeTo('fast', 0.7);
},
stop: function() {
// Return sprite to 100% opacity when finished
$('#bird').fadeTo('fast', 1);
},
drag: function() {
// This event will fire constantly whilst the object is being dragged
}
});

 

Please note that the isDraggable() method requires jQueryUI.

 

Combining actions to produce a single action

You can of course combine actions into a single method, so that you can control the movement of your entire scene. The following code, for instance, defines a method 'fly_forwards_quickly()' that you can control with a single click:

 

var fly_quickly_forwards = function() {
$('#bird')
.fps(20)
.spState(1);
$('#clouds, #hills')
.spRelSpeed(30)
.spChangeDir('left');
};

 

Note that you are recommended to build all your methods into a single object rather than creating page variables, however we include the above example for the sake of simplicity.

 

Making a sprite play for a fixed number of frames

Another new method available in version 0.2, though not demonstrated in the demo, is the ability to create a sprite which plays for a fixed number of frames and then stops:

 

// play a sprite for a maximum of 30 frames
$('#my_sprite').sprite({fps: 9, no_of_frames: 3, play_frames: 30});

 

More examples

More code examples may be found by reading the source code of this page - and don't forget you can combine Spritely with other jQuery methods to produce complex animations.

 

Wordpress

We have implimented Spritely into the default TwentyEleven Wordpress theme as an example to show how you can add Spritely to your custom Wordpress themes.

 

TwentyEleven - Spritely

 

One final word of caution...

Use Spritely sparingly. A little Spritely goes a long way, but over-ambitious use of these techniques may lead to poor performance, especially on mobile devices. A little movement on a large page may be better than a lot of movement on a small one. Please test Spritely carefully for your target audience/platforms before you develop your site as performance may vary from platform to platform.

 

Unofficial Documentation

We list unofficial documentation and resources here. This also includes translations of the official documentation.

 

Translations