mirror/aseprite
1
0
Fork 0
mirror of https://github.com/aseprite/aseprite.git synced 2025-04-10 21:44:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fix .ase specs

Browse Source 
Don't use GitHub tables for the spec, they don't work for this kind of
documents. I've restored the old layout using just plain text to
describe chunks and fields.
This commit is contained in:
David Capello 2017-07-25 23:46:08 -03:00
parent 534458a2c1
commit 913a32fbab
1 changed files with 193 additions and 231 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

424
docs/ase-file-specs.md
View File

@ -1,38 +1,34 @@
Aseprite File Format (.ase/.aseprite) Specifications # Aseprite File Format (.ase/.aseprite) Specifications
====================================================
> Copyright (C) 2001-2017 by David Capello > Copyright (C) 2001-2017 by David Capello
1. [References](#1-references) 1. [References](#references)
2. [Introduction](#2-introduction) 2. [Introduction](#introduction)
3. [Header](#3-header) 3. [Header](#header)
4. [Frames](#4-frames) 4. [Frames](#frames)
5. [Chunk Types](#5-chunk-types) 5. [Chunk Types](#chunk-types)
6. [File Format Changes](#6-file-format-changes) 6. [File Format Changes](#file-format-changes)
1. References ## References
-------------
ASE files use Intel (little-endian) byte order. ASE files use Intel (little-endian) byte order.
Data Type | Details | * `BYTE`: An 8-bit unsigned integer value
--------------- | -------------------------------- | * `WORD`: A 16-bit unsigned integer value
BYTE | An 8-bit unsigned integer value * `SHORT`: A 16-bit signed integer value
WORD | A 16-bit unsigned integer value * `DWORD`: A 32-bit unsigned integer value
SIGNED WORD | A 16-bit signed integer value * `FIXED`: A 32-bit fixed point (16.16) value
DWORD | A 32-bit unsigned integer value * `BYTE[n]`: "n" bytes.
FIXED | A 32-bit fixed point (16.16) value * `STRING`:
BYTE[n] | "n" bytes. - `WORD`: string length (number of bytes)
STRING | WORD: string length (number of bytes) - `BYTE[length]`: characters (in UTF-8)
| BYTE[length]: characters (in UTF-8) The `'\0'` character is not included.
| The \0 character is not included. * `PIXEL`: One pixel, depending on the image pixel format:
PIXEL | One pixel, depending on the image pixel format: - **RGBA**: `BYTE[4]`, each pixel have 4 bytes in this order Red, Green, Blue, Alpha.
| **RGB**: Each pixel have 4 bytes in this order Red, Green, Blue, Alpha. - **Grayscale**: `BYTE[2]`, each pixel have 2 bytes in the order Value, Alpha.
| **Grayscale**: Each pixel have 2 bytes in the order Value, Alpha. - **Indexed**: `BYTE`, Each pixel uses 1 byte (the index).
| **Indexed**: Each pixel uses 1 byte (the index).
2. Introduction ## Introduction
---------------
The format is much like FLI/FLC files, but with different magic number The format is much like FLI/FLC files, but with different magic number
and differents chunks. Also, the color depth can be 8, 16 or 32 for and differents chunks. Also, the color depth can be 8, 16 or 32 for
@ -43,64 +39,59 @@ optional.
To read the sprite: To read the sprite:
* Read the [ASE header](#3-header) * Read the [ASE header](#header)
* For each frame do (how many frames? the ASE header has that information): * For each frame do (how many frames? the ASE header has that information):
+ Read the [frame header](#4-frames) + Read the [frame header](#frames)
+ For each chunk in this frame (how many chunks? the frame header has that information) + For each chunk in this frame (how many chunks? the frame header has that information)
- Read the chunk (it should be layer information, a cel or a palette) - Read the chunk (it should be layer information, a cel or a palette)
3. Header ## Header
---------
A 128-byte header (same as FLC/FLI header, but with other magic number): A 128-byte header (same as FLC/FLI header, but with other magic number):
Field | Details | DWORD File size
------------- | -------------------------------- | WORD Magic number (0xA5E0)
DWORD | File size WORD Frames
WORD | Magic number (0xA5E0) WORD Width in pixels
WORD | Frames WORD Height in pixels
WORD | Width in pixels WORD Color depth (bits per pixel)
WORD | Height in pixels 32 bpp = RGBA
WORD | Color depth (bits per pixel) 16 bpp = Grayscale
| 32 bpp = RGBA 8 bpp = Indexed
| 16 bpp = Grayscale DWORD Flags:
| 8 bpp = Indexed 1 = Layer opacity has valid value
DWORD | Flags: WORD Speed (milliseconds between frame, like in FLC files)
| 1 = Layer opacity has valid value DEPRECATED: You should use the frame duration field
WORD | Speed (milliseconds between frame, like in FLC files) **DEPRECATED:** You should use the frame duration field from each frame header from each frame header
DWORD | Set be 0 DWORD Set be 0
DWORD | Set be 0 DWORD Set be 0
BYTE | Palette entry (index) which represent transparent color in all non-background layers (only for Indexed sprites). BYTE Palette entry (index) which represent transparent color
BYTE[3] | Ignore these bytes in all non-background layers (only for Indexed sprites).
WORD | Number of colors (0 means 256 for old sprites) BYTE[3] Ignore these bytes
BYTE | Pixel width (pixel ratio is "pixel width/pixel height"). If this or pixel height field is zero, pixel ratio is 1:1 WORD Number of colors (0 means 256 for old sprites)
BYTE | Pixel height BYTE Pixel width (pixel ratio is "pixel width/pixel height").
BYTE[92] | For future (set to zero) If this or pixel height field is zero, pixel ratio is 1:1
BYTE Pixel height
BYTE[92] For future (set to zero)
4. Frames ## Frames
---------
After the header come the "frames" data. Each frame has this little After the header come the "frames" data. Each frame has this little
header of 16 bytes: header of 16 bytes:
Field | Details | DWORD Bytes in this frame
----------- | -------------------------------- | WORD Magic number (always 0xF1FA)
DWORD | Bytes in this frame WORD Number of "chunks" in this frame
WORD | Magic number (always 0xF1FA) WORD Frame duration (in milliseconds)
WORD | Number of "chunks" in this frame BYTE[6] For future (set to zero)
WORD | Frame duration (in milliseconds)
BYTE[6] | For future (set to zero)
Then each chunk format is: Then each chunk format is:
Field | Details | DWORD Chunk size
----------- | -------------------------------- | WORD Chunk type
DWORD | Chunk size BYTE[] Chunk data
WORD | Chunk type
BYTE[] | Chunk data
5. Chunk Types ## Chunk Types
--------------
### Old palette chunk (0x0004) ### Old palette chunk (0x0004)
@ -108,39 +99,34 @@ Ignore this chunk if you find the new palette chunk (0x2019) Aseprite
v1.1 saves both chunks 0x0004 and 0x2019 just for backward v1.1 saves both chunks 0x0004 and 0x2019 just for backward
compatibility. compatibility.
``` WORD Number of packets
WORD Number of packets + For each packet
+ For each packet BYTE Number of palette entries to skip from the last packet (start from 0)
BYTE Number of palette entries to skip from the last packet (start from 0) BYTE Number of colors in the packet (0 means 256)
BYTE Number of colors in the packet (0 means 256) + For each color in the packet
+ For each color in the packet BYTE Red (0-255)
BYTE Red (0-255) BYTE Green (0-255)
BYTE Green (0-255) BYTE Blue (0-255)
BYTE Blue (0-255)
```
### Old palette chunk (0x0011) ### Old palette chunk (0x0011)
Ignore this chunk if you find the new palette chunk (0x2019) Ignore this chunk if you find the new palette chunk (0x2019)
``` WORD Number of packets
WORD Number of packets + For each packet
+ For each packet BYTE Number of palette entries to skip from the last packet (start from 0)
BYTE Number of palette entries to skip from the last packet (start from 0) BYTE Number of colors in the packet (0 means 256)
BYTE Number of colors in the packet (0 means 256) + For each color in the packet
+ For each color in the packet BYTE Red (0-63)
BYTE Red (0-63) BYTE Green (0-63)
BYTE Green (0-63) BYTE Blue (0-63)
BYTE Blue (0-63)
```
### Layer Chunk (0x2004) ### Layer Chunk (0x2004)
In the first frame should be a set of layer chunks to determine the In the first frame should be a set of layer chunks to determine the
entire layers layout: entire layers layout:
``` WORD Flags:
WORD Flags:
1 = Visible 1 = Visible
2 = Editable 2 = Editable
4 = Lock movement 4 = Lock movement
@ -148,13 +134,13 @@ Ignore this chunk if you find the new palette chunk (0x2019)
16 = Prefer linked cels 16 = Prefer linked cels
32 = The layer group should be displayed collapsed 32 = The layer group should be displayed collapsed
64 = The layer is a reference layer 64 = The layer is a reference layer
WORD Layer type WORD Layer type
0 = Normal (image) layer 0 = Normal (image) layer
1 = Group 1 = Group
WORD Layer child level (see NOTE.1) WORD Layer child level (see NOTE.1)
WORD Default layer width in pixels (ignored) WORD Default layer width in pixels (ignored)
WORD Default layer height in pixels (ignored) WORD Default layer height in pixels (ignored)
WORD Blend mode (always 0 for layer set) WORD Blend mode (always 0 for layer set)
Normal = 0 Normal = 0
Multiply = 1 Multiply = 1
Screen = 2 Screen = 2
@ -174,75 +160,64 @@ Ignore this chunk if you find the new palette chunk (0x2019)
Addition = 16 Addition = 16
Subtract = 17 Subtract = 17
Divide = 18 Divide = 18
BYTE Opacity BYTE Opacity
Note: valid only if file header flags field has bit 1 set Note: valid only if file header flags field has bit 1 set
BYTE[3] For future (set to zero) BYTE[3] For future (set to zero)
STRING Layer name STRING Layer name
```
### Cel Chunk (0x2005) ### Cel Chunk (0x2005)
This chunk determine where to put a cel in the specified This chunk determine where to put a cel in the specified
layer/frame. layer/frame.
``` WORD Layer index (see NOTE.2)
WORD Layer index (see NOTE.2) SHORT X position
SIGNED WORD X position SHORT Y position
SIGNED WORD Y position BYTE Opacity level
BYTE Opacity level WORD Cel type
WORD Cel type BYTE[7] For future (set to zero)
BYTE[7] For future (set to zero) + For cel type = 0 (Raw Cel)
WORD Width in pixels
+ For cel type = 0 (Raw Cel): WORD Height in pixels
PIXEL[] Raw pixel data: row by row from top to bottom,
WORD Width in pixels
WORD Height in pixels
PIXEL[] Raw pixel data: row by row from top to bottom,
for each scanline read pixels from left to right. for each scanline read pixels from left to right.
+ For cel type = 1 (Linked Cel)
WORD Frame position to link with
+ For cel type = 2 (Compressed Image)
WORD Width in pixels
WORD Height in pixels
BYTE[] "Raw Cel" data compressed with ZLIB method
+ For cel type = 1 (Linked Cel): Details about the ZLIB and DEFLATE compression methods:
WORD Frame position to link with * https://www.ietf.org/rfc/rfc1950
* https://www.ietf.org/rfc/rfc1951
+ For cel type = 2 (Compressed Image): * Some extra notes that might help you to decode the data:
http://george.chiramattel.com/blog/2007/09/deflatestream-block-length-does-not-match.html
WORD Width in pixels
WORD Height in pixels
BYTE[] ZLIB compressed "Raw Cel" data. Details about the
ZLIB and DEFLATE compression methods:
https://www.ietf.org/rfc/rfc1950
https://www.ietf.org/rfc/rfc1951
Some extra notes that might help you to decode the data:
http://george.chiramattel.com/blog/2007/09/deflatestream-block-length-does-not-match.html
```
### Cel Extra Chunk (0x2006) ### Cel Extra Chunk (0x2006)
Adds extra information to the latest read cel. Adds extra information to the latest read cel.
``` DWORD Flags (set to zero)
DWORD Flags (set to zero) 1 = Precise bounds are set
1 - precise bounds are set FIXED Precise X position
FIXED Precise X position FIXED Precise Y position
FIXED Precise Y position FIXED Width of the cel in the sprite (scaled in real-time)
FIXED Width of the cel in the sprite (scaled in real-time) FIXED Height of the cel in the sprite
FIXED Height of the cel in the sprite BYTE[16] For future use (set to zero)
BYTE[16] For future use (set to zero)
```
### Mask Chunk (0x2016) DEPRECATED ### Mask Chunk (0x2016) DEPRECATED
``` SHORT X position
SIGNED WORD X position SHORT Y position
SIGNED WORD Y position WORD Width
WORD Width WORD Height
WORD Height BYTE[8] For future (set to zero)
BYTE[8] For future (set to zero) STRING Mask name
STRING Mask name BYTE[] Bit map data (size = height*((width+7)/8))
BYTE[] Bit map data (size = height*((width+7)/8))
Each byte contains 8 pixels (the leftmost pixels are Each byte contains 8 pixels (the leftmost pixels are
packed into the high order bits) packed into the high order bits)
```
### Path Chunk (0x2017) ### Path Chunk (0x2017)
@ -250,39 +225,35 @@ Adds extra information to the latest read cel.
### Frame Tags Chunk (0x2018) ### Frame Tags Chunk (0x2018)
``` WORD Number of tags
WORD Number of tags
BYTE[8] For future (set to zero)
+ For each tag
WORD From frame
WORD To frame
BYTE Loop animation direction
0 - Forward
1 - Reverse
2 - Ping-pong
BYTE[8] For future (set to zero) BYTE[8] For future (set to zero)
BYTE[3] RGB values of the tag color + For each tag
BYTE Extra byte (zero) WORD From frame
STRING Tag name WORD To frame
``` BYTE Loop animation direction
0 = Forward
1 = Reverse
2 = Ping-pong
BYTE[8] For future (set to zero)
BYTE[3] RGB values of the tag color
BYTE Extra byte (zero)
STRING Tag name
### Palette Chunk (0x2019) ### Palette Chunk (0x2019)
``` DWORD New palette size (total number of entries)
DWORD New palette size (total number of entries) DWORD First color index to change
DWORD First color index to change DWORD Last color index to change
DWORD Last color index to change BYTE[8] For future (set to zero)
BYTE[8] For future (set to zero) + For each palette entry in [from,to] range (to-from+1 entries)
+ For each palette entry in [from,to] range (to-from+1 entries) WORD Entry flags:
WORD Entry flags:
1 = Has name 1 = Has name
BYTE Red (0-255) BYTE Red (0-255)
BYTE Green (0-255) BYTE Green (0-255)
BYTE Blue (0-255) BYTE Blue (0-255)
BYTE Alpha (0-255) BYTE Alpha (0-255)
+ If has name bit in entry flags + If has name bit in entry flags
STRING Color name STRING Color name
```
### User Data Chunk (0x2020) ### User Data Chunk (0x2020)
@ -290,45 +261,41 @@ Insert this user data in the last read chunk. E.g. If we've read a
layer, this user data belongs to that layer, if we've read a cel, it layer, this user data belongs to that layer, if we've read a cel, it
belongs to that cel, etc. belongs to that cel, etc.
Field | Details | DWORD Flags
----------- | -------------------------------- | 1 = Has text
DWORD | Flags 2 = Has color
| 1 - Has text + If flags have bit 1
| 2 - Has color STRING Text
If flags have bit 1 | + If flags have bit 2
STRING | Text BYTE Color Red (0-255)
If flags have bit 2 | BYTE Color Green (0-255)
BYTE | Color Red (0-255) BYTE Color Blue (0-255)
BYTE | Color Green (0-255) BYTE Color Alpha (0-255)
BYTE | Color Blue (0-255)
BYTE | Color Alpha (0-255)
### Slice Chunk (0x2022) ### Slice Chunk (0x2022)
Field | Details | DWORD Number of "slice keys"
----------- | -------------------------------- | DWORD Flags
DWORD | Number of "slice keys" 1 = It's a 9-patches slice
DWORD | Flags 2 = Has pivot information
| 1 - It's a 9-patches slice DWORD Reserved
| 2 - Has pivot information STRING Name
DWORD | Reserved + For each slice key
STRING | Name DWORD Frame number (this slice is valid from
For each slice key ... | this frame to the end of the animation)
DWORD | Frame number (this slice is valid from SHORT Slice X origin coordinate in the sprite
| this frame to the end of the animation) SHORT Slice Y origin coordinate in the sprite
SIGNED WORD | Slice X origin coordinate in the sprite WORD Slice width (can be 0 if this slice hidden in the
SIGNED WORD | Slice Y origin coordinate in the sprite animation from the given frame)
WORD | Slice width (can be 0 if this slice hidden in the WORD Slice height
| animation from the given frame) + If flags have bit 1
WORD | Slice height SHORT Center X position (relative to slice bounds)
If flags have bit 1 | SHORT Center Y position
SIGNED WORD | Center X position (relative to slice bounds) WORD Center width
SIGNED WORD | Center Y position WORD Center height
WORD | Center width + If flags have bit 2
WORD | Center height WORD Pivot X position (relative to the slice origin)
If flags have bit 2 | WORD Pivot Y position (relative to the slice origin)
WORD | Pivot X position (relative to the slice origin)
WORD | Pivot Y position (relative to the slice origin)
### Notes ### Notes
@ -337,35 +304,30 @@ WORD | Pivot Y position (relative to the slice origin)
The child level is used to show the relationship of this layer with The child level is used to show the relationship of this layer with
the last one read, for example: the last one read, for example:
``` Layer name and hierarchy Child Level
Layer name and hierarchy Child Level -----------------------------------------------
----------------------------------------------- - Background 0
- Background 0 `- Layer1 1
`- Layer1 1 - Foreground 0
- Foreground 0 |- My set1 1
|- My set1 1 | `- Layer2 2
| `- Layer2 2 `- Layer3 1
`- Layer3 1
```
#### NOTE.2 #### NOTE.2
The layer index is a number to identify any layer in the sprite, for The layer index is a number to identify any layer in the sprite, for
example: example:
``` Layer name and hierarchy Layer index
Layer name and hierarchy Layer index -----------------------------------------------
----------------------------------------------- - Background 0
- Background 0 `- Layer1 1
`- Layer1 1 - Foreground 2
- Foreground 2 |- My set1 3
|- My set1 3 | `- Layer2 4
| `- Layer2 4 `- Layer3 5
`- Layer3 5
```
6. File Format Changes ## File Format Changes
----------------------
1. The first change from the first release of the new .ase format, 1. The first change from the first release of the new .ase format,
is the new frame duration field. This is because now each frame is the new frame duration field. This is because now each frame