Skip to content

Add support for tilemaps and tilesets #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cubeghost wants to merge 8 commits into
base: master
Choose a base branch
from
Open

Add support for tilemaps and tilesets #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
521f570
tileset support
cubeghost Jul 19, 2026
824f79d
reverse bitset sequences 😅
cubeghost Jul 19, 2026
351f8ae
add external files chunk
cubeghost Jul 19, 2026
b525410
fix tileset flag padding
cubeghost Jul 19, 2026
b1852f4
add docstrings
cubeghost Jul 19, 2026
d07d824
format
cubeghost Jul 19, 2026
3d5b74a
remove userdata has_properties for now
cubeghost Jul 19, 2026
a76ccf8
remove note references
cubeghost Jul 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
208 changes: 204 additions & 4 deletions aseprite.ksy
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ types:
Palette entry (index) which represents the transparent
color in all non-background layers (only for
pixel_format=indexed (8bpp) sprites).
- type: b24
- size: 3
- id: num_colors
type: u2
doc: |
Expand Down Expand Up @@ -104,10 +104,20 @@ types:
types:
flags_bitset:
seq:
- type: b7
- type: b5
- id: layers_uuid
type: b1
doc: |
Layers have an UUID
- id: valid_groups
type: b1
doc: |
Layer blend mode/opacity is valid for groups
(composite groups separately first when rendering)
- id: valid_opacity
type: b1
doc: Layer opacity has a valid value
doc: |
Layer opacity has a valid value
- type: b24
frame:
seq:
Expand Down Expand Up @@ -174,11 +184,13 @@ types:
'chunk_type_enum::cel': cel_chunk
'chunk_type_enum::cel_extra': cel_extra_chunk
'chunk_type_enum::color_profile': color_profile_chunk
'chunk_type_enum::external_files': external_files_chunk
'chunk_type_enum::mask': mask_chunk
'chunk_type_enum::tags': tags_chunk
'chunk_type_enum::palette': palette_chunk
'chunk_type_enum::userdata': userdata_chunk
'chunk_type_enum::slice': slice_chunk
'chunk_type_enum::tileset': tileset_chunk
_: dummy_chunk
enums:
chunk_type_enum:
Expand All @@ -188,12 +200,14 @@ types:
0x2005: cel
0x2006: cel_extra
0x2007: color_profile
0x2008: external_files
0x2016: mask
0x2017: path
0x2018: tags
0x2019: palette
0x2020: userdata
0x2022: slice
0x2023: tileset
types:
dummy_chunk:
seq:
Expand Down Expand Up @@ -411,10 +425,21 @@ types:
encoding: utf-8
doc: |
Layer name
- id: tileset_index
type: u4
if: type == type_enum::tilemap
doc: |
Tileset index
- id: uuid
size: 16
if: _root.header.flags.layers_uuid == true
doc: |
Layer's universally unique identifier
enums:
type_enum:
0: image
1: group
2: tilemap
blend_mode_enum:
0: normal
1: multiply
Expand Down Expand Up @@ -503,7 +528,13 @@ types:
enum: cel_type_enum
doc: |
The format of the cel's contents
- size: 7
- id: z_index
type: s2
doc: |
0 = default layer ordering
+N = show this cel N layers later
-N = show this cel N layers back
- size: 5
- id: raw_width
type: u2
if: type == cel_type_enum::raw
Expand Down Expand Up @@ -564,11 +595,55 @@ types:

