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/bundlesholds a bundle of each version, written bypantin buildat the time of that version and never written again; the migrations of the project are tested from each version before.
Reading one
- Read the header and the table; check
PANTPACKand the version. - Parse
RIGandMANIas the project format says, andHIT,FLOWandDEFMwhen they are there. - Decode each
PAGE; the region of an image inATLSgives where its pixels are on its page, so the texture coordinates of an attachment are those of its region.NPAGgives the normal at the same place.
The Bevy runtime does this in Character::load_bundle, and pantin_bundle::Bundle in Rust.