tidewaterSwim.package
- .metadata117 B
- README.md5.9 KB
- Swimmer.component
- documentation
- feels.module
- package.yaml930 B
- swim.inputMap
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)
- 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). - In your scene's
build.luau, after the line that makes the player prototype'sbody, add one line:
body.component.add("tidewaterSwim.Swimmer", { feel = "arcade" })
- 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.
| arcade | realistic | heavy | cartoon | |
|---|---|---|---|---|
| swim speed (m/s, surface) | 3.2 | 1.4 | 0.9 | 4.0 |
| sprint multiplier | 1.5 | 1.6 | 1.3 | 1.6 |
| dive / rise speed (m/s) | 2.4 | 1.0 | 0.8 | 3.2 |
| acceleration / drag (1/s) | 6 / 3 | 2.5 / 1.8 | 1.5 / 1.2 | 9 / 4 |
| buoyancy under water (m/s²) | 0.8 | 0.35 | -0.15 (sinks) | 1.6 |
| swim depth (starts swimming, m) | 1.2 | 1.3 | 1.4 | 1.1 |
| wading speed left at that depth | 45% | 35% | 25% | 55% |
| strokes per second | 1.4 | 0.9 | 0.6 | 2.2 |
| surface bob / tread bob (m) | 0.05 / 0.04 | 0.04 / 0.06 | 0.025 / 0.08 | 0.12 / 0.10 |
| body lean while swimming | 72° | 80° | 60° | 85° |
| climb out (quay pull-up, s) | 0.35 to 0.5 | 0.6 to 0.9 | 0.9 to 1.3 | 0.25 to 0.35 |
| ladder speed (m/s) | 2.2 | 1.2 | 0.8 | 3.0 |
| share of a river current | 0.6 | 1.0 | 1.2 | 0.5 |
| breath under water | none | 45 s | 25 s | none |
Your own: require("tidewaterSwim.feels").register("otter", { swimSpeed = 5, breath = 0 }) (missing numbers come from arcade).
Controls
| Keyboard + mouse | Gamepad | Touch | |
|---|---|---|---|
| swim (camera-relative) | WASD / arrows | left stick | the on-screen stick |
| swim faster | Shift (sprint) | the sprint button | the sprint button |
| swim up / climb out | Space | A (south) | Up button |
| dive / swim down | Ctrl | B (east) | Dive button |
| climb out at a quay or ladder | swim into it (or Space against it) | push into it (or A) | push into it (or Up) |
| walk out at a bank | swim toward it | push toward it | push 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 (
tidewaterpackage), 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) usesfeel = "arcade".