Animations

Animations are the EF-JSON half of the pipeline. They live in separate files from the mesh and pose the player’s biped bones while an item is worn. You only need one when an item forces a pose — a collar or gag that just follows the body via skinning needs no animation file at all.

Meshes are NOT made here

Animations are exported with the bundled Epic Fight JSON addon (io_scene_minecraft_json). Meshes use Blender’s built-in glTF 2.0 (.glb) exporter — a different tool. See Overview.

Animation clip types

The constructor’s 5th token names a Java animation class. Pick by what the clip is for.

✅ Available StaticAnimation is the type you author for datapack content — living_motions bindings, overlays, and idle/walk/struggle loops. It is the recommended default and the only type any bundled clip uses. (The base locomotion loops are not shipped on a clean build — author your own.) Unless you have a specific reason, write ...rig.anim.types.StaticAnimation.

✅ Available MovementAnimation is a StaticAnimation subclass for locomotion gaits — WALK / RUN / SNEAK / SWIM. Its playback speed tracks the entity’s actual movement speed, so the feet stay planted instead of sliding when the player moves slower or faster than the clip’s authored cadence (the foot-slide fix). Write ...rig.anim.types.MovementAnimation as the constructor’s 5th token for a gait loop; everything else about the clip (the constructor tokens, the properties block) is the same as StaticAnimation. The in-game pack editor writes this class for you when you bind a WALK/RUN/SNEAK/SWIM gait — see Animating restraints, rule 9.

✅ Available ActionAnimation is usable as a one-shot role clip. You can point any one-shot at one — the item JSON’s animations.on_equip / on_unequip fields (see Item JSON) and a synced-action role clip accept any registered clip id; if it resolves to an ActionAnimation, its action-specific properties apply.

One-shots — equip/unequip and gameplay events (capture grab, death, struggle, leash yank) — play to all viewers, including the affected entity itself, so everyone sees the same clip. Datapack authors reach this through synced actions & events. The built-in gameplay-event actions currently fire to placeholder clip ids that resolve to empty (no visible pose) until an artist authors them — see synced actions and Planned & partial.

❌ Planned AttackAnimation and MainFrameAnimation are still inert combat stubs inherited from Epic Fight — they provide no behaviour beyond a plain pose clip. Don’t author them.

Position is server-owned — clips never move the entity

Clips never move the entity through the world (the COORD property family is unsupported by design): the server owns the entity’s position. Scripted anchored movement — a takedown that drags two entities along a path — is done with coop actions (see Coop actions), not by clip root motion.

• living_motions bindings (IDLE/WALK/STRUGGLE/…) play per-tick from gameplay state.
• One-shots — equip/unequip and gameplay events (capture, death, struggle, leash-yank) — play on all viewers, including the affected entity itself. Equip/unequip authoring is the on_equip / on_unequip fields on Item JSON; gameplay-event one-shots bind a synced action in action_events.json. The built-in gameplay-event actions currently use placeholder clip ids with no authored clip, so they show no visible pose until an artist authors them.

The constructor block (required, hand-added)

🔧 Manual / tool-gap An exported clip is not loaded by file path. Each animation JSON must carry a top-level constructor block that registers it under a namespace:id the item JSON references. The Blender addon never emits this block — you add it by hand (one line). Without it the loader logs “No constructor information has provided” and the clip never registers (the item silently falls back to vanilla motion).

{
  "constructor": {
    "invocation_command": "(0.15#F,true#Z,tiedup:my_cuffs_idle#java.lang.String,tiedup:biped#com.tiedup.remake.rig.armature.Armature)#com.tiedup.remake.rig.anim.types.StaticAnimation"
  },
  "format": "ATTRIBUTES",
  "animation": [ /* the addon-exported per-bone tracks go here */ ]
}

Read the invocation_command as the constructor arguments of StaticAnimation(float transitionTime, boolean isRepeat, String path, Armature armature):

