Synced actions & events

A synced action is the one unit a gameplay moment triggers to play a synchronized animation. When the server fires a capture grab, a death, a struggle, or a takedown, it looks up a synced action, then broadcasts the per-role clip to every viewer — including the entity it happened to — so everyone sees the same thing. The whole map of event → action → clip is datapack-authorable: no Java.

The system is wired; the default clips are EMPTY

✅ Available The plumbing is real and fires end-to-end — you can define your own synced actions, bind them to events, and the server will broadcast them. But 🔧 Manual / tool-gap TiedUp ships only placeholder clip ids for the built-in actions (e.g. tiedup:reaction.restrain.initiator, tiedup:reaction.flinch). Those ids are not backed by an authored clip, so they resolve to the empty animation — the broadcast fires, the gameplay logic runs, but you see no pose until an artist authors the real clip. So: the trigger path is available today; the default visuals are unauthored.

The model in one picture

gameplay event  ──action_events.json──▶  synced action id  ──synced_actions/<id>.json──▶  per-role clip(s)
 (closed enum)                            (datapack)                                       (broadcast S→C)

1. Server-authoritative gameplay code passes a gameplay event (a closed enum value).
2. action_events.json maps that event to a synced action id.
3. synced_actions/<id>.json defines the action — one or more roles, each naming a clip and (optionally) a waypoint path.
4. The server branches by shape:
   • clip-only (no role has waypoints) → for each role, broadcast its clip to every tracking client and the entity itself. Cosmetic only.
   • waypointed (any role has waypoints) → engage the position driver that anchors and moves both entities along the path (this is a coop / takedown — see Coop actions), and also broadcast the clips.

This works on a dedicated server (clients resolve and render the clip locally).

Defining a synced action ✅ Available

One JSON file per action:

data/<namespace>/synced_actions/<id>.json

The action id is the file name (without .json), keyed by its path: a file at data/mymod/synced_actions/struggle_kick.json registers the id struggle_kick. Actions reload on world load and on /reload, and are synced to clients.

A clip-only (cosmetic) one-shot

The common case: a single self-clip that plays on the affected entity. This is exactly the shape of the built-in struggle, hurt, lockpick_fail, … defaults (the shipped struggle.json):

{
  "duration_ticks": 1,
  "proximity_gate": 0.0,
  "priority": "MIDDLE",
  "roles": [
    { "role": "self", "clip": "tiedup:reaction.struggle" }
  ]
}

A two-role clip-only action (e.g. an initiator + target restrain pose) lists two roles, neither with waypoints — the server fans out one broadcast per entity. This is the shape of the shipped capture_grab.json / enslave.json / recapture.json / punish.json, which all share the one reaction.restrain clip pair:

{
  "duration_ticks": 1,
  "proximity_gate": 0.0,
  "priority": "HIGHEST",
  "roles": [
    { "role": "initiator", "clip": "tiedup:reaction.restrain.initiator" },
    { "role": "target",    "clip": "tiedup:reaction.restrain.target" }
  ]
}

Top-level fields

Verified field-by-field.

Field	Type	Required?	Notes
duration_ticks	int ≥ 1	required	Session length in server ticks (20 = 1 s). 1 is the conventional value for an instant clip-only one-shot; a waypointed action uses the real duration. Values ≤ 0 are rejected.
proximity_gate	double	required	Max start distance (blocks) for waypointed actions. Ignored for clip-only defs (no position driving means no proximity check).
cinematic_camera	bool	optional (default false)	Behind-player cinematic for waypointed actions when no camera block is present. See Coop actions → Cinematic camera.
camera	object {x,y,z}	optional	Anchor-local cinematic camera offset (doubles). Waypointed actions only.
priority	string	optional (default MIDDLE)	One of LOWEST / LOW / MIDDLE / HIGH / HIGHEST. Informational only; it does not change where the clip renders.
roles	list	required	1+ roles. See below.

Roles

Each entry in roles:

Field	Type	Notes
role	"initiator" | "target" | "self"	Lowercase. self and initiator both map to the initiating entity; target maps to the second entity (the one passed as the target). Use self for single-entity one-shots (death, hurt).
clip	string	A full ResourceLocation (e.g. "mymod:grab_initiator") naming the per-role visual clip. Should match a registered clip’s constructor id for a visible pose — see Animations. An unmatched id is not rejected: it falls back to the empty animation (you’ll see a one-time warning in the log — see the caution below).
waypoints	list (≥ 2)	Optional. Omit (or leave empty) → the role is clip-only (cosmetic, no movement). Present → the role drives anchored position and engages the coop position driver; the full list of constraints is documented on Coop actions.

Clip-only vs waypointed — the one rule

