pantin

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

The pantin project format, version 0.37

A character is a folder whose name ends in .pantin. It holds a manifest and one file for each kind of thing the character has:

hero.pantin/
├── pantin.toml     the manifest: what the project is, and where its images are
├── rig.json        the skeleton, what it shows and its animations
├── hit.json        the boxes a game tests, when there are some (format of its own: hit.md)
└── sources/        the images, wherever the manifest says they are

More files will join rig.json as the tools grow (a graph of states, deformation). The boxes (hitboxes, hurtboxes) are in hit.json, with versions of their own. Each file can be read alone, so that a change shows as a small difference in version control.

This page says what pantin.toml and rig.json mean. The same structure is given to machines by two JSON Schemas beside it: pantin-manifest-0.37.schema.json and pantin-rig-0.37.schema.json.

Status. This is the format the application opens and saves, and the one of the examples of the repository. The format of one file, versions 0.1 to 0.3, came before: it is still read, to be turned into a project (pantin migrate, or File › Import › A .pantin.json file… in the application), and it is no longer written by the application.

Identifiers

Everything a file can name has an identifier: a bone, a slot, a skin, an attachment, an image, a constraint, an animation, an event. An identifier is a ULID: 26 capital letters and digits, such as 01ARZ3NDEKTSV4RRFFQ69G5FAV. It is given once and never changes.

A thing is named by its identifier, never by its name. A bone says who its parent is by the identifier of the parent; a slot says which bone it is on by the identifier of the bone. A bone can therefore be renamed by changing one line, and what was on it is still on it.

  • No two things of a project have the same identifier.
  • An identifier that leads to nothing is refused, and the error says who named it.
  • Names are still what people read, and the rules of the format before still hold: two bones cannot have the same name, nor two slots, two skins, two constraints or two animations.

One reference is by name on purpose: the attachment of a slot. It says which attachment of the slot is shown, and the same name may be in several skins: it is how a skin replaces another. Each attachment has an identifier too, for what needs to name one exactly.

pantin.toml

format_version = "0.37"
name = "robot"

[images]
01HZX3K0Q8M6W2R9V5T7YB4N1C = "sources/arm.png"
01HZX3K0Q9D4S8G2J6P0FA7E3M = "sources/body.png"

[pack]
padding = 4
skip = ["01HZX3K0Q8M6W2R9V5T7YB4N1C"]

[light]
strength = 1.5

[[guides]]
axis = "y"
at = 0.0

[[psd]]
file = "art/robot.psd"
folder = "sources/robot"

[psd.layers]
01HZX3K0Q8M6W2R9V5T7YB4N1C = "body/arm"
Field Meaning
format_version "0.37". The version of every file of the project.
name The name of the character.
images For each image, its identifier and its file. The path is relative to the folder of the project, with / between its parts on every system. Default: none.
pack How the atlas of the project is packed, by the Pack workspace and pantin pack. Written only when it is not the default. Since 0.11.
light How the normal maps of the project are made, by the Light workspace and pantin light: strength, how steep the slopes are, from 0 (flat) to 10, default 1; softness, over how many pixels the edges are rounded, from 0 to 64, taken to a whole number, default 4. Written only when it is not the default. How a map is made and laid out is in the atlas format. Since 0.22.
guides The guides of the canvas, lines across the whole world that the editor's drags snap to: each an axis, x (an upright line, where x is at) or y (a line across, where y is at), and at, in units of the world. They are for the one who draws: nothing exported has them, and a runtime reads past them. Default: none. Since 0.21.
psd The PSD files whose layers are images of the project, for the editor to read them again: each a file, the PSD file, and a folder, where its layers are written as PNG files, both relative to the folder of the project when they are in it; hidden, true when the hidden layers are imported too (written only then); and layers, for each image made of a layer, its identifier in images and the name of the layer after those of its groups, the tags of the names taken out (head/eye). Read again, a layer replaces the image of the piece that shows its file, and an image whose layer is gone is offered to be taken away. Nothing exported has them. Default: none. Since 0.25.

pack has these fields, each with its default:

Field Meaning
padding How many empty pixels are left around each image of the atlas. Default: 2.
page The largest side of a page of the atlas, in pixels; one that is not a power of two is taken down to the one under it. Default: 4096.
skip The identifiers of the images the rig shows that are left out of the atlas. Default: none.
trim true: the transparent border of each image is left out of the atlas, which says where it was. Default: false. Since 0.28.
rotate true: an image is turned a quarter when that takes less room. Default: false. Since 0.28.
scale Every image packed at this share of its pixels, in hundredths, from 1 to 100. Default: 100. Since 0.28.
tight true: a slower packing that leaves less room between the images. Default: false. Since 0.28.
per_skin true: beside the atlas of all the images, one atlas of the images of each skin. Default: false. Since 0.28.

How each of them packs is in the atlas format.

An image is a PNG file or an SVG file, told apart by the extension of its file (.png, .svg, in any case). An SVG is drawn at the size it gives, one pixel for each of its units, as a PNG of that size would be; its text is drawn with the fonts of the machine.

An image is named by its identifier in the other files. Moving or renaming the file of an image changes one line of the manifest and nothing else.

rig.json

rig.json says what the format of one file said, version 0.3, with identifiers. What a transform means, what a bone inherits, how a key is interpolated, how a constraint is solved, when an event is told: all of this is unchanged and is said on that page. What follows is what differs.

