Guide

Game swimming, diving and underwater systems explained

Harbor Outpost's coastal quest chain hid a sunken vault 40 m off the eastern reef. Playtesters found the entrance in four minutes — then spent eleven minutes drowning on repeat because surface locomotion speeds carried into deep water, the oxygen bar drained while they fought camera tilt, and a single mis-pressed jump made them bob helplessly at the surface instead of diving. Completion rate on that quest sat at 31%. Refactoring water into explicit states (wade, surface swim, submerged dive), tuning buoyancy so “sprint” actually pulled the player under, and adding a 3-second grace period after surfacing raised completion to 78% and turned the reef into one of the region's highest-rated exploration beats.

Swimming and diving systems govern how characters move through water volumes: wading at ankle depth, surface swimming with horizontal control, submerged diving with vertical thrust, optional breath meters, and transitions back to land. They sit between land locomotion and vehicle traversal in open-world pacing — water can gate secrets, shorten routes, or punish players who treat lakes as flat terrain. This guide covers volume detection and state machines, buoyancy and drag, oxygen and pressure, underwater combat and interaction, camera and audio presentation, the Harbor Outpost reef refactor, a technique decision table vs boats and fast travel, pitfalls, and a production checklist.

What swimming systems solve

Water without dedicated verbs reads as broken land: players sink slowly, jump spam fails, and collision feels mushy. Dedicated swimming states answer three design needs:

Traversal variety — rivers, lakes, and coastlines become routes instead of hard walls. Underwater caves reward gear or skill instead of arbitrary invisible barriers.
Risk and resource tension — oxygen, cold, or stamina drains turn dives into short puzzles with readable clocks, not instant death on misclick.
Biome identity — audio muffling, caustic lighting, and slower combat make submerged spaces feel distinct from surface arenas.

Players rarely praise “buoyancy coefficients.” They say diving “feels good” when entry is instant, direction is predictable, and failure states (drowning, blacking out) telegraph clearly before they happen.

Water volumes and locomotion states

Most implementations use trigger volumes or physics material tags with a small state machine:

Dry — standard character controller.
Wade — depth below knees; reduced walk speed, no swim animation; optional splash VFX only.
Surface swim — chest-deep or deeper while head stays above water; horizontal thrust on XZ, gentle buoyancy holding Y near surface; jump may dive or cancel to tread water.
Submerged — full 3D thrust; look direction or separate ascend/descend inputs control pitch; buoyancy counteracts gravity with tunable neutral depth.
Exit assist — ledge grab onto docks, auto-walk up shallow ramps, or mantle onto pool edges when within height band.

Transitions should be one-frame or cross-faded: lag between “feet wet” and “swim anim playing” causes the classic “I'm walking on the lake bottom” bug. Store previous state for 2–3 frames to debounce surface bobbing at wave height.

Depth detection

Raycast or sample water surface height vs capsule foot position. For animated waves, use the surface at the player's horizontal position, not global sea level. Deep water flags (e.g. depth > 8 m) can enable pressure damage, darker fog, or predator spawns independent of oxygen rules.

Buoyancy, drag and feel tuning

Buoyancy applies upward force proportional to submerged volume (or a simplified “depth below surface” term). Neutral buoyancy means the player neither sinks nor floats when idle — ideal for exploration sections where camera pitch steers movement. Positive buoyancy pushes toward the surface (survival horror treading water); negative buoyancy suits weighted diving suits or “pull to bottom” treasure hunts.

Drag scales linear or quadratic velocity, killing land sprint speeds in water. A common pattern: surface swim at 60–70% of run speed, submerged at 40–50%, sprint-underwater only with a dedicated perk or consumable. Without drag, players skip boats entirely; with too much, crossing a lake feels like punishment.

Input mapping: on controllers, many games map “sprint” to dive while submerged and to faster surface paddle while at surface. On mouse and keyboard, Space ascend / Ctrl descend avoids fighting jump's land binding. Document the mapping in the first water tutorial beat.

Oxygen, pressure and failure

Breath meters are optional but powerful pacing tools:

