Guide

Game ledge hang and shimmy systems explained

Harbor Spire's outer cliff is a six-platform ascent over a 200-meter drop. Each platform is reachable with a standing jump from the one below — on paper. Playtest telemetry showed 71% of entrants dying on the first cliff face because their jump apex cleared the lip by millimeters, then gravity pulled them past the edge with no recovery state. Designers widened platforms twice; deaths fell only to 64%. The real problem was missing verb: players needed to grab the underside of a ledge, hang, shimmy to a safer anchor point, and either climb up or jump off — not instantly mantle onto the surface like a third-person cover shooter.

Ledge hang is a suspended locomotion state triggered when the character's hands contact a validated platform lip while airborne or falling. From hang, the player can shimmy laterally along the edge, pull up via a mantle handoff, drop, or jump away (often chaining into a wall-jump if a vertical face is adjacent). Unlike ladder climb, which requires authored ladder geometry, ledge hang works on any grabbable platform edge. This guide covers lip detection and grab windows, the hang state machine, shimmy bounds and corner rules, stamina and slip-off timers, climb-up transitions, camera and capsule changes, level authoring envelopes, the Harbor Spire refactor, a technique decision table, pitfalls, and a production checklist.

Hang vs mantle: two different ledge verbs

Teams often conflate these because both involve “the ledge.” In production they are separate systems with different detection volumes and player expectations.

Mantle / vault — character ends standing on top of the surface. Detection is a height band in front of the lip; motion is a short scripted pull-up. Best when the player clearly reached standing height at the edge.
Ledge hang — character ends suspended below the surface, hands on the lip, feet dangling. Detection is a forward-up probe during fall or jump apex. Best when the player almost made it — recovery, not reward.

Hang can transition into mantle via a dedicated “climb up” input, but the entry condition is more forgiving: you grab while still below the walkable plane. Many precision platformers (Celeste-style climbs, Metroidvania cliff faces) treat hang as the primary verb and mantle as the exit. Action adventures often invert that priority. Document which verb is canonical in your movement spec so level designers know whether to author “near-miss recovery” or “auto-pull-up” ledges.

Lip detection and grab windows

Grab reliability is probe geometry, not player skill. Production implementations share these components:

Lip probe — a box or ray cast from the character's upper chest forward and slightly upward, active only while airborne and not already hanging. Typical size: 0.3–0.5 m forward, 0.2 m up from capsule center.
Grabbable tag — surface metadata: GrabbableLedge, exclude moving platforms unless snap-synced, exclude crumble platforms after break state.
Approach filter — optional max downward speed (e.g. 12 m/s) so terminal-velocity falls skip grab unless a parachute or glide verb is active.
Grab grace — extend detection 100–400 ms after the lip would visually pass the hands; pairs with coyote-time philosophy for ledges.
Input policy — auto-grab on lip contact vs hold “grab” button. Auto-grab feels better on console; hold-grab enables intentional fall-through for speedrun routes.

Log denial reasons in playtest builds: speed_too_high, lip_too_thin, moving_platform_unsynced, already_hanging. Most “ledge is broken” bugs are thin colliders without grabbable metadata.

Hang state machine

Once grab succeeds, transition from airborne locomotion to a constrained hang controller. A typical FSM:

State	Entry	Allowed exits
Grab	Lip probe hit	Hang (after 80–150 ms snap animation)
Hang idle	Snap complete	Shimmy, climb up, drop, jump off, slip (timer)
Shimmy	Horizontal input while hanging	Hang idle at boundary, corner wrap, slip
Climb up	Up input or auto after delay	Standing on platform (mantle handoff)
Drop	Down input	Airborne fall
Jump off	Jump input	Airborne with lateral + upward impulse
Slip	Stamina expired or hazard	Airborne fall (no re-grab for 300 ms)

Zero horizontal velocity on grab entry unless you explicitly preserve momentum for skill jumps. Snap the character's hands to the lip anchor point (nearest point on ledge polyline) to avoid floating-hand artifacts. Freeze gravity while in hang states except during drop/slip transitions.

Shimmy bounds, corners and one-way edges

Shimmy lets players reposition along the lip before committing to climb or jump. Implementation details that affect feel:

Traversable span — precompute grabbable polyline per platform; shimmy clamps X (or arc-length) to endpoints minus half body width.
Corner behavior — outer corners allow wrap to perpendicular ledge segment; inner corners block shimmy (prevents clipping through V-shaped rock).
One-way platforms — if the top surface is one-way, hang still works on the solid lip collider; document whether jump-through is allowed from hang (usually no).
Shimmy speed — 1.5–3.0 m/s feels responsive; slower reads as stuck; faster skips hazard telegraphs on narrow lips.
Drop-through intent — down + jump from hang should not accidentally trigger climb-up; use input chord priority table.

Author ledge segments at least 1.2 m wide for tutorial shimmies; production cliffs can be narrower if stamina timer is generous.

Stamina, slip-off and tension

Unlimited hang removes tension and breaks vertical pacing. Common limit models:

Fixed timer — 4–8 seconds then forced slip; show subtle hand tremor animation at 75% elapsed.
Stamina bar — drain while hanging and shimming; regen only on ground. Enables upgrades that extend hang time.
Chalk / grip resource — consumable per grab; common in climbing sims ported to action platformers.
No limit in safe rooms — disable timer below hazard height or in tutorial zones.

