pantin

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

The pantin file format, version 0.3

A pantin file is a JSON document, in UTF-8, that holds one skeleton and its animations. Its name ends in .pantin.json. This page says what each field means; the same structure is given to machines by the JSON Schema beside it, pantin-0.3.schema.json.

The format will change before 1.0, and each change gets a new version number. A file says which version it is written in, and a reader refuses the versions it does not know.

Version What it added Schema
0.1 Bones, slots, region attachments, skins, animations of bones. pantin-0.1.schema.json
0.2 Mesh attachments. pantin-0.2.schema.json
0.3 Constraints (ik) and events of animations. pantin-0.3.schema.json

Each version only adds to the one before: the tools read all three and write 0.3. A file that holds what its version does not have, like a mesh in a file that says 0.1, is refused.

Files of this format: fixtures/legacy, which the examples of the repository are made from.

Images can be packed into a texture atlas, which has a format of its own, and the boxes a game tests (hitboxes, hurtboxes) have theirs, and so has the graph of states of a character, flow.json, and the parameters that deform its meshes, deform.json. All of a character that a game loads is put in one file, the bundle.

This is the format that came before. A character is now a folder, where everything has an identifier that never changes: the project format, version 0.37. It is what the application opens and saves. A file of the format of this page is still read, to be turned into a project. What a transform, a key, a constraint or an event means is said here and holds for both.

Conventions

  • y points up. A positive angle turns counter-clockwise.
  • Angles are in degrees.
  • Times are in seconds.
  • Things are named, and refer to each other by name. A name is the only one of its kind in the file: two bones cannot share a name, nor two slots, two skins or two animations.
  • A field that is left out has its default value, and the writer leaves out the fields that have it.
  • A field the format does not know is refused, and so is a file in another version. A reader never guesses.

The file

Field Type Meaning
format_version "0.1", "0.2" or "0.3" The version of the format. Required.
name text The name of the skeleton. Required.
bones list of bones Required. Each parent comes before its children.
slots list of slots In drawing order: the first one is behind the others. Default: none.
skins list of skins Default: none.
ik list of constraints Since 0.3. In the order they are solved. Default: none.
animations list of animations Default: none.

Bones

Field Default Meaning
name required
parent none The name of the parent bone, written earlier in the list. A bone with no parent is a root.
length 0 How long the bone is drawn, along its x axis. It changes no computation.
x, y 0 The position of the bone in the space of its parent.
rotation 0
scale_x, scale_y 1
shear_x, shear_y 0
inherit "full" What the bone takes from its parent, see below.

What a transform means

The seven numbers of a bone describe the affine transform that goes from the space of the bone to the space of its parent. It sends

  • the origin to (x, y);
  • the x axis to a vector of length scale_x, at the angle rotation + shear_y;
  • the y axis to a vector of length scale_y, at the angle rotation + 90 − shear_x.

With no shear this is a scale, then a rotation, then a translation. shear_x leans the y axis towards the x axis, so that what is above the bone slides along it; shear_y leans the x axis towards the y axis. A shear changes the direction of an axis and never its length.

As a matrix, a point (px, py) of the bone is in its parent at

x' = scale_x · cos(rotation + shear_y) · px − scale_y · sin(rotation − shear_x) · py + x
y' = scale_x · sin(rotation + shear_y) · px + scale_y · cos(rotation − shear_x) · py + y

The transform of a bone to the world is the transform of its parent to the world applied after its own. A root bone is in the world directly.

What a bone inherits

The position of a bone is always given in the space of its parent, whatever inherit says. inherit says what happens to its two axes.

Value The axes of the bone
full follow the parent entirely: its rotation, its scale and its shear.
translation_only ignore the parent: they are what the bone itself says, in the world.
no_rotation follow the scale and the shear of the parent, not its rotation. The rotation of the parent is the angle of its x axis in the world; it is taken away from both of its axes.
no_scale follow the rotation and the shear of the parent, not its scale: each axis of the parent is taken with a length of one.
no_scale_or_reflection as no_scale, and not a reflection either: when the axes of the parent are mirrored (its x axis turned onto its y axis is a turn clockwise, x.x × y.y − x.y × y.x < 0), the y axis taken is turned back. Since the project format 0.23.