Pixels are read row by row from top to bottom,
for each scanline read pixels from left to right.
- id: tiles_width
type: u2
if: type == cel_type_enum::compressed_tilemap
doc: |
Width in number of tiles
- id: tiles_height
type: u2
if: type == cel_type_enum::compressed_tilemap
doc: |
Height in number of tiles
- id: bits_per_tile
type: u2
if: type == cel_type_enum::compressed_tilemap
doc: |
Bits per tile (at the moment it's always 32-bit per tile)
- id: tile_id_bitmask
type: u4
if: type == cel_type_enum::compressed_tilemap
doc: |
Bitmask for tile ID (e.g. 0x1fffffff for 32-bit tiles)
- id: x_flip_bitmask
type: u4
if: type == cel_type_enum::compressed_tilemap
doc: |
Bitmask for X flip
- id: y_flip_bitmask
type: u4
if: type == cel_type_enum::compressed_tilemap
doc: |
Bitmask for Y flip
- id: d_flip_bitmask
type: u4
if: type == cel_type_enum::compressed_tilemap
doc: |
Bitmask for diagonal flip (swap X/Y axis)
- size: 10
if: type == cel_type_enum::compressed_tilemap
- id: tiles_compressed
size: _parent.size - 54
if: type == cel_type_enum::compressed_tilemap
doc: |
Row by row, from top to bottom tile by tile
compressed with ZLIB method
enums:
cel_type_enum:
0: raw
1: linked
2: compressed
3: compressed_tilemap
cel_extra_chunk:
seq:
- id: flags
Expand Down Expand Up @@ -848,3 +923,128 @@ types:
doc: |
Each byte contains 8 pixels (the leftmost pixels
are packed into the high order bits)
external_files_chunk:
seq:
- id: num_entries
type: u4
doc: |
Number of entries
- size: 8
- id: entries
type: entry
repeat: expr
repeat-expr: num_entries
types:
entry:
seq:
- id: id
type: u4
doc: |
Entry ID (this ID is referenced by tilesets, palettes, or extended properties)
- id: type
type: u1
doc: |
0 - External palette
1 - External tileset
2 - Extension name for properties
3 - Extension name for tile management (can exist one per sprite)
- size: 7
- id: name_size
type: u2
- id: name
type: str
size: name_size
encoding: utf-8
doc: |
External file name or extension ID
tileset_chunk:
seq:
- id: tileset_id
type: u4
doc: |
Tileset ID
- id: flags
type: flags_bitset
doc: |
Flags for tileset
- id: num_tiles
type: u4
doc: |
Number of tiles
- id: tile_width
type: u2
doc: |
Tile width
- id: tile_height
type: u2
doc: |
Tile height
- id: base_index
type: s2
doc: |
UI only
- size: 14
- id: name_size
type: u2
- id: name
type: str
size: name_size
encoding: utf-8
doc: |
Tileset name
- id: external_file_id
type: u4
if: flags.include_external == true
doc: |
ID of the external file. This ID is one entry
of the the External Files Chunk.
- id: external_tileset_id
type: u4
if: flags.include_external == true
doc: |
Tileset ID in the external file
- id: data_length
type: u4
if: flags.include_internal == true
doc: |
Data length of the compressed Tileset image
- id: pixels_compressed
size: data_length
if: flags.include_internal == true
doc: |
Compressed Tileset image:
(Tile Width) x (Tile Height x Number of Tiles)
types:
flags_bitset:
seq:
- type: b2
- id: d_auto
type: b1
doc: |
Same as x_auto but for diagonal flips
- id: y_auto
type: b1
doc: |
Same as x_auto but for Y flips
- id: x_auto
type: b1
doc: |
Aseprite will try to match modified tiles with their X
flipped version automatically in Auto mode when using
this tileset.
- id: empty_zero
type: b1
doc: |
Tilemaps using this tileset use tile ID=0 as empty tile
(this is the new format). In rare cases this bit is off,
and the empty tile will be equal to 0xffffffff (used in
internal versions of Aseprite)
- id: include_internal
type: b1
doc: |
Include tiles inside this file
- id: include_external
type: b1
doc: |
Include link to external file
- type: b24
4 changes: 4 additions & 0 deletions index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,11 @@ function inflate(ase) {
const cel = chunk.data;
if (cel.type === CelTypeEnum.COMPRESSED) {
cel.pixels = zlib.inflateSync(cel.pixelsCompressed);
} else if (cel.type === CelTypeEnum.COMPRESSED_TILEMAP) {
cel.tiles = zlib.inflateSync(cel.tilesCompressed);
}
} else if (chunk.type === ChunkTypeEnum.TILESET) {
chunk.data.pixels = zlib.inflateSync(chunk.data.pixelsCompressed);
}
}
}
Expand Down