Pack a set of images into a single spritesheet along its json description file. (CLI version)
Install
npm install @pencil.js/spritesheet
Usage
import spritesheet from "@pencil.js/spritesheet";
import { writeFileSync } from "fs";
// List of files to pack
const files = ["image1.png", "image2.jpg", "image3.gif"];
const options = {
outputFormat: "png",
};
// Call the async function and extract the json and image values
(async () => {
const { json, image } = await spritesheet(files, options);
// Write the files (for example)
writeFileSync("spritesheet.png", image);
writeFileSync("spritesheet.json", JSON.stringify(json));
})();
import { writeFileSync } from "fs";
// List of files to pack
const files = ["image1.png", "image2.jpg", "image3.gif"];
const options = {
outputFormat: "png",
};
// Call the async function and extract the json and image values
(async () => {
const { json, image } = await spritesheet(files, options);
// Write the files (for example)
writeFileSync("spritesheet.png", image);
writeFileSync("spritesheet.json", JSON.stringify(json));
})();
Documentation
spritesheet(files, [options])
The methods accept two arguments.
| Name | Type | Default | Comment |
|---|---|---|---|
| files | Array |
required | List of paths to the images |
| options | Object |
(see below) | Some options |
options
You can specify some options on the second argument.
| Name | Type | Default | Comment |
|---|---|---|---|
| outputFormat | String |
"png" |
Format of the output image ("png" or "jpeg") |
| outputName | String |
"spritesheet.png" |
Name of the image file (for reference in the JSON file) |
| margin | Number |
1 |
Added pixels between sprites (can prevent pixels leaking to adjacent sprite) |
| crop | Boolean |
true |
Cut transparent pixels around sprites |
returns
spritesheet returns a Promise for an Object containing a json and image field.
| Name | Type | Comment |
|---|---|---|
| json | Object |
All data related to the spritesheet (example) |
| image | Buffer |
The result image as a buffer |
JSON
The returned JSON file is composed of two parts:
meta- Global data about the generated fileframes- Set of all frames/spites with path as key
Each frames gives data about itself:
frame- Thex,yposition on the whole image andw,hfor the sizerotated- Tell is the sprite have been rotated (not yet supported)trimmed- Tell is the sprite have been croppedspriteSourceSize- The relativex,yposition andw,hsizesourceSize- The originalw,hsize
Related
Want to display your generated spritesheet easily on a browser canvas ? Checkout Pencil.js the nice 2D drawing library.