ase-parser/README.md

Parser for Aseprite files

[![npm](https://img.shields.io/npm/v/ase-parser.svg)](https://www.npmjs.com/package/ase-parser)
[![npm](https://img.shields.io/npm/dt/ase-parser.svg?maxAge=3600)](https://www.npmjs.com/package/ase-parser)
[![install size](https://packagephobia.now.sh/badge?p=ase-parser)](https://packagephobia.now.sh/result?p=ase-parser)

# 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.

```js
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`](https://www.npmjs.com/package/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`](https://www.npmjs.com/package/sharp) lib.

```js
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](#aseprite-object).

 Example:
 ```js
 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:
 ```js
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](#frame-object) objects | frames                                 |
| layers       | array of [layer](#layer-object) 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](#tag-object) objects    | tags                                   |
| colorProfile | [colorProfile](#color-profile-object) object    | Color profile                          |
| palette      | [palette](#palette-object) object         | Palette                                |
| tilesets     | array of [tileset](#tileset-object) objects | Tileset                                |
| slices       | array of [slice](#slice-object) objects | Info on slices |

## Frame Object
| Field         | Type                  | Description      |
|---------------|-----------------------|------------------|
| bytesInFrame  | integer               | size (in bytes)  |
| frameDuration | integer               | duration (in ms) |
| cels          | array of [cel](#cel-object) objects | cels             |

## Layer Object
| Field           | Type    | Description                   |
|-----------------|---------|-------------------------------|
| flags           | [layer flags](#layer-flags-object) | 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](#color-object) 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](#tileset-external-file-object) 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](#tileset-external-file-object) 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](#slicekey-object) 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](#patch-object) object | Patch info on the slice |
| pivot? | [pivot](#pivot-object) 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](https://github.com/aseprite/aseprite/blob/master/docs/ase-file-specs.md)