# ledge (climbKit)
The physics probes behind `ClimbMover`, usable on their own by any mover: a custom controller, an NPC planner deciding whether a ledge is reachable, a level-validation tool checking a roofline is climbable. Pure functions over the physics world's colliders; they answer in edit mode too.
```luau
local Ledge = require("@root::climbKit.ledge") -- ~.ledge from inside the package
local spot, why = Ledge.findLedge({
feet = body.position, dirX = 0, dirZ = -1,
height = 1.8, radius = 0.3, reach = 2.3, selfId = body.id,
})
if spot then print("mantle", spot.height, "onto a", spot.slope, "degree top at", spot.landing) else print(why) end
```
| Function | Answers |
|---|---|
| `findLedge(opts)` | A top in front within `reach` the body can stand on: `top`, `landing` (feet position), `risen` (where the straight rise ends), `height`, `slope`, `edgeDistance`, `climbable`; or nil and why (`no top`, `too tall`, `too low`, `too high`, `no headroom on top`, `blocked above`, `blocked across`, `blocked over the edge`). |
| `wallAhead(feet, dx, dz, height, distance, selfId?)` | Nearest steep surface in front at 35/55/85% of the height, with `climbable`. |
| `wallRay(feet, dx, dz, atHeight, distance, selfId?, maxNormalY?)` | One horizontal wall ray. |
| `isClimbable(entityId, hit?)` | The `climbable` attribute on the entity or nearest ancestor that has one decides (true or false); otherwise the registered climb rules decide. |
| `addClimbRule(name, rule)` / `removeClimbRule(name)` / `hasClimbRule(name)` | Rules that make unmarked surfaces climbable by what they are: `rule(entityId, hit) -> true / false / nil`. |
| `fits(feet, height, radius, lift?, selfId?)` | Whether a standing capsule fits there. |
| `pathClear(feet, delta, height, radius, selfId?)` | Whether a capsule sweep along `delta` is clear. |
| `mantlePoint(start, risen, landing, t, split?)` | The feet along a mantle at progress t: up first, then over. |
| `mantleDuration(height, reach, minTime, maxTime)` | Mantle time scaled by height. |
| `groundBelow(p, above, depth, selfId?)` | Ground ray under a point. |
Positions are feet (capsule bottom) in world space; directions are horizontal unit vectors; up is world +Y.
# ClimbMover
Mantle, wall climb and ledge hang for a character body that walks on the built-in `CharacterController`. Put it on the same entity as the controller: the player body a scene's `PlayerPrototype` names, or an NPC. It needs nothing else; with `Locomotion` on the body too it turns the visible model to face the wall during a move.
```luau
body.component.add("climbKit.ClimbMover", {})
wall.attribute.set("climbable", true) -- walls you want climbable
```
## How it drives the character
It runs just ahead of the controller (`executionOrder = -150`) and reads the controller's input bus (`inputX`, `inputZ`, `inputJump`), so the player's map (keyboard, gamepad, touch) and an AI writing the bus both trigger it.
While a move runs it switches the controller off (`enabled = false`) and writes the body's position itself, so the controller's gravity and wall push-out never fight the pull-up. The local player's body reads its `move` / `jump` controls from the controller's `inputMap` while the controller is off; other bodies read the bus their driver keeps writing. When the move ends the controller is switched back on and handed the exit velocity through its own bus: a one-frame jump whose `jumpForce` is the vertical speed (0 to stand, up for a kick-off) and `inputX` / `inputZ` across. Nothing the controller held before the move (a jump's rise, a fall) carries over. `jumpForce`, `jumpBuffer` and `Locomotion.moveDeadzone` are restored afterwards.
Only the peer that owns the body runs it.
## Triggers
| Situation | Move |
|---|---|
| Grounded, jump pressed, moving toward a top ≤ `reach` above the feet | mantle |
| Grounded, walking into an obstacle ≤ `walkReach` (`autoMantleWhileWalking`) | mantle |
| Airborne, moving toward a top ≤ `reach` (`autoMantleInAir`) | mantle |
| Falling faster than 2.5 m/s past an edge `hangDepth` ± 0.4 m above the feet | hang |
| Pushing into a `climbable` wall (blocked, or airborne, or jump) | climb (mantles instead if the top is in reach) |
| Climbing, head past the top | mantle over |
| Climbing down onto ground | stand |
| Climbing/hanging + jump | kick off (`kickOffSpeed` out, `kickOffUp` up) |
| Climbing/hanging + jump while pulling away, or hanging + back | drop (the edge let go of is not caught again until the body lands or 1.5 s pass) |
| Hanging + forward (once the stick has eased off since the catch) or jump | pull up |
| Hanging + sideways | shimmy |
A mantle needs a top no steeper than `maxTopSlope`, room for the standing capsule on it, and a clear way straight up and then over (an eave overhanging the body blocks it until the body stands clear of the edge).
## Fields
| Field | Default | |
|---|---|---|
| `mantleEnabled` / `climbEnabled` / `hangEnabled` | true | turn each move on or off |
| `reach` | 2.3 | highest top above the feet a jump mantles onto (m) |
| `walkReach` | 1.2 | highest top walking into it steps up onto |
| `autoMantleWhileWalking` | true | walk-up without a jump press |
| `autoMantleInAir` | true | grab ledges in reach while airborne and moving toward them |
| `minLedgeHeight` | 0.45 | lower tops are left to the controller's step |
| `probeDistance` | 0.6 | how far ahead of the body to look for an edge (m) |
| `maxTopSlope` | 42 | steepest top it lands on (deg) |
| `mantleMinTime` / `mantleMaxTime` | 0.35 / 0.6 | mantle duration, scaled by height |
| `climbSpeed` | 1.6 | m/s up, down, sideways on a wall |
| `wallGap` | 0.05 | gap kept off the wall |
| `kickOffSpeed` / `kickOffUp` | 3.5 / 4.0 | jump off a wall or ledge |
| `shimmySpeed` | 1.1 | sideways along a ledge |
| `hangDepth` | 2.0 | feet below the ledge top while hanging |
| `regrabDelay` | 0.4 | seconds before grabbing again after letting go |
| `autoClimbDwell` | 0.3 | seconds of holding forward against a climbable wall from the ground before the climb starts by itself (players and NPCs alike; 0 turns it off) |
## Telemetry (synced, read-only in practice)
`state` (`idle` / `mantling` / `climbing` / `hanging`), `progress` (0..1 through a mantle), `ledgeHeight`, `ledgeSlope`, `wallNormalX` / `wallNormalZ`, `climbX` / `climbY` (climb input, -1..1).
## Events (synced)
`onMantleStart { height, slope, duration }`, `onMantleEnd { height }`, `onClimbStart { normalX, normalZ }`, `onClimbEnd { reason }` (`top`, `ground`, `jump`, `drop`, `lost wall`, `overhang`, `no way up` (pinned with nowhere to go for a second: a dead end, a pocket under an eave; or held going nowhere for 2 s), after which that wall is not climbed again for 3 s; `blocked below` (from 1.1.30) when a stick held down or away takes the feet no more than 5 cm lower in 0.5 s with ground within 2.5 m below: the foot of a wall over a plinth), `onHangStart { height }`, `onHangEnd { reason }` (`ground` when a hang sunk below the floor stands on it, `over lip` when pushing up from a lip climbs over it, `no way up` when held going nowhere for 2 s), `onKickOff { speed }`.
Climbing over a lip or a narrow shelf fires `onMantleStart`, then `onMantleEnd` and `onClimbStart` as the climb goes on up the wall above; climbing over from a climb fires no `onClimbEnd` first, and from a hang `onHangEnd { reason = "over lip" }` comes first. The move goes out from under the lip, up past it, then back in to the wall.
```luau
local climb = entity(bodyId).component.get("ClimbMover")
climb.events.onMantleStart:connect(function(e) playClip("mantle", e.duration) end)
```
## Methods
- `tryMantle(dirX, dirZ, exclude?, opts?) -> boolean`: pull up onto a ledge in that horizontal direction now, if there is one (AI, scripted sequences). `opts` widens the search for one call (see `Ledge.applyMantleOpts`): `minHeight` (-1 to reach; a negative value steps across onto a floor at or a little below the feet, as from a rope or pole top onto a deck), `maxHeight` (0 to reach), `probeDistance` (0.1 to 2 m) and `skipRiseCheck` (skips the room-straight-above check only when the body rises at most 0.3 m, and lets that step duck 0.3 m under something over the head on its way across; the landing must still fit a standing body). A step across fires `onMantleStart` with a height of 0 or less.
- `release()`: let go of whatever move is running and stand.
## Added in 1.1.0
| Field | Default | |
|---|---|---|
| `hangCatchSpeed` | 2.5 | fall speed (m/s) above which an edge dropped past is caught as a hang |
| `cornerShimmy` | true | shimmy round outside and inside corners |
| `cornerTime` | 0.3 | seconds a corner turn takes |
| `ledgeTopY` | (telemetry) | world height of the edge hung from / mantled onto |
| `ledgeEntity` | (telemetry) | entity of the ledge hung from / mantled onto, the lip being climbed over; "" once the controller is handed back |
- Event `onCorner { inside, normalX, normalZ }` (synced).
- `tryHang(dirX, dirZ, exclude?) -> boolean`: catch an edge in that direction as a hang now.
- `tryClimb(dirX, dirZ) -> boolean`: start climbing the climbable wall in that direction now.
- Climbability goes through `ledge.isClimbable`, which reads the `climbable` attribute first (true or false) and then any registered climb rules (`Ledge.addClimbRule`).
- On every peer other than the owner the visible body turns toward the synced wall normal while a move runs.
## 1.1.2: control schemes that drive the bus
While a move runs, the controller is switched off, so ClimbMover reads what drives the body itself. It now reads the controller's input bus (`inputX` / `inputZ` / `inputJump`) first, for every body including the local player's, and falls back to the player's own input map only when nothing is on the bus. A control scheme that drives the character through the bus and turns the controller's own map off (such as controlsKit's `ControlsMover`) now climbs, hangs and shimmies with no extra wiring.
The bus is read the way the controller reads it: units per second, so a full push is the controller's `moveSpeed`. A scheme that writes a slower speed reads as a partial push (pulling up and dropping need more than 0.6 of a full one). A bus that carries only a jump keeps the direction from the player's own map that frame.
## 1.1.4: overhangs and ignore lists
- Climbing up into an overhang (an eave, a balcony) no longer sticks: the body stops at that height and can still shimmy sideways out from under it, climb down or jump off.
- `tryMantle(dirX, dirZ, exclude?)` and `tryHang(dirX, dirZ, exclude?)` take an optional list of entity ids the ledge search ignores: the rope or pole the body is holding, whose own top is not the ledge to pull onto.
# climbKit: mantle, wall climb and ledge hang for any character
climbKit adds the traversal moves the built-in `CharacterController` does not have, as one component you put on a character's body:
- **Mantle**: run at a crate, a wall top, a market stall or a sloped roof and jump (or just walk into anything up to waist height) and the character pulls itself up and over onto the top in 0.35 to 0.6 s. It works onto sloped roofs up to ~40°, from one roof up to a higher eave, and from mid-jump (a jump that has already risen reaches higher).
- **Wall climb**: walls whose collider entity, or any entity above it, carries the attribute `climbable = true` can be climbed by holding forward against them: up, down and sideways at `climbSpeed`. Jump kicks off the wall; climbing past the top pulls over onto it; climbing down to the ground stands again.
- **Ledge hang**: dropping fast past an edge catches it. Sideways shimmies along it, forward or jump pulls up, back drops.
It uses the player's existing controls (the `move` axis and the `jump` action of the controller's input map, or whatever drives the controller's input bus, such as controlsKit), so it works on keyboard, gamepad and touch with no new bindings, and NPCs that drive a `CharacterController` through its input bus get the same moves. It sets no game rules (no stamina, no damage).
## Quick start: an empty world
Install the package, then in your scene's `build.luau` (or by hand on the body entity):
```luau
-- 1. Give the player prototype's body the moves. `body` is the entity your
-- PlayerPrototype names as its body (the one carrying the avatar Asset).
body.component.add("climbKit.ClimbMover", {})
-- 2. A 2 m ledge to pull up onto: anything with a collider.
local ledge = entity.spawn("Ledge")
ledge.component.add("Model", { model = "cube" })
ledge.component.add("BoxCollider", {})
ledge.localPosition = { 0, 1, -6 }
ledge.localScale = { 4, 2, 2 }
-- 3. A climbable wall: mark it (or any parent of it) climbable.
local wall = entity.spawn("ClimbingWall")
wall.attribute.set("climbable", true)
wall.component.add("Model", { model = "cube" })
wall.component.add("BoxCollider", {})
wall.localPosition = { -6, 3, -6 }
wall.localScale = { 4, 6, 1 }
```
In play, run at the ledge and press jump; walk into the wall and hold forward.
The `ledgework` world this package comes from has a showcase scene (`scenes/main`) with a course of crates, a 2 m ledge, a market stall under a townhouse eave, a climbable stone wall and a hang ledge.
## What it ships
| Part | What it is |
|---|---|
| `ClimbMover.component` | The moves. Goes on a body that has a `CharacterController`. Fields, telemetry and events in its README. |
| `ledge.module` | The probes behind it, usable on their own: `findLedge` (can this body pull up here, onto what, landing where), `wallAhead` / `wallRay` (is there a wall, is it climbable), `fits`, `pathClear`, `mantlePoint`, `isClimbable`. |
| `tests/climbKit_ledges.testSuite` | Mantle heights at jump and walk reach, too-tall walls, headroom, 20/30/40° roofs, a too-steep roof, mid-jump reach, climbable vs plain walls, overhangs, the mantle path. |
| `docs/climbing.guide` | How to let players climb walls and pull up onto ledges: the recipe, level-design numbers, animation hookup. |
## Climbable by rule (1.1.0)
Marking is not the only way in. Any package can register a **climb rule** that decides, for a surface nobody marked, whether it can be climbed: by how steep it is, how high, what it is made of. A marked surface always wins: `climbable = true` on the entity or a parent makes it climbable, `climbable = false` makes it never climbable whatever the rules say.
```luau
local Ledge = require("@root::climbKit.ledge")
-- Every near-vertical surface taller than 2 m is climbable.
Ledge.addClimbRule("myGame.tallWalls", function(entityId, hit)
if hit and hit.normal and math.abs(hit.normal.y) < 0.3 then
local e = entity(entityId)
if e.localScale.y > 2 then return true end
end
return nil -- no opinion: ask the next rule
end)
```
A rule answers `true`, `false` (stop asking) or `nil` (no opinion). The `hit` describes the surface being asked about: the wall face for the wall probes (`wallRay`, `wallAhead`, so its normal is near-horizontal) and the ledge top for `findLedge` (normal pointing up). A rule that errors is skipped and reported once. Rules live in module state, so a package that registers them checks `Ledge.hasClimbRule(name)` and registers again after a reload.
## Corners, catches and script control (1.1.0)
- Shimmying to the end of a ledge carries on round an **outside corner** onto the side face, and into an **inside corner** onto the wall across, over `cornerTime` seconds (`cornerShimmy` turns it off; `onCorner` fires). The direction held through the turn keeps going until the player changes it, so camera-relative controls do not read the turn as "let go".
- `tryHang(dirX, dirZ, exclude?)` catches an edge in that direction as a hang now, and `tryClimb(dirX, dirZ)` starts climbing the climbable wall there: for assisted jump catches, dropping to the ledge below, AI and scripted sequences.
- `hangCatchSpeed` sets how fast a fall has to be for an edge to be caught as a hang instead of mantled (was fixed at 2.5 m/s).
- `ledgeTopY` (synced) is the world height of the edge being hung from or mantled onto: where hand IK goes.
- Every peer now turns the visible body toward the wall from the synced `wallNormalX/Z`, so other players see a climber face the wall, not only the owner.
## Animations and game code
`ClimbMover` publishes `state` (`idle` / `mantling` / `climbing` / `hanging`, synced), `progress`, `ledgeHeight`, `ledgeTopY`, `ledgeSlope`, `climbX` / `climbY` (the climb input, for blending) and the wall normal, and fires `onMantleStart`, `onMantleEnd`, `onClimbStart`, `onClimbEnd`, `onHangStart`, `onHangEnd`, `onKickOff`, `onCorner` (synced to other peers). Play your mantle, climb and hang clips from those. `tryMantle`, `tryHang`, `tryClimb` and `release()` drive it from AI or script.
## Multiplayer
The peer that owns the body runs the moves; other peers see the body move through the normal body replication and read the synced `state` and events.
## Limits
- Up is world +Y: it does not climb in `GravityField` frames.
- A hang only catches when falling faster than `hangCatchSpeed` (2.5 m/s by default); slower, an in-reach ledge is mantled instead.
- Corner turns follow the edge at the height being hung from; an edge that steps up or down by more than 0.25 m at the corner is not followed.
## Changes
**1.1.6**: a hang caught while sliding off a sloped roof no longer throws the body across the map. The wall probe under a ledge could meet a near-flat roof surface, and normalising its tiny horizontal direction placed the hang metres away in one frame (seen as a 12 m jump in a castle town). The probe has to meet a wall (as of 1.1.12, steeper than 60 degrees), otherwise the hang lines up on the ledge's own edge, and a hang never moves the body further than its radius plus the probe distance plus 0.6 m. Airborne ledge probes now run 20 times a second instead of every frame, which keeps their cost low in levels with thousands of colliders.
**1.1.8** (first sent as 1.1.7 without this note): `Ledge.suspendClimbRules()` takes every registered climb rule out for a while and answers a function that puts them back (for a test that checks climbKit's own answer, or a scene that wants marked surfaces only). climbKit's ledge tests use it, so they pass in a world where another package (traverseKit's climb-by-rule) has registered a rule.
**1.1.9**: a hang now holds until the player asks to climb. A push toward the wall that was already held when the hang began (the pull-back that caught an edge just stepped off) no longer pulls up at once: the stick has to ease off for a moment (0.12 s) and push again. Jump still pulls up straight away; NPCs driving the body through the controller's input are unchanged.
**1.1.10**:
- Holding forward against a climbable wall starts the climb on its own after a short dwell (`autoClimbDwell`, 0.3 s by default; 0 turns it off), so a body standing on the ground climbs a wall such as a castle keep's stone base without a jump. This applies to NPCs driving the body through the controller too.
- Battered walls climb. A face that leans back as it rises (a castle's dry-stone base) no longer reads as its own top: the head probe is lengthened by the wall's lean, read from its normal, and the climber stands out from the face by that lean so its feet clear the stone.
- Over an overhang. A climb blocked by an overhang above (an eave, a keep's skirt roof) reaches out round its edge and pulls up onto the roof above, the way a climber goes over a cornice.
- No lurches. A single step this component makes is refused if it would carry the body more than 2.6 m in one frame, which stops a far-off ledge, corner or wall answer from throwing the body across a rooftop.
- The player's own controls are taken afresh at the start of each move.
**1.1.11**: letting go of a hang drops the body. The ledge just let go of (by pulling back, a jump away, or `release()`) is not caught as a hang again, neither by this component nor through `tryHang`, until the body lands or 1.5 s pass, so a script or kit that catches "the ledge below" after a drop no longer grabs the same edge straight back. Ledges more than 0.35 m lower, or more than 1.5 m along the wall, still catch.
**1.1.12** (follow-ups from the post-merge reviews of 1.1.6, 1.1.9, 1.1.10 and 1.1.11):
- A step that would be NaN is refused like a far one (the lurch guard compared with `>`, which NaN passes); refused steps warn at most every 2 s, and a hang that cannot be placed hands the body back instead of holding it in place.
- The wall under a ledge being hung from has to be steeper than 60 degrees (`wallRay` with `maxNormalY` 0.5); a roof slope seen from below lines the hang up on the edge instead.
- A wall or corner face with no horizontal direction is treated as no wall, in climbing and in corner turns (no divide by near zero).
- Falling fast with hang on, the air probe runs every frame again (20 times a second could skip the 0.8 m catch window at speed); a jump press is never throttled, and the throttle resets when a move hands back.
- The `autoClimbDwell` timer resets whenever the push is broken (stick released, hand-back, a new move), so taps no longer add up into a climb.
- A hang arms its pull-up once the push drops below 0.45 (was 0.3), so a diagonal stick while shimmying arms it; re-taking the player's controls keeps the push already held, so a late first report cannot pull up from a fresh catch.
- The overhang pull-up checks the way out from under the overhang is clear and runs its search at most 10 times a second while a climb is blocked.
- The released-ledge lock (1.1.11) clears as soon as the body stands, also stops the in-air pull-up back onto the same ledge, and leaves a ledge facing another way (across a narrow alley) catchable.
- Tests: the hang wall probe refuses a sloped roof underside.
**1.1.13** (review of 1.1.12): a hang spot that would be refused is refused before the controller is taken over (no stop in mid-air); a push kept across the controls re-take lapses after 0.25 s if the new activation never reports; the in-air released-ledge guard skips only the pull-up, so a lower ledge can still be hung from.
**1.1.14** (review of 1.1.13): the "move reported" flag resets before an activation that fails, so a push kept across the re-take still lapses; a hang probe that already failed in a frame is not run twice.
**1.1.15**: a climb or hang whose feet end up below the floor under them (a wall grabbed while dropping into a narrow gap) stands on that floor instead of holding still for good: every step up was blocked and the way down started inside the floor. It ends with `onClimbEnd` / `onHangEnd` reason `ground`.
**1.1.16** (review of 1.1.15): changelog in order; no code change.
**1.1.17**: a wall that goes on up under an eave or a cornice is climbed round it. When the head probe meets no wall but the top is still above reach (`too high`) or the column above the top is solid (`too tall`), the climb reaches out round the overhang (the same search a body blocked above makes, now `reachRoundOverhang`) and otherwise keeps climbing, instead of stopping below the eave for good.
**1.1.18** (review of 1.1.17): the overhang throttle's comment names both of its callers. A let-go rule for a wedged climb tried here was taken out again in review: it would drop a climber pushing up under an eave or shimmying into an inside corner.
**1.1.19**: version for the change above; the climbing code is 1.1.17's.
**1.1.20**: lips, shelves, eaves and slow machines.
- A ledge to hang from needs no room to stand on (`findLedge` option `forHang`), so a thin lip on a wall is caught on the way down; the hang sits out past a lip that sticks out of the wall, and is refused when something is over the hanging body (a roof seen from under its eave).
- Climbing up under a thin lip climbs up over it onto the wall above (`climbOverLip`, a mantle that ends climbing); pushing up from a hang on a lip does the same (`onHangEnd` reason `over lip`).
- A top within reach whose one landing spot is blocked (a post's cap) is pulled up onto a little to the side (`mantleBeside`).
- Pushed straight up under a block with no way round or over it, the climber edges sideways toward where it opens; in a dead end with neither side open it lets go after a second (`onClimbEnd` reason `no way up`; from 1.1.22 any pinned climb lets go, whatever the stick's direction). A head probe that starts inside geometry counts as blocked above, not as past the top.
- A body held out from the wall by a bump at its foot climbs straight up until the face is clear; a body a long frame pushed into the ground or a post beside the wall is moved to the nearest free spot; a hanging body is kept at its hang height.
- Long frames are climbed in steps of at most 1/30 s with the frame's input held for each step, so the head probe cannot pass a short face's top (Ledgework issue #12).
- `ledgeEntity`: the entity of the ledge hung from, mantled onto or climbed over, synced, cleared when the controller is handed back, for events that say which ledge was caught.
**1.1.21**: review fixes for 1.1.20 (PR #13). Climbing over a lip goes out, up, then in, so the body never passes through the lip, and ends with `onClimbStart`. `ledgeEntity` names the lip being climbed over and is cleared on hand-back. Pushing up at a wall top with nothing to pull onto (or with mantling off) holds still as before; only a body that cannot rise where it is edges sideways or lets go. The held-out straight-up step has no sideways part.
**1.1.22**: no climb holds the player for good. A climber that cannot rise where it is and whose stick (in any direction but down or away from the wall) moves it nowhere lets go after a second (`onClimbEnd` reason `no way up`): the pocket under a low eave, pushed sideways toward where the player is heading. With the head past a top whose one landing spot is blocked (a post's cap) and mantling on, the climber edges along the top for another spot and drops when the wall runs out, instead of holding still. When the step back in to the usual distance from the wall runs into something (a log's bulge) while straight up is free, the climb goes straight up. A shelf too narrow to stand on (up to 0.8 m deep, was 0.5 m) is climbed over like a lip, from below and from a hang on it, at a pace set by the whole path. Edging along a blocked top goes one way only and at most 2 m, then lets go (`no way up`), so it can never go to and fro. Checked on High Ground's Ridge Run with frames of 20 to 60 ms and spikes up to 270 ms: three of four keyboard runs finished, the fourth stalled at the post cap, which is what the second change fixes.
**1.1.23**: review fixes for 1.1.22 (PR #14). The search along a blocked top goes one way only and at most 2 m: one that would turn back (blocked at both ends) or runs out lets go (`no way up`), so it cannot go to and fro. Climbing over a lip or narrow shelf takes as long as its whole path (out, up, in), not the rise alone. ClimbMover README event list put back together.
**1.1.24**: a hang no longer waits for good on a push the player is already holding. A caught hang still holds for a moment when the stick was already toward the wall (so a catch does not flick straight into a pull-up), but a push held on toward the wall for 0.6 s pulls up (`HELD_PUSH_TIME`). A push held only partly toward the wall (more than 0.3 of it, less than the 0.6 a pull-up asks for) that shimmies nowhere pulls up (or climbs over a lip) after 0.4 s. Found on High Ground's Ridge Run, where a run-up held forward caught a roof eave and hung there.
**1.1.25**: hangs under a ledge that sticks out of the wall (a slab, a balcony's edge). A catch steps out from the wall, up to 0.6 m (was 0.44 m, and only when the body did not fit), until the body fits and nothing is over its head, so such a ledge is caught out in front of it, where it can be pulled up onto. A hang a long frame or a re-snap left under such a ledge steps out the same way (checked five times a second), instead of hanging there with the pull-up blocked above. Found on High Ground's Ridge Run under a slowed machine.
**1.1.26**: review fixes for 1.1.25 (PR #15). The catch's limit on how far it moves the body is checked on the final spot, after the step-out, and allows the step-out's 0.6 m on purpose. A shallow eave (underside ending within about 0.95 m of the wall) is now caught out in front of its edge, like a slab, and pulled up onto; a deeper eave is still refused.
**1.1.27**: safety nets so no wall or hang keeps the player. A climb or a hang whose stick is held (not down, not away from the wall) while the body stays within 5 cm for 2 s lets go (`onClimbEnd` / `onHangEnd` reason `no way up`): a corner the stick pushes into, a dead end along an eave the body can still rise a little under, a bar a rope hangs from with no wall above it. After a `no way up` let-go the same wall (facing the same way, within 2 m) is not climbed again for 3 s, so the player is not put straight back into the dead end. A hang keeps the colliders a `tryHang` caller excluded, so its overhead check agrees with the catch.
**1.1.29** (first sent as 1.1.28, changed on review in PR #16): `tryMantle(dirX, dirZ, exclude, opts)` takes an optional `opts` table for one call, applied by the new `Ledge.applyMantleOpts`: `minHeight` (clamped to -1 .. reach; a negative value lets the body step across onto a floor at or a little below its feet: tops down to half of it below the feet are found, landings down to all of it are taken), `maxHeight` (0 .. reach), `probeDistance` (0.1 .. 2 m) and `skipRiseCheck`. NaN and infinite values are ignored. `skipRiseCheck` skips the check for room straight above the body only when the body rises at most 0.3 m (the new `skipRiseUpTo` ledge option); such a step may duck 0.3 m under something over the head on its way across, while the landing still has to fit a standing body. A higher rise is always checked, so no top over a ceiling is reached. A step across fires `onMantleStart` with a height of 0 or less, and the mantle path then moves level or a little down. Why: a rope or pole often tops out level with the deck beside it, which a plain mantle (a ledge 0.4 m or more above the feet) never finds, so a climber at the top of such a rope stayed on it whatever they pushed. New tests: options clamped, stepping across onto a deck, stepping across under a rope's anchor beam, and a top over a ceiling refused even with `skipRiseCheck`. Calls without `opts` behave exactly as before.
**1.1.31** (first sent as 1.1.30, changed on review in PR #17): no hold at the foot of a wall. A climber whose stick is held down or away from the wall, whose feet have gone no more than 5 cm lower in 0.5 s, and who has ground within 2.5 m below now lets go and drops (`onClimbEnd` reason `blocked below`; a let-go like `drop`: no push-off, the usual regrab delay). That is the foot of a wall over a plinth or foundation that sticks out, which no step down can pass. Before, the going-nowhere rules only counted a stick held up or along the wall, so a player pushing down or away there was held for good (seen at a log cabin's stone foundation in High Ground's Ridge Run). The drop is measured over the whole half second, not frame by frame, so a slow step down at a high frame rate or with a light stick never counts as blocked. Higher up a wall (no ground within 2.5 m) a blocked climb down holds as before. The timer resets with the other climb timers (hand-back, a new climb, a climb over a lip). Pushing up or along still holds, and still lets go after 2 s of going nowhere.
**1.1.35** (sent as 1.1.32 to 1.1.34 in PR #18, changed on three reviews): three fixes found playing High Ground's Ridge Run on the current engine.
- `ignoreLedges` (new field, not synced): entity ids, separated by commas, whose tops this body never takes as a ledge: a ladder, pole or rope it holds. It joins every probe that could take the held thing for the ledge or the wall under it: the climb's top-out, the hang catch (ledge, wall under it, room for the body) and every room check while hanging (the five-times-a-second check, the re-snap, the shimmy and the corner turn), the pull-ups from a hang, a climb over a lip, a corner turn and the shimmy's edge, `tryMantle` and `tryHang`. Why: on a ladder whose rails stand above the deck it leads to, the top-out found the ladder's own top first and stood the climber on a 14 cm slab 0.9 m over the deck, where the next step fell back onto the ladder and caught it again, round and round. Whatever drives the body fills the field (traversalKit does, with the ladder held). `ledgeExclusions(extra?)` answers what the searches will leave out. Two new tests: a held ladder's own top is left out and the deck is found; the field is read with spaces and empty entries skipped and joined to a caller's list.
- A body with no `Locomotion` turned its back to the wall it grabbed: the facing fallback still assumed the old `{0, 0, 1}` front. The engine's default front is now the anchor's -Z (`transform.forward`, Locomotion's own default `{0, 0, -1}`), and the fallback follows it.
- Hand-back keeps the move's speed. The `CharacterController` walks from a walk of its own toward the input at its `acceleration` and `braking`, and resets that walk while it is switched off, so handing over only the input restarted every move from standing. For the one frame it is handed over, the controller's `acceleration` is 0 (reach the request at once); its own value is back once the controller has taken that frame (it clears the hand-back's one-frame jump), or after a quarter second at most, and also when ClimbMover is switched off or removed in between, or when the body is handed to another peer in between, so a 0 can never stay behind (the field is synced). Switching ClimbMover off also puts back the jump force and jump buffer a hand-back was holding. (1.1.32 wrote `velocityX`/`velocityZ` instead, which the controller only reports and never reads.)