Field Meaning
format_version "0.37".
bones Each bone has an id. parent is the identifier of a bone written earlier. A bone may name the skins that have it: see Bones and constraints of some skins.
slots Each slot has an id. bone is the identifier of a bone. attachment is still a name. A slot may have a dark colour and a blend mode: see below.
skins Each skin has an id, and each of its attachments has an id. slot is the identifier of a slot.
ik Each constraint has an id. bones and target are identifiers of bones. It may soften, stretch and compress: see IK constraints.
springs The bones that follow with a delay. See below.
sliders Animations held at a time, which pose the skeleton. See Sliders. Since 0.34.
gravity How fast the springs are pulled down, in units of the world per second squared. Not negative; 0, or no field, is none. See below. Since 0.17.
path_constraints Chains of bones laid along the paths of slots. See below.
transform_constraints Bones brought towards the transform of another bone. See below. Since 0.12.
folders Pieces of a bone, or constraints, grouped under a name: see Folders. Since 0.29.
solve_order The order the constraints are solved in, by their identifiers, whatever their kinds: see The order of solving. Written only when it is not the order of their kinds. Since 0.26.
animations Each animation has an id. In bones, bone is the identifier of a bone. Each event has an id. slots holds the keys of the slots that change, paths those of the path constraints, transforms those of the transform constraints, ik those of the IK constraints (since 0.31), springs those of the springs (since 0.32), sliders those of the sliders (since 0.34), deforms those of the vertices of meshes, and draw_order the order the slots are drawn in: see below. looping, when it is true, says the animation is made to play again and again: its last pose is its first. It is a hint for a game, which chooses how it plays an animation; the editor writes a key set on the first or the last moment of such an animation on both, and pantin check names one whose last pose is not its first. No field is false. Since 0.18. markers are notes of the animator, each an id, a time within the animation and a text, in the order of time: where a foot touches, where the loop may be cut. A game is not told them, unlike events. Since 0.19. offsets are chains of bones that follow each other a beat later: see below. Since 0.20. A bone may have a list of keys flip, the bone turned over: see below. Since 0.24.

The name of the skeleton is no longer in this file: it is the name of the manifest.

A region and a mesh no longer have a path. They have an image, the identifier of an image of the manifest:

{ "id": "01HZX3K0QB…", "slot": "01HZX3K0QA…", "name": "body",
  "attachment": { "region": { "image": "01HZX3K0Q9…", "x": 26, "width": 44, "height": 56 } } }

In a mesh, the bone of each weight is the identifier of a bone.

Events with a sound

An event may carry a sound for the game to play when it is told the event: a footstep, a hit. pantin plays none; the runtimes give it with the event. Since 0.37.

{ "id": "01HZ…", "time": 0.5, "name": "step", "sound": { "file": "sounds/step.wav", "volume": 0.8, "balance": -0.5 } }
Field Meaning
sound.file Where the file is, relative to the folder of the project, with /: a WAV, an OGG, an MP3, whatever the game plays.
sound.volume From 0, silent, to 1, as the file is. Default: 1, not written.
sound.balance From -1, all on the left, to 1, all on the right. Default: 0, the middle, not written.

Linked meshes

A mesh may bend as another: it takes the vertices, the triangles and the weights of a mesh of another entry of a skin, with an image of its own: a sleeve of another colour, the other side of a flag, a face for each expression. Since 0.36.

{ "mesh": { "image": "01HZ…", "link": { "source": "01HZX3K0QB…", "deforms": true } } }
Field Meaning
link.source The identifier of the entry of a skin whose mesh it takes: a mesh that is not linked itself, and not this one.
link.deforms When true, the keys of the vertices of its source (deforms, by the name of the source) move it too while its slot shows it, when it is in the same slot. Default: false.

A linked mesh writes no vertices and no triangles: one that has them, or whose source is not a mesh of its own, is refused. Its UVs are those of its source, laid over its own image, which has the size of the image of the source. An entry that linked meshes take cannot be taken away, nor made something else than a mesh of its own, while they do.

Sequences

A region or a mesh may step through more images, as a flipbook: a flame, a blinking eye, a walk drawn frame by frame. Since 0.15.

{ "region": { "image": "01HZ…", "frames": ["01J0…", "01J1…"], "setup_frame": 1,
              "width": 40, "height": 60 } }
Field Meaning
frames More images of the manifest, after image, which is frame 0. Default: none.
setup_frame The frame shown in the setup pose, and whenever no key says otherwise, from 0 to the number of frames. Default: 0.

Every frame is drawn in the place and at the size of the region, or on the triangles of the mesh: the frames of a sequence have the same size.

How a slot is drawn

Beside its color, a slot may say two things of how its images are drawn. Since 0.13.

{ "id": "…", "name": "flame", "bone": "…", "attachment": "flame",
  "color": [1, 0.9, 0.6, 1], "dark": [0.4, 0, 0], "blend": "additive" }
Field Meaning
dark Red, green and blue, each from 0 to 1: the colour the dark parts of the images take. Each channel s of an image becomes s × color + (1 − s) × dark: the light parts take color, the dark ones dark. Default: [0, 0, 0], which changes nothing, and is then not written.
blend How the slot is put over what is behind it: normal, additive, multiply or screen. Default: normal, not written.

With c a channel of the slot's colour at a pixel and b the same channel of what is behind, both from 0 to 1, what is seen where the image covers all and what is behind is opaque is c for normal, b + c for additive (held at 1), b × c for multiply, and 1 − (1 − b) × (1 − c) for screen. Where what is behind is partly transparent, c is mixed with that in proportion of its alpha; over nothing, every mode draws c. The image then goes over by its alpha, times the alpha of color, as a normal one does.

Slot timelines

An animation can change what a slot shows: which of its attachments, and its colour. An eye blinks by showing another image for a moment; a hand changes; a ghost fades.

"slots": [
  { "slot": "4G7WKD871E0MV7W5XS2ZYPH3X8",
    "attachment": [
      { "time": 0.0, "name": "eye_open" },
      { "time": 1.2, "name": "eye_closed" },
      { "time": 1.3, "name": "eye_open" },
      { "time": 1.8 } ],
    "color": [
      { "time": 0.0, "color": [1, 1, 1, 1] },
      { "time": 2.0, "color": [1, 1, 1, 0], "curve": "stepped" } ],
    "dark": [
      { "time": 0.0, "color": [0, 0, 0] },
      { "time": 1.0, "color": [0.3, 0, 0.5] } ] }
]
Field Meaning
slot The identifier of a slot. An animation has one entry for a slot, at most.
attachment Keys of the attachment shown, in the order of time. name is the name of an attachment of the slot, as the attachment of a slot is; a key with no name shows nothing. A key holds until the next one: there is no curve. Default: none.
color Keys of the colour, in the order of time. color is red, green, blue and alpha, each from 0 to 1, not premultiplied, as the color of a slot. curve is that of a key of a bone: each channel goes from one key to the next on it, and a channel that a curve takes past 0 or 1 is held there. Default: none.
dark Keys of the dark colour, as those of color, with red, green and blue only. Since 0.13. Default: none.
sequence Keys of how the sequence of the image the slot shows plays from each key on, until the next: mode (hold, once, loop or ping_pong, default hold), reverse (true plays the frames from the last to the first), frame (the frame it starts at, counted in the order it plays, default 0) and delay (in seconds, how long a frame is shown). There is no curve. Since 0.15. Default: none.

