Binary specs

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. .px files use little-endian byte order.

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

  • The rest are the elements

• Type[n] - n consecutive value of Type

  • UInt8[3] - 3 consecutive UInt8

Composite types

Coordinate

Int32        x-value
Int32        y-value

Size

UInt32        Width
UInt32        Height

Rect

Coordinate    Origin
Size          Size

ARGBColor

RGB channels are alpha pre-multiplied

UInt8    R-value
UInt8    G-value
UInt8    B-value
UInt8    A-value

BlendMode

UInt16
  0  - Normal
  1  - Multiply
  2  - Screen
  3  - Overlay
  4  - Darken
  5  - Lighten
  6  - Color dodge
  7  - Color burn
  8  - Hard light
  9  - Soft light
  10 - Difference
  11 - Exclusion
  12 - Hue
  13 - Saturation
  14 - Color
  15 - Luminosity

Corners

OptionSet<UInt8> 
  1 << 0 - Top left
  1 << 1 - Top
  1 << 2 - Top right
  1 << 3 - Right
  1 << 4 - Bottom right
  1 << 5 - Bottom
  1 << 6 - Bottom left
  1 << 7 - Left

Models

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

CustomData

Store some custom data set by the users

Header (16 bytes)

UInt64    Total size of this model
UInt8     Data type
            0 - String

Content

Depending on the data type value in the header, the content will be different

String - 0:
String      The string data

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.
              NOTE: for this array, the UInt64 at the begining is for size in bytes,
              not element count.
              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
Int16             Z-index
                  Default: 0
[CustomData]      Custom datas set by the users

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
UInt8             Direction
                    0 - Forward
                    1 - Backward
                    2 - Ping-pong
UInt16            Loop count

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]
UInt16        Tiles per row
              Default: 6
ARGBColor     Grid color
              Default: Black

Fx

Header (16 bytes)

UInt64    Total size of this model
UInt8     Fx type
            0 - Color overlay
            1 - Outline
            2 - Anti-aliasing
            3 - Pattern overlay

Content

Depending on the fx type value in the header, the content will be different

Color overlay - 0:
Bool          Enabled
ARGBColor     Color
BlendMode     Blend mode

Outline - 1:
Bool          Enabled
Corners       Corners
ARGBColor     Color
[ARGBColor]   Ignored colors
Bool          Outside/inside
                true - outside
                false - inside
Bool          Is water color on

Anti-aliasing - 3:
Bool          Enabled
[Corners]     Set of corners
Float32       Intensity

Pattern overlary - 4:
Bool          Enabled
[UInt8]       Uncompressed color data of the pattern. 
              The data is in the form of [ARGBColor]
Size          Pattern size
Float32       Opacity
BlendMode     Blend mode

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)
[Fx]              Fxs
                  Default: []

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 (32 bytes)

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
              Default: false
ARGBColor     Color
              Default: (0, 0, 0, 0)

Stats

Contains 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

Header (14 bytes)

UInt32        Backward compatibility, has to be all 0
UInt16        Total size of this model
UInt8         Guide line type
                0 - Grid
                1 - Isometric
                2 - Perspective

Content

Depending on the value of guide line type in the header, the content will be different.

Grid - 0 and Isometric - 1:
Size         Size
ARGBColor    Color
Bool         Visible
Bool         Show in preview

Perspective - 2:
[Float32]        An array of x-values of perspective point coordinates
[Float32]        An array of y-values of perspective point coordinates
[UInt32]         An array of line counts for each point
[ARGBColor]      Colors of each point
Bool             Visible
Bool             Show in preview

Post-processor

Header (16 bytes)

UInt16        Total size of this model
UInt8         Processor
                0 - CRT
                1 - Vignette
                2 - Bloom
                3 - Round pixel

Content

Depending on the processor value in the header, the content will be different

CRT - 0:
String        ID
Bool          Pixel-independent
Float64       Scan line intensity (0-1)
Float64       Glow intensity (0-1)
Bool          Enabled

Vignette - 1:
String        ID
Bool          Pixel-independent
ARGBColor     Color
Float64       Intensity (0-1)
Bool          Enabled

Bloom - 2:
String        ID
Bool          Pixel-independent
Float64       Threshold (0-1)
Float64       Intensity (0-1)
Float64       Radius (0-1)
Bool          Enabled

Round pixel - 3:
String        ID
Bool          Contiguous
ARGBColor     Background color
Float64       Intensity (0-1)
Bool          Enabled

PaletteOrganization

Header (16 bytes)

UInt16     Total size of this model
UInt8      Organization type
             0 - Packed
             1 - Anywhere

Content

Depending on the organization type in the header, the content will have different data

Packed - 0:
Empty content

Anywhere - 1:
Size        The width and height of the board
[Bool]      The arrangement that fits into the size above. 
              true - empty space
              false - color space

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
                          Default: RGB
Stats                     Some stats of this file
                          Default: Empty stat, everything is 0
UInt8                     Ignore this byte
CanvasGrid                Canvas grid config
                          Default: 16 x 16, 2 gray colors
GuideLine                 Guide line config
                          Default: 16 x 16 Grid with blue color
[Post-processor]          Post-processors
                          Default: []
PaletteOrganization       The palette organization
                          Default: Packed
Bool                      Should record timelapse
Corners                   Tiled corners