ase-parser

Parse Aseprite files with Node.js, no external dependencies.

Install

To install for use:

npm i ase-parse

Instructions

You'll probably want to get the Buffer of the Aseprite file in whatever way you feel like. For the example, we'll just use fs.readFileSync(). But you can get it from a network request, etc.

const Aseprite = require('ase-parser');
const fs = require('fs');

const buff = fs.readFileSync('./somefile.aseprite');
const aseFile = new Aseprite(buff, 'somefile.aseprite');

aseFile.parse();
console.log(aseFile.numFrames);

After parsing, you can get the data and do something like generate an image with the sharp npm lib, which accepts raw pixel data and supports image composition.

Here is a more advanced example generating a png image of the first frame using the sharp lib.

const Aseprite = require('ase-parser');
const fs = require('fs');
const sharp = require('sharp');

async function makePNG() {
  const buff = fs.readFileSync('./my_chocobo.aseprite');
  const ase = new Aseprite(buff, 'my_chocobo.aseprite');
  
  ase.parse();
  // Create a blank png image buffer that's the same size as the Aseprite sprite (only make the promise because we'll use Promise.all a little later)
  const bgPromise = sharp({create: {
    width: ase.width,
    height: ase.height,
    channels: 4,
    background: {r: 0, g: 0, b: 0, alpha: 0}
  }}).png().toBuffer();
  
  // Get the cels for the first frame
  const cels = ase.frames[0].cels
    // copy the array
    .map(a => a)
    .sort((a, b) => {
      const orderA = a.layerIndex + a.zIndex;
      const orderB = b.layerIndex + b.zIndex;
      // sort by order, then by zIndex
      return orderA - orderB || a.zIndex - b.zIndex;
    })
  
  // Create png image buffers per cel to create an image of the first frame (creating the Promises to be used)
  const otherPromises = cels.map(cel => {
    return sharp(cel.rawCelData, {raw: {width: cel.w, height: cel.h, channels: 4}}).png().toBuffer();
  });
  
  // Run the promises all at once to get the buffers for the base image and the cels to combine
  const [ bg, ...others ] = await Promise.all([bgPromise, ...otherPromises]).catch(console.log);
  
  // take the first image and add on the png buffers on top of it (the cels should be in order from bottom to top from the parse)
  const finalBuff = await sharp(bg)
    .composite(others.map((img, index) => ({
      input: img,
      top: cels[index].ypos,
      left: cels[index].xpos
    })))
    .png()
    .toBuffer();
  // saves the file as a png with the buffer from sharp.composite
  fs.writeFileSync(ase.name.replace('.aseprite', '.png'), finalBuff);
}

makePNG();

Aseprite Functions

constructor

Parameters:

• buffer: Expects a Node.js Buffer of the Aseprite file.
• name: Expects a string that's the name of the Aseprite file, including the extension.

Returns:

• Aseprite: Returns Aseprite.

Example:

const Aseprite = require('ase-parser');
const fs = require('fs');

const buff = fs.readFileSync('./somefile.aseprite');
const aseFile = new Aseprite(buff, 'somefile.aseprite');

parse

Description:
Parses the Aseprite file and populates the Aseprite class with the information from the file.

Parameters:

• none

Returns:

• none

Example:

const Aseprite = require('ase-parser');
const fs = require('fs');

const buff = fs.readFileSync('./somefile.aseprite');
const aseFile = new Aseprite(buff, 'somefile.aseprite');

aseFile.parse();

Aseprite Object

Field	Type	Description
frames	array of frame objects	frames
layers	array of layer objects	layers
fileSize	integer	size of the file (in bytes)
numFrames	integer	number of frames the Aseprite file has
width	integer	width (in pixels)
height	integer	height (in pixels)
colorDepth	integer	color depth (in bits per pixel)
paletteIndex	integer	position of the indexed color based on the palette
numColors	integer	number of colors
pixelRatio	string	width:height
name	string	name of the file
tags	arry of tag objects	tags
colorProfile	colorProfile object	Color profile
palette	palette object	Palette
tilesets	array of tileset objects	Tileset
slices	array of slice objects	Info on slices

