Coop actions

A coop action choreographs two entities at once — an initiator and a target — along authored, anchor-local motion paths, with an optional cinematic camera. The shipped example is the takedown: aim at a bondage-eligible entity, press a key, and the target is pulled in and tackled while both bodies follow scripted curves and the camera frames the scene.

A coop action is just a waypointed synced action

A coop action is one kind of synced action — specifically a waypointed one (every role carries a waypoints path). The same synced_actions/ files, loader, and registry hold both the cosmetic clip-only one-shots and the position-driving coop actions; what makes an action “coop” is purely that a role declares waypoints, which engages the server position driver described below. If you only want a one-shot pose with no movement, write a clip-only def instead — see Synced actions & events.

The whole thing is datapack-authorable: one JSON file per action defines duration, the proximity gate, both roles’ waypoint paths, and the camera. The two visual poses are a pair of EF-JSON clips (authored exactly like any other animation).

There is NO ownership or consent gate

Any player can initiate a coop action against any bondage-eligible entity — including another player — as long as they are within proximity_gate blocks. The trigger packet does no permission, ownership, or consent check before starting the session. Server owners running this in multiplayer should know this: there is no built-in protection against a player grabbing another player. If you need that, gate it yourself (e.g. a permissions mod on the keybind) — the mod does not.

How it runs ✅ Available

The lifecycle is server-authoritative and wired end-to-end:

1. Trigger. The initiator aims their crosshair at a LivingEntity and presses the V key (default, rebindable under key.categories.tiedup). A request packet is sent to the server with the target’s id and the action id (takedown).
2. Gate + start. The server looks up the action, checks the target is bondage-eligible, checks the distance against proximity_gate, reserves both entities atomically, snapshots the anchor (the initiator’s position + yaw at start), snaps both participants to t=0, and — only on a successful gate — broadcasts each role’s clip and the position lock to all viewers.
3. Drive. Every server tick, the server samples each role’s waypoint curve in anchor-local space and moves both participants’ authoritative position along it. Motion is 100% waypoint-driven — the server never reads animation clip data.
4. Mirror. Clients snap the local participant to the identical computed path (no rubber-band), suppress its movement input, render the per-role clip for that participant, and — for a cinematic action — drive the camera.
5. End. When elapsed >= duration_ticks, the session ends and control returns to both entities. Lost packets, death, disconnect, or dimension change abort cleanly; late joiners re-sync.

Player-initiated only

Mob-initiated coop (AI auto-initiate) is attached to no mob and does nothing today. In-game, coop is only triggered by the player keybind. See Planned & partial.

File location & the action id

A coop action is a single JSON file, in the canonical synced-actions directory:

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

The action id is the file name (without .json). data/tiedup/synced_actions/takedown.json → the action id takedown. The loader is a server data-reload listener, so actions reload on world load and on /reload, and are synced to clients on login and on /reload.

The legacy `coop_actions/` directory still loads (deprecated)

The older data/<ns>/coop_actions/<id>.json location is still read for back-compat, but it is deprecated: every file found there logs a one-time deprecation WARN on /reload. If the same id exists in both directories, the synced_actions/ copy wins. Move your files to synced_actions/ — the legacy directory will be removed in a future version. The shipped takedown now lives at synced_actions/takedown.json.

Fail-soft batch loading

A malformed action is skipped — you’ll see a warning in the log — and the rest of the batch keeps loading. If the whole batch is empty or all-invalid, the built-in takedown default is restored. Watch the server log on /reload if a custom action doesn’t appear.

The schema

Verified field-by-field against the parser. Top-level fields:

Field	Type	Required?	Notes
duration_ticks	int ≥ 1	required	Total session length in server ticks (20 = 1 s). Values ≤ 0 are rejected at load.
proximity_gate	double	required	Max start distance (blocks) between initiator and target. Farther → the start is silently refused.
cinematic_camera	bool	optional (default false)	Enables the cheap behind-player cinematic when no camera block is present. See Cinematic camera.
camera	object {x,y,z}	optional	Anchor-local cinematic camera offset (doubles). See Cinematic camera.
priority	string	optional (default MIDDLE)	LOWEST/LOW/MIDDLE/HIGH/HIGHEST — informational only; it does not change where the clip renders. Shared with all synced actions.
roles	list	required	For a coop (waypointed) action: both an initiator and a target, each with a waypoints path. A waypointed action missing a role is rejected at load. (Clip-only synced actions relax this — see Synced actions.)