How a sequence plays. With n frames and steps the number of whole delays since the key (none when delay is 0), the frame counted in the order it plays is: frame for hold; frame + steps, at most n − 1, for once; (frame + steps) mod n for loop; and for ping_pong, with p = (frame + steps) mod (2(n − 1)), p when it is at most n − 1 and 2(n − 1) − p after. With reverse, the frame shown is n − 1 minus that. Before the first key the first key plays, from its time; a slot with no key shows setup_frame.

A key says what the slot shows, not a change to its setup pose: a colour key of [1, 1, 1, 0.5] is half transparent, whatever the colour of the slot. Before the first key of a list the value of the first key holds, and after the last the value of the last; a slot with no key of a list shows what its setup pose says. A key comes no later than the duration of the animation.

A key whose name is not an attachment of its slot in any skin is read, and shows nothing: pantin check says where it is.

Timelines of vertices

An animation can move the vertices of a mesh: an eyelid that closes over an eye, a cheek that swells, a cloth that folds, with no bone for each.

"deforms": [
  { "slot": "4G7WKD871E0MV7W5XS2ZYPH3X8", "attachment": "lid",
    "keys": [
      { "time": 0, "offsets": [[0, 0], [0, 0], [0, 0]] },
      { "time": 0.2, "offsets": [[0, -6], [0, -9], [0, -6]], "curve": "stepped" } ] }
]
Field Meaning
slot The identifier of a slot.
attachment The name of the mesh in that slot, as the attachment of a slot names it: the offsets move it only while the slot shows it. A slot has one entry for a mesh, at most.
keys In the order of time. offsets holds an offset [x, y] for each vertex, in the order of the vertices of the mesh; a vertex past the end of the list is not moved. curve is that of a key of a bone: each offset goes from one key to the next on it.

Where an offset goes. An offset is added to the place of the vertex on each bone that carries it, in the space of that bone, before the bones carry it: the vertex is where the sum of weight × bone × (x + offset) puts it. A deformed mesh therefore still bends with its bones. Before the first key the first holds, and after the last the last.

The draw order in time

An animation can change the order the slots are drawn in: a hand that passes behind the body and comes back in front of it.

"draw_order": [
  { "time": 0.4, "slots": ["4G7WKD871E0MV7W5XS2ZYPH3X8", "0K3C6TQ9NWZ4F1B7X2M8D5R0YA", "…"] },
  { "time": 0.9, "slots": ["0K3C6TQ9NWZ4F1B7X2M8D5R0YA", "4G7WKD871E0MV7W5XS2ZYPH3X8", "…"] }
]
Field Meaning
time In seconds from the start, no later than the duration. The keys are in the order of time, one at each time.
slots Identifiers of slots, in the order they are drawn from this time until the next key, the first one behind the others. A slot is named once at most.

A key holds from its time until the next one: an order is not taken part of the way to another. Before the first key the first holds, and after the last the last; an animation with no key draws the slots in the order of slots of the rig.

The slots a key does not name are drawn after the ones it names, in the order of slots: the editor names every slot, and a slot made after the key was written goes in front, where a new slot goes. A key that names a slot that is not there is refused when it is read.

Mixed with another animation, the order of the one that weighs half or more is drawn, as the attachment of a slot is.

A bone turned over

In an animation, the keys of a bone may hold a list flip: from each key until the next, the bone is turned over, or not, compared with its setup pose.

{ "bone": "01HZX3K0Q7…", "flip": [{ "time": 0 }, { "time": 0.5, "x": true }] }
Field Meaning
time In seconds from the start, no later than the duration. The keys are in the order of time, one at each time.
x true: the bone is turned over across its y axis, its scale x of the sign other than that of its setup pose. No field is false.
y true: the bone is turned over across its x axis, its scale y of the sign other than that of its setup pose. No field is false.

A flip is applied after the scale of the bone: each of its two scales keeps its size and takes the sign of the setup pose, or the other sign where the key says so. A key holds from its time until the next one: a flip is not taken part of the way to another. Before the first key the first holds, and after the last the last. Mixed with another animation, the flip of the one that weighs half or more is taken, as the attachment of a slot is. A bone turned over in its setup pose is one of a negative scale: there is no other word for it.

Points

A point is a place and a direction on a bone that a game reads: where a bullet leaves a gun, where dust rises from a foot. It is an attachment of a slot, as an image or a path is, and draws nothing: the editor shows it, a game asks where it is. Since 0.14.

{ "id": "…", "slot": "…", "name": "muzzle",
  "attachment": { "point": { "x": 24, "y": 3, "rotation": 10 } } }
Field Meaning
x, y Where the point is, in the space of the bone of the slot. Default: 0.
rotation The direction it points at, in degrees, counter-clockwise from the x axis of the bone. Default: 0.

In the world, the point is where the bone takes (x, y), and its direction is where the bone takes the unit vector at rotation: a scaled or sheared bone turns it as it turns its axes. The point is found by its slot, and only while the slot shows it, as a path is.

Clips

A clip is a polygon on the bone of its slot that cuts out what the slots drawn after it show: what is outside it is not drawn. A mouth seen through the outline of a head, a hand in a pocket. It is an attachment of a slot, as a point is, and draws nothing itself. Since 0.16.

{ "id": "…", "slot": "…", "name": "mask",
  "attachment": { "clip": { "points": [[0, 0], [40, 0], [40, 30], [0, 30]], "end": "…" } } }
