Guide

Game mantling and vaulting systems explained

Harbor Ruins shipped a mandatory cliff exit: a 1.4-meter lip players reached with a running jump — their capsule apex cleared the walkable plane, but collision resolution bounced them backward into the chasm. Playtest telemetry showed 58% of attempts ended in fall death even though the jump arc “looked” successful on replay. Designers widened the landing collider twice with no improvement. The fix was a mantle assist: when the player's chest probe intersects a grabbable lip within a defined height band, snap into a 0.65-second pull-up and place the capsule on the surface. Fall deaths on that beat dropped to 9%, and optional speed-vault clips preserved momentum for players who held sprint through the obstacle.

Mantling pulls the character onto a ledge they nearly reached; vaulting carries them over a waist-high obstacle without stopping on top. Both are traversal assists that convert near-miss jumps into successful state transitions — distinct from ledge hang (suspended below the lip) and from wall-run (lateral speed on vertical faces). Action adventures, open-world parkour stacks, and forgiving platformers all rely on height-band detection, animation selection, and handoff rules to other verbs. This guide covers probe geometry, mantle vs vault taxonomy, finite-state machine design, root motion vs procedural placement, hang integration, the Harbor Ruins refactor, a technique decision table, pitfalls, and a production checklist.

Mantle vs vault vs hang

Teams collapse these verbs because all involve “the ledge.” In production they are separate systems with different end states and player expectations.

Mantle — character ends standing on top of the surface. Input is often implicit (auto on lip contact) or a single “climb” button. Duration 0.5–0.9 s; player loses steering unless you blend early exit.
Vault — character clears an obstacle and lands on the far side without pausing on top. Preserves horizontal speed; common on chest-high cover and parkour lines. Duration 0.3–0.6 s.
Hang — character ends suspended below the lip, hands on the edge. Recovery verb, not reward. Mantle is the typical exit via “climb up.”

Document priority in your movement spec: action games often auto-mantle before offering hang; precision platformers invert that order so intentional near-miss grabs feel skillful. Mixing priorities without clear rules produces the classic bug: player wanted to hang for a puzzle but got yanked onto the platform.

Ledge detection probes and height bands

Mantle reliability is geometry, not player timing. Production implementations share these components:

Forward-up probe — box cast from upper chest (0.4–0.6 m above capsule center) forward 0.25–0.45 m and slightly upward. Active while airborne, rising, or within coyote time after leaving ground near a ledge.
Height delta — measure lip Y minus character foot Y. Mantle band typically 0.9–2.2 m for humanoid scale; vault band 0.6–1.3 m for waist-high obstacles. Reject if delta < min (jump already cleared) or > max (offer hang instead).
Clearance sweep — capsule cast along the pull-up arc; abort if head or shoulders intersect geometry. Log clearance_fail in playtest builds.
Surface normal — require walkable up-vector within 35° of world up unless you support sloped mantles explicitly.
Grabbable metadata — layer or tag MantleLedge; exclude moving platforms unless snap-synced to platform velocity.

Extend detection 100–200 ms after visual lip pass (mantle grace) so frame-perfect apex alignment is not required. Pair with jump input buffer so a late “up” press still triggers mantle on landing approach.

Mantle and vault state machines

Once a probe hit qualifies, transition from locomotion to a constrained traversal controller. Typical mantle FSM:

State	Entry	Allowed exits
Detect	Probe hit + height band OK	Approach snap, reject (clearance fail)
Approach snap	Horizontal align to lip anchor	Pull-up animation (80–120 ms)
Pull-up	Root motion or procedural Y lift	Stand on surface, interrupt (hit/damage)
Stand	Capsule on walkable navmesh	Locomotion, combat, jump

Vault FSM compresses this: Detect → Vault clip (single blended animation) → Land on far-side navmesh with preserved horizontal velocity (often 70–95% of pre-vault speed). Select vault variant by approach speed and obstacle width:

Step vault — low speed, narrow cover; hand on lip, feet pass over.
Speed vault — sprint entry; lateral leg lead, minimal vertical loss.
Kong / dash vault — both hands push, body passes low; best for continuous parkour lines.

Gate vault behind sprint or minimum speed (e.g. 4.5 m/s) so walking players get mantle-on-top instead of accidental vault-off the far edge.

Root motion vs procedural snap

Two placement strategies dominate; many shipped games blend both.

Root motion driven

Animation carries the mesh; code disables player steering and enables root motion on the skeleton. Pros: artist-authored hand placement on the lip, strong visual quality. Cons: variable end position per clip; must match lip anchors in level art or foot sliding appears. Mitigate with IK hand targets and a final 2–3 frame capsule snap to navmesh.

Procedural snap

