pantin

This page is docs/format/bundle.md of the repository, as it is on main.

The pantin bundle, version 0.3

A bundle is everything a game needs of a character, in one file that it loads in one call: the skeleton and the animations, the boxes, the graph of states, the parameters that deform meshes, the images packed into an atlas and their normal maps. pantin build writes it, as build/<name>.pantinpack in the folder of the project, once pantin check finds no problem in it.

It is a container. Each section is a file of the project as it is written elsewhere: JSON in UTF-8, or the PNG of a page of an atlas. A game reads it with a reader of JSON and one of PNG, and the meaning of each section is the page of its format.

The file

All numbers are little-endian.

Bytes What they are
0 to 7 PANTPACK, in ASCII.
8 to 9 The major version, 0, an unsigned 16-bit number.
10 to 11 The minor version, 3, an unsigned 16-bit number.
12 to 15 The number of sections, n, an unsigned 32-bit number.
16 to 16 + 20 n The table: for each section, its kind (4 bytes of ASCII), where it starts (an unsigned 64-bit number, in bytes from the start of the file) and its length (an unsigned 64-bit number).
after The sections.

A reader takes a bundle of its major version whose minor version is not above its own, and refuses others, naming both versions (see Every version is read). A section of a kind it does not know is passed over: a later minor version adds sections, never changes one.

The sections

Kind How many What it is
MANI one The manifest, pantin.toml of the project as JSON, its fields those of the project format. Each image is named by its own identifier: images maps each identifier to itself.
RIG one rig.json of the project, the project format. Its attachments name their images by identifier.
HIT one, when the project has boxes hit.json, the boxes format.
FLOW one, when the project has a graph of states flow.json, the graph format. Since 0.2.
DEFM one, when the project has parameters that deform meshes deform.json, the deform format. Since 0.3.
ATLS one The atlas file of the images, the atlas format: each region is named by the identifier of its image.
PAGE one for each page of ATLS, in its order The PNG of the page. The name image of the page in the atlas file says nothing in a bundle.
NATL one, or none The atlas file of the normal maps: the same pages and regions as ATLS.
NPAG one for each page of NATL, in its order The PNG of the page of normal maps, as the atlas format says.

The version 0.2 was this format without DEFM, read as one with no parameter; the version 0.1 was 0.2 without FLOW, read as one with no graph.

An image the settings of the atlas leave out is not in the bundle: the attachments that show it draw nothing.

Every version is read

A file written by pantin stays readable: a game keeps the characters it shipped when it takes a newer runtime, and a project made long ago opens. The promise holds for every file here: the project, the boxes, the graph, the parameters, the atlas and the bundle.

  • A reader reads every version of a file from the first one on: before 1.0 every version 0.n, from 1.0 on every version of its major version and of the major versions before it. What a version before did not have is read as its default.
  • A file newer than the reader is refused, never read wrong or in part, and the message names both versions: the one of the file and the last one the reader knows.
  • A test reads a file of every published version with the libraries the runtimes use: fixtures/bundles holds a bundle of each version, written by pantin build at the time of that version and never written again; the migrations of the project are tested from each version before.

Reading one

  1. Read the header and the table; check PANTPACK and the version.
  2. Parse RIG and MANI as the project format says, and HIT, FLOW and DEFM when they are there.
  3. Decode each PAGE; the region of an image in ATLS gives where its pixels are on its page, so the texture coordinates of an attachment are those of its region. NPAG gives the normal at the same place.

The Bevy runtime does this in Character::load_bundle, and pantin_bundle::Bundle in Rust.