Frame Object

Field	Type	Description
bytesInFrame	integer	size (in bytes)
frameDuration	integer	duration (in ms)
cels	array of cel objects	cels

Layer Object

Field	Type	Description
flags	layer flags	flags for the layer translated into a map
type	integer	type
layerChildLevel	integer	layer child level
opacity	integer	opacity (0-255)
tilesetIndex?	integer	the tileset id, if applicable
name	string	name of layer

Tag Object

Field	Type	Description
from	integer	first frame index
to	integer	last frame index
animDirection	string	Forward, Reverse, Ping-pong or Ping-pong Reverse
repeat	integer	repeat animation N times
color	string	hex color of the tag (no # included)
name	string	name

Color Profile Object

Field	Type	Description
type	string	None, sRGB or ICC
flag	integer	fixed gamma flag
fGamma	integer	fixed gamma
icc?	buffer	ICC profile data

Palette Object

Field	Type	Description
paletteSize	integer	number of colors
firstColor	integer	index of the first color
lastColor	integer	index of the last color
colors	array of color objects	colors
index?	integer	position of the indexed color based on the palette

Tileset Object

Field	Type	Description
id	integer	tileset id number
tileCount	integer	number of tiles
tileWidth	integer	pixel width of each tile
tileHeight	integer	pixel height ofeach tile
name	string	name
externalFile?	tileset external file object	external file linkage info, if applicable
rawTilesetData?	Buffer	raw pixel data for tiles, if applicable

Tileset External File Object

Field	Type	Description
id	integer	id of the external file
tilesetId	integer	id of the tileset in the external file

Cel Object

Field	Type	Description
layerIndex	integer	index of the layer associated
xpos	integer	x position of the cel compared to the sprite
ypos	integer	y position of the cel compared to the sprite
opacity	integer	opacity (0-255)
celType	integer	internally used
zIndex	integer	show this cel N layers later/back
w	integer	width (in pixels)
h	integer	height (in pixels)
tilemapMetadata?	tilemap metadata object	tilemap metadata, if applicable
rawCelData	Buffer	raw cel pixel data

Tilemap Metadata Object

Field	Type	Description
bitsPerTile	integer	number of bits used to represent each tile (usually 32)
bitmaskForTileId	integer	which bit(s) represent the tile ID
bitmaskForXFlip	integer	which bit(s) indicate X-axis flip
bitmaskForYFlip	integer	which bit(s) indicate Y-axis flip
bitmaskFor90CWRotation	integer	which bit(s) indicate 90-degree clockwise rotation flip

Color Object

Field	Type	Description
red	integer	red value (0-255)
green	integer	green value (0-255)
blue	integer	blue value (0-255)
alpha	integer	alpha value (0-255)
name	string	'none' or the actual color name if it has one

Slice Object

Field	Type	Description
flags	integer	Flags set
keys	array of SliceKey objects	Array of keys and their values
name	string	Name of the slice

SliceKey Object

Field	Type	Description
frameNumber	integer	Frame number that the slice is from
x	integer	X position of the slice
y	integer	Y position of the slice
width	integer	Width of the slice
height	integer	Height of the slice
patch?	patch object	Patch info on the slice
pivot?	pivot object	Pivot info on the slice

Patch Object

Field	Type	Description
x	integer	X postion of the patch
y	integer	Y position of the patch
width	integer	Width of the patch
height	integer	Height of the patch

Pivot Object

Field	Type	Description
x	integer	X position of the pivot
y	integer	Y position of the pivot

Layer Flags Object

This object is a utility object that will have ALL fields present. If a field is "on" it will be true, if the field is "off" it will be false.

Field	Description
visible	Whether or not the layer is visible
editable	Whether or not the layer is editable
lockMovement	Whether or not the layer is a background layer
preferLinkedCels	Whether or not the layer prefers linked cels
collapsedGroup	Whether or not the layer group should be displayed collapsed
reference	Whether or not the layer is a reference layer

Further Info

If you would like to read up on the Aseprite file spec: Spec