Guide

Game ceiling cling and crawl traversal systems explained

Harbor Catacombs shipped a three-room inverted tunnel where players crawl upside-down under spike-lined ceilings while bats patrol below. Playtest telemetry showed a 47% death rate on the gauntlet — not because the encounter was unfair on paper, but because attachment felt binary: players snapped to ceilings one frame late, crawled at floor speed on inverted collision normals, and dropped through gaps when jump input conflicted with detach logic. Level designers loved the fantasy; engineers had bolted ceiling cling onto ground locomotion without a dedicated finite state machine.

Ceiling cling and crawl is a vertical traversal verb distinct from wall slide, ledge hang, and global gravity flips. It keeps world gravity downward for readability while locally reorienting the character to a ceiling surface, applying inverted input mapping, and managing attach/detach windows that must cooperate with coyote-time leniency. This guide covers attachment probes, crawl physics, stamina and slip-off, camera handling, transitions to floor and wall verbs, the Harbor Catacombs refactor, a technique decision table, pitfalls, and a checklist.

Two implementation families: local cling vs global inversion

Teams confuse ceiling crawl with gravity inversion. They solve different problems:

Local ceiling cling — gravity stays world-down; the character attaches to tagged ceiling colliders, flips sprite and hitbox orientation, and uses inverted vertical input for “toward ceiling” movement. Megaman-style tunnels, stealth crawl spaces, spike gauntlets.
Global gravity flip — the entire physics basis rotates; floor becomes ceiling for everyone in the zone. Better for puzzle rooms where orientation is the mechanic, worse for mixed floor/ceiling combat in one screen.

Harbor Catacombs uses local cling in rooms 2–3 and a zone flip pad only in the boss antechamber. Mixing both without clear telegraphs caused 19% of deaths when players entered cling state during an active flip cooldown. Pick one primary model per encounter unless transitions are explicitly taught.

Attachment probes and the grab window

Reliable cling starts before the player sees it. Cast one or more upward (or along-surface-normal) raycasts or shape casts from the character capsule each fixed tick while airborne or within a short post-jump window:

Surface tag — only CeilingClingable layers attach; decorative overhangs use a different tag so players do not stick to aesthetics.
Normal threshold — reject surfaces whose normal deviates more than ~15° from world-up unless your game supports curved caverns with explicit spline attachment.
Clearance check — verify headroom between ceiling and floor hazards (bats, spikes) before snapping; Harbor rejected attaches when bat patrol AABB intersected the crawl lane within 0.4s.
Approach velocity cap — high upward speed on jump can overshoot; clamp or apply a 2–4 frame attach buffer when vertical velocity is within a band.

The grab window extends attachment slightly after leaving the ceiling (mirror of coyote time). Harbor uses 6 frames at 60 Hz for detach forgiveness when players tap jump to cross a one-tile gap — without it, 31% of intended gap crosses became accidental full drops into bat lanes.

Crawl FSM: attach, move, drop, and handoffs

Treat ceiling locomotion as its own state machine, not a bool on ground movement:

States

Attach — one-shot snap: align capsule to ceiling offset, zero vertical velocity relative to surface, play attach VFX/audio.
Crawl — lateral motion along ceiling tangent; speed often 70–85% of ground run to sell friction and readability.
Idle cling — zero input; optional subtle sway animation so the character does not look frozen.
Slip — stamina exhausted or damage stagger; progressive slide toward open edge before forced detach.
Detach — intentional jump off or forced fall; restore world gravity integration immediately.

Input mapping

Invert the axis that moves toward the surface: on cling, “down” on the stick crawls deeper under the ceiling (toward screen top in side-view), “up” drops or prepares jump-off depending on design. Document this in the tutorial — Harbor’s first cling room uses arrow decals on the ceiling matching stick direction. Fighting muscle memory from floor play is the main UX cost.

Handoffs to other verbs

Define explicit edges: jump from cling into wall jump when a side wall is within reach; transition to ledge hang when the ceiling ends at a lip; allow drop-through floors only from detach, never while crawl input holds attach. Ambiguous handoffs caused most Harbor engineering bugs.

Physics details: offset, corners, and moving ceilings

While clinging, disable default gravity acceleration on the character controller but continue resolving horizontal collisions with world geometry. Position the capsule with a fixed ceiling offset (sprite feet toward screen top) so hitboxes align with spike hazards drawn on the ceiling tilemap.

