speet.js: Dynamic Spritesheet Generator for web

Minimum module to create spritesheet dynamically.
Currently, it is mostly for creating pixi.js spritesheet.

Install

npm install speet

Usage

Sample

Basic

Traditional browser style

<script src="path/to/speet.js"></script>
<script>
const imageList = {
  player: "./assets/player.png",
  enemy: "./assets/enemy.png",
}

speet.generate(imageList)
.then((ss)=> {
  console.log(ss.data); // json of sprite frame data
  document.body.appendChild(ss.image);
})
</script>

Modern ES style

import {generate} from "speet";

const imageList = {
  player: "./assets/player.png",
  enemy: "./assets/enemy.png",
};

(async ()=> {
  const { image: ssImage, data: ssData } = await generate(imageList)
  console.log(ssData); // json of sprite frame data
  document.body.appendChild(ssImage);
})();

Combination with pixi.js

import {generate} from "speet";
function createPixiSpriteSheet(image, dataJson) {
  return new Promise((resolve)=> {
    const baseTexture = PIXI.BaseTexture.from(image);
    const ss = new PIXI.Spritesheet(baseTexture, dataJson);
    ss.parse(()=> resolve(ss))
  })
}

const imageList = {
  player: "./assets/player.png",
  enemy: "./assets/enemy.png",
};

(async ()=> {
  // pixi app
  const app = new PIXI.Application();
  document.body.appendChild(app.view);
  const interaction = app.renderer.plugins.interaction;

  // Create pixi spritesheet
  const baseSS = await speet.generate(imageList, { forcePOT: true });
  const pixiSS = await createPixiSpriteSheet(baseSS.image, baseSS.data);

  // Add sprite using spritesheet
  const spr = new PIXI.Sprite(pixiSS.textures["player"]);
  app.stage.addChild(spr);
  interaction.on('pointerdown', (e) => {
    spr.position.set(e.data.global.x, e.data.global.y)
  });
})();

Setting options

(async ()=> {
  const ss = await speet.generate(imageList, {
    padding: 4,
    border: 4,
    forcePOT: true,
    formatter: (sprites) => {
      return sprites.map((s)=> {
        return {
          x: s.x,
          y: s.y,
          w: s.width,
          h: s.height,
        }
      })
    }
  });
  
  console.log(ss.data); // array of objects with x, y, w, h property
})();

| Name | Type | Description | Default | |-----------|----------|----------------------------------------------------------------------------------------------------------------------------------------|---------| | padding | number | Sets padding between sprites. | 2 | | border | number | Sets border padding at the edges of spritesheet. | 0 | | forcePOT | boolean | Force spritesheet size to be power of two (e.g. 512x512). This option is for optimization of GPU-powered graphic system (mostly WebGL). | false | | formatter | function | Sets your own formatting function for spritesheet data json. | undefined |

Misc

Supported types of image

Instead of image path string, you can also pass dataURI string, HTMLImageElement, or HTMLCanvasElement.

function createCanvasRect(w, h) {
  const canvas = document.createElement('canvas');
  const ctx = canvas.getContext('2d');
  canvas.width = w;
  canvas.height = h;
  ctx.fillStyle = "#D93788";
  ctx.fillRect(0, 0, w, h);
  return canvas;
}

const imageList = {
  eggplant: "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADcAAAAtCAMAAAA9SAOJAAAAYFBMVEUAAAAiIDRFKDxmOTGPVjvfcSbZoGbuw5r78jaZ5VBqvjA3lG5LaS9SSyQyPDk/P3QwYIJbbuFjm/9fzeTL2/z///+brbeEfodpampZVlJ2QoqsMjLZV2PXe7qPl0qKbzD7Y7zPAAAAIHRSTlMA/////////////////////////////////////////5KarXYAAACqSURBVEiJ7dOxDsMgDEVRZhg8ZXn//6F1qFAqgm2eo3bqDVOUI1tCKeXfs2prv3W15sbpk2LnybBOM+N4V6EEtGutO4XkPOBktMOIu3pcJRnhgITDHPu9JpFbIWW+W6PImUqZBOw49Gj7DrYTx9lLdha5ecPBxF/TdPyaknOPGOvkYowL2cqJxGx28hkcVywUsGKgt/J+2OW88WrL3XOYB11mykgt7R76ei8wAEus0oBkTgAAAABJRU5ErkJggg=="
  canvasRect: createCanvasRect(128, 128),
}

speet.generate(imageList)

Other

Sprite packing algorithm is inspired by bertrand_a's idea.