Attach Rope (Entity Action Type) • Data Pack • Handbook

Attaches a rope between two endpoints. Each end is a Rope Endpoint — an entity or a fixed point — so this one action covers grappling (self ↔ block), whip-grabbing (self ↔ entity) and tethering (entity ↔ block). An entity can hold several ropes at once; label them with slot so they can be cut or counted individually.

This action is registered in both the entity and bi-entity contexts. Use it as a bi-entity action (e.g. inside bientity_action) when an endpoint’s source is target.

Type ID: apoli:attach_rope

Controls: while you hold a controllable rope, the built-in keys drive it — jump/sneak reel it in and out and WASD swings. Everything else (launching, grabbing, cutting a specific whip) is done with the Rope Pull and Detach Rope actions, which you bind to keys with an active power.

Fields

Field	Type	Default	Description
`from`	Rope Endpoint	`{ "source": "self" }`	One end of the rope.
`to`	Rope Endpoint	`{ "source": "raycast", "blocks": true }`	The other end. The default reproduces the classic grapple (a block you look at).
`slot`	String	optional	A label for this rope. Attaching again with the same `slot` replaces the previous rope in it (so `left_whip`/`right_whip` give you exactly two).
`texture`	Identifier	`apoli:textures/rope/rope.png`	The texture the rope is drawn with.
`toggle`	Boolean	`true`	When `true` and no `slot` is given, re-firing while you already hold a controllable rope releases it instead of adding another (classic one-key grapple).
`controllable`	Boolean	`true`	Whether the built-in reel/swing keys drive this rope for its owner. Set `false` for tethers you cast on other entities.
`mode`	String	`"leash"`	How the length constraint behaves. `leash` = free within length, springy swinging grapple past it (the default). `spring` = a soft elastic pull past length, so the rope visibly stretches and eases back (a rubber band). `rigid` = holds a fixed distance both ways — pulled in when too far and pushed out when too close (a rod/pole).
`break_beyond`	Float	`0.0`	If greater than 0, the rope snaps (auto-detaches) once its two ends are pulled farther apart than this many blocks. `0` never breaks. (Ropes also always break when an entity end dies or unloads.)
`min_length`	Float	`1.0`	Shortest the rope can reel to.
`max_length`	Float	`30.0`	Longest the rope can be.
`start_length`	Float	see below	The length the rope is created at, clamped to `min_length`–`max_length`. Left out, a `controllable` rope starts taut — exactly as far apart as its two ends already are, so a grapple bites the moment it lands — and a rope that is not `controllable` starts at `max_length`, so a tether has its full slack immediately. Set it explicitly when you want a taut tether or a slack grapple.
`stiffness`	Float	`0.1`	How hard the rope yanks an end back once it passes its length. Higher = snappier. Range `0.0`–`1.0`.
`radial_damping`	Float	`0.85`	How much outward speed is bled off at the length limit. Range `0.0`–`1.0`; it is a damping factor, so above `1.0` it would amplify instead.
`spring_scaling`	Float	`0.65`	Extra softening while swinging inward. Range `0.0`–`1.0`.
`swing_boost`	Float	`1.08`	Speed multiplier applied to a sprinting player’s swing. Range `0.0`–`2.0`.
`max_swing_speed`	Float	`0.7`	Cap on the sprint swing boost.
`reel_step`	Float	`0.2`	Blocks per tick the length changes while a reel key (jump/sneak) is held. This is the main “pull speed” knob for a `controllable` grapple — `1.0` reels in 20 blocks per second; much above ~2 feels like teleporting.
`slack_pull_rate`	Float	`5.0`	Multiplier applied to reeling in while there is slack.
`constrain_from`	Boolean	`true`	Whether the physics may pull the `from` end (only matters when it is an entity).
`constrain_to`	Boolean	`true`	Whether the physics may pull the `to` end.

The physics fields are clamped to a stable range at load time, and a value outside it is clamped with a warning naming the field. stiffness, radial_damping and spring_scaling must be 0.0–1.0; swing_boost must be 0.0–2.0. Above those, the per-tick spring integrator diverges instead of settling: radial_damping above 1.0 multiplies outward speed every tick, and stiffness above 1.0 overshoots further each correction — which is what threw players hundreds of blocks. The rope also refuses to apply more than 4 blocks/tick of correction, so no combination of settings can launch an endpoint across the world.

Physics settings are captured when the rope is cast. Editing them and reloading the data pack does not change ropes that already exist — re-cast the rope to pick up new values.

Examples

{
   "type":"apoli:attach_rope",
   "to":{
      "source":"raycast",
      "blocks":true
   },
   "stiffness":0.2,
   "max_swing_speed":1.4
}

A grappling hook that swings a little faster than default — fire it at a wall you’re looking at.

{
   "type":"apoli:attach_rope",
   "from":{
      "source":"target"
   },
   "to":{
      "source":"position",
      "position":[
         100,
         64,
         200
      ]
   },
   "controllable":false,
   "max_length":8
}

Used as a bientity_action, this tethers the target entity to a point so it can’t wander more than 8 blocks from it. It is not controllable, so it is created at its full 8-block length no matter where the target was standing.

{
   "type":"apoli:attach_rope",
   "to":{
      "source":"raycast",
      "entities":true
   },
   "mode":"rigid",
   "break_beyond":12,
   "controllable":false,
   "slot":"harpoon"
}

A harpoon-style rope that holds a rigid distance to whatever you hit and snaps if the two ends are ever pulled more than 12 blocks apart.

Fields#

Examples#

Fields

Examples