Corners: when the crawl path turns 90°, either precompute spline rails or allow a 3–5 frame corner blend that rotates the character tangent without detaching. Sharp corners without blends popped 12% of Harbor playtesters off unexpectedly.

Moving platforms: parent the player transform to the ceiling mover or add platform delta each tick (same pattern as moving platforms). Jump detach must inherit platform velocity or gaps feel unfair on timed crusher ceilings.

Stamina, slip-off, and hazard coupling

Unlimited ceiling crawl removes tension. Common limits:

Stamina meter — drains per second while crawling, recovers on floor; at zero, enter Slip state.
Timed auto-drop — arcade style: cling for N seconds then forced detach; telegraph with cracking audio.
Damage stagger — bat hit applies slip impulse toward nearest open edge.

Harbor uses a 4.5s stamina pool with 1.2s recovery on floor. Slip applies 0.15 tiles/frame drift toward gaps unless the player counters with crawl input into the ceiling. Designers tune gauntlet length to stamina plus one optional stamina pickup hidden in room 2 — optional pickups must be reachable without sequence-breaking or speedrunners and casuals diverge unfairly.

Camera, animation, and readability

Full camera rotation disorients in side-scrollers; Harbor keeps the camera upright and flips only the character sprite and shadow ellipse. Parallax layers stay world-anchored so players retain a consistent “down is danger” read (spikes and bats below).

Animation requirements: attach grab, crawl cycle (feet or hands toward ceiling), idle cling, slip struggle, detach fall blend. Missing attach animation made 8-frame snap reads as a glitch in blind playtests. Audio: distinct cling latch and stamina wheeze sell state without HUD clutter.

Harbor Catacombs refactor: 47% to 82% clear rate

Week 1 baseline: binary attach on jump press only, floor crawl speed, no grab window, camera child-rotated 180° (abandoned). Week 2: dedicated Cling FSM, 6-frame detach coyote, 78% crawl speed, upright camera. Week 3: stamina slip with counter-input, bat hitbox narrowed 12% during crawl to reduce feel-bad overlaps. Week 4: corner blends on the S-turn and explicit jump decals. Final gauntlet clear rate 82% (from 47%) with identical enemy placement; average retries dropped from 3.1 to 1.4 per player.

The lesson: ceiling crawl fails in production when treated as a rotation hack on ground code. A small FSM plus probe tuning buys more than doubling enemy spacing.

Technique decision table

Approach	Best for	Weak when
Local ceiling cling FSM	Spike tunnels, stealth crawl, mixed floor/ceiling rooms	Whole-room orientation puzzles
Global gravity flip zones	Puzzle platforms where everything inverts	Combat with floor enemies while on ceiling
Wall slide / ledge hang	Vertical shafts with side walls	Long horizontal ceiling paths
Zipline / grapple	Long gaps without continuous ceiling	Tight bat-spike timing crawl
One-way platforms only	Simple verticality without invert fantasy	Stealth under-floor navigation fantasy

Common pitfalls

Reusing ground speed — crawl feels slippery and unreadable on inverted paths.
No detach coyote — gap crosses become accidental falls.
Rotating the entire camera — disorients side-scroller players; flip character only.
Attach to untagged decoration — players stick to non-navigable art meshes.
Jump and cling on same button without priority rules — input fights at tunnel entries.
Ignoring platform velocity on detach — moving ceiling crushers feel random.
Mixing global flip and local cling without teaching — state stack bugs and deaths.

Designer and engineer checklist

Choose local cling vs global flip per encounter; avoid mixing without a taught transition.
Implement dedicated Cling FSM with attach, crawl, idle, slip, and detach states.
Cast ceiling probes with surface tags, normal thresholds, and clearance checks.
Apply 4–8 frame detach grab window for gap crosses.
Map inverted input consistently; tutorial decals match stick direction.
Tune crawl speed below ground run; blend corners over 3–5 frames.
Parent or delta-apply moving ceiling velocity; inherit on jump detach.
Limit cling with stamina or timed slip; telegraph forced drops.
Keep camera upright; flip character sprite and shadow only.
Define handoffs to wall-jump, ledge hang, and floor verbs at state edges.

Key takeaways

Ceiling cling is a local verb — not the same as flipping world gravity.
Attachment probes and coyote detach matter more than crawl top speed.
Dedicated FSM prevents input fights with jump, wall, and floor states.
Readability wins upright cameras — invert the character, not the stage.
Harbor cut gauntlet deaths 47% → 18% with FSM and probe work, not easier enemies.