Animating restraints — the contract

This page answers one question: “how do I make a restraint look right when the player moves?” It’s the decision-first starting point — read it before the deep Animations reference (the mechanics: export, the constructor block, the properties unlocks). Here we cover what to author and the handful of rules that keep it from silently doing nothing.

The one-sentence model

A restraint binds, per locomotion state (idle, walk, run, …), one animation clip. Each clip is either an OVERLAY (a pose on specific joints, with the rest of the body showing through) or a FULL_BODY clip (a whole-body animation that replaces the base for that state). That’s the whole contract.

The two kinds of clip

Every clip you bind is one of these two. Picking the right one is the single most consequential choice when animating a restraint.

OVERLAY — a pose on some joints

A pose masked to a joints list. It owns exactly those joints; the base animation shows through on every joint not listed. It reuses the base for the rest of the body. Use it for arm / hand / head / mouth / eye poses. Several overlays on different limbs compose freely.

FULL_BODY — a whole-body animation

A whole-body clip that replaces the base for that state. Use it when the restraint changes the gait itself — a restricted “walk a little”, a hop, a hobble. It becomes the base for that state, so it drives the whole body including movement. A FULL_BODY gait and an OVERLAY arm pose still compose.

They compose

OVERLAY and FULL_BODY aren’t either/or for the whole item. A hobble (FULL_BODY, legs/gait) and a wrist pose (OVERLAY, arms) can run on the same state at once — the FULL_BODY becomes the base, the OVERLAY rides on top of it.

The per-state shape

In the item definition you map each locomotion state to a clip under animations.living_motions. An OVERLAY is an object with a mode and a joints list:

"living_motions": {
  "WALK": {
    "animation": "ns:armbinder_walk",
    "mode": "OVERLAY",
    "joints": ["Shoulder_R", "Arm_R", "Elbow_R", "Hand_R",
               "Shoulder_L", "Arm_L", "Elbow_L", "Hand_L"]
  }
}

A FULL_BODY clip needs no joints (it owns the whole body) — write "mode": "FULL_BODY":

"living_motions": {
  "WALK": { "animation": "ns:hobble_walk", "mode": "FULL_BODY" }
}

Two more pieces live alongside living_motions:

• on_equip / on_unequip — item-level one-shot clips that play once when the item goes on or comes off.
• pose_priority — a top-level item field; a relative rank. When two worn restraints fight over the same joint, the higher pose_priority wins that joint.

Full schema lives next door

The exact field list, the equip/unequip details, and the worked end-to-end example are on Item JSON → the animations block and the Animations reference. This page is the contract; those are the schema.

The golden rules

Each rule below prevents a real, silent failure — the kind that produces no error, just a wrong look. Internalise these and most “why is my restraint not animating?” questions answer themselves.

1. POSE = OVERLAY, GAIT = FULL_BODY. A pose on a limb → OVERLAY masked to that limb. A change in how you walk / hop → FULL_BODY.

2. Always write "mode": "OVERLAY" for poses. If you omit mode, it defaults to FULL_BODY, and your arm clip will freeze the whole body (legs included) — with no error.

3. Keyframe exactly the joints you list, and copy joint names exactly — they’re case-sensitive (Arm_R, not Arm_r). A clip that doesn’t actually animate a listed joint renders nothing there (the base shows through); you only get a one-time log warning.

4. Never put Root in an overlay’s joints. Overlays don’t reconcile the root/hips — keep overlays to limb chains. Anything that moves the root must be FULL_BODY.

5. Own whole limb chains (Shoulder → Arm → Elbow → Hand together), so the seam between your overlay and the base lands at a near-static parent joint.

6. Bind your overlay to EVERY state the wearer can reach — IDLE, WALK, RUN, SNEAK, SWIM, FALL, JUMP (and STRUGGLE). Re-list the same clip per state. An armbound player with only IDLE/WALK bound will flash free arms when sprinting or swimming. (Some states are player-only — see the animation list before binding one on an NPC-only item.)

7. Keep co-equipped restraints’ joint lists disjoint (arms vs head vs legs). Two clips that keep the same joint do not blend — the higher pose_priority wins it outright.

8. Max 4 overlays per state. A 5th overlay on the same state is dropped (lowest pose_priority first), with only a log warning.

9. Gait clips speed-sync to movement automatically. When a WALK/RUN/SNEAK/SWIM gait is bound (the pack editor does this for you), its cadence follows the player’s actual speed (no foot-sliding). This is a property of the gait clip class, not just an editor feature — a hand-written JSON clip gets the same behaviour by targeting it (see Animations). Author the base WALK at vanilla walk pace and RUN at sprint pace; pair a slowed bound gait with the item’s movement-speed restriction so the steps match the distance travelled.

10. Iterate with F3+T (it reloads animation content), not /reload.

Rule 2 is the #1 silent trap

"mode": "OVERLAY" is not the default. Forgetting it turns your hand pose into a full-body freeze with no warning in the log. If a restraint locks the legs when it shouldn’t, check mode first.

Animation = look, not movement

Two separate dials, used together

The animation makes a restraint look right — arms pinned, a hobbled hop. The actual movement limit — slower walk, forced small jumps — is a separate gameplay setting on the item (see Item JSON → Movement style). They’re independent. Use both together: a hobble that looks like short steps should also be slowed, so the feet land where the body travels.

Quick smoke checklist

Run this before you produce a lot of art — it catches every rule above with five quick equips.

1. An arm OVERLAY on idle + walk + run + sneak + swim + jump — arms stay pinned in all of them, no pop. (Catches rule 6.)
2. A FULL_BODY restricted-walk gait — the body reads right and the feet don’t slide at normal speed. (Catches rules 1 and 9.)
3. A hop (FULL_BODY) — the body actually bounces. (Confirms FULL_BODY drives movement.)
4. Gag + arm cuffs + leg hobble worn together — all three apply at once. (Catches rules 7 and 8: disjoint joint lists, under the 4-overlay cap.)
5. A deliberately wrong joint name — confirm the warning shows in the log, so you can trust the log to catch your real typos later. (Catches rule 3.)

Where to go next

• The mechanics of exporting and registering a clip → Animations reference.
• The full per-state catalogue (which states exist, what’s shipped) → Animation list.
• The item schema these bindings live in → Item JSON.
• Build it without hand-writing JSON → In-game pack editor.