Each entry in roles:

Field	Type	Notes
role	"initiator" | "target" | "self"	Lowercase string in JSON. A coop action uses initiator + target; self exists for single-entity clip-only one-shots (see Synced actions).
clip	string	A full ResourceLocation (e.g. "tiedup:takedown_target") naming the per-role visual clip. See The two clips.
waypoints	list (≥ 2)	The anchor-local motion path, sampled by the server. Optional in general — a role with no waypoints is clip-only (cosmetic). For a coop action both roles must carry one; it is the presence of waypoints that makes the action position-driving.

Each waypoint:

Field	Type	Notes
t	double, 0.0–1.0	Normalized time over the session. Strictly increasing across the list — validated at load.
x, y, z	double	Anchor-local offset in blocks (Minecraft Y-up). Rotated by the anchor yaw and added to the anchor position at runtime.
yaw	double (degrees)	Added to the anchor yaw to set the participant’s facing at that waypoint.

Waypoint semantics

The anchor is the initiator’s position and yaw captured when the session starts. Every waypoint (x,y,z) is relative to that anchor (rotated into world space by the anchor yaw), and every yaw is added to the anchor yaw — so an action authored facing “forward” works regardless of which way the initiator was looking.

• 2 waypoints → straight linear interpolation (constant velocity).
• 3 or more waypoints → a uniform Catmull-Rom spline through the points (smooth eased curves).

The initiator must start at the origin

The initiator role’s first waypoint must be at (or within ~0.1 blocks of) the anchor origin — i.e. x:0, y:0, z:0. The start guard rejects the action if the initiator’s first waypoint magnitude is ≥ 0.1 (the anchor is the initiator’s position, so it cannot start somewhere else). Author the initiator’s path starting from 0,0,0; put all the motion on the target (and the rest of the initiator’s own path).

Load-time validation

Each waypointed role’s list is validated when the datapack loads. An action is skipped (logged as an error) if a role that declares waypoints has:

• fewer than 2 waypoints,
• a t outside [0.0, 1.0],
• non-strictly-increasing t (catches unsorted lists and duplicate t values),

…or if the def is waypointed but missing a role (a position-driving action needs both initiator and target), or has a decode failure (a wrong type / missing required field).

A clip-only role skips waypoint validation

A role with no waypoints is clip-only and is not waypoint-validated — and a def with no waypointed roles is not required to carry both initiator and target. The two-role requirement applies only to position-driving (waypointed) actions. A non-empty but malformed waypoint list is still rejected.

A complete example

This is the shipped takedown (data/tiedup/synced_actions/takedown.json) — a 2-second action where the initiator stays put and the target is pulled in from 1.5 blocks ahead, eased to 0.4 blocks (the tackle), facing the initiator (yaw: 180):

{
  "duration_ticks": 40,
  "proximity_gate": 2.5,
  "cinematic_camera": true,
  "roles": [
    {
      "role": "initiator",
      "clip": "tiedup:takedown_initiator",
      "waypoints": [
        { "t": 0.0, "x": 0, "y": 0, "z": 0, "yaw": 0 },
        { "t": 1.0, "x": 0, "y": 0, "z": 0, "yaw": 0 }
      ]
    },
    {
      "role": "target",
      "clip": "tiedup:takedown_target",
      "waypoints": [
        { "t": 0.0, "x": 0, "y": 0,   "z": 1.5, "yaw": 180 },
        { "t": 0.5, "x": 0, "y": 0,   "z": 0.8, "yaw": 180 },
        { "t": 1.0, "x": 0, "y": 0.2, "z": 0.4, "yaw": 180 }
      ]
    }
  ]
}

