pantin

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 default with 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 a and b, each offset is (1 - t) × the first + t × the second, with t = (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.