Token	Meaning
0.15#F	transition time in seconds (0.15 = 3 ticks; keep the default unless you have a reason)
true#Z	loop? true for idle/walk/struggle cycles, false for one-shots (equip/unequip)
tiedup:my_cuffs_idle#java.lang.String	the registry id — this is what the item JSON’s living_motions references
tiedup:biped#...Armature	always tiedup:biped (the 20-bone skeleton)

Note

The id comes from the constructor, not the filename. The file’s path under assets/<ns>/animmodels/animations/ is conventional; the item resolves clips by the registered tiedup:my_cuffs_idle id.

format: "ATTRIBUTES"

🔧 Manual / tool-gap Set "format": "ATTRIBUTES" explicitly. The single-file export only writes it when you picked the ATTR option; if it’s absent the loader defaults to MATRIX. The loader self-corrects per element, but stating it avoids surprises.

Each keyframe is { "loc": [x,y,z], "rot": [w,x,y,z], "sca": [x,y,z] } — local joint transforms relative to the bone’s rest pose (identity rotation [1,0,0,0] = no change). Author at 20 FPS (Minecraft ticks at 20 Hz); higher rates are de-duplicated to ticks and drop frames. Always set an explicit keyframe at frame 0.

Note

The loader applies the quaternion conjugate on read (it negates rot’s x/y/z). A Blender-exported clip already accounts for this and is correct as-is — only relevant if you hand-edit a quaternion.

LivingMotion bindings

An animation is the motion of biped bones during a motion state, not the motion of the item. The item JSON’s animations.living_motions maps each state to a clip. Covered in detail on Item JSON — the essentials:

• Bare string → FULL_BODY: "IDLE": "tiedup:my_cuffs_idle" replaces the whole-body motion.
• Object with joints → OVERLAY: drives only the listed joints; the rest keep the global motion. This is what a partial restraint wants (arms posed, legs still walk). Up to 4 overlays stack; the higher pose_priority wins a contested joint.

The mode you pick — and, for an overlay, which joints you list — is the single most consequential decision when authoring a restraint. The next section, FULL_BODY vs OVERLAY, is the deep dive.

Vanilla EF motions (always available): IDLE WALK RUN JUMP FALL SNEAK SWIM (plus SIT/KNEEL/SLEEP/FLOAT/LANDING_RECOVERY, mostly NPC-only or unselected — see the animation list).

TiedUp custom motions ✅ Available bindable by name:

POSE_DOG  POSE_FURNITURE_SEAT  POSE_KNEEL_BOUND  STRUGGLE  POSE_SLEEP_BOUND

No `*_BOUND` locomotion motions

A bound entity plays the plain WALK / SNEAK / FALL base, and the restraint look is a per-item arm OVERLAY on top. STRUGGLE is the sustained writhe while the struggle minigame is active. Bind your bound-walk arm overlay to plain WALK, not a *_BOUND motion — see the animation list.

❌ Planned POSE_UNCONSCIOUS is bindable but not selectable yet — no trigger selects it, so binding a clip to it does nothing today. Do not author for it.

FULL_BODY vs OVERLAY: the binding mode ✅ Available

Every living_motions value carries a fusion mode that decides how the clip combines with the global motion the engine is already playing for that state. There are exactly two modes, and the JSON shape you write picks one:

JSON form	Mode	What it does
"IDLE": "ns:clip" (bare string)	FULL_BODY	Replaces the whole-body motion. The clip becomes the base layer for that state — every joint the clip animates is driven by it, every joint it leaves at rest sits at the clip’s rest pose. The global IDLE/WALK is gone.
"IDLE": { "animation": "ns:clip", "mode": "OVERLAY", "joints": [...] }	OVERLAY	Composes on top of the global motion. The clip is routed to a composite layer above the base, and only the joints you list in joints are surfaced. Everything else keeps doing the global motion (arms posed, legs still walk).

