Grappling Hook

A grappling hook flies out along the aim, catches the first anchor on its path and pulls the character in while the button is held. Check the whole stretch the hook covers each step so it cannot skip an anchor, set the pull speed instead of adding to it, and fire again only on a fresh press.

Also called: Grapple, Rope hook, Grapple line.

A heron courier in a red cape is hauled through the air over a dark chasm on a taut rope whose hook has just bitten into a stone ring on a far rock spire, in a carved woodblock print style. — Sorrelwick Gorge, an invented rope-swinging adventure. Invented game, image generated with AI.

Paste this to your AI

Copy it into Claude, Cursor or ChatGPT. It already has good values and the usual mistakes in it.

Add "Grappling Hook" to my game.

What it should do: A hook lets the player cross gaps and pick their own route. It trades the safety of the ground for speed and reach, so catching an anchor has to feel reliable and the pull has to feel the same every time.

Build it exactly as this state machine. First check that it fits my game, then build it like this:

```mermaid
stateDiagram-v2
  [*] --> ready
  ready: Hook ready
  flying: Hook flying
  pulling: Pulling in
  retracting: Hook returning
  ready --> flying: button pressed
  flying --> pulling: hook catches
  flying --> retracting: misses or let go
  pulling --> retracting: arrives or lets go
  retracting --> ready: hook is back
```

Use these starting values:
- hookSpeed: 40 units/s
- maxRange: 12 units
- hookRadius: 0.6 units
- reelSpeed: 14 units/s
- arriveDistance: 1 units
- keepMomentum: 0.5
- retractSpeed: 60 units/s

Watch out for these common mistakes:
- A fast hook skips a thin anchor: Tell your AI: check the whole stretch the hook covers in one step against each anchor, not only where the hook ends up.
- Two anchors on one path: Tell your AI: of all the anchors the hook passes in one step, catch the one it meets first along its way.
- Holding the button after the hook comes back: Tell your AI: remember if the button was held on the last tick, and fire only on a new press.
- A wall between the character and the hook: Tell your AI: when something solid is between the character and the hook, let go at once and give no push.
- The pull adds to the speed: Tell your AI: set the speed toward the anchor to the pull speed every tick, never add to it.
- A long aim is a faster hook: Tell your AI: keep only the direction of the aim, scale it to a length of 1, and fix it when the hook is fired.

Do not change anything else in the game. Do not claim anything without proof: model what it takes, and show me what your solution rests on and how I can see that it works. If you cannot show something, say you do not know. When you are done, tell me in plain words how to try it.

Or skip this and connect the MCP: your AI then finds all of this by itself.Connect the MCP

What it does

A hook lets the player cross gaps and pick their own route. It trades the safety of the ground for speed and reach, so catching an anchor has to feel reliable and the pull has to feel the same every time.

How it runs, as a diagram

Everything it can be in, and what moves it on. Your AI builds from exactly this.

How it runs, as a diagram

Hook ready → Hook flying: button pressed
Hook flying → Pulling in: hook catches
Hook flying → Hook returning: misses or let go
Pulling in → Hook returning: arrives or lets go
Hook returning → Hook ready: hook is back

Good starting values

Value	Start with	What it changes
hookSpeed	40 units/s	How fast the hook flies out. About three times the pull speed makes the throw feel quick without being instant.
maxRange	12 units	The farthest an anchor can be from the character. About six body heights is enough to cross a gap but not the whole level.
hookRadius	0.6 units	How close the hook must pass to an anchor to catch it. A little wider than the anchor forgives a slightly bad aim.
reelSpeed	14 units/s	How fast the pull is. About twice a running speed, so the hook is a shortcut and not a teleport.
arriveDistance	1 units	Closer than this to the anchor, the pull ends. It stops the character from pushing into the anchor and shaking.
keepMomentum	0.5	The share of the pull speed the character keeps on letting go. Half carries it over the edge without making chained hooks too fast to aim.
retractSpeed	60 units/s	How fast the hook flies back. It is also the wait before the next shot, so a quick return keeps the player moving.

What usually goes wrong

A fast hook skips a thin anchor

The hook moves in steps. When one step is longer than the anchor is wide, the hook can sit before the anchor in one step and past it in the next, and nothing is ever caught. It happens on slow computers and with fast hooks.

Fix: Tell your AI: check the whole stretch the hook covers in one step against each anchor, not only where the hook ends up.

Two anchors on one path

