Skip to content

Latest commit

 

History

History
289 lines (238 loc) · 12.8 KB

README.md

File metadata and controls

289 lines (238 loc) · 12.8 KB

npm npm install size

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:

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