Pick FULL_BODY when the restraint dictates the entire silhouette and you don’t want the underlying locomotion bleeding through — a hogtie, a full sack, a kneel. Pick OVERLAY when the restraint only governs part of the body and you want the rest to keep animating normally — cuffs that lock the wrists while the player still walks, a collar that tilts the head while everything else is free.

Joint masking: the crux of OVERLAY ✅ Available

This is the single point that trips up every first overlay. An OVERLAY only surfaces the joints listed in its joints array. Those are the joints it keeps; every other joint is masked, and on a masked joint the base motion (the layer below) shows through unchanged. For each joint in the list the overlay’s pose replaces the base’s; for every joint not in the list, the base pose renders.

The Root-only-placeholder trap — an overlay that lists the wrong joints renders nothing

The joints your clip animates and the joints you list must overlap, or the overlay surfaces nothing. Two distinct ways to render an empty overlay:

1. You listed joints the clip doesn’t animate. The mask keeps Hand_R, but the clip only has a Chest channel → the kept joint has no pose to surface, and the animated joint is masked out.
2. The clip animates only non-listed joints (the classic case: a placeholder clip that only keyframes Root). Every joint it drives is masked away; nothing surfaces.

A one-time WARN is logged — “Overlay animation … animates NONE of its masked joints … — it will render nothing (the base motion shows through). … a Root-only placeholder cannot surface through an OVERLAY mask.” If your overlay does nothing, this is the first log line to grep for.

The rule: to affect a body part with an overlay, that body part’s joint must be in joints AND the clip must animate it. To pose the torso, Chest (or whichever torso joint) must be in the list — listing only the arms will never move the torso even if the clip keyframes it.

Tip

Joint names are validated at equip time (the armature isn’t available at /reload). An unknown name is dropped from the mask with a deduplicated WARN; if every listed joint is unknown the whole binding is skipped and the base motion just keeps playing — fail-soft. So a typo silently narrows or voids your overlay rather than crashing; watch the log.

Contested joints & stacking: winner-takes-the-joint ✅ Available

Several overlays can ride the same motion at once — armbinder arms and a collar head both on IDLE, for instance. Up to 4 overlays stack on one motion. The higher-pose_priority overlay wins a contested joint.

On a joint two overlays both drive, the composition is not a blend — it is winner-takes-the-joint. The highest-priority overlay that animates-and-keeps that joint wins it outright; the lower overlay’s value for that joint is discarded. There is no additive averaging.

Two restraints on the same joint do NOT blend

If a wrist-binder (pose_priority 30) and a separate arm-cuff (pose_priority 10) both list Hand_R, the wrist-binder’s Hand_R pose wins completely on every tick the cuff is also equipped — the cuff’s Hand_R contribution is thrown away, not averaged in. Two systems fighting for one joint is resolved by priority, period. If you want both to be visible, give them disjoint joints lists.

Slot cap — the 5th overlay on a motion is dropped

Only 4 composite slots exist per motion. If more than four overlays compete for the same LivingMotion, the engine keeps the top-N by pose_priority and drops the lowest-priority surplus, each with a WARN — “N overlay animations stack on motion M but only 4 composite slots exist — dropping lowest-priority overlay …”. In practice four simultaneous partial restraints on one motion is already extreme; the cap is a guard rail, not a budget to plan around.

The base-layer dependency ⚠️ Partial

An OVERLAY is a layer on top of a base motion — it needs a base motion to exist underneath, or there is nothing for the unmasked joints to show. For the standing/idle states this is fine: the base is vanilla IDLE or a FULL_BODY bound idle, so unmasked joints have something to do.

For a walking bound entity, bind the restraint as a per-item arm OVERLAY on the plain WALK base — the legs cycle on the real walk base and only the arms are re-posed. The shipped armbinder does exactly this: its WALK overlay keeps the 8 arm-chain joints and lets the leg walk cycle show through.

Bind bound-walk to plain WALK, as an arm overlay