For example, under a parent whose world axes are x = (−2, 0) and y = (0, 3), mirrored, a child at (10, 0) in it with no transform of its own is at (−20, 0) in the world. With no_scale its axes are x = (−1, 0) and y = (0, 1): it is mirrored. With no_scale_or_reflection they are x = (−1, 0) and y = (0, −1): the parent turned half a turn, not mirrored.

Slots

A slot is a place on a bone where one attachment is shown at a time.

Field Default Meaning
name required
bone required The name of the bone the slot is on.
attachment none The name of the attachment shown in the setup pose.
color [1, 1, 1, 1] Red, green, blue and alpha, each from 0 to 1, not premultiplied.

Skins and attachments

A skin is a set of attachments. Each entry of attachments says in which slot it can be shown, under which name, and what it is. Two entries of one skin cannot have the same slot and the same name.

An attachment is a region or, since 0.2, a mesh.

Regions

A region is a rectangular image:

{ "slot": "palm", "name": "open", "attachment": { "region": { "path": "open.png", "width": 16, "height": 8 } } }
Field of region Default Meaning
path required Where the image is, relative to the file.
width, height required The size of the image in the space of the bone, before its scale.
x, y, rotation, scale_x, scale_y, shear_x, shear_y as for a bone Where the centre of the image is in the space of the bone, and how it is turned and scaled.

Meshes

A mesh is an image cut into triangles whose corners follow bones, so that the image bends when the bones move.

{ "mesh": {
  "path": "tail.png",
  "vertices": [
    { "u": 0, "v": 0, "weights": [{ "bone": "base", "x": 0, "y": 12 }] },
    { "u": 0.5, "v": 0, "weights": [
      { "bone": "base", "x": 40, "y": 12, "weight": 0.5 },
      { "bone": "tip", "x": 0, "y": 12, "weight": 0.5 } ] },
    { "u": 1, "v": 0, "weights": [{ "bone": "tip", "x": 40, "y": 12 }] }
  ],
  "triangles": [[0, 1, 2]]
} }
Field of mesh Meaning
path Where the image is, as for a region.
vertices The corners of the triangles.
triangles Three vertices for each triangle, each named by its place in vertices, the first one being 0.
Field of a vertex Meaning
u, v Where the vertex is on the image: u from 0 at its left to 1 at its right, v from 0 at its top to 1 at its bottom.
weights The bones that carry the vertex, at least one.
Field of a weight Default Meaning
bone required The name of a bone. It does not have to be the bone of the slot.
x, y required Where the vertex is in the space of that bone, in the setup pose.
weight 1 The share of that bone in the place of the vertex, from 0 to 1.

Where a vertex is. Each of its bones would take it to one point of the world: the point (x, y) of the weight, sent through the world transform of the bone. The vertex is at the average of those points, each counted for its weight:

position = Σ weight · world(bone) · (x, y)

The weights of a vertex add up to 1, within a thousandth. A vertex with one weight follows its bone like a region does. In the setup pose all the bones of a vertex take it to the same point, which is why its place is written once for each bone: nothing has to be worked out from the setup pose when the file is read.

Unlike a region, a mesh is not placed on the bone of its slot: its vertices say where they are. The slot still gives the mesh its place in the drawing order and its colour.

Which attachment is drawn

The editor draws the attachment that each slot names, looked up in the skin chosen in its panel first, then in the skins in their order: the first skin that has it gives it. Which skin is shown is a way of looking at the character, chosen by the editor or by the game, and is not written in the file.

When the path of an image is relative, it is relative to the folder of the pantin file, with / between its parts on every system.

Constraints

Since 0.3. A constraint of ik turns bones by itself so that the end of a chain reaches a target: one bone turned towards it, or two bones bent so that the tip of the second one is on it. It is what lets a hand or a foot be put somewhere and the limb follow.

