# traversalKit.assists
The three amounts of help, swappable while running with the Traverser's `assist` field.
| Level | Jumps | Slips | Ridges | Grip | Climb by rule |
|---|---|---|---|---|---|
| `arcade` | steered onto ledges and posts within 1.6 m, +0.8 m reach | caught automatically | barely wobble, mostly self-correct | unlimited | generous: 62°+, 1.2 m+, any rough-ish surface |
| `standard` | steered within 0.9 m, +0.4 m | jump within 0.55 s to catch | a wobble you steer out of | unlimited | 68°+, 1.5 m+ |
| `strict` | no help | jump within 0.3 s | wobbly, no self-correction | runs out while holding on | 72°+, 1.8 m+, only rough stone and wood |
On every level, stepping off an edge and pulling back toward it catches it as a hang (the player's own move). Arcade also catches an edge you walk off without asking, and catches the ledge below when you let go (standard does the drop-catch too).
Fields of an assist level: `catchRadius`, `catchUp`, `magnet`, `slipCatchWindow`, `autoSlipCatch`, `wobbleScale`, `autoBalance`, `gripLimit`, `edgeCatch`, `dropCatch`, `regrabDelay`, `hangCatchSpeed`, `ruleSteepness`, `ruleRoughness`, `ruleMinHeight`, `ruleMaxHeight`.
```luau
local Assists = require("traversalKit.assists")
Assists.define("kids", { catchRadius = 2.2, autoSlipCatch = true, wobbleScale = 0.1 }, "arcade")
```
`get(id)`, `has(id)`, `define(id, def, base?)`, `list()`, `order`.
# ClimbCamera (traversalKit)
Camera framing for climbing and rooftop moves. Put it on the player's climbing body; `kit.equip` adds it (`camera = false` leaves it out). It works on the engine's orbit-follow camera (`@builtin::controller.orbital_follow`) and does nothing with any other camera.
On the peer that owns the body it eases the camera per move, then back to the player's own framing on the ground:
| Move | Framing |
|---|---|
| climbing, ladder, rope | pulls back (×1.2-1.25) and aims 0.55-0.6 m higher, so the next hold and the top are in view |
| hanging | pulls back ×1.2 and aims 0.8 m higher, at the ledge |
| pulling up, wall run | a little back and up |
| balancing, slipping | aims a little lower, so the drop reads |
| vault, wall run, slip | a short field-of-view kick for speed |
It keeps whatever zoom or aim height the player (scroll) or the game sets, using it as the new base, and writes to the camera only while a change is easing in, so the camera's own damping runs undisturbed the rest of the time.
| Field | Default | |
|---|---|---|
| `active` | true | frame the camera for climbing moves |
| `strength` | 1 | 0..1.5 scale on every framing change |
| `fovKick` | 6 | degrees of field-of-view kick on a vault, wall run or slip |
| `ease` | 3.5 | how quickly the framing follows the move, per second |
| `adoptCamera` | true | a player camera on the engine's legacy third-person behaviour (what a new world's player scene starts with) is moved onto orbit-follow once, so climbing is framed and the camera swings behind the climber at corners; off leaves the camera alone |
# 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.
```luau
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}`.
```luau
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.
# ClimbRig (traversalKit)
How a climber looks and sounds, on every peer. Put it on the same body as `Traverser` and climbKit's `ClimbMover`. It writes no synced state, so it runs everywhere and every player sees every climber the same way.
- **Animation**: crossfades the kit's climbing clips (`anims/`: climb up/side/idle, ladder, rope, hang, shimmy, mantle, vault, wall run, balance walk/wobble, slip, land roll) on the body's own Locomotion graph and back to walking, at the speed the climber moves and the feel's `animSpeed`.
- **Hands and feet on the holds**: four `IKLimb`s (the engine's IK): hands on the ledge edge while hanging or pulling up, hand over hand on the wall while climbing (on the rungs of a ladder), round the rope on a rope; feet on the wall, rungs or rope.
- **Facing**: turns the body the way a traversalKit move goes (rope, vault, wall run, balance); climbKit faces its own moves.
- **Sounds**: each hold kind's own grab, hand, foot and slip sounds plus vault, hard-landing, wobble and pull-up (`holdSounds.module`, through soundstage).
- **Feedback**: juiceKit `landingHard`, `shakeLight` on a slip or a helped catch, `dust` on a vault, fired once from the owner's peer (juiceKit shows it to everyone).
| Field | Default | |
|---|---|---|
| `animate` | true | play the climbing clips |
| `placeHands` / `placeFeet` | true | IK on hands / feet |
| `sounds` | true | hold sounds |
| `feedback` | true | juiceKit feedback |
| `volume` | 1 | hold sound volume |
The clips are made with the engine's animation generator (anim_gen) on a humanoid rig and play on any humanoid avatar; `anims/clipImport.module` takes out their travel, blends the loops' seams and trims the one-shots to the move. Replace any clip with your own by putting a clip of the same name in its folder (its play rate and length are set in `RATE` and `LENGTH` at the top of this component).
# navClimb
Tells navKit which walls traversalKit can climb. `link(opts)` probes every wall face round a point (or the walls you list): a face that climbs (by rule, or marked climbable) and has a top a character can stand on becomes a navKit `ladder` link from the ground at its foot to its top. An NPC on navKit's `climber` style (an aiKit guard, any `NavAgent`) then plans its route up that wall the way a player would climb it, instead of walking round.
```luau
local K = require("traversalKit.kit")
K.linkClimbableWalls({ center = { 0, 0, 0 }, radius = 40 }) -- once the level has loaded
```
Options: `center`, `radius` (60), `entities` (exact walls instead of a search), `spacing` (4 m between links on one face), `minHeight` (1.6 m; lower walls are stepped or mantled), `maxHeight` (14 m). `clear()` removes the links it made, `links()` lists their ids. Called by game code on every peer after the level is built (the links are navKit's own, which every peer registers the same way).
# traversalKit.holds
The catalogue of hold kinds: **stone** (stone blocks), **timber** (posts, beams), **tiles** (roof tiles and thatch), **rope**, **ladder**, **tree**, **cliff** (rock faces, terrain) and **bamboo**. Each kind carries how it handles (`climbSpeed` / `shimmySpeed` multipliers, `grip`, `slip` underfoot, `handSpacing` for hand IK, `snapAxis` for things climbed on one line), whether it is climbable by rule when steep, a gallery colour, and the words in a material or entity name that mark it.
```luau
local Holds = require("@root::traversalKit.holds") -- ~.holds inside the package
local c = Holds.classify(hit.entityId)
print(c.kind, c.source) -- "timber", "material"
print(Holds.get("rope").climbSpeed)
```
`classify(entityId)` walks the entity and its parents: a `ClimbSurface` component or `climbKind` attribute decides on purpose; otherwise the first collider's material name, then its entity name, then terrain (cliff). Smooth materials (glass, ice, metal, polished, …) are reported as `smooth`, which the climb rule never climbs. Results are cached for 2 s; `invalidate(entityId?)` clears them.
# traversalKit.rules
Climbable by rule, so a town or a mountain with sensible colliders just works with no tagging. traversalKit registers this test with climbKit (`ledge.addClimbRule`); it decides only for surfaces nobody marked (a `climbable` attribute or a `ClimbSurface` always wins).
A surface climbs when:
1. it is not a moving body (characters, dynamic or kinematic physics) and not smooth (glass, ice, metal, polished, chrome, plastic, lacquer, water, by material or entity name);
2. it is steep enough: at least the assist's `ruleSteepness` degrees from horizontal;
3. it is tall enough: the face stands at least `ruleMinHeight` above the ground under it (shorter ones are mantled and vaulted instead);
4. it gives a hold: a known hold kind by its material or name (stone, brick, ashlar, wood, timber, plank, bark, rock, cliff, granite, bamboo, rope, ladder, …) or terrain (cliff); or an unknown material at least `ruleRoughness` rough and no taller than `ruleMaxHeight`.
Usable edges (ledges, wall tops, eaves) are always grabbable and mantled by climbKit whatever the rule says.
```luau
local Rules = require("traversalKit.rules")
print(Rules.explain(wall.id, hit).reason) -- "stone by material", "too shallow (40 deg < 68)", ...
```
`install(assist)`, `uninstall()`, `explain(entityId, hit)`, `active()`, `RULE_NAME`.
# ClimbSurface (traversalKit)
Mark something climbable on purpose and say what kind of hold it is. Most surfaces need nothing: traversalKit climbs steep, tall, rough surfaces by rule. Use a marker for what the rule cannot see (a rope, a ladder, a bamboo pole too thin to have a face), to choose the hold kind, or to forbid climbing.
```luau
ladder.component.add("traversalKit.ClimbSurface", { kind = "ladder" })
glassTower.component.add("traversalKit.ClimbSurface", { climbable = false })
```
| Field | Default | |
|---|---|---|
| `kind` | `stone` | `stone`, `timber`, `tiles`, `rope`, `ladder`, `tree`, `cliff`, `bamboo`: how it handles, sounds and is held |
| `climbable` | true | true: always climbable; false: never (its ledges can still be grabbed and mantled). A `rope` is climbed by traversalKit's rope move along it, never as a wall, so climbKit is told it is not a wall. |
| `tint` | false | tint the Model with the kind's gallery colour (greyboxing) |
It writes the `climbable` and `climbKind` attributes climbKit and traversalKit read, on every peer, and applies changes while running, so a level can swap a wall from stone to tiles with one field. It marks its entity and everything under it.
# ClimbFollower (traversalKit)
An NPC that follows a player everywhere, up walls included. Put it on an NPC body that walks on the built-in `CharacterController` with climbKit's `ClimbMover` and traversalKit's `Traverser` (add `ClimbRig` so it looks the part), or spawn one ready-made with `kit.spawnFollower`.
```luau
local K = require("traversalKit.kit")
K.spawnFollower({ position = { 0, 0, 10 }, feel = "armoured" }) -- follows the nearest player
```
It drives the body only through the controller's input bus, like a player's controls, so every move of the kit is open to it. On walkable ground it follows a path from navKit (`NK.findPath`; it bakes a grid map once if none exists). When the one it follows is higher and no walk gets there, it heads straight for them: climbable walls are climbed, low ones mantled, smooth ones run up, ropes and ladders climbed, ledges pulled over. While holding on it pushes toward them.
| Field | Default | |
|---|---|---|
| `target` | none | entity to follow; empty = nearest player (with `followNearestPlayer`) |
| `followNearestPlayer` | true | |
| `followDistance` | 2.2 | stop this close (m) |
| `climbWhenHigher` | 1.0 | go straight and climb when the target is this much higher and unreachable on foot |
| `speedScale` | 1 | fraction of the body's move speed |
| `replanEvery` | 0.8 | seconds between path plans |
| `bakeIfMissing` | true | bake a navKit map once if there is none |
| `state` | (synced) | `idle`, `walking`, `climbing`, `waiting`, `lost` |
Events: `onStartClimb {height}`, `onReached`. Only the peer that owns the NPC runs it.
# traversalKit.feels
The four movement feels, each one table of the numbers that make a climber feel a certain way, spread over the CharacterController (`moveSpeed`, `jumpForce`, …), climbKit's ClimbMover (`reach`, `climbSpeed`, `shimmySpeed`, mantle times, kick-off, corner time) and traversalKit's own moves (vault speed and height, wall-run steps, balance skill, rope speed, grip time, animation speed).
| Feel | What it is |
|---|---|
| `nimble` | Light and quick: a shinobi who flows up walls and along ridges. 3 wall-run steps, steady on ridges. |
| `armoured` | Heavy and deliberate: a samurai in plate. Slow climbing, short reach, 1 wall-run step, wobbly on ridges. |
| `ordinary` | Cautious and human: a townsperson who climbs carefully. |
| `acrobat` | Showy and springy: long reach, 4 wall-run steps, big kick-offs, rolls out of hard landings. |
Switch while running with the Traverser's `feel` field (`kit.setFeel(body, "armoured")`). Add your own:
```luau
local Feels = require("traversalKit.feels")
Feels.define("ninjaCat", { climbSpeed = 3.0, reach = 2.8, label = "Ninja cat" }, "acrobat")
```
`get(id)`, `has(id)`, `define(id, def, base?)`, `list()`, `order`.
# traversalKit: climbing and rooftop movement for any character
A nimble character who scales walls, hangs off ledges, shimmies round corners, vaults fences at a run, balances along roof ridges and runs up walls to reach a higher edge: the movement a stealth game in a feudal castle town needs, and just as useful for platformers and adventures. Built on **climbKit** (mantle, wall climb, ledge hang and shimmy) and the engine's own CharacterController, IK and animation; works on keyboard, gamepad and touch, for players and NPCs, in multiplayer.
## Paste this into an empty world
Install traversalKit from ZeroMind (search **traversalKit**). If the new world has no `scenes/main.scene` yet, make one with a player first: in the editor's Scenes panel choose New scene with a player and set it as the startup scene (an agent runs `zero scene create --startup main player`). Then open `scenes/main.scene/build.luau` and add these lines at the end of `content()`, just before its `end` (the scene already has ground, light and a player `body`), then press play:
```luau
local K = require("traversalKit.kit")
K.equip(body) -- climbing, ledges, vaults, ridges, ropes, IK, sounds
local wall = entity.spawn("Wall") -- an ordinary box: it climbs by rule, nothing marked
wall.component.add("Model", { model = "cube" })
wall.component.add("BoxCollider", {})
wall.localPosition = { 0, 3, -6 }
wall.localScale = { 6, 6, 1 }
```
Walk into the wall and keep pushing: you climb it and pull up over the top. Walk off the top and pull back toward it: you catch the edge and hang; push left or right to shimmy round the corners, push toward the wall to pull up. The example guide (*Build a small climbing level from an empty world*) builds a whole course with vaults, ridges, ropes, a timer and a guard that climbs after you.
## Installs with it
Installing traversalKit brings everything it needs; nothing else has to be installed by hand:
| Package | Version | What traversalKit uses it for |
|---|---|---|
| climbKit (Ledgework) | 1.1.35 | mantle, wall climb, hang, shimmy, corners, climb rules |
| juiceKit | 1.2.12 | screen feedback: shakes, landing squash, dust on catches, slips and hard landings |
| navKit | 1.5.4 | NPC routes (ClimbFollower) and climb links for navKit's `climber` style |
| soundstage | 2.1.3 | the sound pool the hold sounds play through (footsteps and impacts too) |
| aiKit | 1.3.19 | the `climbingGuard` preset `ClimbNav` defines: aiKit's guard that climbs after a player (aiKit brings MatchFlow and SecondWind with it) |
The engine's own CharacterController, IKLimb and animation graph come with every world. For keyboard, gamepad and touch control schemes add **controlsKit** (checked with 1.4.4). aiKit and traversalKit must share one navKit: install aiKit and navKit at versions that agree (aiKit 1.3.19 with navKit 1.5.4), or a guard plans on a second navKit copy that knows nothing of the climb links.
## What it does
- **Climb up, down and sideways** on walls, cliffs, posts and trees; **grab a ledge, hang, shimmy, go round corners, pull up and mantle over** (climbKit).
- **Vault** a waist-high fence or wall at a run without breaking stride.
- **Balance** along a narrow ridge or beam: a wobble you steer out of, a slip down the roof you can catch at the eave.
- **Helped catches**: a jump is steered onto the ledge or post it is heading for; letting go catches the ledge below on the way down, a thin lip as well as a deep shelf (above a shelf the drop is carried out past its edge, so the shelf is caught as a hang instead of landed on); step off an edge and pull back toward it to hang from it (arcade catches it for you). The catch ends in a steady hang on every help level: keeping the stick pulled back holds it, and you pull up only when you ease off and push toward the wall again (or press jump). The help level decides how far out and how late a catch still works, with a scrabbling grab that slows the fall while the hands reach back: arcade 1.8 m and 1.3 s, standard 1.5 m and 1.0 s, strict 0.9 m and 0.7 s.
- **Ridges and beams**: a small push gives a wobble you recover from; a long one tips you off, and the ridge or beam is caught as a hang (arcade by itself, standard and strict with a jump press).
- **Lips, eaves and dead ends**: climbing up under a thin lip (a string course, a sill) climbs up over it onto the wall above, and pushing up from a hang on a lip does the same. Pushed straight up under an eave it cannot get past, the climber edges sideways toward where the eave opens; in a true dead end (no way up, round, over or to either side) it lets go after a second rather than pinning the player to the wall.
- **Ladders and ropes**; **wall run-ups** of a few steps to a higher edge.
- **Hands control back cleanly**: every move hands the CharacterController back its walking and jumping when it lands.
## No tagging needed
Surfaces climb **by rule**: steep enough, tall enough, and not smooth. On the arcade and standard help levels that is every solid wall a level already has, an ordinary unmarked box included; strict wants something that gives a real hold (stone, brick, wood, bark, rock, cliff, terrain or a rough material). Glass, ice, metal and polished surfaces never climb. An existing town or mountain with sensible colliders just works. To mark something on purpose and say what hold it is, add a `ClimbSurface` (`K.mark(entity, "ladder")`) or set it never climbable (`K.mark(entity, "stone", false)`). `K.explain(entity, hit)` says why a surface did or did not pass.
## Swap while it runs
| Setting | Choices |
|---|---|
| Movement feel (`feel`) | `nimble`, `armoured`, `ordinary`, `acrobat` |
| Hold kind (`ClimbSurface.kind`) | `stone`, `timber`, `tiles`, `rope`, `ladder`, `tree`, `cliff`, `bamboo`: each handles, sounds and is held differently |
| Help (`assist`) | `arcade`, `standard`, `strict` |
Every feel, hold kind and help level carries `tags` ("heavy", "stealth", "roof", "slippery", "easy", "speedrun" and more), and each list filters by them: `require("traversalKit.feels").withTag("heavy")`, `require("traversalKit.holds").withTag("slippery")`, `require("traversalKit.assists").withTag("easy")`.
`K.setFeel(body, "armoured")`, `K.setAssist(body, "arcade")`, a `TraverseZone` volume, or the `TraverseHud` buttons. The **gallery scene** (`scenes/gallery` in the High Ground world) shows all of them side by side.
## For game code
`K.state(body).mode` is `grounded`, `airborne`, `falling`, `climbing`, `ladder`, `rope`, `hanging`, `mantling`, `vaulting`, `wallrunning`, `balancing` or `slipping`, on every peer. Events fire on every peer: `onGrab`, `onRelease`, `onPullUp`, `onVault`, `onWallRun`, `onWobble`, `onRecover`, `onSlip`, `onCatch`, `onLand`, `onModeChanged`.
`onGrab` and `onCatch` say what was taken hold of: `kind` is the hold kind under the hands (also on a catch made while dropping onto a lip or shelf below); `ledgeId` is the entity of the ledge being hung from (or of the wall or hold being climbed; "" for a rope or a jump catch with nothing in hand) and `topY` the height of its edge. `onLand` and the `grounded` mode come only from real ground under the feet: letting go of a hang reports `airborne` and then `falling`, never a landing in mid air.
```luau
K.on(body, "onCatch", function(e)
if e.ledgeId ~= "" and entity(e.ledgeId).name == "BellTowerLip" then print("caught the bell tower at", e.topY) end
end)
K.on(body, "onGrab", function(e) print("grabbed", e.kind) end)
K.on(body, "onPullUp", function(e) print("up and over a", e.height, "m edge") end)
```
## NPCs
`K.spawnFollower({ position = p, feel = "armoured" })` makes an NPC that follows the nearest player (or a `target`) with navKit paths on foot and climbs, mantles, vaults and runs up walls after them.
Any navKit NPC can climb too: `K.linkClimbableWalls({ center = { x, y, z }, radius = 40 })` tells navKit about every wall traversalKit climbs, as a `ladder` link from its foot to a top a character can stand on. An ordinary **aiKit** guard on navKit's `climber` style then plans its chase up the wall. The `ClimbNav` component does both in one step: put it on the entity holding a navKit `multiLevel` map and it defines aiKit's `climbingGuard` preset (aiKit's `guard`, moving on navKit's `climber` style) and links the walls once the map has baked; then give the guard `aiKit.Brain` with `preset = "climbingGuard"`. The High Ground gallery has one.
## Touch
With controlsKit, a floating stick suits climbing best (it appears under the thumb; a gentle push climbs slowly, sideways on a ledge shimmies): `require("controlsKit.controls").setStick("floating", "left")`. While you hang or climb, the camera swings round behind the climber at corners, so up on the stick always points up the wall.
## Multiplayer
Each body's own peer runs its moves; the body's position replicates with the engine's interpolation (smooth, not snapping), `mode` and the events are synced, and `ClimbRig` draws every climber's animation, hand and foot placement and facing on every peer from that synced state. Feedback goes through juiceKit, which shows it to everyone.
## What it ships
| Part | |
|---|---|
| `kit.module` | the one interface: `equip`, `mark`, `setFeel`, `setAssist`, `state`, `on`, `spawnFollower`, `explain` |
| `Traverser.component` | the moves, synced mode and events |
| `ClimbRig.component` | animations, hand and foot IK (hanging hands rest on top of the lip), facing, sounds, soft fading dust puffs and feedback for every move, on every peer |
| `ClimbCamera.component` | camera framing per move (pull back and look up on walls, lower on ridges, a speed kick on vaults and wall runs), keeping the player's own zoom and the orbit rig's own distance (from its rings), so it never settles closer just because the rig's collision sweep pulled in. The camera stays out of walls, roofs and anything with a collider and aims for at least 2.9 m from the climber (a standing climber then fills at most about half the screen height, and on walls, ladders and ropes typically 25 to 35 %): when the way straight back is blocked it looks round and above the climber for a clear spot instead of closing in. From 1.0.24, when nothing near behind has room and the climber is not holding on, it looks all the way round and higher, and as a last resort looks down from high above, before settling anywhere under 1.2 m (on a hold it stays close to behind, because the stick is read against the camera there). Where there is truly no room (a body dropping past a roof's edge under a taller wall, the foot of a ladder under a deck) it can still come within about 0.3 to 0.7 m for up to half a second; on Ridge Run on 18 November that happened two or three times a run, never on a hold, and never with the camera inside a collider. From 1.0.22 it runs after the orbit rig each frame (`executionOrder` 50), so the spot it picks is where the camera really is; during a pull-up it looks for room from just above the ledge and, with none at 2.9 m, holds where it was; and with no room anywhere it never settles nearer than the rig's own spot. Trees and other drawn-only scenery never push it in: what is drawn between the camera and the climber with no collider (branches of a forest's instanced trees, which no raycast sees and which are read back from the renderer as the climber moves 15 m, and ordinary drawn-only meshes) is not drawn, the near plane moving out to 0.6 m before the climber. Under a lip or shelf the aim point drops so the camera keeps its distance. The rope being climbed (`Traverser.heldRope`) is left out of the camera's collision checks while held and for 1.5 s after letting go (a top-out still has the body against it), and the aim test skips everything on the rig's `cameraIgnore` list, so a rope running through the aim column no longer leaves the aim in a beam overhead and the camera in the climber's head (fixed at Ridge Run's rope 2 top-out in 1.0.20). The near plane clears what is drawn before the climber from where the camera really is as well as from where it was placed, since the orbit rig can hold the camera further out (1.0.20). Two read-only fields help debugging: `treeBoxes` and `clipNote`. The climber is never hidden: up to 1.0.20 the camera switched the climber's model off as a last resort when it had no room, through a setting every player shares and that only that camera's memory switched back on, so after a reload or a new play session a climber could stay invisible for good. From 1.0.21 the camera never hides the climber, and switches back on a climber model it finds switched off. When the lens comes within 0.5 m of the ground under it (a slope rising behind on a trail), the rig pitches up over it, at most three-quarters of the way to its top ring, and eases back to the player's own pitch once clear (1.0.21 also pitched up for a climber nearer than 1.2 m, which on a wall ended looking straight down on the head; 1.0.22 does not). For small props that should vanish while in the way (crates, lanterns, banners), add **viewClear** (Dockhands world) on their group, as Ridge Run does for its checkpoint banners; do not put holds the player climbs in such a group |
| `ClimbSurface.component` | mark a hold on purpose, choose its kind |
| `ClimbFollower.component` | NPC that follows players up walls |
| `ClimbNav.component` | the `climbingGuard` aiKit preset and the navKit wall links for it |
| `TraverseZone.component` | volume that switches feel / help |
| `TraverseHud.component` | mode readout and feel / help switchers (touch, mouse, F / G) |
| `holds.module`, `feels.module`, `assists.module`, `rules.module` | the catalogues and the climb rule |
| `holdSounds.module`, `sounds/` | grab, hand, foot and slip sounds per hold kind, plus vault, landing, wobble and pull-up |
| `anims/` | 15 humanoid climbing clips and the module that keys them |
| `docs/` | the two guides below |
| `tests/` | probes for the rule, holds and moves |
Guides (open with the `guides` tool): **How to make my character climb walls and ledges** and **Build a small climbing level from an empty world**.
## Limits
- Up is world +Y (no climbing in `GravityField` frames), like climbKit.
- The 15 climbing clips are made with the engine's animation generator (anim_gen) and made in place by `anims/clipImport.module`; hands and feet are placed by IK on top of them. Drop in your own clips under the same names to change them.
- One climb rule tuning is active per peer: the local player's assist level.
- Hanging just under a deep eave (the Ridge Run cabin), the hands rest on the roof but the forearms pass through the eave board.
- Slow machines: a long frame is climbed in steps of at most 1/30 s, and a body a long frame pushed into the ground or a post beside the wall is moved free, so climbing keeps working at low frame rates (Ridge Run finishes on keyboard with frames averaging 150 to 200 ms and spikes of several seconds). Frames longer than 0.1 s are still counted as 0.1 s, so below 10 frames a second everything, climbing included, runs slower than real time.
- A climber pinned where it cannot rise (a true dead end, a pocket under a low eave) lets go after one second of the stick asking for a way nothing gives, in any direction but down or away (`onClimbEnd` reason `no way up`). A player who wants to stay there eases off the stick. From climbKit 1.1.27 a climb or a hang whose stick is held (not down or away from the wall) while the body moves less than 5 cm for 2 s lets go the same way, including a hang pushed sideways at a ledge's dead end; after any `no way up` let-go (from a climb or a hang) that wall is not climbed again for 3 s, so the player is not put straight back into it. From climbKit 1.1.31 a stick held down or away at the foot of a wall that sticks out below (a plinth, a foundation) lets go after 0.5 s of going no lower when the ground is within 2.5 m (`onClimbEnd` reason `blocked below`). A rope topped out from is not taken again for 4 s, nor ever from a standing height near its top (1.0.21). From 1.0.22 a light push (about 15 % of the stick or a short touch drag) gets a climber off a rope's top: at Ridge Run's rope 1, 1.0 s with the gamepad stick at 35 % and 1.1 s with a 45 px touch drag, where 1.0.21 wanted half the stick and a person measured 1.7 s on gamepad and up to 9 s on touch. Also from 1.0.22, a player pushing with no headway on the ground for half a second gets help: into a climbable wall at a slant the climb starts (a missed jump into the alley under Ridge Run's second house: out in 0.6 to 3.9 s at any angle from 50 to 80 degrees off straight in, where a person stood 24 s), and against a wall that gives nothing the push turns along it to the side that is open and has ground under it, further each time it is stuck again; never away from a ladder or rope being walked into. On 18 November 2026 (traversalKit 1.0.24, climbKit 1.1.35) a scripted route driver ran Ridge Run through real simulated input on a heavily loaded desktop (5 to 30 frames a second): keyboard finished start to finish twice (2:41 and 2:56) and gamepad once (3:07), every checkpoint, no falls, and a watcher saw no stall, no rope or ladder loop, the camera never inside a collider and the climber never hidden. Other runs that day did not finish, all at the jumps to the post and the ledge: at that frame rate the driver's jumps fell short, and from the alley under the second house the driver could not find its way back, though a steady push into the house's stone wall climbs out onto the ledge in about 5 s (most push angles; the first 2 s are the wait before a push into a wall starts a climb). One finding was real and is fixed in Ridge Run 0.1.9: the stone bases of the second and third houses stopped above a dip in the ground, so a climber there grabbed the stone, found no wall at the feet and let go, over and over; and the cabin's corner fill left a pocket and a shelf under the eave. Touch was driven once and stopped in that alley; a full touch run and the second gamepad run are not proven on this version. A scripted driver steers differently from a person, so stalls that depend on how a person arrives are not proven gone.
- Ropes top out on any push but down within their last 35 cm: onto a floor about level with the feet up to 1.3 m away (a deck or roof beside the rope's top), the way pushed first and then round the rope, or else onto a ledge above the feet, the way pushed and then all the way round (1.0.24; before, a roof behind the climber was never tried, and a push the wrong way held them at the top).
- Arrivals (1.0.24): after any pull-up (a wall, a ladder, a post, a rope's top, a ledge), for 1.5 s, and until the stick is let go or a jump is asked for, walking stops short of a drop deeper than 0.9 m, so the push that carried the climber up no longer walks them straight off a small top and back onto the hold. A ladder being climbed is on climbKit's `ignoreLedges` list (climbKit 1.1.35), so its own rails are never taken for the top: before, Ridge Run's second ladder stood the climber on a 14 cm slab 0.9 m above the deck. A narrow top only counts as a beam to balance along when it runs on for 1.2 m, so a post cap is somewhere to stand. Measured with a sweep (every feel, every help level, the stick held at -90 to 180 degrees from the moment of the pull-up): ladder 1, ladder 2 and the post cap stand the climber on top every time; the only exceptions were the climber walking on along the roof to a corner and stopping there, or onto the rope that hangs beside ladder 2's deck.
- Hand-back (1.0.24 and climbKit 1.1.35): the engine's CharacterController now speeds up and brakes toward the stick (`acceleration`, `braking`) from a walk of its own that it resets while switched off, so a vault or pull-up handed back only the input restarted from standing. Both kits now hand the move's own speed across with one frame of `acceleration` 0, and the controller's own feel is back the next frame.
- Facing (1.0.24): a body with no `Locomotion` faces `transform.forward` (the engine's default front, Locomotion's own default `{0, 0, -1}`); ClimbRig and climbKit both assumed the old `+Z` and turned such a body's back to the wall. A floor at the feet wins over a beam overhead (the rope's own anchor). This needs climbKit 1.1.29 or later (`tryMantle` options).
## Reused versus new
traversalKit is the new layer; most of what it does runs on published parts and the engine.
| | Code (Luau lines) | Share |
|---|---|---|
| climbKit 1.1.35, juiceKit 1.2.12, navKit 1.5.4, soundstage 2.1.3, aiKit 1.3.19 | 28,510 | 84% |
| traversalKit itself | 5,391 | 16% |
Also reused, not counted: the engine's CharacterController, IKLimb and animation graph. The High Ground world as a whole is about 97% installed code (236,116 lines across 11 installed packages and the 16 packages they depend on) against 3% made for it (7,960 lines: traversalKit 5,391, Ridge Run 1,233, scenes and world components 1,336), counted on 18 November 2026. `reuse-review.md` in the High Ground world rates every installed part 1 to 5 and lists what was built new.