Bind your restraint’s walk pose as an OVERLAY on WALK that lists only the arm joints — the legs keep the base WALK cycle and never slide. Reserve FULL_BODY for a state where the restraint genuinely owns the entire silhouette (a hogtie, a full sack). The base WALK clip is not shipped on a clean build (licensing) — author it.

When does any of this play? The render gate (brief) ✅ Available

Overlays (and all rig poses) only render when the player is actually drawn through the RIG biped instead of the vanilla model. A player renders via the rig only when bound (wearing any bondage item) or seated on a furniture entity; a free, unseated player is plain vanilla and no living_motions binding is consulted. The rig is the same player skin on the rig armature — not a different character model — so the swap is invisible apart from the new posing. The bound-or-seated gate is player-only: TiedUp NPCs are always rig-rendered.

Defining a new LivingMotion ✅ Available

The motions above (IDLE, STRUGGLE, …) are built-in Java enum values. You can also define a brand-new motion from a datapack — no Java, no recompile. Drop a JSON file in:

data/<ns>/tiedup/living_motions/<name>.json

The motion’s id is derived from the file path, exactly like a clip’s registry id is derived from its constructor: data/mymod/tiedup/living_motions/orgasm_shake.json registers mymod:orgasm_shake. There is no id field inside the file — the path is the id.

{
  "description": "Orgasm shake shiver — fired on the VX reaction state",
  "category": "vx_reactions"
}

Field	Type	Req?	Notes
description	string	required	Human-readable label, surfaced in logs. A file missing this (or with a non-string value) is skipped with a WARN; the rest of the batch still loads.
category	string	optional	Editorial grouping only (e.g. locomotion, restraint, vx_reactions). Has no runtime effect.

Defining is NOT binding — and a definition alone does nothing visible

This file only registers the motion name so the engine knows it exists. It does not attach any pose, and it does not select itself. To make an item pose the body during your motion you still bind a clip to it in the item JSON’s animations.living_motions map (see LivingMotion bindings above and Item JSON):

"animations": {
  "living_motions": {
    "mymod:orgasm_shake": "mymod:orgasm_shake_clip"
  }
}

And separately, something has to switch the entity into that motion state at runtime. The built-in TiedUp motions are driven by bondage state; a freshly-defined custom motion has no trigger of its own unless your own code or another system sets it. A definition with no binding and no trigger is inert — it just reserves the name.

Cross-namespace and reload behaviour

• The full namespace:path is the dedup key, so mymod:orgasm_shake and tiedup:orgasm_shake coexist without collision.
• The listener runs on both sides of an integrated server and on the client resource reload — both share one JVM-wide motion registry, so there is no double-counting.
• A motion’s ordinal is stable for the JVM session but is re-assigned (in alphabetical scan order) after a server restart. All internal TiedUp consumers reference motions by ResourceLocation, never by ordinal, so this only matters if you persist an ordinal yourself — don’t.
• Re-/reloading a file with a changed description logs a WARN and keeps the original description until the next JVM restart (the ordinal is already committed).

The properties block

This is the biggest under-documented unlock. Add an optional top-level properties object alongside constructor / format / animation. Every key below is parsed at load time and consumed at runtime.

{
  "constructor": { "invocation_command": "(0.15#F,true#Z,tiedup:hogtie_idle#java.lang.String,tiedup:biped#com.tiedup.remake.rig.armature.Armature)#com.tiedup.remake.rig.anim.types.StaticAnimation" },
  "format": "ATTRIBUTES",
  "properties": {
    "fixed_head_rotation": true,
    "pose_modifier": { "type": "tiedup:joint_rotation_offset", "joint": "Hand_R", "pitch": 15.0 }
  },
  "animation": [ /* tracks */ ]
}

pose_modifier — per-joint nudges ✅ Available

Nudge individual joints on top of the keyframed pose, every tick, without re-exporting the clip. Three modifier types are registered:

"pose_modifier": {
  "type": "tiedup:chain",
  "modifiers": [
    { "type": "tiedup:joint_rotation_offset",    "joint": "Arm_R",  "pitch": 15.0, "yaw": 0.0, "roll": 0.0 },
    { "type": "tiedup:joint_translation_offset", "joint": "Hand_R", "x": 0.0, "y": -0.05, "z": 0.0 }
  ]
}

Type	Fields	Notes
tiedup:joint_rotation_offset	joint (required), pitch / yaw / roll	Euler offset in degrees; missing axes = 0.
tiedup:joint_translation_offset	joint (required), x / y / z	Translation offset; missing axes = 0.
tiedup:chain	modifiers (array)	Runs the listed modifiers in order. Use for >1 nudge.

A single nudge can be the bare object (no chain needed):

"pose_modifier": { "type": "tiedup:joint_rotation_offset", "joint": "Hand_R", "pitch": 15.0 }

play_speed_modifier / elapsed_time_modifier ✅ Available

Reshape playback timing. Each takes a type dispatch:

"play_speed_modifier": { "type": "tiedup:constant_factor", "factor": 0.5 }

"elapsed_time_modifier": { "type": "tiedup:loop_section", "loop_start": 0.3, "loop_end": 0.8 }

play_speed_modifier also supports tiedup:linear_ramp; elapsed_time_modifier supports a loop_section (seconds). factor: 0.5 plays the clip at half speed.

no_physics / fixed_head_rotation ✅ Available

"no_physics": true,
"fixed_head_rotation": true

• no_physics — sets entity.noPhysics while the clip plays and restores it on end (the player passes through blocks, e.g. a sinking/struggling pose).
• fixed_head_rotation — locks the head to the body instead of tracking the look direction — ideal for hoods or fully-immobilised poses.

Events: on_begin / on_end / tick_events ✅ Available

Fire actions when the clip starts, ends, or crosses a time. on_begin / on_end accept either a bare action list or { "actions": [...], "side": "..." }:

"properties": {
  "on_begin": [
    { "type": "tiedup:play_sound", "sound": "minecraft:block.chain.place", "volume": 0.8 }
  ],
  "tick_events": [
    { "frame": 0.5, "actions": [
        { "type": "tiedup:spawn_particle", "particle": "minecraft:smoke", "count": 5, "offset_y": 1.2 }
    ]},
    { "start": 1.0, "end": 2.0, "actions": [
        { "type": "tiedup:apply_effect", "effect": "minecraft:slowness", "duration_ticks": 40, "amplifier": 1 }
    ]}
  ]
}

A tick_events entry uses frame (fire once when elapsed time crosses it) or start + end (fire every tick within the window) — both in seconds. Optional side is CLIENT, SERVER, LOCAL_CLIENT (only the owning player’s own client) or BOTH (default).

The 4 action types:

Action	Fields	Notes
tiedup:play_sound	sound (required), volume (1.0), pitch (1.0), category (neutral)	Server-authoritative broadcast. Unknown sound id → WARN + skip.
tiedup:spawn_particle	particle (required), at, count (1), speed (0.0), offset_x/y/z (0.0)	Client-side. See the at caveat below.
tiedup:apply_effect	effect (required), duration_ticks (required), amplifier (0), ambient, show_particles, show_icon	Server-side.
tiedup:damage_entity	amount (required), source (GENERIC)	Server-side.

Server-side actions are singleplayer-only

🖥️ Client / singleplayer only apply_effect, damage_entity and play_sound run on the server side, but on a dedicated server the animation is never ticked (the server never runs the animation timeline). They fire in singleplayer/integrated only. A “slowness while struggling” clip will silently do nothing on a multiplayer server. Particle spawns are client-side and work everywhere the player is rendered.

Note

spawn_particle’s at: "<joint>" is cosmetic — ⚠️ Partial the joint name is validated but the particle always spawns at the entity origin (joint→world transform is a TODO). count, speed and the offset_* fields work.

Unsupported properties (skipped with a warning)

