pantin

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

The pantin graph format, version 0.1

A character in a game is in one state at a time: it idles, runs, jumps, attacks. Each state plays an animation, and the game goes from one to another by setting parameters (a speed, a switch « on the ground », a trigger « jump »), the graph saying which way, when and over what crossfade. The graph of a character is kept in flow.json, a file of its own in the folder of a project, beside rig.json. The Flow workspace writes it, and only it: the other tools read it. A project with no graph has no flow.json.

This page says what the file means. The same structure is given to machines by the JSON Schema beside it, pantin-flow-0.1.schema.json. The graph format has version numbers of its own, apart from those of the project. As there, a field the format does not know is refused, and so is a file in another version.

{
  "format_version": "0.1",
  "parameters": [
    { "id": "01JAB0R7Q2W1H4S8K6D3F9M5XN", "name": "hello", "kind": "trigger" }
  ],
  "entry": "01JAB0S3C8V6N1T4P7K2R9X5QM",
  "states": [
    { "id": "01JAB0S3C8V6N1T4P7K2R9X5QM", "name": "idle", "animation": "01JA9Z7R1F5K2S9W4Y0D8N3M6Q", "at": [0.0, 0.0] },
    { "id": "01JAB0SX4M7B2Q9W5H1D8K3N6R", "name": "wave", "animation": "01JA9Z8H3D6P1V4S7X0B2N5K9T", "once": true, "at": [260.0, 0.0] }
  ],
  "transitions": [
    {
      "id": "01JAB0TB9K2X5N8R1D4W7Q3M6H",
      "from": "01JAB0S3C8V6N1T4P7K2R9X5QM",
      "to": "01JAB0SX4M7B2Q9W5H1D8K3N6R",
      "fade": 0.2,
      "conditions": [{ "parameter": "01JAB0R7Q2W1H4S8K6D3F9M5XN", "test": "fired" }]
    },
    {
      "id": "01JAB0TQ5W8D1K4N7R2X9M3B6H",
      "from": "01JAB0SX4M7B2Q9W5H1D8K3N6R",
      "to": "01JAB0S3C8V6N1T4P7K2R9X5QM",
      "fade": 0.3,
      "at_end": true
    }
  ]
}

The file

Field What it is
format_version "0.1".
parameters What the game sets. Default: none.
entry The state played first, by its identifier. Default: the first state.
states The states. Default: none.
transitions The ways between states, in the order they are tried. Default: none.

Each identifier is once in the file, each parameter and each state has its own name.

A parameter

Field What it is
id Its identifier, a ULID.
name What the game calls it.
kind number (by default), switch (on or off) or trigger (fired by the game, spent by the transition it lets through).
default Its value at first: a number, or for a switch 1 for on and 0 for off. Default: 0. A trigger starts unfired.

A state

Field What it is
id Its identifier.
name Its name.
animation The animation it plays, by the identifier of rig.json.
speed How fast: 1 (the default) at its own pace, 0 or more.
once true: played once and held on its last moment; by default it plays again and again.
at Where the Flow workspace draws it; a runtime reads past it.

A transition

Field What it is
id Its identifier.
from The state it leaves; left out for a transition from any state, which is never taken into the state it would leave.
to The state it goes to.
fade The seconds of the crossfade, 0 or more. Default: 0, at once.
conditions Tests of parameters, which must all hold: each a parameter by identifier, a test and a value. greater, less, equal, not_equal compare a number with value (default 0); on and off test a switch; fired a trigger.
at_end true: it waits for the animation of the state it leaves to reach its end: for a state played once, its last moment; for one that loops, the end of each lap.
event It waits for an event of that name, told by the animation of the state it leaves.
box It waits for an edge of a range of a box of hit.json: box, its identifier, and edge, start or end. Only a range whose events is true tells its edges.

What a runtime does with it

The graph starts in its entry state. Each time the game lets time pass, the animation of the state plays at its speed; then the transitions are tried in their order, those from the state and those from any state alike, and the first whose every part holds is taken: the state it goes to starts its animation from the beginning, crossfading from the one it leaves over fade, and the triggers its conditions tested are spent. At most one transition is taken each time. A trigger that no transition takes stays fired.

pantin_runtime::flow::Machine does this. A state whose animation is no longer in rig.json plays nothing, and a transition that waits for a box no longer in hit.json is never taken: pantin check names both.