If the game takes the first anchor in its list that is close enough, the hook can reach through a near anchor and grab a far one.

Fix: Tell your AI: of all the anchors the hook passes in one step, catch the one it meets first along its way.

Holding the button after the hook comes back

A player who keeps holding the button fires again the moment the hook is back, and swings off where they did not mean to go.

Fix: Tell your AI: remember if the button was held on the last tick, and fire only on a new press.

A wall between the character and the hook

The pull keeps pushing the character into the wall, or drags it through a corner it should have caught on.

Fix: Tell your AI: when something solid is between the character and the hook, let go at once and give no push.

The pull adds to the speed

A pull that adds speed every tick makes the character faster the longer it hangs on, and a pull while falling feels weak. The same hook feels different each time.

Fix: Tell your AI: set the speed toward the anchor to the pull speed every tick, never add to it.

A long aim is a faster hook

If the aim comes from a stick or a mouse, a long or diagonal aim can fly faster than a short straight one.

Fix: Tell your AI: keep only the direction of the aim, scale it to a length of 1, and fix it when the hook is fired.

How to check it works

The hook is ready and the player aims right. Press the button, then wait one tick: The hook flies out and has moved 0.67 units to the right.
The hook is ready and there is no aim. Press the button: Nothing is fired.
The player aims with a long diagonal stick. Fire and wait one tick: The hook moves the same 0.67 units as for a short aim, split 0.4 across and 0.53 up.
A hook is flying to the right. The player swings the aim up and then down: The hook keeps flying straight to the right.
An anchor is 5 units away, a little off the line. The hook flies toward it: The hook catches the anchor and starts to pull.
A fast hook moves 8 units in one step and an anchor sits 4 units away. One step is taken: The hook catches the anchor anyway.
Two anchors lie on the path, the far one listed first. One long step passes both: The near anchor is the one caught.
The only anchor is 13 units away and the range is 12. The hook flies out: The hook is not caught and flies back, while an anchor at 11.9 units is caught.
The hook is flying. Let go of the button: The hook flies back and the character gets no push.
The hook holds an anchor straight ahead, and another at 3 across and 4 up. Hold the button for one tick: The speed is 14 straight ahead, and 8.4 across with 11.2 up for the other, always 14 in all.
The character is half a unit from the anchor. The pull takes one more tick: The hook lets go and the character keeps a speed of 7.
The hook is pulling. Let go of the button: The hook lets go and the character keeps half the pull speed.
The hook is pulling and a wall comes between the character and the hook. One tick passes: The hook lets go and the character gets no push at all.
The hook has let go 10 units from the character. Wait 10 ticks: The hook is back and ready.
The hook just came back and the button is still held. Keep holding, then let go and press again: Nothing happens while held, and the new press fires.

Works well with

Stamina System: A hook that costs stamina to fire or to hold needs the meter's answer before the press counts. Let the pull end when the meter runs out. Check the meter first, then fire.
Double Jump: Give the air jumps back when the hook lets go, so a pull can be followed by a jump. Decide if a caught anchor counts as landing.

Clashes with Coyote Time: A pull that lets go at an edge can leave the character just over the edge, where the grace time of a late jump may start. Start the grace time only from the ground, not from the end of a pull.

Common questions

how do i add a grappling hook to my game

Paste this: Add a grappling hook. A press fires it along the aim, it catches the first anchor on its path, pulls the character in at a fixed speed while the button is held, lets go on arrival, and cannot fire again until the hook is back.

how fast should a grappling hook pull

Start with a pull about twice the running speed. It then feels like a shortcut. Much faster feels like teleporting, and slower than running makes the hook pointless.

should the player keep speed after letting go of the hook

Keep some of it. Half the pull speed here: the character does not stop dead, and a hop over an edge works, but keeping all of it makes chained hooks too fast to aim.

why does my grappling hook fly through thin anchors

The hook moves in steps, and a fast one can jump over a small target between two steps. Check the whole stretch the hook covered in one step, not just where it ended.

Where it comes from

We could not find a reliable origin for this one yet.

Where this mechanic comes from has not been researched yet.

Games are named only as references. Names and marks belong to their owners, and nothing here is endorsed by them.

What was checked

19 tests pass on the reference code.
The state diagram was checked against the code, at the default values and at every listed low and high value.

This is what separates the blueprint from a catalogue entry: the values on this page come from code that runs.

Your AI gets the code

Tested example code comes through the Spielerando connection, so your AI can use it right away. How to connect it