Traverser.component
README.md
Traverser (traversalKit)
The rooftop-and-climbing layer on a character body. Put it on a body that walks on the built-in CharacterController and carries climbKit's ClimbMover (the player body a PlayerPrototype names, or an NPC). Add ClimbRig beside it for animations, hand/foot IK, sounds and feedback. traversalKit.kit.equip(body) adds all three.
body.component.add("climbKit.ClimbMover", {})
body.component.add("traversalKit.Traverser", { feel = "nimble", assist = "standard" })
body.component.add("traversalKit.ClimbRig", {})
What it adds to climbKit
| Move | How it starts |
|---|---|
| Climb by rule | Any steep, tall-enough surface of a climbable material (stone, wood, bark, rock, terrain, rough unknowns) climbs with no marker. Registered with climbKit's ledge.addClimbRule; climbByRule = false turns it off. |
| Vault | Running at vaultMinSpeed or faster at a thin top up to vaultMaxHeight (feel) with ground beyond: over it in vaultTime, keeping the run's speed. |
| Balance | Walking along a top narrower than the body (a beam, a wall cap, a roof ridge): movement is held to the ridge, sideways input steers a wobble. Past full lean: a slip. |
| Slip and catch | A slip slides down the roof to the eave and falls; jump in the window (assist slipCatchWindow, automatic on arcade) catches the edge as a hang. |
| Wall run | Running into a wall with jump when its edge is beyond a jump's reach but within wallRunSteps x wallRunRise: a few steps up, then a mantle or a hang. |
| Rope | Touching a surface of kind rope (or jumping at it): climb up and down along it, sideways goes round it, jump leaves it, pushing on at the top pulls onto the ledge there. |
| Ladder | A surface of kind ladder climbs through climbKit at the ladder's speed; the mode reads ladder. |
| Helped catch | Airborne toward a ledge or post within the assist's catchRadius: steered onto it and caught. |
| Drop and catch | Letting go of a ledge (back) catches the next ledge below (assist dropCatch). |
| Edge catch | Stepping off an edge and pulling back toward it within 0.9 s catches it as a hang, on every help level; arcade catches an edge walked off without the pull-back. Walking or running straight off still drops. |
Hold kinds tune climb and shimmy speed; under the strict assist, grip drains while holding on and lets go at zero.
Fields
| Field | Default | |
|---|---|---|
feel | nimble | nimble, armoured, ordinary, acrobat (see feels.module). Change it while running. |
assist | standard | arcade, standard, strict (see assists.module). Change it while running. |
climbByRule | true | surfaces nobody marked climb by rule |
vaultEnabled, balanceEnabled, wallRunEnabled, ropeEnabled, assistEnabled | true | each move on or off |
Telemetry (synced: read it on any peer)
mode: grounded, airborne, falling, climbing, ladder, rope, hanging, mantling, vaulting, wallrunning, balancing, slipping. hold: the hold kind in the hands (or underfoot on a ridge), holdMaterial, balance (-1..1), grip (0..1), gripX/Y/Z (where the hands hold), ropeAxisX/Y/Z, facingX/Z, moveProgress.
Events (synced: they fire on every peer)
onModeChanged {from, to}, onGrab {kind, how}, onRelease {kind, reason}, onPullUp {height}, onVault {height, speed}, onWallRun {steps, height}, onWobble {amount}, onRecover, onSlip {side}, onCatch {assisted, how}, onLand {speed, heavy}.
local tr = body.component.get("Traverser")
tr.events.onGrab:connect(function(e) print("grabbed", e.kind) end)
tr.events.onPullUp:connect(function(e) print("up and over", e.height) end)
Methods
setFeel(name), setAssist(name), isHolding(), letGo().
Multiplayer and controls
Only the peer that owns the body runs the moves; the body's position replicates with the engine's interpolation, mode and the events are synced, and ClimbRig draws every climber on every peer. It reads the controller's input bus (whatever drives the body: the controller's own input map, controlsKit's schemes on keyboard, gamepad and touch, or an AI), so there are no new bindings.
Balance direction
A balance runs along the beam itself: the longer horizontal axis of whatever is underfoot (a beam, a ridge cap, a roof slab), pointed the way the player is going, so stepping on a few degrees off still walks straight along it. Shapes with no clear long axis (terrain ridges) follow the direction the player stepped on with.
Ropes
- Up and down on a rope follow the player's forward (stick, keys or touch pad) against the camera, the same way a ladder does, whichever side of the rope they caught it from. AI and scripted climbers use the way the body faces.
- The lowest hold is floor-aware: a rope whose foot hangs just above a deck or roof keeps the climber's feet on that floor, and pushing down there steps off onto it.
- At the top, pushing on pulls onto the ledge the player is pushing toward first, then onto one the body faces.