Log inGet started
Package

tidewaterSwim.package

This package holds more than this page lists. See all of its files in its world.

README.md

tidewaterSwim 1.0.0: let the player swim

Swimming for any Zero game. The player wades (slower the deeper the water gets), swims on the surface, treads water when idle, dives under and swims down and up, and climbs back out at a quay edge, a ladder or a riverbank. A river's current carries a swimmer downstream. Keyboard, gamepad and touch. Multiplayer.

It works on any water the engine knows: every Tidewater kind (lake, pool, river, ocean, ...), an engine Water component, a terrain's lakes and rivers, anything Physics.defineWater defines. It reads the water through Physics.water, so the water kit is not required. Tidewater FX (splash and ripples), juiceKit (a light camera kick on a hard entry) and controlsKit (its schemes) are used when the world has them and left alone when it does not.

Install (a few minutes)

  1. In the editor's ZeroMind panel search for tidewaterSwim and press Install (or zero zeromind installAsset <guid> in the agent shell). climbKit installs with it (it runs the pull-up onto a quay and the ladder climb).
  2. In your scene's build.luau, after the line that makes the player prototype's body, add one line:
body.component.add("tidewaterSwim.Swimmer", { feel = "arcade" })
  1. Press Play and walk into water. That is all: no new input setup, no water wiring.

For a quay you can climb out onto, any collider edge up to about 2.3 m above the swimmer's feet works (a quay top up to about 1 m above the water). For a ladder up a taller wall, mark the ladder's collider (or a parent) climbable: ladder.attribute.set("climbable", true). A bank is any slope the character can walk on.

The four feels

feel picks one; component.get("tidewaterSwim.Swimmer"):setFeel("heavy") switches live.

arcaderealisticheavycartoon
swim speed (m/s, surface)3.21.40.94.0
sprint multiplier1.51.61.31.6
dive / rise speed (m/s)2.41.00.83.2
acceleration / drag (1/s)6 / 32.5 / 1.81.5 / 1.29 / 4
buoyancy under water (m/s²)0.80.35-0.15 (sinks)1.6
swim depth (starts swimming, m)1.21.31.41.1
wading speed left at that depth45%35%25%55%
strokes per second1.40.90.62.2
surface bob / tread bob (m)0.05 / 0.040.04 / 0.060.025 / 0.080.12 / 0.10
body lean while swimming72°80°60°85°
climb out (quay pull-up, s)0.35 to 0.50.6 to 0.90.9 to 1.30.25 to 0.35
ladder speed (m/s)2.21.20.83.0
share of a river current0.61.01.20.5
breath under waternone45 s25 snone

Your own: require("tidewaterSwim.feels").register("otter", { swimSpeed = 5, breath = 0 }) (missing numbers come from arcade).

Controls

Keyboard + mouseGamepadTouch
swim (camera-relative)WASD / arrowsleft stickthe on-screen stick
swim fasterShift (sprint)the sprint buttonthe sprint button
swim up / climb outSpaceA (south)Up button
dive / swim downCtrlB (east)Dive button
climb out at a quay or ladderswim into it (or Space against it)push into it (or A)push into it (or Up)
walk out at a bankswim toward itpush toward itpush toward it

Up and Dive come from the package's own tidewaterSwim.swim input map, live only while the player is in deep water, so they never take Space or Ctrl from your game on land. When a controlsKit scheme is live, its own actions are read instead: move, jump or ascend (up), crouch or descend (down), sprint or dash, with controlsKit's touch controls.

For game code

local sw = body.component.get("tidewaterSwim.Swimmer")
sw.events.onStateChanged:connect(function(e) print(e.from, "->", e.to) end)
sw.events.onOutOfBreath:connect(function() takeDamage(10) end)
sw.events.onClimbOut:connect(function(e) print("climbed out at a", e.how) end)  -- quay | ladder | bank
print(sw.state, sw.breath, sw.depth, sw:isSwimming())

Types: require("tidewaterSwim.feels") exports SwimFeelName, SwimState (walking | wading | swimming | treading | diving | climbing) and SwimFeel.

Animation

When the avatar has swim clips, set swimClip (and treadClip) and they loop while swimming and treading. Otherwise (the built-in humanoid has none) the body is tipped toward horizontal with a stroke roll over its walk cycle, upright and bobbing while treading, nose down while diving and up while rising.

Multiplayer

Put the Swimmer on the player prototype's body and every player who joins gets it. Each peer drives only its own player's body; the body's position replicates as usual, state, vertical and breath are synced, and every peer draws the swim pose, the splash and the ripples for every swimmer from them.

Known limits

  • Up is world +Y: no swimming in a GravityField.
  • The procedural pose tips the whole body; arms and legs play the walk cycle, not a real stroke. Give the avatar swim clips for a true crawl.
  • Climbing out needs climbKit's reach: a quay top more than about 1 m above the water needs a ladder (marked climbable).
  • The muffled sound and the fog under water are the water kit's job (Tidewater's underwater pass), not this package's.
  • Breath runs out with an event only: the game decides what drowning costs.

See also

  • Tidewater (tidewater package), the water for Zero games: How to add water to my game, How to add a lake or pond, How to add a swimming pool or hot spring, How to add a river that carries things downstream, and Example: build a small harbour level, which puts a Swimmer on the player beside a pier with a climbable ladder. The Tidewater showcase scene (scenes/showcase.scene/build.luau) uses feel = "arcade".