climbKit
climbKit adds the traversal moves the built-in `CharacterController` does not have, as one component you put on a character's body:
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 = truecan be climbed by holding forward against them: up, down and sideways atclimbSpeed. 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):
-- 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.
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
cornerTimeseconds (cornerShimmyturns it off;onCornerfires). 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, andtryClimb(dirX, dirZ)starts climbing the climbable wall there: for assisted jump catches, dropping to the ledge below, AI and scripted sequences.hangCatchSpeedsets 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
GravityFieldframes. - 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 (
wallRaywithmaxNormalY0.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
autoClimbDwelltimer 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 (
findLedgeoptionforHang), 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 (onHangEndreasonover 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 (
onClimbEndreasonno 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,tryMantleandtryHang. 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
Locomotionturned 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
CharacterControllerwalks from a walk of its own toward the input at itsaccelerationandbraking, 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'saccelerationis 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 wrotevelocityX/velocityZinstead, which the controller only reports and never reads.)
Scoped to this part · feeds back into the world's score.