To author your own action, drop a new file at data/<yourns>/synced_actions/<id>.json with the same shape. The id (<id>) becomes the action key; the built-in takedown keybind always requests the takedown id, so a brand-new id is loaded and synced but needs its own trigger to fire (the keybind is hard-wired to takedown).

The two per-role clips 🔧 Manual / tool-gap

Each role’s clip field is a full ResourceLocation that must match a registered animation clip. A complete coop action therefore needs two EF-JSON clips shipped as resourcepack assets — one for the initiator, one for the target — authored exactly like any other pose clip (Blender EF-JSON addon export + the hand-added top-level constructor block that registers it under a namespace:id).

The string in clip must equal the registered id from the clip’s constructor block — not its filename. For the shipped takedown:

Role	clip value	The clip’s constructor id must be
initiator	"tiedup:takedown_initiator"	tiedup:takedown_initiator
target	"tiedup:takedown_target"	tiedup:takedown_target

See Animations for the full clip-authoring workflow (the constructor block, format: "ATTRIBUTES", and the properties unlocks).

A typo in `clip` fails SILENTLY

If the clip id doesn’t resolve to a registered clip — a typo, a missing clip, or a clip whose constructor block was never added — the visual driver falls back to the empty animation: the position math still drives both entities correctly, but the entity shows no pose (it just slides along the path). You get only a one-time WARN in the log, no error. If a coop action moves the bodies but they don’t animate, check the clip ids match exactly and that both clips are registered.

Cinematic camera ✅ Available

A coop action can move the camera. There are two modes; the renderer is client-side (🖥️ Client / singleplayer only the camera math runs only on the participating client).

Authored shot — the camera block

Add an optional top-level camera object with x, y, z doubles. This is an anchor-local offset (same space and rotation convention as the waypoints):

{
  "duration_ticks": 60,
  "proximity_gate": 2.5,
  "camera": { "x": 0.0, "y": 1.5, "z": -3.0 },
  "roles": [ /* initiator + target as above */ ]
}

While the action runs, the camera is placed at anchor + rotateYaw(camera, anchorYaw) and aimed at the live midpoint of both participants’ eye positions — so it tracks the action as the bodies move. A terrain clamp pulls the camera in if a block sits between it and the look target, so it never clips through walls. The local participant’s view is forced to third-person for the duration and restored when the session ends.

`camera` is an object, not a list

Use the object form { "x": …, "y": …, "z": … }. The list form [x, y, z] (Minecraft’s built-in Vec3 serialization) is not accepted here. The camera shot is a fixed authored position with a live look-at — there is no per-waypoint moving camera, no explicit look-at point, and no authorable pitch/roll/FOV.

Behind-player fallback — cinematic_camera

If you set cinematic_camera: true but provide no camera block, the action gets a cheap behind-the-player cinematic: third-person view, yaw locked to the authored facing, pitch neutral. The shipped takedown uses exactly this (cinematic_camera: true, no camera).

What you author	Camera behaviour
camera: { x, y, z } present	Static authored shot, live look-at on the participant midpoint, terrain-clamped.
cinematic_camera: true, no camera	Behind-player third-person, yaw locked to facing, pitch 0.
Neither	Default view (no camera takeover).

Not the same as a bind's `camera_offset`

This coop camera is unrelated to the per-item first-person camera_offset documented on Item JSON — that one nudges a worn bind’s first-person eye (e.g. the dogbinder lowering the view). The coop camera is a detached third-person cinematic shot for a coop session. They live on different code paths and don’t interact.

Related

Synced actions & events

The general model — clip-only one-shots, the closed event enum, and action_events.json.

→ Synced actions & events

Animations

Author the two per-role clips: the required constructor block, format, and pose modifiers.

→ Animations reference

Bones & regions

The joint names you can pose in those clips, and the body-region vocabulary.

→ Bones & regions

Item JSON

The per-item camera_offset (distinct from the coop camera) and the bind schema.

→ Item JSON reference

Planned & partial

Mob-initiated coop (AI auto-initiate) and other not-yet-wired features.

→ Planned & partial