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.
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.1 code as a zip file. Version 0.2 methods are also available to download separately: sample 0.2 code.
What's new in version 0.2?
Click here to see what's new in version 0.2 - for all the features that control the slider in the above demo...
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.2
Version 0.2 gives you a whole lot more control over sprite behaviour, after you have instantiated them. This allows you create functionality like the slider at the top of this page which changes the speed and direction of sprites and backgrounds. Version 0.2 also allows you to stop, start and toggle sprite animation, and play animations for a fixed number of frames.
Let's assume you want a sprite $('#bird') and a background comprising two independent items $('#clouds') and $('#hills') on your page:
$('#bird').sprite({fps: 9, no_of_frames: 3});
$('#clouds').pan({fps: 30, speed: 0.7, dir: 'left', depth:5});
$('#hill').pan({fps: 30, speed: 3, dir: 'left', depth: 50});
Note that we have added a 'depth' parameter to the .pan() method. This is an important parameter if we want to produce animation where backgrounds animate at consistent speed, relative to their depth, where a depth of 0 is the horizon (which does not move at all) up to a maximum depth of 100 which would be an object close up to the viewer. Objects at depth 100 will move very fast. Objects at depth 50 will move at half speed, relative to objects at depth 100. For further details, see 'Changing background speeds relative to their depth', below...
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:
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:
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.
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.