Fixed tank — 45–90 seconds base; upgrades extend capacity. Simple to balance; works for action-adventure.
Stamina-linked — swimming shares a bar with sprint and dodge; surface treading regenerates. Ties water to existing resource literacy.
Chunked safe zones — air pockets, bubble columns, or harvestable coral that refills 30% oxygen teach route planning without one long timer.
Grace and warning — yellow pulse at 25% remaining, screen vignette at 10%, 2–3 s of post-surface grace before refill starts (Harbor Outpost's fix). Instant death at zero reads harsh unless genre is roguelike.

Pressure (depth damage, suit requirements) gates endgame trenches without oxygen alone feeling arbitrary. Show depth on HUD only after first pressure injury or when equipping dive gear.

Underwater combat, interaction and AI

Melee underwater usually slows attack rate and shortens lunge range; projectiles get drag arcs or are disabled. Ranged combat often shifts to harpoon, torpedo, or magic that ignores water resistance. AI needs separate behavior trees: surface patrol vs submerged ambush, hearing cones muffled, vision replaced by vibration pulses in murk.

Interaction prompts (loot, levers, doors) must work while submerged — raycast from camera, not feet. Quest objects on the seafloor need larger interact radii and silhouette highlights; caustics and particles obscure small props.

Camera, audio and readability

Third-person cameras often pull back and raise pivot above the head at surface; submerged, pitch follows look with clamped roll to reduce nausea. First-person diving games may add peripheral vignette and FOV narrowing at depth. Always offer invert-Y for pitch and a “reduce camera sway” accessibility toggle.

Audio low-pass filters underwater; surface splash on entry/exit sells transition. Footstep systems should switch to swim loop or silence — stealth games that still play loud footstep SFX underwater break immersion.

Case study: Harbor Outpost reef refactor

Before refactor, one water volume and halved move speed. After:

Split wade / surface / submerged with distinct accel curves.
Mapped sprint to “dive” when camera pitched down > 30°.
Oxygen 75 s base, +3 s grace after surfacing, air bells every 25 m on main quest line.
Added dock mantle volumes on three shore approaches.
Quest item ping visible through murk within 15 m.

Drowning deaths per session dropped 64%; average time-to-vault fell from 11.2 min to 4.8 min. Players still reported tension — the meter mattered — but failure felt fair.

Technique decision table

Approach	Best when	Avoid when
Full swim + dive stack	Coastal open world, underwater dungeons, exploration fantasy	Water is rare border decoration; tight indoor levels only
Surface swim only (no dive)	Rivers as barriers, fishing hubs, low dev budget	Seafloor secrets are core content
Boats / mounts	Long ocean crossings, trade routes, social travel	Player must loot a narrow trench 10 m below a cliff
Fast travel skip	Backtracking after main quest; multiplayer sync points	First discovery of submerged POI
Instant kill water	Old-school platformer hazard, lava reskin	Narrative worlds where water is navigable elsewhere
Dedicated diving suit item	Gating endgame abyss, RPG upgrade path	Every pond requires equip friction

Common pitfalls

Land controller in water — no state change; mushy jumps and unfair drowning.
Jump key fights dive — players surface when trying to descend; bind explicit pitch or descend input.
No shoreline exit assist — players drown next to dock because step height is 20 cm too tall.
Oxygen drains at surface — treading water should pause or slow drain unless design is hardcore survival.
Camera roll without toggle — motion sickness complaints spike on first water level.
Underwater combat identical to land — breaks readability and makes enemies feel glued to the seafloor.
Streaming loads mid-dive — async pop-in at depth kills trust; preload underwater cells in quest radius.
Networked position desync — multiplayer swimmers rubber- band at surface boundary; predict buoyancy on client.

Production checklist

Define wade / surface / submerged states with explicit transition rules.
Raycast water surface height per player position for wave meshes.
Tune buoyancy neutral point and drag separately for surface vs deep.
Map sprint, jump, and descend without conflicting bindings per platform.
Implement oxygen or stamina drain with grace period and clear UI warnings.
Add shoreline mantle, ramp, or ladder exit volumes on every quest beach.
Adjust melee/ranged ranges and AI senses for submerged encounters.
Low-pass audio, splash VFX, and caustic lighting in underwater volumes.
Offer camera sway reduction and invert-Y in accessibility menu.
Playtest first water quest with fresh users; track drown count and time-to-goal.

Key takeaways

Water needs its own locomotion states — wade, surface swim, and submerged dive — not slowed land movement.
Buoyancy and drag are separate knobs; neutral float at depth makes exploration cameras usable.
Oxygen meters work when paired with grace periods, air pockets, and fair shoreline exits.
Harbor Outpost raised reef quest completion from 31% to 78% by fixing state transitions and dive input.
Match technique to content: full dive stacks for seafloor secrets, boats for long crossings, kill planes only when water is a hazard.