Specification for spritesmith engines
In addition to this repo, we offer an integration test suite via spritesmith-engine-test.
This documentation is for version:
1.1.0
In spritesmith, the following terms and definitions will be used:
engine- A library that handles interactions between imagesimage- Object containing metadata about an image file or buffercanvas- Class that handles placing images onto a visual layer and generating an output image
When spritesmith is generating a spritesheet, we will perform the following steps:
- Process images into metadata (e.g. get size of each image)
- Calculate layout based on user preferences (outside of
engine) - Create canvas to place images on
- Place each image on canvas
- Export canvas as an image
A spritesmith engine returns the following properties on its module.exports
String of current specification version the engine is supporting (e.g. '1.0.0')
Function to creates a canvas for engine. This should have the function signature (width, height, cb)
- width
Number- Width in pixels for the canvas - height
Number- Height in pixels for the canvas - cb
Function- Error-first callback function to return canvas viacbwill have the function signature(err, canvas)- If there is an error, run
cb(err). Otherwise, callback with a canvas (i.e.cb(null, canvas)) - This should be called asynchronously (e.g. if creation is synchronous, use
process.nextTick) - Canvas structure is documented in the canvas structure section
Function to create images which will later be laid out via a canvas. This should have the function signature (images, cb)
- images
String[]- Array of filepaths to images - cb
Function- Error-first callback function to return image metadata viacbwill have the function signature(err, images)- If there is an error, run
cb(err). Otherwise, callback with an array of image metadata (i.e.cb(null, images)) - This should be called asynchronously (e.g. if creation is synchronous, use
process.nextTick) - image
Object- Metadata container about corresponding input image at same index- height
Number- Height in pixels of corresponding input image at same index - width
Number- Width in pixels of corresponding input image at same index - Any other metadata can be stored here and will be passed to
canvas.addImage(e.g.filepath)
- height
A canvas for a spritesmith engine should be an object with the following structure:
- addImage
Function- Method to add an image to canvas - export
Function- Method to export canvas as an image
canvas.addImage should have the function signature (image, x, y)
- image
Object- Image object created viaengine.createImages- This will be the same object so any additional metadata will be accessible (e.g.
filepath)
- This will be the same object so any additional metadata will be accessible (e.g.
- x
Number- Horizontal coordinate to position left edge of image - y
Number- Vertical coordinate to position top edge of image
Note: This method is not asynchronous intentionally. Please run all asynchronous actions during export. We suggest saving any critical metadata to canvas and reusing it during export.
canvas.export should have the function signature (options, cb)
- options
Object- Modifiers to indicate how to export (e.g.format,quality)- format
String- Image format to export canvas as (e.g.png,jpeg) - Any other options can be defined custom to your engine (e.g.
quality)
- format
- cb
Function- Error-first callback function to return export image viacbwill have the function signature(err, result)- If there is an error, run
cb(err). Otherwise, callback with an array of image metadata (i.e.cb(null, result)) - This should be called asynchronously (e.g. if creation is synchronous, use
process.nextTick) - result
String- Binary encoded string of output image (e.g.Buffer.toString('binary'))- This novice mistake was done at the inception of
spritesmith. Thankfully it will be patched soon.
- This novice mistake was done at the inception of
In order to make our engines easily discoverable, please provide a spritesmith-engine keyword. Here's a list of existing spritesmith engines:
https://www.npmjs.com/browse/keyword/spritesmith-engine
In lieu of a formal styleguide, take care to maintain the existing coding style.
Support this project and others by twolfson via gratipay.
As of Oct 28 2015, Todd Wolfson has released this repository and its contents to the public domain.
It has been released under the UNLICENSE.