pantin

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.