{ "name": "reach", "bones": ["upper_arm", "forearm"], "target": "hand_goal", "bend": "negative" }
Field Default Meaning
name required The only constraint of that name.
bones required The name of one bone, or of two where the second is a child of the first and inherits everything from it.
target required The name of the bone whose origin is to be reached. It is not a bone of the chain, nor a bone under the first one.
mix 1 How much of the way the bones go, from 0 (where the animation left them) to 1 (on the target).
bend "positive" For two bones, the side of the joint: positive puts it on the left of the line from the first bone to the target, negative on its right.

When. The constraints are solved after the animation has posed the skeleton, in the order they are written, each one from where those before it left the bones. They change the rotation of their bones and nothing else, and what they change is not written back into the pose: a key is still what the animation says.

One bone. The bone is turned so that its x axis points from its origin to the target.

Two bones. In the space of the parent of the first bone, the chain is a triangle: one side from the origin of the first bone to the origin of the second, one side that is the second bone, from its origin to its tip, and the third from the origin of the first bone to the target. The two bones are turned so that the tip of the second one is on the target, with the joint on the side that bend says. A target farther than the two sides together is reached for with a straight chain, and one nearer than their difference with a folded one.

The lengths of the two sides are taken with the scale of the bones, and the solver expects what a limb usually is: the same scale on both axes and no shear. With anything else the chain still turns towards the target and may stop short of it.

With a mix under 1, each rotation goes that share of the way from where the animation left it, by the shortest way round.

Animations

Field Default Meaning
name required
duration required Above 0. No key comes after it.
bones none The bones that move, each one at most once.

Each entry of bones names a bone and gives up to four lists of keys, each in the order of time, with no two keys at the same time:

List A key has What the value does
rotation time, value is added to the rotation of the bone.
translation time, x, y is added to the position of the bone.
scale time, x, y multiplies the scale of the bone: 1 changes nothing.
shear time, x, y is added to the shear of the bone.

The project format has a fifth since 0.24, flip: the bone turned over until the next key.

Values are relative to the setup pose, which is what the bones say: an animation where every rotation key is 0 shows the skeleton as it was built. A property with no key is not touched by the animation.

Before its first key a property has the value of that key, and after its last key the value of that one.

Between two keys

A rotation goes by the shortest way. From a key at 170 to a key at −170, the bone turns by 20 degrees through 180, not by 340 through 0. A turn of more than half a circle therefore needs a key in between, and whole turns between two keys are not made. A turn of exactly half a circle goes clockwise.

Every key may have a curve, which says how the value goes from this key to the next one. It means nothing on the last key.

curve Meaning
"linear" At a constant speed. The default.
"stepped" The value of the key holds until the next key, then jumps.
{ "bezier": [x1, y1, x2, y2] } A cubic Bézier curve from (0, 0) to (1, 1) with the control points (x1, y1) and (x2, y2). x is the share of the time between the two keys that has passed, y the share of the way that is done. x1 and x2 are from 0 to 1, so that time never goes back; y1 and y2 are free, and a curve may overshoot.

Events

Since 0.3. An animation may have events: moments that a game is told about as it plays, like a foot that lands. The file only says when; what an event means is up to the game.

{ "time": 0.5, "name": "step", "text": "right" }
Field Default Meaning
time required From 0 to the duration of the animation. Events are written in the order of time; two may be at the same time.
name required What happens.
int, float, text 0, 0, empty Three values that go with the event, for the game to read as it likes.

A game that asks what happened between two moments is told the events from the first moment, included, to the second, not included: asked frame after frame, each frame from where the one before ended, it is told each event once. A loop tells its events again at each turn, and its very end is its start: an event written at the duration of a loop is never told, and belongs at 0.

Loops

An animation that loops starts again when it reaches its duration: the time that is shown is the time that has passed, modulo the duration. For a loop with no jump, the last keys repeat the first ones.