PCHR Format

Overview

PCHR is a compact binary file format for 2D skeletal animation. A single .pchr file stores a skeleton, including bones, skinned meshes, vertex weights, and sampled animation frames, together with the atlas image the meshes are drawn from.

The format is read sequentially from the start of the file. Every variable-length body is preceded by its length or element count, so a reader never needs to seek backward or parse a text payload.

Conventions

• All multi-byte integers and floats are little-endian. Fields are read in the exact order they appear.
• Integer fields are named by signedness and width: uint8, uint16, uint32, and int16. float32 is an IEEE-754 single-precision float.
• Strings are the string type: a uint16 byte length followed by that many UTF-8 bytes.
• Arrays are written as T[count], where count names the preceding field that holds the number of T elements. That count field and its integer type are shown in each schema.
• Raw byte blocks (uint8[N]) are sized by a length field shown in each schema, such as the image dataLength that precedes the image data.

File structure

A .pchr file is a flat sequence of fields read from the start of the file. Composite fields reference a type defined under Types.

Types

Image

An atlas image. Meshes reference an image by its index in the images array.

The dataLength field gives the exact byte length of the data block for every format, so a reader consumes the image without decoding it. The format field selects how data is interpreted, and width and height give the decoded image dimensions.

Image format

png is the default format and keeps images compact. rgba8888 stores decoded pixels for readers that cannot decode PNG.

Bone

A single bone in the hierarchy. Bones are stored in topological order (parents before children), so a bone’s parent index is always less than its own index.

Mesh

A skinned mesh drawn from one atlas image.

Vertex

A single mesh vertex with its texture coordinate and skinning weights.

Each vertex is skinned by exactly four bones. boneIds[i] and boneWeights[i] form one influence: the bone at that index and its weight. Unused slots are padded with a weight of 0, which contributes nothing and lets a reader ignore the paired bone index. Four is the common upper bound for GPU skinning, so the fixed width maps directly to a skinning attribute without a per-vertex count.

Vertex positions are in the bind pose, in world-space pixels centered on the world origin. Weights are read as authored and are not renormalized by the format.

Animation

A sampled animation. One Bone transform is stored per bone, per frame.

Frames are stored back to back with no per-frame prefix. Each frame is exactly boneCount transforms in the same order as the bones array, so a reader multiplies frameCount by boneCount to know how many transforms follow.

Bone transform

A bone’s pose within a single animation frame.

Root bone transforms are in world space (pixels, centered on the origin). Child bone transforms are relative to their parent.

Reading a .pchr file

The file is read start to finish in a single pass. The example below decodes an entire file into plain data structures.

import struct


def read_pchr(path):
    with open(path, "rb") as f:
        data = f.read()
    o = 0

    def take(n):
        nonlocal o
        b = data[o : o + n]
        o += n
        return b

    def uint8():
        return take(1)[0]

    def uint16():
        return struct.unpack("<H", take(2))[0]

    def uint32():
        return struct.unpack("<I", take(4))[0]

    def int16():
        return struct.unpack("<h", take(2))[0]

    def float32():
        return struct.unpack("<f", take(4))[0]

    def string():
        return take(uint16()).decode("utf-8")

    # Image data format ids.
    FORMAT_PNG = 0
    FORMAT_RGBA8888 = 1

    assert take(4) == b"PCHR"
    version = uint32()
    fps = uint16()
    flags = uint16()

    images = []
    for _ in range(uint16()):
        name, width, height, fmt = string(), uint16(), uint16(), uint8()
        data = take(uint32())  # dataLength, then that many bytes
        images.append(
            {"name": name, "width": width, "height": height, "format": fmt, "data": data}
        )

    bones = [{"name": string(), "parent": int16()} for _ in range(uint16())]

    meshes = []
    for _ in range(uint16()):
        name, image = string(), uint16()
        vertex_count, index_count = uint16(), uint32()
        vertices = []
        for _ in range(vertex_count):
            x, y, u, v = float32(), float32(), float32(), float32()
            bone_ids = [uint16() for _ in range(4)]
            bone_weights = [float32() for _ in range(4)]
            influences = [
                (b, w) for b, w in zip(bone_ids, bone_weights) if w > 0
            ]
            vertices.append((x, y, u, v, influences))
        indices = [uint16() for _ in range(index_count)]
        meshes.append(
            {"name": name, "image": image, "vertices": vertices, "indices": indices}
        )

    animations = []
    for _ in range(uint16()):
        name, aflags = string(), uint8()
        frames = []
        for _ in range(uint16()):
            frames.append(
                [
                    {
                        "x": float32(), "y": float32(), "rotation": float32(),
                        "scaleX": float32(), "scaleY": float32(),
                        "flags": uint8(), "zOrder": int16(),
                    }
                    for _ in range(len(bones))
                ]
            )
        animations.append(
            {"name": name, "loop": bool(aflags & 1), "frames": frames}
        )

    return {
        "version": version, "fps": fps, "images": images,
        "bones": bones, "meshes": meshes, "animations": animations,
    }

Tooling

The pchr CLI inspects .pchr files and converts between the binary format and a JSON representation:

pchr inspect character.pchr
pchr pack    character.json -o character.pchr
pchr unpack  character.pchr -o ./out

• inspect prints the header and a summary of each section, similar to how file and readelf report structure.
• pack reads a JSON description and its referenced image files, encodes the pixel data, and writes a packed .pchr.
• unpack writes a JSON description of the skeleton alongside the atlas images, decoded to PNG.

The JSON is a convenience representation for authoring and inspection. It is not part of the format; a .pchr file never contains JSON. Its structure is described by a JSON Schema.