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.