Guide

Game water current and river flow traversal systems explained

Harbor Delta's main quest required players to ferry a relic upstream through three river bends to a shrine. The prototype applied position += flowDir * 0.22 every frame inside water triggers — no integration with swim input, no cap on drift speed, and instant full current at volume edges. Players who fought the river spun in place; players who stopped steering rocketed past turn markers into whirlpool kill volumes. Quest completion sat at 38% and “unfair river” tickets dominated support for that region. Refactoring currents as per-tick acceleration coupled to swimming states, adding edge falloff and a downstream speed cap, and splitting surface drift from submerged flow raised completion to 81% and cut upstream frustration reports by 67%.

Water current systems apply directional force inside water volumes: lazy downstream drift, fast rapids, tidal reversals, and whirlpool hazards. They extend swimming verbs with environmental routing — rivers become moving corridors, puzzles, and shortcuts rather than flat blue terrain. This guide covers flow field models, surface vs submerged coupling, spline-directed rivers, upstream stamina and counter-flow input, whirlpools and scripted tides, the Harbor Delta refactor, a technique decision table vs wind zones and conveyors, pitfalls, and a production checklist.

What water currents solve

Rivers without flow feel like oversized puddles: swimming is identical to lake traversal and level designers cannot steer players along a channel. Currents answer three design needs:

Routing — push players toward exits, secrets, or hazards without invisible walls.
Pacing — downstream rides create breathers; upstream segments tax stamina and attention.
Puzzle vocabulary — timed gates, log platforms, counter-current lanes, and tide cycles add readable constraints.

Currents pair naturally with platformer and open-world water: the same volume that enables swimming also carries flow data. Land characters should not receive current force unless you explicitly support wading drag (ankle-depth slowdown without full swim state).

Currents vs wind, conveyors and swimming

Environmental movers fall into three families; mixing them without clear rules produces mushy feel:

Surface velocity (conveyors, moving platforms) — sets tangential speed while grounded; jump-off inherits surface velocity.
Continuous force (wind, water current, magnetism) — accelerates velocity each tick inside a volume.
Impulse at contact (springs, bounce pads) — adds velocity once on touch.

Water current belongs in the continuous-force family, like wind — but applies only inside water volumes and often differs between surface and submerged layers. Applying current as position teleport (the Harbor Delta bug) bypasses swim input integration: players cannot steer against flow because displacement happens after input resolution. Production pattern: v += a_flow * dt while the swim hurtbox overlaps the current volume, then clamp to v_flow_max along the flow axis.

Current vs conveyor in shallow water

Moving walkways on flooded factory floors sometimes use conveyor surface velocity on a submerged floor collider. If the player is in surface-swim state, prefer flow acceleration (feels like drift) over hard conveyor coupling (feels like a belt under invisible feet). Document which volumes use which model per level block.

Flow field models

Uniform vector zones

Simplest rapids: constant a_flow inside an axis-aligned box. Fast to author but harsh at boundaries — acceleration snaps on at entry. Use uniform zones in wide channels with smoothstep edge falloff (see below) or tutorial rivers with generous margins.

Spline-directed rivers

Production rivers follow splines: sample nearest point on spline, flow direction = tangent at parameter t, optional width falloff perpendicular to tangent. Spline flow keeps players centered in bends without invisible guard rails. Author flow speed as a curve over t (slow pool, fast chute, slow eddy before waterfall). Reject mesh-normal shortcuts — rotated river meshes with tangent read from transform.forward is a top source of “current pushes sideways” bugs.

Depth layers

Surface current may differ from deep current: surface drift 1.2 m/s downstream, submerged layer 0.6 m/s with stronger lateral eddies. Probe depth from water line to actor root; lerp between layer samples. Deep slow layer lets divers sneak under surface rapids; surface-fast layer rewards log-riding and skipping swim stamina drain.

Edge falloff and eddies

Scale a_flow by weight w from 0 at bank to 1 at channel center. Optional counter-flow eddies near rocks (small negative tangent component) sell realism and create rest pockets where players recover stamina. Harbor Delta added 0.4 m eddy bubbles behind pillar colliders; upstream deaths at bend 2 fell 44%.

Terminal drift caps

Uncapped acceleration plus downstream flow produces runaway speed that skips collision checks on thin turn triggers. Cap speed along flow axis v_flow_max (often 1.5–3× base swim speed). Caps make puzzles solvable: designers compute whether upstream sprint plus counter-input reaches the eddy before the whirlpool volume.

Surface vs submerged coupling

When flow applies

Apply current when the actor is in a water locomotion state (wade, surface swim, submerged dive) — not on land overlap with water trigger alone unless wade drag is an explicit design. On state entry, do not reset velocity; add flow acceleration on the same tick.

Input vs flow

Swim input should add to velocity before or after flow integration consistently. Standard order: read input acceleration, apply flow acceleration, apply drag, integrate position. Counter-flow input magnitude can scale with stamina: full steer downstream, reduced steer upstream when stamina low. Never zero input authority downstream unless the level is a scripted ride (log raft, cutscene current).

Log riding and partial grounding

Rideable logs often use kinematic movers plus inherited surface velocity at stand point. Player on log receives log velocity plus optional local flow if log is partially submerged. Dismount inherits combined velocity; brief coyote window on log edge prevents instant drop into fast undertow.

Boats and mounts

Boats may ignore player swim input and add full flow to hull velocity. Mount dismount rules must match swim dismount: flow at dismount point, not last frame's log speed from ten meters back.

Upstream stamina, rapids and whirlpools