✅ Available Some property keys have no datapack effect — they are skipped with a WARN, and the rest of the clip still loads and applies normally. Authoring one will not crash your clip, but the property itself does nothing.

These keys are no-ops — skipped with a WARN

The following are skipped (WARN + ignored), never applied:

• COORD, COORD_SET_BEGIN, COORD_SET_TICK, COORD_GET, DEST_LOCATION_PROVIDER, ENTITY_YROT_PROVIDER, DEST_COORD_YROT_PROVIDER — the world-movement / action-coord family. Unsupported by design: the server owns the entity’s position, so a clip cannot move the entity through the world (see Animation clip types above — anchored movement is done with coop actions).
• IK_DEFINITION, BAKED_IK_DEFINITION, TRANSITION_ANIMATIONS_FROM / _TO, ON_ITEM_CHANGE_EVENT — no datapack effect; these load only via a dedicated sub-file path, not the properties block.

reset_living_motion parses cleanly but has no runtime consumer — a silent no-op.

ActionAnimation properties that DO apply

The ActionAnimation-specific properties below take effect when an ActionAnimation clip is loaded (see the clip-types caveat about triggering). If you author them, type the serialized key exactly as shown:

• stop_movements — zero the entity’s delta-movement at clip start.
• revmoe_delta_move — remove the entity’s delta-movement at clip start. The serialized key is literally revmoe_delta_move (type it exactly); remove_delta_move is not recognised.
• move_vertically — also correct the Root joint on the Y axis during the transition (otherwise only X/Z are anchored).
• no_gravity_time — flat list of begin, end second-pairs (even length) where gravity is off.

Worked example: a cuffs idle overlay

1. Animate in Blender: keyframe the Hand_R / Hand_L channels (the same joints you will list below) so the clip actually drives them — pose the wrists subtly together, ~2 s, 20 FPS, keyframe at frame 0.
2. Export with the EF-JSON addon (File > Export > Animated Minecraft Model (.json)), format ATTR, into assets/<ns>/animmodels/animations/.
3. Hand-add the constructor block and format: "ATTRIBUTES".
4. Bind it in the item JSON as an OVERLAY on the hand joints:

   "animations": {
     "living_motions": {
       "IDLE": {
         "animation": "tiedup:my_cuffs_idle",
         "mode": "OVERLAY",
         "joints": ["Hand_R", "Hand_L"]
       }
     }
   }

5. /reload and equip — only the hands inherit the pose; the body keeps vanilla IDLE.

Tip

Joint names in joints are validated at equip time, not at /reload. A typo’d joint is dropped (with a WARN) when the item is worn — watch the log if a joint isn’t moving. If the clip keyframes joints you didn’t list (or you listed joints it doesn’t keyframe) the overlay renders nothing — see Joint masking for the WARN to look for.

Joint masks 🖥️ Client / singleplayer only

A joint mask is a named set of joints that a clip’s layer disables — the masked joints keep whatever the lower layer (or the base motion) is doing instead of being driven by the layered clip. It is the building block behind layered animation: an OVERLAY binding implicitly masks the joints it does not list, and a reusable mask lets several clips share the same “drive only these joints” definition.

Client-side only

The joint-mask registry is loaded by the client resource pipeline (it lives under assets/, not data/, and is registered in client setup). It is part of the resource pack, ships in the same pack as your meshes and clips, and has no server presence. On a dedicated server the masks are never read.

Define a mask in:

assets/<ns>/animmodels/joint_mask/<name>.json

The mask’s id is the last path segment, namespaced: assets/mymod/animmodels/joint_mask/upper_body.json registers mymod:upper_body. (Sub-folders are allowed but collapse to the filename — keep names unique within a namespace.)

{
  "joints": ["Chest", "Shoulder_R", "Arm_R", "Elbow_R", "Hand_R",
             "Shoulder_L", "Arm_L", "Elbow_L", "Hand_L", "Head"],
  "bind_modifiers": {
    "Chest": "keep_child_locrot"
  }
}

