This page is docs/format/hit.md of the repository, as it is on main.
The pantin boxes format, version 0.1
The boxes of a character are what a game tests against each other: a fist that strikes, a body
that can be struck, a shape others cannot walk through. Each is a polygon carried by a bone, so
that it follows the character as it moves, and it is active always or on ranges of time of its
animations. They are kept in hit.json, a file of their own in the folder of a
project, beside rig.json. The Hit workspace writes it, and only it: the other
tools read it. A project with no box has no hit.json.
This page says what the file means. The same structure is given to machines by the JSON Schema
beside it, pantin-hit-0.1.schema.json. The boxes format has
version numbers of its own, apart from those of the project: one can change without the other.
As there, a field the format does not know is refused, and so is a file in another version.
{
"format_version": "0.1",
"boxes": [
{
"id": "01JA9Z6Y0B4N7QW6S8C2E1RJ3K",
"name": "fist",
"kind": "hit",
"bone": "01JA9Z5T2M8V0D3H6K1P4X7C9B",
"points": [[0, -5], [12, -5], [12, 5], [0, 5]],
"data": { "damage": 8, "knockback": 120 },
"ranges": [
{ "animation": "01JA9Z7R1F5K2S9W4Y0D8N3M6Q", "start": 0.2, "end": 0.35, "events": true }
]
},
{
"id": "01JA9Z8C6T0X3B7N1R5V9H2Q4L",
"name": "body",
"kind": "hurt",
"bone": "01JA9Z4E3P7Y1K5S9D2W6N0R8F",
"points": [[-14, -10], [30, -10], [30, 10], [-14, 10]],
"always": true
}
]
}
The file
| Field | What it is |
|---|---|
format_version |
"0.1". |
boxes |
The boxes, in any order. Each name and each identifier is once in the file. |
A box
| Field | What it is |
|---|---|
id |
Its identifier, a ULID, which never changes. |
name |
What the game calls it. |
kind |
hit (what strikes, by default), hurt (what can be struck) or push (what others cannot walk through). |
bone |
The bone that carries it, by the identifier of rig.json. |
points |
Its corners, three or more, each [x, y] in the space of its bone (x along the bone, y on its left, as for an image), in order around it. A game tests it as a convex polygon. |
data |
Numbers the game reads, by name: damage, knockback, a stun in frames, whatever it needs. Left out when there are none. |
always |
true for a box active whatever is played, like the hurtbox of a body. Left out when false. |
ranges |
Where it is active besides always. Left out when there are none. |
A range
| Field | What it is |
|---|---|
animation |
The animation, by the identifier of rig.json. |
start, end |
From when to when, in seconds from the start of the animation, both included: 0 ≤ start ≤ end. |
events |
true: the runtime tells an event when the range starts and when it ends, as it tells the events of an animation. Left out when false. |
What a runtime does with it
At a time of an animation, the boxes active are those that are always, and those with a range
of that animation around the time. Their corners are carried into the world by their bone, as
the corners of an image are. Played from one time to a later one, the ranges with events tell
their start and their end that fall between the two, in the order of time: a hit starts, a hit
ends. pantin_runtime::hit does both, and overlap tests two boxes.
A box whose bone is no longer in rig.json, or a range whose animation is no longer there, is
left out by the runtime and said by pantin check.