Upstream tax

Swimming upstream drains stamina faster than neutral swim or adds effective slowdown without a visible bar (multiplier on counter-flow axis). Publish the rule in tutorial copy: “strong current — sprint to cross.” If upstream is impossible without a power-up, gate the channel with a visible barrier rather than infinite struggle.

Rapids and chutes

High v_flow_max sections work as one-way gates: players ride down, climb out at eddy, use ladder or grapple to bypass return. Chute entry needs 300–500 ms audio and VFX telegraph so accidental entry reads as player choice.

Whirlpools

Whirlpools combine inward radial acceleration and downward pull (or damage volume at core). Cap spiral speed; telegraph surface foam rotation synced to phase. Escape window: brief outward push on button press at rim, or eddy lane at fixed phase. Instant kill at center without telegraph fails fairness checks in playtest.

Waterfalls and one-way drops

Waterfalls often transition to fast downstream current plus forced drop state (player cannot swim up the fall). Use distinct volume tag so climb abilities do not fight waterfall volumes. Respawn below fall should preserve quest items.

Tidal cycles and scripted flow reversals

Tides reverse a_flow sign on a shared tide_phase clock. Square-wave reversal feels unfair; use 5–15 s blend through zero flow. Tie buoys, debris, and audio to phase so players read timing without UI timers in immersive modes. Puzzle design: reach island on high slack, return on ebb.

Script reversals for story beats (dam opens, floodgate closes) by blending spline speed curves over 2–4 s rather than snapping vectors. Networked games must replicate phase authority from server tick, not local particle animation.

Networked and deterministic flow

Flow acceleration must be a function of simulation tick and shared phase clocks: a_flow(tick) = tangent(t) * speed(t) * gust_scale(tide_phase(tick)). Rollback netcode includes tide phase in savestates; mispredicting one reversal desyncs players on log co-op rides. Visual foam may interpolate; gameplay force never reads particle velocity.

For co-op rafts, apply one hull velocity driven by spline sample at raft center; both players inherit stand-point offset. Do not integrate flow separately per avatar on the same craft.

Harbor Delta river refactor (case study)

Before: Per-frame position nudge along mesh forward; no v_flow_max; instant full current at volume entry; upstream and downstream same magnitude; whirlpool core kill on first frame. Metrics: 38% relic quest completion, 31% of deaths at bend 2 whirlpool, 22% abandon at upstream segment.

Changes:

Replaced position nudge with v += a_flow * dt and per-segment v_flow_max.
Spline-directed flow with smoothstep bank falloff on all river segments.
Surface current 1.4× submerged; upstream stamina drain 2× in tagged rapids.
Eddy rest pockets behind bend 2 pillars with zero net flow weight.
Whirlpool core damage delayed 800 ms after rim entry; outward escape impulse on dodge.
Shared tide_phase for optional side channel (low priority route).

After: 81% quest completion, whirlpool deaths down 58%, upstream abandon down 67%. Spline authoring fix contributed ~12 points; integration and stamina rules contributed the rest.

Technique decision table

Goal	Prefer	Avoid
Lazy downstream travel	Flow acceleration + cap	Position teleport per frame
Center player in bends	Spline tangent flow + bank falloff	Uniform box only
One-way river gate	High `v_flow_max` chute + eddy exit	Invisible upstream blocker
Underwater sneak route	Slower deep layer current	Same flow all depths
Timed crossing	Tide phase + world telegraphs	Hidden random reversal
Ride sequence	Log kinematic + inherited velocity	Player swim speed ignored on log
Hazard pool	Telegraphed whirlpool + escape window	Instant core kill
vs airborne sections	Wind zones above water	Current applied in air over river
vs factory floor	Conveyor on dry walkway	Conveyor rules in deep swim
Debug unfair drift	Flow gizmo overlay + heatmaps	Repro from player clip alone

Common pitfalls

Position nudge instead of acceleration — breaks swim steering and collision order.
Mesh forward as flow direction — bends push sideways; use spline tangent.
No entry falloff — snap-in velocity spikes feel like bugs.
Uncapped downstream speed — skips triggers; tunnel through thin colliders.
Same flow at all depths — wastes underwater routing options.
Upstream without stamina rule — infinite grind or impossible swim.
Whirlpool instant kill — reads random; add telegraph and escape.
Current in air above river — double-stacks with jump arc; restrict to water state.
Desynced tide VFX — players time wrong phase; lock visuals to tide_phase.

Production checklist

Integrate flow as v += a_flow * dt inside water locomotion states only.
Author river flow from splines with speed curves over parameter t.
Apply smoothstep bank falloff on all open-channel volumes.
Cap v_flow_max per segment; document in level design sheet.
Split surface vs submerged flow samples where routing differs.
Define upstream stamina multiplier and tutorial callout copy.
Telegraph rapids, whirlpools, and waterfalls with audio and surface VFX.
Provide eddy or rest pockets before hard upstream checks.
On log or raft dismount, inherit combined velocity with coyote edge window.
Replicate tide_phase from server tick in networked modes.
Overlay flow gizmos in editor; heatmap death sites per river segment.
Measure quest completion and whirlpool deaths pre/post integration refactor.

Key takeaways

Water current is continuous acceleration, not per-frame position teleport.
Harbor Delta completion rose 38% → 81% with spline flow, caps, and eddies.
Spline tangents keep players centered in river bends without invisible walls.
Surface and submerged layers enable different routes through the same channel.
Phase-synced tides and telegraphs make timed crossings fair and readable.