Code moves the capsule along aBezier or linear curve; animation is cosmetic overlay. Pros: deterministic end position, easier networking, works on arbitrary lip heights within the band. Cons: can feel floaty if overlay does not match displacement speed. Tune curve duration to obstacle height: taller mantles need longer arcs, not stretched clips.

Hybrid pattern: procedural capsule for authority, upper-body overlay animation, foot IK to lip normal. Harbor Ruins uses hybrid with a 12 cm final snap to kill floating-point seam gaps.

Integration with hang, wall-run and combat

Mantle sits in the middle of a verb graph:

From hang — ledge hang “climb up” delegates to mantle with a shortened height band (player already aligned to lip).
From wall-run — exit jump near a ledge triggers mantle if apex probe hits; otherwise wall-run jump-off carry applies.
From ladder top — ladder dismount at apex often reuses mantle pull-up clip for visual continuity.
Combat policy — decide if mantle/vault grants i-frames; action games often grant 0.2–0.4 s vulnerability window at stand for risk/reward cover traversal.

Expose a single TraversalAssist API to level scripts: TryMantle(probeContext) returns enum Mantle | Vault | Hang | None so designers can reason about one detection pass instead of three competing raycasts.

Case study: Harbor Ruins cliff refactor

The mandatory exit cliff before the refactor:

Symptom — 58% fall death; replays showed apex above lip but capsule center below walkable plane at landing frame.
False fix — wider top collider caused standing inside geometry on flat approaches; reverted.
Height band — mantle enabled for delta 1.0–2.0 m with 0.15 s grace after lip pass.
Probe offset — moved forward 8 cm so running jumps registered before backward bounce.
Vault route — optional sprint line over a adjacent waist-high rubble uses speed vault; 34% of repeat players adopted it for time-attack.
Hang fallback — misses above 2.0 m still offer hang if downward speed < 10 m/s.

Fall deaths fell to 9%; median attempts to clear dropped from 4.1 to 1.2. Survey comments shifted from “unfair cliff” to “felt like Uncharted” — evidence the assist read as intentional polish, not invisible autopilot.

Technique decision table

Technique	Best for	Strength	Weakness
Mantle	Chest-head height ledges, near-miss jump recovery	Forgiving, low authoring cost on standard lips	Stops momentum; not for flow parkour chains alone
Vault	Waist-high cover, continuous sprint lines	Preserves speed; readable parkour fantasy	Needs width clearance; fails on thin rails
Ledge hang	Missed jumps, cliff faces, precision routes	Skill expression; enables shimmy puzzles	Slower; frustrates if accidental
Wall-run	Parallel walls, horizontal gap crosses	Flow and speed; strong spectacle	Requires tagged runnable surfaces
Ladder	Vertical shafts, explicit climb beats	Predictable pacing; easy to gate	Rail-like; breaks open exploration feel
Grapple	Large gaps, swing arcs	Spans arbitrary anchor distance	Aim friction; harder to tune

Common pitfalls

Mantle on every chest-high box — players cannot take cover behind low walls; tag vault-only vs mantle-only volumes.
No height band ceiling — auto-mantle on 3 m cliffs looks like teleportation; offer hang or reject.
Competing probes — hang and mantle fire on same frame; define priority table and log conflicts.
Root motion on moving platforms — character left behind or launched; inherit platform velocity during pull-up.
Vault without far-side navmesh — player vaults into void; validate landing polygon before starting clip.
Identical timing for all heights — 1 m and 2 m mantles feel same speed; scale duration with delta Y.
Silent failures — players repeat jumps; show subtle edge highlight or denial SFX when probe almost qualified.
Network transform-only replication — remote avatars slide; replicate mantle phase enum + lip anchor ID.

Production checklist

Define mantle and vault height bands per character scale in design wiki.
Implement forward-up probe with grace window and clearance sweep.
Build mantle FSM: detect, approach snap, pull-up, stand; vault FSM with speed gate.
Choose root motion, procedural, or hybrid placement; document networking authority.
Wire hang climb-up and wall-run exit into shared TryMantle API.
Scale animation duration to height delta; add final navmesh snap.
Tag MantleLedge / VaultCover layers; train level designers.
Log denial reasons in playtest builds for tuning sprints.
Playtest KB+M and gamepad; confirm sprint vault entry on both.
Telemetry: mantle success rate, vault adoption, fall deaths per authored lip.
Accessibility: optional higher bands or reduced pull-up time on assist modes.
Document verb priority (mantle vs hang vs vault) in movement design spec.

Key takeaways

Mantle converts near-miss jumps into standing on the lip — vault carries momentum over without stopping.
Height bands and probe geometry matter more than jump tuning for cliff frustration.
Harbor Ruins cut fall deaths 58% → 9% with banded mantle assist and probe offset.
Root motion vs procedural snap is a quality vs determinism trade; hybrids are common.
Integrate with hang and wall-run via one traversal-assist API and explicit priority rules.