Ledge Grab

A ledge grab catches a falling character by the top corner of a ledge and lets it hang there, then climb up or drop. Look at the whole stretch the hands travelled in a tick so a fast fall cannot skip the corner, and make the hands ignore ledges for a moment after letting go.

Also called: Ledge hang, Edge grab, Mantle.

A small mole in an orange knitted hat hangs by its mittens from the corner of a blue felt cliff, legs dangling over a deep valley. — Stitchwick, an invented felt-world 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 "Ledge Grab" to my game.

What it should do: Players misjudge jumps by a hand's width all the time. A ledge grab turns a near miss into a save, and it makes every edge a place to climb.

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

```mermaid
stateDiagram-v2
  [*] --> ground
  ground: On the ground
  air: In the air
  hang: Hanging
  climb: Climbing
  ground --> air: walks off an edge
  ground --> hang: steps off, finds a ledge
  air --> ground: lands
  air --> hang: hands pass a corner
  hang --> climb: player presses up
  hang --> air: lets go or ledge gone
  climb --> ground: reaches the top
```

Use these starting values:
- handHeight: 1.6 units
- reach: 0.6 units
- climbTime: 0.45 s
- regrabTime: 0.3 s
- gravity: 32 units/s²
- maxFallSpeed: 20 units/s

Watch out for these common mistakes:
- A fast fall skips the corner: Tell your AI: check the whole stretch the hands travelled in this tick against the catch zone.
- Grabbing on the way up: Tell your AI: grab only when the character is falling or has stopped rising.
- Dropping and grabbing again: Tell your AI: after letting go, ignore ledges for a short wait time.
- The floor after the climb: Tell your AI: report the top of the ledge as the floor from the tick the climb ends.
- The ledge disappears or both buttons are pressed: Tell your AI: let go when the ledge is gone, and decide which button wins. Here up wins.

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

Players misjudge jumps by a hand's width all the time. A ledge grab turns a near miss into a save, and it makes every edge a place to climb.

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

On the ground → In the air: walks off an edge
On the ground → Hanging: steps off, finds a ledge
In the air → On the ground: lands
In the air → Hanging: hands pass a corner
Hanging → Climbing: player presses up
Hanging → In the air: lets go or ledge gone
Climbing → On the ground: reaches the top

Good starting values

Value	Start with	What it changes
handHeight	1.6 units	How far the hands are above the feet. A grab puts the body so that the hands sit exactly on the corner, and a climb ends with the feet on it.
reach	0.6 units	How far below the corner the hands may be and still catch it. Large enough to forgive a near miss, small enough that the player still has to aim. About a third of the hand height.
climbTime	0.45 s	How long the climb up takes. Long enough to be seen, short enough not to feel like waiting.
regrabTime	0.3 s	How long after letting go the hands ignore ledges. Without it, the hands catch the same ledge again on the next tick and the player can never drop. Zero turns the wait off.
gravity	32 units/s²	How fast a fall speeds up.
maxFallSpeed	20 units/s	The fastest the character can fall, and so the farthest the hands can travel in a tick before a grab.

What usually goes wrong

A fast fall skips the corner

If the grab only checks where the hands are at the end of a tick, a fast fall or a slow frame can carry them from above the corner to below the catch zone in one step, and the ledge is never caught.

Fix: Tell your AI: check the whole stretch the hands travelled in this tick against the catch zone.

Grabbing on the way up

A jump that passes a ledge while still rising gets yanked onto it, which feels like the game is taking over the jump.

Fix: Tell your AI: grab only when the character is falling or has stopped rising.

Dropping and grabbing again

When the player lets go, the hands are still exactly at the corner. Without a wait the next tick grabs the same ledge again and the player can never drop.

Fix: Tell your AI: after letting go, ignore ledges for a short wait time.

The floor after the climb

When the climb ends, the feet are on top of the ledge. If the game still reports the old, lower ground, the character falls off the ledge it has just climbed.

Fix: Tell your AI: report the top of the ledge as the floor from the tick the climb ends.

The ledge disappears or both buttons are pressed

A crumbling ledge or a press of up and down together leaves the character hanging on nothing or doing both at once.

Fix: Tell your AI: let go when the ledge is gone, and decide which button wins. Here up wins.

How to check it works

Your character falls and its hands reach the corner of a ledge. The hands pass the corner: The character stops with its hands exactly on the corner and hangs.
Your character jumps up past a ledge. The hands pass the corner while it is still rising: Nothing is grabbed and the jump goes on.
Your character falls so fast that in one tick its hands go from above the corner to below the catch zone. That tick runs: The ledge is still caught.
Your character hangs on a ledge. The player does nothing for five seconds: The character does not move at all.
Your character hangs on a ledge. The player presses up: After the climb time the character stands on top of the ledge.
Your character hangs on a ledge. The player presses down: The character lets go and falls.
Your character has just let go of a ledge. Its hands are still at the corner during the wait time, and then again a ledge reaches them after the wait is over: The first is ignored and the second is caught.
Your character hangs on a ledge. The ledge disappears: The character lets go and falls.
Your character is about to land and its hands pass a corner in the same tick. That tick runs: The character lands and grabs nothing.
Your character falls with its hands well above or well below a corner. A tick runs: Nothing is grabbed.

Works well with

Wall Slide: At the top of a wall the slide ends and a grab can begin. When both fit, let the grab win.
Coyote Time: A late jump from the edge you just left should still work, and a grab should not eat the press. Check the ground and its grace time before the grab.
Stamina System: A hang that costs stamina makes ledges a risk, not a free rest. Spend stamina on each tick of the hang and treat an empty bar like pressing down.

Clashes with Wall Jump: A press while hanging can mean a jump off the wall or a climb up. Give the climb its own button, up, and let the jump button kick off the wall.

Common questions

what do i tell my ai to add a ledge grab

Paste this: Add a ledge grab: when the character is falling and its hands pass the top corner of a ledge, check the whole stretch the hands travelled and hang from the corner. Up climbs onto the ledge, down lets go, and after letting go ignore ledges for a short wait time.

why does my character fall through a ledge instead of grabbing it

The grab probably checks only where the hands end up. A fast fall carries them past the catch zone in one tick. Check the whole stretch they travelled instead.

why does my character grab the same ledge again after letting go

After letting go, the hands are still at the corner, so the next tick catches it again. Make the hands ignore ledges for a short wait time, here a third of a second.

should the ledge grab happen on its own or need a button

On its own is the forgiving choice and fits fast games. A button is for games where the player should be able to pass a ledge without catching it. Here it happens on its own.

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