Field	Type	Req?	Notes
joints	array of strings	required	The joints the mask covers. Use the exact case-sensitive EF biped names — see Bones & regions.
bind_modifiers	object	optional	Maps a joint name (which must also appear in joints) to a bind-modifier name. A joint with no entry gets no modifier.

Bind modifiers

Only one bind modifier is registered:

Name	Effect
keep_child_locrot	Keeps the masked joint’s child bones in their lower-layer local position/rotation while the joint itself follows the layered pose — used to stop a child (e.g. a hand) from being dragged off when only its parent is re-posed.

Any other modifier name is silently ignored

bind_modifiers is looked up in a fixed table that contains only keep_child_locrot. A typo or any other string resolves to no modifier (null) — there is no error, the joint just gets the plain mask. Likewise, referencing a mask id that doesn’t exist falls back to the built-in none mask (an empty mask) rather than crashing — so a typo’d mask reference quietly masks nothing.

How a mask is referenced

A mask is not applied by the mask file itself — a clip’s layer sub-file points at it by id. In a layer’s masks array, each entry names a livingmotion and a type (the mask id; a bare name is prefixed with tiedup:). The special motion ALL sets the layer’s default mask:

"masks": [
  { "livingmotion": "ALL",      "type": "mymod:upper_body" },
  { "livingmotion": "STRUGGLE", "type": "mymod:arms_only" }
]

This pairs with the OVERLAY bindings above: an OVERLAY binding builds its mask implicitly from the joints list (the high-level “drive these joints” knob most items want), while a named joint-mask file is the lower-level, reusable primitive for hand-built layered clips that route through their own layer sub-file. Both produce the same joint mask the compositor reads — the joints-on-an-OVERLAY path is just the turnkey version.

Cloth physics 🖥️ Client / singleplayer only

An item can carry one or more verlet cloth strands — a cape flap, a dangling rope tail, a skirt panel, a collar pendant — that physically simulate instead of being baked into the mesh. You declare them in the item JSON with a top-level cloth key; no Java. Each strand is a small soft-body mesh anchored to a biped joint, simulated every render frame and resolved against a body-shaped collider so it drapes over the torso/arms instead of clipping through.

Cloth is client-side render only

The simulator and its render layer live entirely under client/ — cloth has no gameplay effect and no server presence. On a dedicated server the strands are simulated locally on each client that has the assets; nothing is synced. This is purely cosmetic motion.

There is no addon path to author the cloth mesh today

🔧 Manual / tool-gap The cloth JSON block is fully authorable, but the mesh it points at is not. A cloth mesh must be a soft-body rig JSON carrying a cloth_info block (see The cloth mesh below), and the bundled Epic Fight JSON addon cannot emit cloth_info. Until a tool ships, the only cloth mesh that exists is a maintainer-only dev asset. You can write a correct cloth block today, but it has nothing valid to point at — be aware before investing in the JSON.

The cloth block

Add cloth alongside model and animations in data/<ns>/tiedup_items/<item>.json. The value is either a single object (one strand) or an array of objects (several strands on the same item). Internally it is always a list, so going from one strand to many needs no migration.

{
  "type": "tiedup:bondage_item",
  "display_name": "Test Cloth Cape",
  "model": "tiedup:models/gltf/binds/straitjacket.glb",
  "regions": ["TORSO"],
  "cloth": {
    "mesh": "tiedup:layer/default_cape",
    "parent_joint": "Torso",
    "texture": "minecraft:textures/block/white_wool.png",
    "collider_preset": "BIPED",
    "gravity": 9.8
  }
}

Multiple strands — array form:

"cloth": [
  {
    "mesh": "mymod:layer/collar_leash",
    "parent_joint": "Chest",
    "texture": "mymod:textures/cloth/leash.png",
    "collider_preset": "BIPED"
  },
  {
    "mesh": "mymod:layer/collar_tag",
    "parent_joint": "Chest",
    "texture": "mymod:textures/cloth/tag.png"
  }
]

