Log inGet started
Package

Traverser.component

Newest version

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

MoveHow it starts
Climb by ruleAny 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.
VaultRunning at vaultMinSpeed or faster at a thin top up to vaultMaxHeight (feel) with ground beyond: over it in vaultTime, keeping the run's speed.
BalanceWalking 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 catchA 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 runRunning 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.
RopeTouching 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.
LadderA surface of kind ladder climbs through climbKit at the ladder's speed; the mode reads ladder.
Helped catchAirborne toward a ledge or post within the assist's catchRadius: steered onto it and caught.
Drop and catchLetting go of a ledge (back) catches the next ledge below (assist dropCatch).
Edge catchStepping 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

FieldDefault
feelnimblenimble, armoured, ordinary, acrobat (see feels.module). Change it while running.
assiststandardarcade, standard, strict (see assists.module). Change it while running.
climbByRuletruesurfaces nobody marked climb by rule
vaultEnabled, balanceEnabled, wallRunEnabled, ropeEnabled, assistEnabledtrueeach 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.