Field Meaning
points The corners of the polygon, [x, y] in the space of the bone of the slot, in order, three at least; it does not cross itself.
end The identifier of the last slot it cuts. With none, it cuts every slot drawn after it.
inverse true: what is outside the polygon is kept, and what is inside it cut away: a hole, a window. Written only when it is true. Since 0.30.
convex true: the polygon is the convex hull of the corners, whatever their order; it may then cross itself. Written only when it is true. Since 0.30.
weights The bones that carry each corner, one list for each of points, each { "bone", "x", "y", "weight" } as for the vertices of a mesh: the corner is the sum of where each bone puts its x and y, by its weight. With none, the corners are in the space of the bone of the slot, at their points, which are then not used. Since 0.30.

How it is worked out. While the slots are drawn in their order, a slot that shows a clip starts cutting: each slot drawn after it, up to and with end, has its triangles cut to the polygon in the world, the place of each new corner on its image found in proportion along the side it was cut on. The polygon is cut into triangles for this, as a mesh is from its outline. A clip that another clip follows before its end gives way to it. A polygon of no area cuts nothing.

An inverse clip keeps, of each triangle, what lies outside each triangle of the polygon: the triangle is cut by the sides of the first one, the parts outside a side kept and the part inside cut by the next side, and so on for each triangle of the polygon. A convex clip is the convex hull of its corners in the world (the monotone chain), cut from its first corner as a fan.

Paths

A path is a curve that a chain of bones follows: a tail, a rope, a tentacle, a line drawn on the ground. It is an attachment of a slot, as an image is, beside the regions and the meshes of a skin: a skin can give a slot another path. It is a chain of cubic Bézier segments, carried by the bone of the slot, and a path constraint lays a chain of bones along the path its slot shows.

"skins": [
  { "id": "…", "name": "default", "attachments": [
    { "id": "01J0P2…", "slot": "4G7WKD871E0MV7W5XS2ZYPH3X8", "name": "curl",
      "attachment": { "path": {
        "points": [
          { "x": 0, "y": 0, "after": [0, 30] },
          { "x": 40, "y": 40, "before": [20, 40] } ] } } } ] }
],
"path_constraints": [
  { "id": "01J0P3…", "name": "along", "slot": "4G7WKD871E0MV7W5XS2ZYPH3X8",
    "bones": ["1NGZEER7HTGYT1KKKH0C3SC836"], "position": 0.25, "spacing": 2, "mix": 0.5 }
]
Field of a path Meaning
points The points the curve goes through, in order, in the space of the bone of the slot. Each has x and y, and two handles: the segment that comes to the point bends towards before, the one that leaves it towards after. A handle that is not written is on the point.
closed Whether a last segment goes from the last point back to the first. Default: false.
weights The bones that carry each control point, as those of a mesh carry its vertices: three lists for each point, its before, the point, its after, each list of { "bone", "x", "y", "weight" }; the control point is the sum of where each bone puts its x and y, by its weight. With none, the path is carried by the bone of its slot, and points say where; with them, points are not used to place the path. Since 0.35.

Each segment from a point P to the next Q is the cubic Bézier curve of control points P, the after of P, the before of Q, and Q. A path draws nothing: the editor shows it, a game does not.

Field of a path constraint Meaning
id, name The identifier of the constraint, and its name, the only one of that name.
slot The slot whose path is followed: the attachment it shows, when that is a path; a slot that shows something else, or nothing, leaves the chain as it is. Its bone is not one of the chain nor under the first of it.
bones The bones laid along the path, each a child of the one before.
position Where the origin of the first bone is, as position_mode says. Default: 0.
spacing How far apart the bones are, as spacing_mode says. Default: 0.
position_mode percent (not written): position is a share of the length of the path, 0 at its start, 1 at its end. fixed: a length along it. Since 0.35.
spacing_mode length (not written): each bone starts its own length plus spacing after the origin of the one before. fixed: spacing from origin to origin. percent: spacing times the length of the path, from origin to origin. proportional: the chain spans spacing times the length of the path, each bone its share by its length. Since 0.35.
rotate_mode chain (not written): each bone points at where its tip falls on the path. tangent: along the path where its origin is. chain_scale: as chain, and lengthened or shortened along its x axis so that its tip is on the origin of the next bone. Since 0.35.
mix How much of the way the bones go, from 0 (as posed) to 1 (on the path). Default: 1.

How it is worked out. The path is taken into the world by its bone, or each control point by its weights, and measured along its length, each segment cut into 32 straight pieces. The origin of the first bone is at the distance position × length along it (position itself for fixed); each next bone starts after it by the step of spacing_mode, the length of a bone being its length times the length of its x axis in the world. Each bone is turned so that its x axis points at the point one bone length further along (chain), at the point a thousandth of the path further along, or 0.001 when that is less (tangent), or at the origin of the next bone, which its scale along x then reaches (chain_scale, from its length in the world once the bones before it moved). A closed path goes round; an open one goes on straight past its ends. Each bone goes the share mix of the way, in its position and its rotation, from where the pose put it. By default the path constraints are solved after the IK constraints, in their order, each one from where the ones before it left the skeleton, and before the transform constraints and the springs (see The order of solving).

Golden values: a straight path of 100 up from (50, 0), and a chain of three bones of length 10. fixed with position 20: origins at 20, 30, 40. spacing_mode fixed, spacing 25: 0, 25, 50. percent, 0.3: 0, 30, 60. proportional, 0.9, with chain_scale: 0, 30, 60, each bone three times as long in the world (path.rs, tests of pantin-core).

An animation changes what a path constraint says with paths, one entry for a constraint:

"paths": [
  { "constraint": "01J0P3…",
    "position": [ { "time": 0, "value": 0 }, { "time": 2, "value": 1 } ],
    "mix": [ { "time": 0, "value": 1 } ] }
]

position, spacing and mix are lists of keys, each with a time, a value and a curve as those of a bone. A value is what the constraint says, not a change to it.

IK constraints

An IK constraint turns one bone, or a bone and its child, so that the end of the chain reaches for its target, as the format of one file says. Since 0.31 it may also be soft, and lengthen or shorten its bones to reach:

"ik": [
  { "id": "01J0Q5…", "name": "reach", "bones": ["5ZK2…", "5ZK3…"], "target": "5ZK6…",
    "softness": 12, "stretch": true, "thickness": "volume" }
]
Field Meaning
softness Over how far short of the chain stretched out its reach slows down, so that the joint does not snap straight; a chain of two bones only. Not negative; 0, not written, is none.
stretch true: when the target is further than the bones reach, they lengthen to reach it. Not written when false.
compress true: when the target is nearer than the bones reach, they shorten to reach it. Not written when false.
thickness What the width of a bone does as it lengthens or shortens: keep (not written), same (it changes as the length does) or volume (it changes the other way, the area of the bone kept).

How it is worked out. For one bone of length l (its length times its scale_x) and a target at d from its origin: when it stretches and d > l, or compresses and d < l, its scale_x is multiplied by 1 + (d / l − 1) × mix; that factor multiplies its scale_y too for same, and divides it for volume. For two bones of sides a and b (the first from its origin to the origin of the second, the second its length), with d the distance to the target:

  • when it stretches and d > a + b, the chain is straight, and the first bone is scaled by the factor d / (a + b), mixed and given to its width as above; the second, carried by it, follows;
  • when it compresses and d < |a − b|, the chain is folded, and the first bone is scaled by d / |a − b| alike;
  • else, with a softness s > 0, the chain reaches for a distance d′ in place of d: d itself up to a + b − s, then (a + b − s) + s × (1 − e^(−(d − a − b + s) / s)), which comes ever closer to a + b without reaching it.

Golden values, for every runtime to give the same: one bone of length 30 and a target at 75 that stretches is scaled by 2.5; the same with a mix of 0.5 and volume, scale_x 1.75 and scale_y 1 / 1.75; a target at 12 that compresses with same, 0.4 and 0.4. Two bones of 30 and 20 along x and a target at 75 that stretches: the first bone scaled by 1.5, the tip on the target; a target at 5 that compresses: 0.5. A softness of 10 and a target at 45: the chain reaches 43.9347. d′ for d = 100, a + b = 50, s = 10: 49.975.

An animation changes an IK constraint with ik, one entry for a constraint:

"ik": [
  { "constraint": "01J0Q5…",
    "mix": [ { "time": 2.2, "value": 1 }, { "time": 2.6, "value": 0.2 } ],
    "softness": [ { "time": 0, "value": 12 } ],
    "flags": [ { "time": 0, "stretch": true }, { "time": 1.5, "bend": "negative" } ] }
]

mix (from 0 to 1) and softness (not negative) are lists of keys as those of a bone, each with a time, a value and a curve. Each key of flags holds from its time until the next one, whatever its curve: bend (positive, not written, or negative), stretch and compress (not written when false); before the first key the first one holds, as for every list of keys, and with no key what the constraint says holds. Between two keys of mix or softness that change, the value is interpolated; with tracks mixed, a key of flags is taken once the weight of its track reaches one half. A value is what the constraint says, not a change to it. thickness is not keyed. The keys of a constraint that is deleted go with it.

Transform constraints

A transform constraint brings bones towards another bone, its target: an eye that turns as the other does, a shadow that follows a foot, a bone that copies the scale of a limb. It takes the rotation, the position, the scale and the shear of the target in the world, each by a share of its own.

