README

Spritesheet Logo">

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));
})();

Documentation

`spritesheet(files, [options])`

The methods accept two arguments.

Name	Type	Default	Comment
files	`Array<String>`	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 file
frames - Set of all frames/spites with path as key

Each frames gives data about itself:

frame - The x, y position on the whole image and w, h for the size
rotated - Tell is the sprite have been rotated (not yet supported)
trimmed - Tell is the sprite have been cropped
spriteSourceSize - The relative x, y position and w, h size
sourceSize - The original w, h size

Want to display your generated spritesheet easily on a browser canvas ? Checkout Pencil.js the nice 2D drawing library.

License

MIT

@pencil.js/spritesheet

Usage no npm install needed!