Slip-off should telegraph 1–2 seconds before failure: audio strain cue, finger slip VFX, controller rumble ramp. Sudden drops without warning read as input lag. After slip, apply brief re-grab cooldown so players cannot infinite- stall on the same lip frame-by-frame.

Climb-up, jump-off and verb chaining

Exit verbs define how hang connects to the rest of your jump and gravity model:

Climb up — delegate to mantle system with shortened height band (character already at lip elevation). Root-motion clip or procedural snap onto walkable navmesh.
Jump off — apply impulse away from wall: typically 3–5 m/s up and 2–4 m/s lateral. Does not consume double-jump charge if your design treats hang as grounded-equivalent.
Wall-jump chain — if adjacent vertical face within probe range, jump-off can auto-face wall normal and enable wall-jump on next frame.
Drop — restore full fall gravity; optional fast-fall if down held.

Publish whether hang resets air-dash and double-jump charges. Ambiguity here breaks route planning in shaft levels.

Camera, capsule and animation

Hang changes the character silhouette and collision envelope.

Capsule resize — shorten height by 30–50% while hanging; restore on climb-up. Prevents head clipping into platform above.
Camera — pull back 0.5–1.0 m and lower pitch 10–15 degrees so feet and hazards below stay visible.
Animation — hang idle loop, shimmy blend by velocity, strain overlay near stamina end. IK hands to lip normal for uneven rock.
Feedback — distinct grab SFX from mantle; dust on slip; white edge highlight on grabbable lips in tutorial only.

Harbor Spire cliff refactor

Before the refactor, Harbor Spire relied on mantle-only detection at cliff lips. Players who undershot jumps slid past without state change. The movement team shipped:

Lip probe with 0.4 m forward box and 350 ms grab grace after apex pass.
Auto-grab on contact (hold-grab optional in accessibility menu).
6-second stamina timer with tremor telegraph at 4.5 s.
Shimmy along full platform width at 2.2 m/s; inner corners blocked.
Climb-up handoff to existing mantle clip (0.7 s).
Jump-off impulse 4.2 m/s up, 3.0 m/s away from cliff face; does not consume double jump.
Re-grab cooldown 400 ms after slip to prevent stalling.

Fall deaths on the outer cliff dropped from 71% to 14%. Median attempts-to-clear fell from 4.8 to 1.9 without widening platforms a third time. Speedrunners retained skip routes by disabling auto-grab via hold-grab setting.

Technique decision table

Approach	Best for	Tradeoff
Ledge hang + shimmy	Cliff recoveries, near-miss jumps, tension climbs	Needs lip colliders; stamina tuning required
Mantle only	Action adventures, cover traversal, clear lip contact	No recovery when jump undershoots
Wall-jump	Parallel-wall shafts, rhythmic ascent	Requires vertical faces, not platform undersides
Ladder climb	Industrial interiors, explicit climb paths	Authored geometry only; not emergent on any ledge
Grapple hook	Long gaps, arbitrary anchor points	Skips lip tension; needs placed anchors
Wider platforms only	Casual audience, first-time play	Reduces skill expression; may not fix apex timing

Add ledge hang when heatmaps show deaths just below platform lips with horizontal alignment but insufficient apex height. Prefer mantle when players consistently reach standing height at edges. Combine hang + mantle so climb-up is the seamless exit.

Common pitfalls

Thin lip collider without grabbable tag — probe hits walkable top but not hang lip; split colliders explicitly.
Grab grace too short — frame-perfect apex requirement feels broken at 30 FPS on handheld.
Mantle and hang fight for input — same button triggers wrong state; define priority when both volumes overlap.
Shimmy through inner corners — capsule clips into rock; block or wrap with explicit corner nodes.
Moving platform hang without sync — hands detach or character drifts; parent hang anchor to platform velocity.
Silent stamina drain — players blame controls; always telegraph slip.
Jump-off consumes double jump — punishes recovery into continued ascent routes.
No re-grab cooldown — infinite hang on single-pixel lips breaks challenge.
Full-height capsule while hanging — head clips into platform; players think climb-up is blocked.
Networking hang without lip anchor sync — remote characters float; replicate anchor position and shimmy offset.

Production checklist

Document hang vs mantle priority in movement design spec.
Publish lip probe size, grab grace duration, and approach speed cap.
Tag all grabbable lips with GrabbableLedge metadata.
Implement hang FSM: grab, idle, shimmy, climb, drop, jump, slip.
Define shimmy endpoints, corner wrap rules, and inner-corner blocks.
Set stamina model and slip telegraph timing.
Wire climb-up handoff to mantle with shortened height band.
Specify jump-off impulse and double-jump / air-dash charge policy.
Resize capsule on hang entry; restore on climb-up.
Adjust camera pull-back and pitch for hazard visibility.
Add grab / strain / slip SFX and optional tutorial lip highlight.
Log grab denial reasons in playtest builds.
Author minimum 1.2 m shimmy spans in tutorial zones.
Test at 30, 60, and 120 FPS with fixed physics timestep.
Sync hang anchor, shimmy offset, and stamina in multiplayer.

Key takeaways

Ledge hang recovers near-miss jumps; mantle rewards clean lip arrival — keep both verbs distinct.
Grab grace (100–400 ms) and lip probes matter more than platform width for first-attempt success.
Harbor Spire cut fall deaths from 71% to 14% with hang FSM and shimmy — no third platform resize.
Stamina and slip telegraphs create tension without frame-perfect frustration.
Climb-up must hand off cleanly to mantle; jump-off charge policy must be documented for route planners.