"transform_constraints": [
  { "id": "01J0Q4…", "name": "mirror", "bones": ["1NGZEER7HTGYT1KKKH0C3SC836"],
    "target": "4G7WKD871E0MV7W5XS2ZYPH3X8",
    "offset": { "rotation": 180, "y": -4 },
    "mix": { "translation": 0, "scale": 0.5 } }
]
Field Meaning
id, name The identifier of the constraint, and its name, the only transform constraint of that name.
bones The bones that are brought, each once, at least one.
target The bone whose transform is taken. It is none of bones, and none of them carries it: it would move away as they are brought to it.
offset What is added to the target, each field 0 when it is not written: rotation in degrees; x and y, a point in the space of the target where the origin of each bone is brought; scale_x and scale_y, added to the scale of the target on each axis; shear, in degrees, added to how much the y axis of the target leans towards its x axis. Not written when all are 0.
mix How much of the way each part goes, from 0 (as posed) to 1 (the target's): rotation, translation, scale and shear, each 1 when it is not written. Not written when all are 1.
space world (not written): the numbers are those of the world transforms. local: they are the local transforms, as the panel of each bone types them, whatever the parents. Since 0.33.
relative true: the target is added to each bone, its share of it, instead of the bone going towards it. Not written when false. Since 0.33.
drives Numbers of the target that give numbers of the bones, in place of each number going to the same one: each { "from", "to", "factor", "offset", "min", "max" }, from and to one of rotation, x, y, scale_x, scale_y, shear; factor 1 and offset 0 when not written; min and max optional, min not above max. Since 0.33.

How it is worked out. The world transform of the target, and that of each bone, are written as the numbers of a transform with no shear_y (as rotation, scale_x, scale_y and shear_x of a bone, see the format of one file): rotation is the angle of the x axis, scale_x and scale_y the lengths of the axes (scale_y negative for a mirror), and shear_x how far the y axis leans from a right angle. For each bone:

  • its rotation goes the share mix.rotation of the short way round to the rotation of the target plus offset.rotation;
  • its origin goes the share mix.translation of the way to the point (offset.x, offset.y) of the target;
  • each of its scales goes the share mix.scale of the way to that of the target plus offset.scale_x or offset.scale_y;
  • its shear goes the share mix.shear of the way to that of the target plus offset.shear.

The bone is then given the local transform that puts it there under its parent, as it inherits from it; a bone under a parent that flattens the plane is left as it is. The bones are brought parents first, so that a child of a bone that was brought starts from where its parent went. By default the transform constraints are solved last, after the path constraints, in their order, each one from where the ones before it left the skeleton (see The order of solving); then the springs swing.

In local space the numbers of the bone (now) and of the target (goal) are their local transforms, and the bone is given the numbers worked out as they are, with no conversion; the point of the offset is goal.x + offset.x, goal.y + offset.y. Relative, in either space, each number is added rather than reached: x = now.x + (goal.x + offset.x) × mix.translation, the same for y; rotation = now.rotation + (goal.rotation + offset.rotation) × mix.rotation; scale_x = now.scale_x × (1 + (goal.scale_x − 1 + offset.scale_x) × mix.scale), the same for scale_y; shear = now.shear + (goal.shear + offset.shear) × mix.shear.

With drives, only the numbers they name change, and the offset is not used. Each drive takes the number from of the target, given = from × factor + offset, brought up to min and down to max; the number to of the bone then goes the share of the mix of its part (rotation; translation for x and y; scale; shear) of the way to given (a rotation the short way round), or, relative, has given times that share added (a scale is multiplied by 1 + (given − 1) × share). Drives are applied in their order.

Golden values: a root turned by 10°, a target at (30, 40) turned by 90°, its scale_x 2 and shear 20, and an arm under the root at x 5. In local space the arm takes the numbers of the target: (30, 40), 90°, 2, 20. Relative and local, with a translation mix of 0.5: x 20, y 20, 90°, 2, 20. A drive of the rotation of the target to x, factor 0.5, offset 1, local: x 46; with a max of 40: 40. A drive of the x of the target to the rotation, factor 2, in the world: the arm at 60° in the world, 50° under its root (transform.rs, tests of pantin-core).

An animation changes the mixes of a transform constraint with transforms, one entry for a constraint:

"transforms": [
  { "constraint": "01J0Q4…",
    "rotation": [ { "time": 0, "value": 0 }, { "time": 1, "value": 1 } ] }
]

rotation, translation, scale and shear are lists of keys of the mixes, each with a time, a value from 0 to 1 and a curve, as those of a bone. A value is what the constraint says, not a change to it. The offset is not keyed.

Springs

A spring makes one bone follow what carries it with a delay: a tail, an antenna, the end of a flag. Its keys and its constraints still say where the bone points; the spring makes it get there late, swing past, and settle.

"gravity": 300.0,
"springs": [
  { "id": "7ZZ3M0W6Q9K4T1X8B5N2C7D0HF", "name": "antenna spring",
    "bone": "1NGZEER7HTGYT1KKKH0C3SC836", "stiffness": 90.0, "damping": 4.0,
    "gravity": 0.5, "inertia": 0.8 }
]
Field Meaning
id, name The identifier of the spring, and its name, the only spring of that name.
bone The identifier of the bone. A bone has at most one spring.
stiffness How hard the tip of the bone is pulled to its place, per second squared. Above 0. The higher, the sooner it follows.
damping How fast the swing dies, per second. Not negative; 0 swings for ever.
gravity How much of the gravity of the skeleton the tip feels: 0 none, 1 all of it. Not negative. 1 when there is no field. Since 0.17.
inertia How much the tip keeps to where it was when what carries the bone moves: 1 it stays behind as a weight would, 0 it is carried along at once. From 0 to 1; 1 when there is no field. Since 0.17.
skeleton_inertia The same, when the game moves the whole skeleton (a run, a jump). From 0 to 1; 1 when there is no field. Since 0.17.
mass How heavy the tip is: the pull of the spring and its damping move it the less, the heavier it is; gravity pulls every mass alike. Above 0; 1 when there is no field. Since 0.32.
mix How much of its swing the bone takes: 0 none, it is as posed; 1 all of it. From 0 to 1; 1 when there is no field. Since 0.32.

How it is worked out. A spring gives a weight to the tip of its bone, the point at length along it (one unit along it for a bone of no length). Everything is in the space of the skeleton, and in 32-bit floating point numbers, in the order written here: a runtime that does the same gives the same numbers.

The game puts the skeleton somewhere in its world: a placement, an affine transform from the space of the skeleton to the world of the game (the identity in the editor, or while the game says nothing). Each time the skeleton is stepped by elapsed seconds:

  1. elapsed is taken from 0 to 0.1 (a time that is not a number is 0), and cut into n = ceil(elapsed / (1/240)) steps of h = elapsed / n.
  2. moved is inverse(placement) ∘ placement_before: it takes a point of the space of the skeleton at the step before to the point of the space of the skeleton now that is at the same place in the world of the game. placement_before is placement the first time. down is inverse(placement) applied to the direction (0, -1), and pull is down * gravity, with the gravity of the skeleton. A placement that cannot be inverted gives moved the identity and down the direction (0, -1).
  3. The pose, with its constraints solved, is worked out. Then each spring, from the roots outwards (a bone swings from where the bones above it have swung): - wanted is where the pose, with the springs above it, puts the tip. - The first time, the tip is at wanted with no velocity. Otherwise, with s its skeleton_inertia and i its inertia, and wanted_before its wanted of the step before:

    text place = place + s * (moved(place) - place) velocity = velocity + s * (moved_direction(velocity) - velocity) place = place + (1 - i) * (wanted - wanted_before)

    where moved_direction is moved without its translation. - Then, n times, with weight = pull * gravity (the gravity of the spring):

    text velocity += ((stiffness * (wanted - place) - damping * velocity) / mass + weight) * h place += velocity * h

  • A place or a velocity that is not a number puts the tip back at wanted, still.
  • The bone is turned around its origin by mix times the angle from wanted to place, the short way, in degrees (the other way for a bone whose world transform mirrors): it turns, it does not stretch. A tip on the origin of its bone does not turn it.

Each number of a spring here is the one the pose gives it at that moment: its own, or what the animation keys (see below). Numbers that cannot be stepped (a mass or a stiffness of 0, a mix past 1…) are taken as those of the spring itself.

A project with no gravity and springs with no field of 0.17 moves as it did in 0.16.

The numbers to give. A root at the origin with a bone first of length 10 at x 10 under it, and a bone second of length 10 at x 10 under first, both on springs of stiffness 120, damping 8, gravity 1, inertia 0.5 and skeleton_inertia 1; the skeleton has a gravity of 300. It is stepped once by 1/60 s in its setup pose, with the identity as placement; then the root is turned by 30° and the placement moved by (5, 20), and it is stepped five times by 1/60 s. The tip of first is then at (13.0358, -3.9919) and the tip of second at (15.4301, -13.7011), in the space of the skeleton, within 0.001 (the_golden_values_of_the_solver, in crates/pantin-core/src/spring.rs). The same, with every spring of mass 2 and mix 0.5: the tip of first at (18.0267, 1.4972) and that of second at (24.9033, -5.7631) (the_golden_values_of_a_mass_and_a_mix).

An animation changes the numbers of a spring with springs, one entry for a spring:

"springs": [
  { "spring": "7ZZ3M0W6Q9K4T1X8B5N2C7D0HF",
    "mass": [ { "time": 1.6, "value": 1 }, { "time": 2, "value": 4 } ],
    "mix": [ { "time": 0, "value": 0.5 } ] }
]

stiffness, damping, gravity, inertia, skeleton_inertia, mass and mix are lists of keys as those of a bone, each with a time, a value and a curve; each value follows the rule of its field above. A value is what the spring says, not a change to it. With tracks mixed, each number is mixed as the weights of the tracks say. The keys of a spring that is taken away go with it.

A spring depends on what came before, unlike everything else in a pose: the same time of an animation does not always give the same picture. A program that needs the pose of a time alone, as an export of frames does, starts from rest at the beginning of the animation and steps forward.

Sliders

A slider holds an animation at a time: the skeleton is posed as that animation poses it then, by a share. Its time is its own, keyed by another animation, set by a game, or given by a number of a bone: a face that poses itself as an eye moves.

"sliders": [
  { "id": "01J0Q7…", "name": "turn", "animation": "01J0Q6…", "time": 0.5,
    "driver": { "bone": "5ZK2…", "property": "x", "factor": 0.05, "offset": 0.5 } }
]
Field Meaning
id, name The identifier of the slider, and its name, the only slider of that name.
animation The identifier of the animation it holds. An animation that a slider holds is not deleted, and does not key that slider.
time In seconds, not negative; 0 when not written.
mix How much of the way the pose goes to what the animation gives, from 0 to 1; 1 when not written.
driver A number of a bone that gives the time in place of time: bone, property (rotation, x, y, scale_x, scale_y, shear, of its local transform as the pose has it), factor (1 when not written) and offset (0 when not written): the time is value × factor + offset.

How it is posed. After the animations played on the tracks, and before the constraints are solved, each slider in the order of the list takes its time (its driver's, or what the pose says of it), keeps it from 0 to the duration of its animation, and applies that animation at that time, as it plays once, each property going the share mix of the way from the pose to what the animation gives (an attachment and the draw order switch at a mix of one half or more). It poses the setup pose too.

An animation changes a slider with sliders, one entry for a slider: time and mix, lists of keys as those of a bone. Golden values: a bone whose setup rotation is 30 and an animation that keys it from 0 to 90 degrees over a second; a slider at 0.5 s gives 75 degrees, at a mix of 0.5 52.5, at 3 s 120; driven by the x of a bone at 0, factor 0.1 and offset 0.25, 52.5 (a_slider_poses_its_animation_at_its_time_by_its_mix, tests of pantin-runtime).

Offsets along a chain

An offset makes the bones of a chain (a tail, hair, an arm) follow each other a beat later, without physics. The keys in the file are the keys as the animator set them; the offset is added when the animation is played, until the editor applies it into the keys and takes it away.

"offsets": [
  { "id": "01J8…", "bones": ["3SXK…", "78PM…", "3JD5…"], "step": 0.0667 }
]
Field Meaning
id The identifier of the offset.
bones The bones of the chain, from the first; a bone is in one offset of an animation at most.
step In seconds. The first bone plays its keys as they are, the second step later, the third 2 × step later, and so on. Negative is earlier.

How the keys of a bone are played delay seconds later, in an animation of duration seconds, for each list of keys of the bone (rotation, translation, scale, shear, flip):

  • In an animation that loops, shift is delay taken into [0, duration); with no shift there is nothing to do. The seam is duration − shift, the moment of the keys that now falls on both ends. Each key before duration goes to its time plus shift, less duration when that reaches the end. A key at 0 and one at duration hold the value the keys gave at the seam.
  • Otherwise, each key goes to its time plus delay, and those that leave [0, duration] are left out. With a delay after, a key at duration holds the value the keys gave at seam = duration − delay; with a delay before, a key at 0 holds the value at seam = −delay.
  • The span of keys that the seam cuts keeps its motion: its curve is cut at the share of its time where the seam falls, by De Casteljau's construction on the cubic Bézier of the curve, and each part is brought back to go from (0, 0) to (1, 1). The key before the seam takes the first part, the key put at the start of what follows the second. A linear or stepped curve stays as it is; a part along which the value does not move is linear.
  • Two keys on one moment are one: the key put on an end is kept.

The order of solving

Each constraint moves its bones from where the constraints solved before it left the skeleton, so their order matters: a bone that follows another (a transform constraint) and is then turned towards a target (IK) is not where it would be the other way round. By default the IK constraints are solved first, then the path constraints, then the transform constraints, each in the order of its list.

solve_order chooses another order: identifiers of constraints of any kind, each once, solved in that order. A constraint it does not name is solved after those it names, in the default order. An identifier that is no constraint of the rig is refused.

Any constraint (ik, path_constraints, transform_constraints) may say "off": true: it is switched off. It keeps everything it says and its keys, and keeps its place in the order, but is not solved: its bones are where the pose and the constraints before put them. off is written only when it is true.

"transform_constraints": [
  { "id": "01JC0NSTRA1NT0000000000001", "name": "first", "bones": ["…"], "target": "…", "off": true },
  { "id": "01JC0NSTRA1NT0000000000002", "name": "second", "bones": ["…"], "target": "…" }
],
"solve_order": ["01JC0NSTRA1NT0000000000002", "01JC0NSTRA1NT0000000000001"]

Here the second is solved first, and the first not at all.

Springs are not constraints: they swing after all the constraints are solved.

Bones and constraints of some skins

A bone, an IK constraint, a path constraint or a transform constraint may say skins: the identifiers of the skins that have it. It is there only while one of them is shown, so that one skeleton holds the cape of one costume and the tail of another. With no skins, it is always there, as before.

A bone that is not there carries nothing that is drawn: the slots on it, and on every bone under it, draw nothing. A constraint that is not there is not solved, as if it were switched off. The skin shown is the game's choice, as for its images; with no skin shown, nothing that names skins is there.

"bones": [
  { "id": "…", "name": "head" },
  { "id": "01JC0BEARD0000000000000001", "name": "beard", "parent": "…", "skins": ["01JC0W1ZARD000000000000001"] }
]

A skin named that is not a skin of the rig is refused. Since 0.27.

Folders

A folder groups pieces of one bone, or constraints, under a name, for the one who rigs: the tree of the editor shows it, folded or not. Each has an id, a name, and either a bone, the bone whose pieces it holds, with slots, identifiers of slots on that bone, or no bone, with constraints, identifiers of constraints of any kind. A slot or a constraint is in one folder at most; a slot of a folder that is not on its bone, an identifier that is not there, or one in two folders, is refused.

"folders": [
  { "id": "01JFD0000000000000000000A1", "name": "held", "bone": "…", "slots": ["…", "…"] }
]

Nothing a runtime plays depends on a folder. The editor moves the pieces of a folder as one in the draw order, in the setup pose (the order of slots) and in the keys of draw_order, which still name every slot: a runtime reads the order as it always did. Since 0.29.

Tracks mixed

This changes nothing in the files: it is how a runtime mixes the animations it plays, which every runtime of pantin does alike (pantin_runtime::Player). A game plays animations on tracks, laid one over the other, the first at the bottom, from the setup pose:

  • A track changes what its animation has keys for, the share weight of the way from what the tracks under it gave: a rotation the short way around, an attachment, a sequence and the draw order taken once the weight is half or more.
  • An additive track adds instead what its animation changes from the setup pose, by its weight: its animation is applied to the setup pose, and each difference is added over what the tracks under it gave. A rotation, a position, a shear, the offsets of the vertices of a mesh and the mixes of the constraints are added; a scale is multiplied by the ratio of what the animation gives to the setup, taken the share weight of the way from 1. What can only be shown (the attachment, the colours and the sequence of a slot, the draw order) is taken as on any track. A nod on an additive track over a walk turns the head a little more than the walk does.
  • A track that fades from one animation to the next mixes the two by the share of the fade done, then lays the result as above.

Golden values, which a test of the runtime holds: a bone set up at rotation 30, x 5 and scale_x 2. Track 0 plays a walk that keys a rotation of 20 and a scale of (1.5, 1); track 1, at the weight 0.5, plays a nod that keys a rotation of 10, a translation of (4, 0) and a scale of (3, 1).

Track 1 rotation x scale_x
additive 30 + 20 + 10 × 0.5 = 55 5 + 4 × 0.5 = 7 2 × 1.5 × (1 + (3 − 1) × 0.5) = 6
not additive 50 + (40 − 50) × 0.5 = 45 5 + (9 − 5) × 0.5 = 7 3 + (6 − 3) × 0.5 = 4.5

From the versions before

Every version since 0.4 is read and migrated, as the bundle says for every file of pantin; a project newer than the application is refused, the message naming its version and the last one read.

The version 0.36 was this format with no sound on events. The version 0.35 was this format with no linked meshes (link). The version 0.34 was this format with paths carried by the bone of their slot alone, and path constraints with no position_mode, spacing_mode or rotate_mode. The version 0.33 was this format with no sliders, neither in the rig nor in animations. The version 0.32 was this format with transform constraints in the world only, none relative or driven: no space, relative or drives. The version 0.31 was this format with springs that have no mass and no mix, and no springs in animations. The version 0.30 was this format with IK constraints that neither soften, stretch nor compress, and no ik in animations. The version 0.29 was this format with no inverse, convex or weights on clips. The version 0.28 was 0.29 without folders. The version 0.27 was 0.28 without trim, rotate, scale, tight and per_skin in [pack]. The version 0.26 was 0.27 without skins on bones and constraints. The version 0.25 was 0.26 without solve_order and off: its constraints are solved in the order of their kinds, none switched off. The version 0.24 was 0.25 without psd in the manifest. The version 0.23 was 0.24 without the keys flip of a bone. The version 0.22 was 0.23 without the inherit value no_scale_or_reflection. The version 0.21 was 0.22 without light: a project of 0.21 is read with the normal maps made as they are by default. The version 0.20 was 0.21 without guides. The version 0.19 was 0.20 without offsets. The version 0.18 was 0.19 without markers. The version 0.17 was 0.18 without looping: a project of 0.17 is read with no animation said to loop. The version 0.16 was 0.17 without the gravity of the skeleton and the gravity, inertia and skeleton_inertia of springs: a project of 0.16 is read with none of them, so with no gravity and all its inertia. The version 0.15 was 0.16 without clips, 0.14 was 0.15 without sequences, 0.13 was 0.14 without points, 0.12 was 0.13 without the dark colour and the blend mode of slots, 0.11 was 0.12 without transform constraints, 0.10 was 0.11 without the settings of the atlas (pack), 0.9 was 0.10 without the draw order in time, and 0.8 was 0.9 without timelines of vertices.

The version 0.7 had its paths in a list of their own, paths, each with an id, a name, the slot that carried it, its points and closed, and a path constraint named its path. A project of 0.7 is read with each path made an attachment of its slot, under its name and its identifier, in the skin default, which is made when it is not there; a slot that showed nothing shows its path; a path constraint names the slot of its path.

The version 0.6 was 0.7 without paths, 0.5 was 0.6 without slot timelines, and 0.4 was 0.5 without springs. The schemas of all of them are still beside this page. A project of any of them is read as it is, and written back as 0.37 the next time it is saved. A file that says it is of a version before and holds what came after it is refused.

From a file of the format before

A .pantin.json of version 0.1, 0.2 or 0.3 is turned into a project without losing anything: the skeleton and the animations of the project are the same, which a test holds for every example of the repository. Each thing gets an identifier made from what it was named by, so the same file always gives the same project.