This page is docs/format/deform.md of the repository, as it is on main.
The pantin deform format, version 0.1
The parameters of a character are numbers that deform its meshes: a head that turns, a mouth that
opens, a chest that breathes. A game, or the graph of states, sets them; they are not keys in time.
For each key of a parameter, at one of its values, the shape of some meshes: an offset for each
vertex. Between two keys the shapes are blended; the shapes of all the parameters are added, and
added to what the keys of the vertices of an animation give. They are kept in deform.json, a file
of their own in the folder of a project, beside rig.json. The Deform workspace
writes it. A project with no parameter has no deform.json.
This page says what the file means. The same structure is given to machines by the JSON Schema
beside it, pantin-deform-0.1.schema.json. The deform format has
version numbers of its own, apart from those of the project. A field the format does not know is
refused, and so is a file in another version.
{
"format_version": "0.1",
"parameters": [
{
"id": "01JB1Q8W3N5R7T9V2X4Z6B8D0F",
"name": "turn",
"min": -1,
"max": 1,
"default": 0,
"keys": [
{
"at": 1,
"shapes": [
{
"slot": "01JA9Z5T2M8V0D3H6K1P4X7C9B",
"mesh": "01JA9Z6Y0B4N7QW6S8C2E1RJ3K",
"offsets": [[0, 0], [8.5, 0], [12, 0], [8.5, 0], [0, 0]]
}
]
}
]
}
]
}
| Field | Meaning |
|---|---|
format_version |
"0.1". |
parameters |
The parameters, each named once. |
id |
The identifier of the parameter, a ULID that never changes. |
name |
What a game and the graph of states call it. A number of the graph of the same name sets it. |
min, max |
Its smallest and its largest value; min is less than max. A value outside is taken to the nearest end. |
default |
The value it rests at, between min and max. There nothing is deformed, unless a key is there. |
keys |
In the order of their values, each once, between min and max. |
at |
The value of the parameter the key is for. |
shapes |
The shapes of the meshes at that value; a mesh a key does not name is not moved by it. |
slot |
The slot, by its identifier in rig.json. |
mesh |
The mesh, by the identifier of its entry in a skin of rig.json. The shape moves it while its slot shows it. |
offsets |
An offset [x, y] for each vertex of the mesh, in its order, in the space of each bone that carries the vertex: as the keys of the vertices of an animation (deforms of the project), added to the place each bone gives it before the bones carry it. |
Blending
For a value v of a parameter, taken within min and max:
- its keys are those of the file, and one more at
defaultwith no shape when no key is there: the shapes grow from nothing at rest to what each key says; - at the value of a key, the shapes of that key; before the first key or past the last, those of that key;
- between two keys at
aandb, each offset is(1 - t) × the first + t × the second, witht = (v - a) / (b - a), a mesh missing from a key counting as no offset.
The offsets of all the parameters are added, mesh by mesh, then added to those the animation keys
give the mesh shown by its slot. A game that sets no value has each parameter at its default.