Aseprite File Format (.ase / .aseprite) & GIMP Palette (.gpl) Specifications #
Official Aseprite Specifications: aseprite/aseprite Recommended Ebitengine Integration Library: SolarLune/goaseprite
1. Primitive Types & Byte Order #
ASE files use Intel (little-endian) byte order across all headers and chunks.
BYTE: 8-bit unsigned integer (uint8)WORD: 16-bit unsigned integer (uint16)SHORT: 16-bit signed integer (int16)DWORD: 32-bit unsigned integer (uint32)LONG: 32-bit signed integer (int32)FIXED: 32-bit fixed-point (16.16) valueFLOAT: 32-bit single-precision value (float32)DOUBLE: 64-bit double-precision value (float64)QWORD: 64-bit unsigned integer (uint64)LONG64: 64-bit signed integer (int64)BYTE[n]: Sequence ofnraw bytesSTRING:WORD: String length in bytesBYTE[length]: UTF-8 characters (no trailing'\0'byte)
POINT:LONG: X coordinateLONG: Y coordinate
SIZE:LONG: Width in pixelsLONG: Height in pixels
RECT:POINT: Origin coordinatesSIZE: Rectangle dimensions
PIXEL: Single pixel value matching the header color depth:- RGBA (32 bpp):
BYTE[4]in order Red, Green, Blue, Alpha - Grayscale (16 bpp):
BYTE[2]in order Value, Alpha - Indexed (8 bpp):
BYTEpalette index
- RGBA (32 bpp):
TILE: Tilemap entry stored asBYTE,WORD, orDWORDwith bit masksUUID: 16-byte Universally Unique Identifier (BYTE[16])
2. File Architecture #
An .aseprite file starts with a fixed 128-byte file header followed immediately by one or more frames. Each frame begins with a 16-byte frame header followed by a sequence of typed chunks.
To read or write an .aseprite file:
- Read or write the 128-byte File Header (magic number
0xA5E0). - Iterate through each frame (
0 .. Frames - 1):- Read or write the 16-byte Frame Header (magic number
0xF1FA). - Read or write each chunk in the frame:
- Frame 0 typically defines the Palette Chunk (
0x2019), Layer Chunk(s) (0x2004), and Tags Chunk (0x2018), followed by the frame’s Cel Chunk(s) (0x2005). - Subsequent frames store their per-frame Cel Chunk(s) (
0x2005) containing ZLIB-compressed pixel buffers.
- Frame 0 typically defines the Palette Chunk (
- Read or write the 16-byte Frame Header (magic number
3. File Header Specification (128 Bytes) #
Offset Type Description
0 DWORD Total file size in bytes
4 WORD Magic number (0xA5E0)
6 WORD Number of frames
8 WORD Width in pixels
10 WORD Height in pixels
12 WORD Color depth (32 = RGBA, 16 = Grayscale, 8 = Indexed)
14 DWORD Flags:
1 = Layer opacity has valid value
2 = Layer blend mode/opacity is valid for groups
4 = Layers have a UUID
18 WORD Speed in ms between frames (deprecated: use frame duration)
20 DWORD Reserved (set to 0)
24 DWORD Reserved (set to 0)
28 BYTE Transparent palette index (for 8 bpp Indexed sprites)
29 BYTE[3] Ignore (set to 0)
32 WORD Number of colors (0 means 256 for legacy sprites)
34 BYTE Pixel width ratio (default 1)
35 BYTE Pixel height ratio (default 1)
36 SHORT X position of grid
38 SHORT Y position of grid
40 WORD Grid width (default 16)
42 WORD Grid height (default 16)
44 BYTE[84] Reserved for future use (set to 0)4. Frame Header (16 Bytes) & Chunk Envelope #
Offset Type Description
0 DWORD Total bytes in this frame (including the 16-byte frame header)
4 WORD Magic number (0xF1FA)
6 WORD Old chunk count (if 0xFFFF, read the 32-bit New chunk count)
8 WORD Frame duration in milliseconds (for example, 100 for 10 FPS)
10 BYTE[2] Reserved (set to 0)
12 DWORD New chunk count (if 0, use Old chunk count)Every chunk inside a frame starts with a 6-byte envelope:
Offset Type Description
0 DWORD Chunk size in bytes (includes these 6 header bytes)
4 WORD Chunk type identifier
6 BYTE[] Chunk payload (Chunk size - 6 bytes)5. Primary Chunk Types #
5.1 Layer Chunk (0x2004) #
Defines a sprite layer in the layer stack (ordered bottom to top):
WORD: Flags (1= Visible,2= Editable,4= Lock movement,8= Background)WORD: Layer type (0= Normal image layer,1= Group,2= Tilemap)WORD: Child nesting levelWORD: Default width (ignored, set to0)WORD: Default height (ignored, set to0)WORD: Blend mode (0= Normal)BYTE: Opacity (0..255, valid when file header flag1is set)BYTE[3]: Reserved (0)STRING: Layer name (for example,"Base")
5.2 Cel Chunk (0x2005) #
Stores pixel data for a specific layer in the current frame:
WORD: Layer index (0for the first layer)SHORT: X position in canvas coordinatesSHORT: Y position in canvas coordinatesBYTE: Opacity level (255= opaque)WORD: Cel type:0: Raw Image Data (uncompressed)1: Linked Cel2: Compressed Image (ZLIB-compressed pixels, standard for.asepriteexport)3: Compressed Tilemap
SHORT: Z-Index (0= default layer order)BYTE[5]: Reserved (0)- For Cel type
2(Compressed Image):WORD: Cel width in pixelsWORD: Cel height in pixelsBYTE[]: ZLIB stream (compress/zlibin Go) ofwidth * height * 4RGBA bytes
5.3 Tags Chunk (0x2018) #
Stores named animation frame ranges (idle, run, attack, hit, death):
WORD: Number of tagsBYTE[8]: Reserved (0)- For each tag:
WORD: From frame index (inclusive, 0-based)WORD: To frame index (inclusive, 0-based)BYTE: Loop animation direction (0= Forward/Loop,1= Reverse,2= Ping-pong,3= Ping-pong Reverse)WORD: Repeat count (0= infinite loop,1= play once,N= repeatNtimes)BYTE[6]: Reserved (0by default;sprite-designstores0xA5at byte0followed byWORDLoopFromFrameat bytes1..2when a tag defines lead-inonceintro frames such astag run 8 once, 9..11 loop, remaining 100% compatible with standard Aseprite readers)BYTE[3]: Tag RGB color (deprecated, still written for compatibility)BYTE: Extra byte (0)STRING: Tag name (UTF-8)
5.4 Palette Chunk (0x2019) #
Stores the sprite’s color swatches:
DWORD: New palette size (total number of entries)DWORD: First color index to changeDWORD: Last color index to changeBYTE[8]: Reserved (0)- For each palette entry (
First .. Last):WORD: Entry flags (1= Has color name string)BYTE: Red (0..255)BYTE: Green (0..255)BYTE: Blue (0..255)BYTE: Alpha (0..255)- Optional
STRING: Color name (present only if bit1of Entry flags is set)
5.5 Slice Chunk (0x2022) & Tileset Chunk (0x2023) #
- Slice Chunk (
0x2022): Defines named rectangular regions, 9-patch UI borders, and custom pivot coordinates (Pivot X,Pivot Y) relative to the slice origin. - Tileset Chunk (
0x2023): Stores tileset ID, tile dimensions (Width x Height), and compressed tile imagery for tilemap layers.
6. GIMP Palette File Format Extension (.gpl) #
Aseprite reads and writes GIMP Palette (.gpl) files extended with RGBA alpha values:
GIMP Palette
Channels: RGBA
#
0 0 0 0 Transparent
15 12 28 255 Outline
48 56 82 255 SteelShadow
92 108 142 255 SteelBase
156 178 214 255 SteelLight
232 242 255 255 SteelSpecThe header must declare Channels: RGBA, and each color line lists Red Green Blue Alpha Name.
7. Zero-Allocation goaseprite Integration Pattern #
When loading exported Aseprite JSON manifests and sprite sheet atlases with SolarLune/goaseprite in Ebitengine, pre-slice all frame sub-images during initialization and reuse a struct-level ebiten.DrawImageOptions value so Draw() performs zero heap allocations per frame:
package entity
import (
"fmt"
"image"
"github.com/SolarLune/goaseprite"
"github.com/hajimehoshi/ebiten/v2"
)
type AsepriteActor struct {
File *goaseprite.File
Frames []*ebiten.Image
X, Y float64
drawOp ebiten.DrawImageOptions
}
func NewAsepriteActor(jsonBytes []byte, atlas *ebiten.Image) (*AsepriteActor, error) {
if len(jsonBytes) == 0 {
return nil, fmt.Errorf("sprite-design: empty Aseprite JSON manifest")
}
if atlas == nil {
return nil, fmt.Errorf("sprite-design: nil atlas image")
}
file := goaseprite.Read(jsonBytes)
if file == nil || len(file.Frames) == 0 {
return nil, fmt.Errorf("sprite-design: failed to parse Aseprite frames from JSON")
}
// Pre-slice every frame at load time (zero SubImage allocations in Draw)
frames := make([]*ebiten.Image, len(file.Frames))
for i, f := range file.Frames {
rect := image.Rect(f.X, f.Y, f.X+f.Width, f.Y+f.Height)
frames[i] = atlas.SubImage(rect).(*ebiten.Image)
}
return &AsepriteActor{
File: file,
Frames: frames,
}, nil
}
func (a *AsepriteActor) Update(dt float32) {
a.File.Update(dt)
}
func (a *AsepriteActor) Draw(screen *ebiten.Image) error {
idx := a.File.CurrentFrame
if idx < 0 || idx >= len(a.Frames) {
return fmt.Errorf("sprite-design: frame index %d out of bounds [0, %d)", idx, len(a.Frames))
}
a.drawOp.GeoM.Reset()
a.drawOp.GeoM.Translate(a.X, a.Y)
screen.DrawImage(a.Frames[idx], &a.drawOp)
return nil
}