devkit-spriter
v0.0.9
Published
a 2D spriter for the DevKit game engine
Downloads
3
Readme
devkit-spriter
The devkit-spriter package provides three functions for the devkit build process:
- loading images
- spriting images into spritesheets
- caching spritesheets
Loading Images
To load images, use the loadImages(filenames : String[]) :
Promise<ImageInfo[]>
function:
var spriter = require('devkit-spriter');
spriter.loadImages(['image1.png', 'image2.png'])
.then(function (images) {
// images is an array of ImageInfo objects
});
An ImageInfo
object is a representation of an image that the spriter can use
to create spritesheets. It has the following properites:
x : int
the location of the image in a spritesheety : int
the location of the image in a spritesheetfilename : string
the full path to the image on diskhash : string
an md5 hash of the image bitmapbuffer : ImageBuffer
the pixels of the image wrapped in a Jimp object (see https://github.com/oliver-moran/jimp). An ImageBuffer extends the Jimp base class with adrawImage
call (based on the HTML5 canvasdrawImage
call and promisifiesgetBuffer
andwrite
.width : int
the original image widthheight : int
the original image heightarea : int
the image's areadata : Buffer
the raw data in a nodeBuffer
, alias forbuffer.bitmap.data
depth : int
the number of channels for the image, e.g. 4 for rgbahasAlphaChannel : boolean
true if the depth is 4margin : {top : int, right : int, bottom : int, left : int}
the size of the margins around the image (transparent regions in original image)contentWidth : int
the width minus the marginscontentHeight : int
the height minus the marginscontentArea : int
the content area, the number of pixels this image will occupy on a spritesheet (excluding spritesheet padding)
Spriting images
To sprite images, first load them into ImageInfo objects. Then call
layout(ImageInfo[], opts) : Spritesheet[]
:
var spritesheets = spriter.layout(images);
Note that this is a synchronous call since no IO is performed. This call maybe expensive, depending on how many images you provide.
opts
can include:
padding : int
number of pixels on each side of an image to pad out the image. Padding works by extending the border of the image. Defaults to2
, which prevents most texture artifacts in OpenGL.maxSize : int
the largest dimension of a spritesheet. Spritesheets cannot exceed this value in either width or height. Defaults to1024
.powerOfTwoSheets : boolean
whether sheets should round their dimensions up to the nearest power of two. Defaults totrue
.name : string
a prefix for spritesheet namesext : string
a postfix for all spritesheet names
Caching spritesheets
The spriter provides utility functions for reading and writing to a disk
cache. It verifies the integrity of the disk cache before returning cached
results. Call loadCache(cacheFile : string, outputDirectory :
string) : Promise<DiskCache>
to load a disk cache file:
var group = 'group1';
var filenames = ['image1.png', 'image2.png'];
spriter.loadCache('.my-cache-file', 'build/spritesheets/')
.get(group, filenames)
.then(function () {
// cached
})
.catch(Spriter.NotCachedError, function () {
// should resprite
});
The spriter is commonly used with groups of spritesheets, since a common use case is to sprite images that will probably be used together into the same spritesheet(s). For example, all sprites in a common animation should be placed in a single group. Compression is another example of grouping: images compressed as jpgs should be sprited separately from images compressed as pngs so that the resulting spritesheets can be compressed correctly.
Calling get
on DiskCache
verifies the following:
- no files were added to the group
- no files were removed from the group
- no files have changed in the group (comparing modified times)
- the generated spritesheet files still exist
- the spritesheet data looks valid (every sheet has a name and images, every image in the spritesheet is in the group)