Tidewater: Oceans, Lakes, Rivers, Waterfalls, Swimming and Splashes Water Kit
README.md
Tidewater FX
Water effects for any Zero game or kit, with or without a water kit: a splash when something falls in (automatic, sized by the body and how hard it hits: a pebble plops, a person throws a crown and a column), droplets, spray and spindrift off breaking waves, foam, a wake behind boats and swimmers, waterfall mist, drips, bubbles under water, footsteps in puddles and shallows, fish jumps, rain splashes, and rings on the water (a GPU ripple field plus visible ring particles). Seven looks: realistic, crystal (tropical clear), cartoon, painted (ink), lowpoly (retro), pixel and toy (glossy plastic, for toy-style games).
Every effect finds the water through the engine's Physics.water, so it lands on any water that
declares itself there: Tidewater's, the engine's Water component, terrain lakes, another kit's.
Tidewater depends on this package; this package depends on nothing but the engine.
Quick start (2 minutes)
- Put a
Splashescomponent on any one entity in your scene (a manager, the water):
Now anything that falls into water splashes, whatever comes out drips, every character splashes footsteps in shallows and leaves a wake when it swims, and when a weather kit says it rains, the water round the camera splashes with raindrops. Splashes are sent to every peer.entity.find("GameManager").component.add("Splashes", { look = "" }) -- "" = the water's own look - Put a
Wakeon each boat (its +Z is the bow):boat.component.add("Wake", { width = 1.6, length = 4.5 }) - Call effects yourself:
local Fx = require("tidewaterFx.modules.fx") Fx.ripple(point, 0.5) -- a ring on whatever water is there Fx.splash("plop", point, { size = 1, sync = true }) -- every peer sees it local mist = Fx.mist(poolCentre, { width = 6 }) -- continuous; mist:stop() - Press Play. Effects are particles on the engine's procgen simulation: they only run while the game runs (in edit mode an effect holds its frame).
API (require("tidewaterFx.modules.fx"))
| Call | What |
|---|---|
Fx.splash(kind, point, opts?) | one-shot: plop, body, droplets, spray, footstep, fishJump, rainSplash, ring (aliases: pebble, stone, person, jump, puddle, rain, ...). Continuous kinds play for opts.duration s. opts: size (1 = the kind's natural size), look, dir, wind, ripple = false, snap = false, sync = true. |
Fx.ripple(point, strength, opts?) | a ring: strength 0..4 (raindrop 0.1, stone 0.5, person 1). Goes into the ripple field every Tidewater-style water shader samples, and from 0.25 up also plays a visible ring lying on the surface (opts.visible forces it either way). sync = true for every peer. Answers false off water. |
Fx.emitter(kind, opts) | continuous bow, spindrift, mist, drips, bubbles, wake, foam; handle :set(opts), :stop(). Shortcuts Fx.mist, Fx.spray, Fx.drips, Fx.bubbles. |
Fx.autoSplash(opts?) | splash anything entering water (what Splashes runs). Answers a stop function. |
Fx.watchCharacters(opts?) | footsteps, entry splashes, swimmer wakes for every CharacterController. |
Fx.watchRain(opts?) | rain splashes on water round the camera while weather.rain > 0. |
Fx.warm(kinds?, count?, { looks?, sizes? }) | build plays ahead (see Known limits). |
Fx.setLookProvider(name, fn), Fx.setDefaultLook(look) | how a water kit tells effects which look its water has. |
Fx.surfaceAt(point), Fx.stats(), Fx.snapSize(size) | helpers. |
Fx.stopAll(filter?) | stop live emitters and wakes (and a wake's laid foam); { scene = name } or { owner = entity } narrows it. Answers how many stopped. |
Emitters never outlive what started them. Each emitter remembers the scene that was active
when it started (opts.scene overrides) and, given opts.owner (an entity or id; root counts
too), that entity. A scene unloading stops its emitters; an owner despawning stops its own within
a second. Wake passes its boat as the owner. Fx.stats() counts them as unloadStopped and
orphaned.
Components: Splashes (everything, look, minSpeed, scale, drips, sync,
characters, rain) and Wake (width, length, minSpeed, spraySpeed, fade,
look, bowSpray, ripples, intensity; read status).
Without a dependency: named values
A kit that must not depend on this package writes named values on any entity; this package listens on every peer and plays them:
values.set(myEntity, "water.ripple.strength", 0.6) -- optional, default 0.5
values.set(myEntity, "water.ripple", vector.create(x, y, z))
values.set(myEntity, "water.splash.size", 1.5) -- optional, default 1
values.set(myEntity, "water.splash.plop", vector.create(x, y, z)) -- any one-shot kind
Each write is one request. Declare the value with replicate on a synced entity and every peer
hears it. Nothing happens (and nothing breaks) when the package is not installed.
Weather
Rain, wetness and wind come from any weather kit that publishes weather.rain (0..1),
weather.wetness, weather.wind named values (Cloudburst does), read by
tidewaterFx.modules.weather; a game with no weather kit calls
require("tidewaterFx.modules.weather").set({ rain = 0.6 }).
Looks
realistic lit beads with sun glints and scattering spray; crystal glassy, mostly see-through
beads with a turquoise rim and hard glints; cartoon solid white blobs with an inked outline;
painted brush-dabbed bands with paper grain; lowpoly flat-shaded octahedron chunks and
hexagon cards; pixel square pixels, two tones, stepped fade; toy glossy moulded-plastic droplets in two candy bands with a hard highlight (also plastic, toybox, bathtub). An effect takes opts.look, else
the look of the water it lands on (a registered look provider; Tidewater registers its water's
look), else the default look.
Multiplayer
sync = true splashes are sent by the caller to every peer (Splashes sends each entry splash
from the body's owner only, so it is seen once per player). Wakes, footsteps and swimmer wakes run
on every peer from the replicated transforms, so nothing is sent for them.
What changed in 1.0.10
- Parked and warming effects now cost nothing. A continuous emitter that is stopped (or primed and parked far
below the world at y -5000, ready for reuse) used to keep simulating with its rate at zero, forever: a water body
priming its look left six such loops (mist, bubbles, foam, spindrift, drips, bow) running every frame. A parked
play is now paused once its last particles are gone (at once when it is parked far below the world), and resumed
when it is taken over, so the first real use still shows on the next frame. Each warming play is paused the moment
it has built, and every warming play is stopped at the end of its job even after an error.
Fx.primeskips a continuous kind already live or parked in that look (no second drips build). Measured in Tsukimichi: procgen generators still updating each frame 14 -> 7, their average cost 1.81 -> 0.32 ms.
Cost (measured here, desktop, heavily shared engine)
- A one-shot play: ~0.07 ms CPU per frame while it plays; GPU particle capacities plop 50, body 204, droplets 30, spray 68, bow 400, spindrift 560, mist 600, drips 320, bubbles 400, wake 600.
- Ripple field: 256² over 64 m round the camera, ~0.04 ms GPU per frame.
- A ready (warmed) play shows on the next frame: body, plop, droplets, ring and rainSplash all advanced 0.05 s after the call. A play built on the spot waits for the GPU: 1-10 s on a quiet machine, and several minutes (mist about 400 s, bubbles about 450 s) on this machine while its GPU queue ran 80-90 s behind.
Known limits
- An effect played before it is readied shows late: engine #26227 (a new play draws nothing
until a long hidden warm-up through its whole graph finishes).
lookis a build input: each look is its own build; every other input (size,width,rate, ...) is live, so one ready play of a kind in a look serves every size. A Tidewater water callsFx.prime(look)when it is built: every one-shot kind, two of each, through this module's warming queue, and one of each continuous kind (mist, bubbles, foam, spindrift, drips, bow) started out of sight and parked. Measured on a busy desktop: one-shots ready 0 to 8 s after the water was built, continuous kinds 30 to 38 s after; from then on every effect drew within 0.05 s of being triggered, every time. An effect triggered before that waits for the engine (more than 8 s on the same desktop). A game with a look of its own callsFx.prime(look)at load, behind a loading screen if it can. (world tracker #1) - A stopped endless play does not go back to the pool: engine #26226. Worked around here: a stopped mist, drips, bubbles, foam, spindrift or bow spray is parked (emission to zero) and the next of its kind and look takes it over with no build. (world tracker #2)
- Effects do not animate in edit mode: the engine holds effect plays until play. (world tracker #3)
- After a shader or effect edit, live materials and pooled plays keep the old build: engine #26228. Rebuild the water (reload the scene once it has finished loading) before judging it.
- Ripple-field rings show only on water whose shader samples the field (Tidewater's waters) and
within 64 m of the camera, or of
require("tidewaterFx.modules.ripples").setFocus(x, z); on other waterFx.rippleplays ring particles instead (world tracker #5). In the realistic look a field ring is a gentle bend in the reflections; the ring particle is the part you see from a distance. On puddles a few millimetres of water bend too little light for a field ring to read, so a hit of a stone's strength or more (0.2 and up) on a puddle also plays the visible ring, even while rain rings fill the pool (documentation/media/r8_puddle_impact_rings.jpg: impacts on the rainy street's puddles, strong and gentle). The engine's'tidewater_ripple_field' ... is not a resident GPU texturewarning is spurious: the field is bound and resident. - Rain rings on Tidewater water are drawn by the water shader from
weather.rain, whatever the camera; rain splash particles fall only withinradiusof the active camera. - At most 40 one-shots and 48 emitters at once from this module (and the engine bounds each entry), so loops cannot pile plays up.
- A burst can start late. The effect keeps up to
pool: 4plays per entry (counting the ones playing), and a pool that runs dry refills itself at the front of the warming queue; a play while all of them are out builds a fresh one on the spot (engine #26227). Warm the kinds you burst withFx.warm(kinds, n, { looks = {...} })sonplays are ready.