In this section, we'll learn about the binary specs of .px files so that anyone can decode the file for various purposes.
Disclaimer: There are a lot of backward compatibility details in the files, but for the sake of simplicity, they will be ignored and only the latest specs are available here.
How to decode
Models without header
These are pretty simple, their sizes are pre-determined, so just consume data and decode the values one by one to fill the properties of the models
Models with header
All headers contain a field to specify the length of the model. Use that field to determine where the model ends.
We'll see that there are properties within the models that have default values. If we reach the end of the data for the model, but there are still fields that need values, simply use the default value in this case.
Data types
These are some simple data types
Primitive types
These are notated similarly to Swift data types
UInt - A n-bit unsigned integer
UInt8 is an 8-bit unsigned integer
Int - A n-bit signed integer
Int16 is a 16-bit signed integer
Float - A n-bit float
Float32 is a 32-bit float
Bool - A boolean value, 1 byte
OptionSet<UInt> - A set of true (1) - false (0) flags using each bit of the UInt type
OptionSet<UInt8> has 8 flags. So0b10010001 has 1 << 0, 1 << 4, and 1 << 7 flag set
DumbString - UTF8 data of a string
String - A string
The first 2 bytes are a UInt16 to specify the length of the String
The remaining is the UTF8 data of the string
Don't ask me why there is a DumpString in the first place
[Type] - An array of Type
The first 8 bytes are a UInt64 to specify the length of the Array
Most models in this section have a header. Pixquare uses ID for everything.
All sizes specified in the headers are in bytes and the size doesn't include the header
FrameContent
The color data of a cel.
Header (32 bytes)
UInt64 Size of this model
UInt8 ID length
UInt32 Backward compatibility. Ignore this value
UInt32 Color data length
OptionSet<UInt8> Backward compatibility. Ignore this value
Content
DumbString ID, the length is specified in the header
[Byte] Compressed color data using zlib compression.
After decompressing, it will be in the form of [ARGBColor]
TilemapFrameContent
The alignment of a tilemap cel.
Header (32 bytes)
UInt64 Size of this model
Content
String ID
Size Tile size
[UInt16] Alignment of tile on the canvas
UInt16.max is for unassigned tiles
Frame
A frame of the artwork.
Header (32 bytes)
UInt32 Size of this model
UInt8 ID length
UInt8 Content ID length
Content
DumbString ID, the length is specified in the header
Frames with the same index have the same ID
UInt32 Duration
Frames with the same index have the same duration
Bool Selected
DumbString Content ID, the length is specified in the header
This is the ID of the `FrameContent` for `Layer`
and `TilemapFrameContent` for `TilemapLayer`
Float16 Opacity
Value from 0 to 1 is the actual value
2 means using the opacity of the Layer
Default: 2
SymmetryLline
Header (16 bytes)
UInt32 Size of this model
UInt8 ID length
UInt8 Backward compatibility. Ignore this value
Content
DumbString ID, the length is specified in the header
ARGBColor Color
Bool Selected
Bool Enabled
Float32 x-value of the origin
Float32 y-value of the origin
Float32 Rotation angle in radians
UInt8 Segment count
UInt8 Symmetry type
0 - Mirror
1 - Rotate
Tag
Header (16 bytes)
UInt32 Size of this model
UInt8 ID length
UInt8 Name length
Content
DumbString ID, the length is specified in the header
DumbString Name, the length is specified in the header
UInt16 Start frame index
UInt16 End frame index
Bool Selected
ARGBColor Color
Tileset
Header (32 bytes)
UInt32 Size of this model
Content
String ID
String Name
Size Tile size
[[Byte]] Compressed color data of each tile using zlib compression
After decompressing, it will be in the form of [ARGBColor]
Entry
Represents an entry in the artwork (layer, group, etc.), but doesn't have any actual data of the entry.
Header (16 bytes)
UInt32 Total size of this model
UInt8 Entry type
0 - Regular layer
1 - Group
2 - Reference layer
3 - Tilemap layer
Content
UInt8 ID length
DumbString ID
This ID is the same as the ID of `Layer`, `ReferenceLayer`, `Group`,
and `TilemapLayer`
Layer
A layer with all data.
Header (32 bytes)
UInt32 Size of this model
UInt8 ID length
UInt8 Name length
OptionSet<UInt8> Backward compatibility, ignore it
Content
DumbString ID, the length is specified in the header
This is the same ID as the one in `Entry`
DumbString Name, the length is specified in the header
[Frame] Frames of this layer
Float16 Opacity
Bool Visible
Bool Locked
Bool Selected
Bool Alpha-locked
BlendMode Blend mode
Default: Normal
Bool Linked
Default: false
[Entry] Cropping masks, sorted in the actual order
A higher index means being above
Default: []
[Entry] Clipping masks, sorted in the actual order
A higher index means being above
Default: []
ARGBColor Color
Default: (0, 0, 0, 0)
Group
A group with all data.
Header (32 bytes)
UInt32 Size of this model
UInt8 ID length
UInt8 Name length
OptionSet<UInt8> Backward compatibility, ignore it
Content
DumbString ID, the length is specified in the header
This is the same ID as the one in `Entry`
DumbString Name, the length is specified in the header
[Entry] Child entries, sorted in the actual order
A higher index means being above
Float16 Opacity
Bool Visible
Bool Content locked
Bool Selected
Bool Alpha locked
Bool Expanded
Default: true
[Entry] Cropping masks, sorted in the actual order
A higher index means being above
Default: []
[Entry] Clipping masks, sorted in the actual order
A higher index means being above
Default: []
ARGBColor Color
Default: (0, 0, 0, 0)
ReferenceLayer
A reference layer with all data
Header (32 bytes)
UInt32 Size of this model
UInt64 Data Length
UInt8 ID length
UInt8 Name length
Content
DumbString ID, the length is specified in the header
This is the same ID as the one in `Entry`
[Byte] PNG data of the reference image
Length is specified in the header
DumbString Name, the length is specified in the header
Float16 Opacity
Bool Visible
Bool Selected
Rect Bounds
Float32 Rotation angle in radians
Default: 0
ARGBColor Color
Default: (0, 0, 0, 0)
OptionSet<UInt8> Flip axes
1 << 0 - Set if flipped horizontally
1 << 1 - Set if flipped vertically
Default: 0
TilemapLayer
A tilemap layer with all data
Header
UInt32 Size of this model
Content
String ID, this is the same ID as the one in `Entry`
String Tileset ID
String Name
[Frame] Frames of this tilemap layer
Float16 Opacity
Bool Visible
Bool Locked
Bool Selected
Bool Alpha-locked
BlendMode Blend mode
Default: Normal
Bool Linked
ARGBColor Color
Default: (0, 0, 0, 0)
Stats
Contains the data like time spent on this file, stroke count, etc.
Header (16 bytes)
UInt16 Total size of this model
Content
UInt32 Time spent in seconds
UInt32 Stroke count
UInt32 Number of undos
Default: 0
UInt32 Number of redos
Default: 0
CanvasGrid
Size Grid size
ARGBColor First color
ARGBColor Second color
GuideLine
Size Size
ARGBColor Color
Bool Isometric
Artwork
This is the data of .px files.
Header (64 bytes)
UInt64 Total size of the file
UInt8 Length of `id`
UInt16 Backward compatibility. Ignore this value
The rest of this header is unused
Content
DumbString ID, the length is specified in the header
Size Canvas size
[Entry] Entries at the root level of the artwork
Sorted in the actual order
A higher index means being above.
[Group] Groups
[Layer] Layers
[FrameContent] Frame contents
[ARGBColor] Palette
[ReferenceLayer] Reference layers
Default: []
[[Byte]] PNG data for reference images
Default: []
[SymmetryLine] Symmetry lines
Default: []
[Tag] Tags
Default: []
[Tileset] Tilesets
Default: []
[TilemapLayer] Tilemap layers
Default: []
[TilemapFrameContent] Tilemap frame contents
Default: []
UInt8 Color depth
0 - RGB
1 - Indexed
Stats Some stats of this file
UInt8 Ignore this byte
CanvasGrid Canvas grid config
GuideLine Guide line config
Bool Guide line show/hide
