Log inGet started
Package

climbKit.package

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

SituationMove
Grounded, jump pressed, moving toward a top ≤ reach above the feetmantle
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 feethang
Pushing into a climbable wall (blocked, or airborne, or jump)climb (mantles instead if the top is in reach)
Climbing, head past the topmantle over
Climbing down onto groundstand
Climbing/hanging + jumpkick off (kickOffSpeed out, kickOffUp up)
Climbing/hanging + jump while pulling away, or hanging + backdrop (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 jumppull up
Hanging + sidewaysshimmy

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

FieldDefault
mantleEnabled / climbEnabled / hangEnabledtrueturn each move on or off
reach2.3highest top above the feet a jump mantles onto (m)
walkReach1.2highest top walking into it steps up onto
autoMantleWhileWalkingtruewalk-up without a jump press
autoMantleInAirtruegrab ledges in reach while airborne and moving toward them
minLedgeHeight0.45lower tops are left to the controller's step
probeDistance0.6how far ahead of the body to look for an edge (m)
maxTopSlope42steepest top it lands on (deg)
mantleMinTime / mantleMaxTime0.35 / 0.6mantle duration, scaled by height
climbSpeed1.6m/s up, down, sideways on a wall
wallGap0.05gap kept off the wall
kickOffSpeed / kickOffUp3.5 / 4.0jump off a wall or ledge
shimmySpeed1.1sideways along a ledge
hangDepth2.0feet below the ledge top while hanging
regrabDelay0.4seconds before grabbing again after letting go
autoClimbDwell0.3seconds 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). 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

FieldDefault
hangCatchSpeed2.5fall speed (m/s) above which an edge dropped past is caught as a hang
cornerShimmytrueshimmy round outside and inside corners
cornerTime0.3seconds 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.