ClimbMover.component
README.md
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.
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.
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).optswidens the search for one call (seeLedge.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) andskipRiseCheck(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 firesonMantleStartwith 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 theclimbableattribute 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?)andtryHang(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.