Skip to content

🥤 Pack images into a spritesheet.

License

Notifications You must be signed in to change notification settings

pencil-js/spritesheet

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

47 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Spritesheet Logo

Package size

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

Related

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

License

MIT