A def is waypointed (position-driving) iff any role declares a non-empty waypoints list; otherwise it is clip-only. That single predicate decides the whole routing: clip-only defs never touch the position driver, waypointed defs do. A waypointed def still requires both initiator and target roles (the driver moves the pair); a clip-only def may have 1 or 2 roles or a single self role.

A typo in `clip` fails SILENTLY (the EMPTY-animation path)

If a clip id doesn’t resolve to a registered clip — a typo, a missing clip, or a clip whose constructor block was never added — it resolves to the empty animation: the broadcast still fires and (for waypointed defs) the position math still drives the entities, but the entity shows no pose. This is also what every built-in default clip does today (the shipped clip ids are placeholders with no authored clip). You get a one-time warning in the log, no error.

Binding an event ✅ Available

Gameplay code does not name a synced action directly — it fires a gameplay event, and action_events.json maps events to action ids. One table file per namespace:

data/<namespace>/tiedup/action_events.json

{
  "tiedup:capture_grab": "tiedup:capture_grab",
  "tiedup:struggle":     "mymod:struggle_kick",
  "tiedup:hurt":         "mymod:hurt_flinch"
}

The key is a gameplay event; the value is a synced-action id (resolved by its path against the registry). To re-skin a built-in event, point its key at your action id — e.g. bind tiedup:struggle to mymod:struggle_kick and the struggle one-shot plays your action instead.

The bindable events are a closed set

✅ Available Event keys are a fixed, mod-defined enum — you cannot invent new gameplay events from a datapack (that would need Java to fire them). Every key is validated against this set, and any unknown key is rejected (skipped, with a warning in the log). These are the exact built-in keys (a fixed set):

Event key	Fired when	Built-in default action → clip(s)
tiedup:capture_grab	A kidnapper grabs / captures a target	capture_grab (2-role) → reaction.restrain.{initiator,target}
tiedup:enslave	A captured target is enslaved	enslave (2-role) → reaction.restrain.{initiator,target} (same pair)
tiedup:recapture	A fled target is recaptured	recapture (2-role) → reaction.restrain.{initiator,target} (same pair)
tiedup:punish	A captor punishes a target	punish (2-role) → reaction.restrain.{initiator,target} (same pair)
tiedup:hurt	A bound entity is hurt / shocked	hurt (self) → reaction.flinch
tiedup:lockpick_fail	A lockpick attempt fails	lockpick_fail (self) → reaction.flinch (same flinch clip)
tiedup:struggle	A struggle beat fires (start edge or shock-collar interrupt)	struggle (self) → reaction.struggle
tiedup:leash_yank	A leash is yanked (edge-detected, fires once per pull)	leash_yank (self) → tiedup:leash_yank — a shipped self-role def whose clip id is an unauthored placeholder (resolves to the empty animation)
tiedup:death	A bound entity dies	death (self) → tiedup:death — a shipped self-role def whose clip id is an unauthored placeholder (resolves to the empty animation)

The capture flows and the flinch flows SHARE clips

capture_grab / enslave / recapture / punish all use the single reaction.restrain.{initiator,target} pair; hurt and lockpick_fail share reaction.flinch; struggle uses reaction.struggle. leash_yank and death each ship a self-role synced_actions/ def (leash_yank.json → tiedup:leash_yank, death.json → tiedup:death); the def resolves and the broadcast fires, but its clip id is an unauthored placeholder. Every shipped def points at a placeholder clip id with no authored clip, so the visible result is currently nothing — author the tiedup:reaction.* (and tiedup:leash_yank / tiedup:death) clips, or bind these events to your own actions, to make them visible.

Fail-soft loading

• An unknown event key in action_events.json is rejected (skipped — check the log); the rest of the table still loads.
• A binding whose action id has no def no-ops at trigger time (you’ll see a warning in the log).
• A malformed synced_actions/*.json is skipped — check the log; the rest keep loading. If everything is empty or invalid, the built-in defaults stay in place (you never end up with no actions at all).

Authoring workflow ✅ Available

1. Author the clip(s) in Blender (EF-JSON addon) and register each with a constructor id — exactly like any pose clip. See Animations.
2. Write the synced action at data/<ns>/synced_actions/<id>.json with one role per participant, each naming a clip id. Omit waypoints for a cosmetic one-shot.
3. Bind it to a gameplay event in data/<ns>/tiedup/action_events.json — or, for a waypointed coop action, wire your own trigger (see the coop keybind note on Coop actions).
4. /reload and trigger the event in-game. Watch the server log for skipped defs or rejected keys.

Related

Coop actions

Waypointed synced actions — anchor-local paths, the cinematic camera, the takedown.

→ Coop actions

Animations

Author the per-role clips: the constructor block, format, pose modifiers, events.

→ Animations reference

Item JSON

on_equip / on_unequip one-shots — the per-item flavour of a synced one-shot.

→ Item JSON reference

Planned & partial

The unauthored default clips and other honest limitations.

→ Planned & partial