Field	Type	Default	Notes
mesh	RL	—	Required. The cloth-mesh asset id, resolved via the rig Meshes loader (not the .glb pipeline). Must carry a cloth_info block. Missing/unregistered at equip → that strand is skipped + warn-once (no crash).
parent_joint	string	—	Required, must be a string. The biped joint that drives the strand’s reference frame (e.g. Torso, Chest, Hand_R). Case-sensitive EF name. Resolved at equip; unknown joint → skip + warn-once.
texture	RL	—	Required. The texture the cloth render layer draws for this strand. Must be a full namespace:path. A strand missing a valid texture is dropped at parse — it does not fall back to the player skin.
collider_preset	string	BIPED	Which body-collider set to resolve cloth against. Only BIPED and BIPED_SLIM are defined (case-sensitive). Unknown value → defaults to BIPED + warn-once.
gravity	float	—	⚠️ Partial Parsed but currently ignored. Host gravity is global and there is no per-strand gravity hook yet, so this value is recorded and does nothing. Declare it for forward-compat only. A non-number value is warned and dropped (no throw).

The parser is fail-soft here too

cloth absent → no cloth, item unchanged. Value that is neither object nor array → WARN + ignored. A malformed element (missing mesh / parent_joint / texture, or a non-object array entry) → WARN + that element skipped, the rest still parse. If every element is malformed the whole cloth is treated as absent.

collider_preset values

Value	Use
BIPED	Default. OBB colliders fitted to the standard 4-pixel-arm (Steve) body — torso, arms, legs, head.
BIPED_SLIM	Slimmer arm colliders for the 3-pixel-arm (Alex) model.

The collider only stops cloth that uses shaping constraints; a strand built only of stretch edges passes through the body. That distinction is baked into the mesh, not the item JSON.

The cloth mesh 🔧 Manual / tool-gap

The mesh field does not point at a .glb. A cloth mesh is a rig soft-body JSON (the same loader as skinned item meshes — under assets/<ns>/models/…, registered with Meshes) that carries a cloth_info block describing the verlet particles, their pinned roots, and the stretch/shape/bend constraints. The format is the upstream Epic Fight verlet-mesh format.

Tool gap — you cannot make this mesh with the bundled addon

The bundled EF JSON addon exports pose clips and ordinary skinned meshes, but it does not generate the cloth_info block. There is no shipped tool that produces a valid cloth mesh today. Without cloth_info the soft-body check fails and the strand never starts (a silent no-op, not a crash). This is the single reason cloth is marked a tool-gap rather than fully available.

The only built-in cloth asset is a dev-only cape

The lone reference mesh, tiedup:layer/default_cape (used by the built-in test_cloth item and the F9 debug cape), is a maintainer dev asset that is gitignored and never shipped. On any normal install it is absent, so test_cloth resolves the mesh to null and the strand is silently skipped — the item renders with no cloth. That is the graceful-degradation path you will hit if you reference a mesh that doesn’t exist.

Runtime notes

• Per-player cap of 4. At most 4 item cloth strands simulate per player at once; beyond that, new strands are silently not started. (The F9 debug cape is exempt and never counts against this.)
• Multi-region items register once. An item occupying e.g. both TORSO and ARMS registers its strands a single time (deduped by item id), so it doesn’t burn the cap twice.
• parent_joint is the reference frame, not the skinning root. It tells the simulator which joint orients the strand in world space; which bones the vertices are weighted to is set by the mesh’s own skinning. So a single strand skinned across both Hand_R and Hand_L (a wrist-to-wrist leash) can use one cloth entry with parent_joint: "Chest" — you don’t need two strands for a bilateral piece.
• Client config toggle. Players can disable cloth physics entirely in the client config (RigCloth → enableClothPhysics, default on); both the simulator and the render layer respect it.