chippy-sprites 🐿
Philosophy
A lot of game frameworks are very heavy-weight and rigid. chippy-sprites is an attempt to build a basic animated sprite that could be used in HTML-based games that can be used without a heavy framework, and can be easily integrated into any game or app.
chippy-sprites also provides clean separation of concerns by organizing code using simple functions instead of classes. This makes the logic more reusable. If you want to load images using some other image loader, you can. If you want to create your own custom format for parsing sprite sheets or atlases, you can!
Right now chippy-sprites only works with sprite sheets that have fixed-sized frames.
Demo
You can load a demo sprite, or try out your own sprites, using this simple interactive demo.
You can also view the code for the demo.
Example
Here's an annotated example using plain javascript.
// First we need to load an image, if we don't already have one.sprites
Or using Jquery and browser-game-loop.
sprites
API
loadImage(src: url): Promise<Image>
Pass in an image url, get back a promise for a ready-to-use Image element. The promise will resolve when the image is fully loaded.
createSheet(props: object): object
Property | Type | Description |
---|---|---|
img | Image element | An Image element with the image already loaded |
rows | int | The number of rows in the sprite sheet |
cols | int | The number of columns in the sprite sheet |
All of these properties are required.
Returns a simple object with the sheet width and height, frame sizes, frame count, etc.
Example:
cols: 4 frameCount: 16 frameHeight: 733 frameWidth: 732 height: 2932 img: Image rows: 4 width: 2928
createSprite(sheet: sheet object, props: object): object
Takes a chippy sheet and some properties, and returns a sprite object that includes a DOM element where the sprite will render. You can place the element anywhere in your page.
Property | Type | Description | Default |
---|---|---|---|
backgroundColor | Any CSS color | Background color for the sprite, if the image has any transparency | "transparent" |
width | Number or 'auto' | The width (in px) that the sprite will render | 'auto' |
height | Number or 'auto' | The height (in px) that the sprite will render | 'auto' |
speed | Number | The number of frames to advance per each call to updateSprite |
1 |
All of these properties are optional.
About width and height
The width and height parameters can be used to scale your sprite to render at a different size. If you use the default value of "auto"
, your sprite will render at the same size as a single frame of the sheet.
About speed
The speed property is used to slow down or speed up the rate of animation. By default, the speed is 1
, and every call to updateSprite
will advance your sprite by one frame. If your game loop renders at 60 frames-per-second, your sprite frames will advance at 60 frames-per-second.
For animations with fewer frames, you will probably want to slow down the speed to a value less than 1
. For example, if your game loop renders at 60 frames-per-second, and your set your sprite's speed to .1
, your animation will advance one frame for every 10 calls to updateSprite
, which means your animation will render at 6 frames-per-second.
normalizeFrame(currentFrame: Number, frameCount: int): frameData: object
This function is used internally by updateSprite
to round partial frames, overflow frames, and negative frames (when animating backwards) to actual frame indices. It returns a frameData object with both an integer animation frame and a normalized copy of the partial value that was passed in. The partial frame is used to properly wrap values around the end of the actual frames (forward or backward), while still maintaining which partial frame we are on.
For example:
> frame: 1 partialFrame: 15