fx
Tidewater's water effects for gameplay, each in the seven looks and usable without any other part of the kit:
fx
Tidewater's water effects for gameplay, each in the seven looks and usable without any other part of the kit:
local Fx = require("tidewater.modules.fx") -- inside the package: require("~.modules.fx")
Fx.splash("plop", { x, y, z }) -- pebble
Fx.splash("body", pos, { size = 1.2, sync = true }) -- person, played on every peer
Fx.splash("spray", pos, { wind = { 8, 0, 0 } })
local mist = Fx.mist(pos, { width = 8, sparkle = 0.6 }) -- continuous: :set(opts) / :stop()
local bow = Fx.emitter("bow", { position = p, dir = d, speed = 9 })
local stop = Fx.autoSplash() -- everything entering water splashes, exits drip
One-shots: plop, body, droplets, spray. Continuous (Fx.emitter, or Fx.splash for
duration s): bow, spindrift, mist, drips, bubbles, wake. The look defaults to the
look of the Tidewater water at the point, else opts.look, else realistic. Every one-shot rings
the water through the ripple field (ripple = false skips it). sync = true sends the effect
to every peer on the tidewater.fx channel; Fx.autoSplash / the Splashes component play
automatic splashes on the body's owner only, synced, so nothing is doubled. Fx.classify,
Fx.lookFor, Fx.windFor, Fx.warm, Fx.stats and Fx.stopAll round it out.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2strict Water effects in six looks, for any water: splashes (plop, body, droplets, spray, footstep, fishJump, rainSplash, ring), bow spray, spindrift, mist, drips, bubbles, foam and wake trails. One-shots with Fx.splash, rings with Fx.ripple, continuous emitters with Fx.emitter / Fx.mist / Fx.wake, automatic splashes for anything entering water with Fx.autoSplash, footsteps and swimmer wakes with Fx.watchCharacters. The water is found through the engine's `Physics.water`, so every water kit works. `sync = true` plays a splash on every peer. Kits with no dependency on this package ask through named values (`water.ripple`, `water.splash.<kind>`; see Fx.listenToValues).
snapSize(size: number?) → number
The size a splash is played at: `size` snapped to the nearest of the steps every effect is cooked at (0.35, 0.5, 0.7, 1, 1.4, 2, 2.8, 4, 6), so splashes share builds.
| arg | type | description |
|---|---|---|
| size | number? |
effectRef( ) → any
vec(p: any) → vector
| arg | type | description |
|---|---|---|
| p | any |
plain(v: vector) → void
| arg | type | description |
|---|---|---|
| v | vector |
resolveKind(kind: string) → string
The canonical effect kind for a name or alias ("pebble" -> "plop", "person" -> "body").
| arg | type | description |
|---|---|---|
| kind | string |
kinds( ) → void
Every effect kind, one-shots first.
setLookProvider(name: string, fn: ((x: number, y: number, z: number) → void
Register a function a water kit answers "which look is the water at x, y, z?" with (a look name or nil). Several kits can register; the first answer wins. Tidewater registers its `Water.lookAt`. Answers a function that unregisters it.
| arg | type | description |
|---|---|---|
| name | string | |
| fn | ((x: number, y: number, z: number |
setDefaultLook(look: string?) → void
The look effects are drawn in when nothing says otherwise (default realistic).
| arg | type | description |
|---|---|---|
| look | string? |
lookFor(pos: Vec, opts: { [string]: any }?) → string
The look an effect at `pos` is drawn in: `opts.look`, else the look a registered water kit names for the water there (Fx.setLookProvider), else the default look, else realistic.
| arg | type | description |
|---|---|---|
| pos | Vec | |
| opts | { [string]: any }? |
surfaceAt(pos: Vec, reach: number?) → void
The water surface height at a point from the engine's `Physics.water` (any water kit that declares its water there answers), searching a little above and below; nil off water. Answers the height and the sample.
| arg | type | description |
|---|---|---|
| pos | Vec | |
| reach | number? |
windFor(opts: { [string]: any }?) → vector
The wind effects are blown by: `opts.wind`, else Tidewater's weather, else a light breeze.
| arg | type | description |
|---|---|---|
| opts | { [string]: any }? |
inputsFor(kind: string, opts: { [string]: any }, look: string) → void
The inputs a play of `kind` takes, from the caller's opts (vectors as vectors).
| arg | type | description |
|---|---|---|
| kind | string | |
| opts | { [string]: any } | |
| look | string |
ring(kind: string, p: vector, opts: { [string]: any }) → void
| arg | type | description |
|---|---|---|
| kind | string | |
| p | vector | |
| opts | { [string]: any } |
listen( ) → void
Sync: one listener per engine, whichever version of this module is current answers.
wireOpts(opts: { [string]: any }, look: string) → void
What crosses the wire: plain numbers, strings and {x,y,z} tables only.
| arg | type | description |
|---|---|---|
| opts | { [string]: any } | |
| look | string |
claim(name: string) → number
Take the named loop claim: answers a token, and any earlier token for the same name stops holding. A scene or kit that runs its own loop of effects checks `Fx.holds(name, token)` each pass, so restarting the loop (a reload, a rebuild) ends the old one instead of doubling it.
| arg | type | description |
|---|---|---|
| name | string |
holds(name: string, token: number) → boolean
Whether `token` (from `Fx.claim(name)`) is still the newest claim of `name`.
| arg | type | description |
|---|---|---|
| name | string | |
| token | number |
release(name: string) → void
Release a named loop claim: the loop holding it stops on its next pass.
| arg | type | description |
|---|---|---|
| name | string |
readyFor(kind: string) → number
Play a water effect once at a world point. One-shots: plop, body, droplets, spray, footstep, fishJump, rainSplash, each freed when it ends, at most 40 at once. Continuous kinds and bow, spindrift, mist, drips, bubbles, wake (played for `opts.duration` seconds, default 2). opts: `look` (default: the water's look there), `size`/`strength` (1 = the kind's natural size), `wind`, `dir`, `speed`, `width`, `rate` as the kind takes them, `ripple = false` to skip the ring, `sync = true` to play it on every peer. Answers the play handle (or the emitter).
| arg | type | description |
|---|---|---|
| kind | string |
splash(kind: string, pos: Vec, opts: { [string]: any }?) → any
| arg | type | description |
|---|---|---|
| kind | string | |
| pos | Vec | |
| opts | { [string]: any }? |
release( ) → void
activeSceneNameFwd( ) → string
Filled in further down (scene / owner lifetimes); used when an emitter starts.
ownerIdFwd(v: any) → string
| arg | type | description |
|---|---|---|
| v | any |
emitterInputs(self: any) → void
| arg | type | description |
|---|---|---|
| self | any |
startNow(self: any) → void
| arg | type | description |
|---|---|---|
| self | any |
parkKey(kind: string, look: string) → string
| arg | type | description |
|---|---|---|
| kind | string | |
| look | string |
takeParked(self: any) → boolean
| arg | type | description |
|---|---|---|
| self | any |
park(self: any) → boolean
| arg | type | description |
|---|---|---|
| self | any |
hold( ) → void
start(self: any) → void
An emitter starts at once: a parked play of its kind and look is taken over first, else a ready one is played, else one is built on the spot. Only when several emitters start cold in the same moment (a scene starting twenty drips at load) do the later ones wait in the warming queue, at its front, so they never wait behind background warming.
| arg | type | description |
|---|---|---|
| self | any |
set(self: any, opts: { [string]: any }) → void
Change a running emitter: `position`, `look`, and any input its kind takes (rate, width, wind, dir, speed, ...). A changed look restarts it in the new look.
| arg | type | description |
|---|---|---|
| self | any | |
| opts | { [string]: any } |
position(self: any) → vector
Where the emitter stands now.
| arg | type | description |
|---|---|---|
| self | any |
stop(self: any) → void
Stop emitting; what is already in the air finishes.
| arg | type | description |
|---|---|---|
| self | any |
isAlive(self: any) → boolean
| arg | type | description |
|---|---|---|
| self | any |
dropFoam(self: any) → void
| arg | type | description |
|---|---|---|
| self | any |
set(self: any, opts: { [string]: any }) → void
| arg | type | description |
|---|---|---|
| self | any | |
| opts | { [string]: any } |
position(self: any) → vector
| arg | type | description |
|---|---|---|
| self | any |
stop(self: any, hard: boolean?) → void
| arg | type | description |
|---|---|---|
| self | any | |
| hard | boolean? |
isAlive(self: any) → boolean
| arg | type | description |
|---|---|---|
| self | any |
emitter(kind: string, opts: { [string]: any }?) → Emitter
Start a continuous water effect and answer a handle with `:set(opts)`, `:stop()`, `:destroy()`, `:isAlive()`. Kinds: bow, spindrift, mist, drips, bubbles, wake. opts: `position` (world point), `look` (default: the water's look there), and the kind's inputs: bow `{dir, speed, width}`, spindrift `{wind, width, rate}`, mist `{width, rate, rise, wind, sparkle}`, drips `{width, fall, rate}`, bubbles `{depth, rate, width, size}`, wake `{dir, speed, width, fade}`. Emitters are local to this peer; drive them from replicated state.
| arg | type | description |
|---|---|---|
| kind | string | |
| opts | { [string]: any }? |
mist(pos: Vec, opts: { [string]: any }?) → Emitter
Rising mist (a waterfall's plunge pool). `opts`: width, rate, rise, wind, sparkle, look.
| arg | type | description |
|---|---|---|
| pos | Vec | |
| opts | { [string]: any }? |
spray(pos: Vec, opts: { [string]: any }?) → Emitter
Continuous spray off a line (rapids, a waterfall's impact line): the spindrift emitter.
| arg | type | description |
|---|---|---|
| pos | Vec | |
| opts | { [string]: any }? |
drips(pos: Vec, opts: { [string]: any }?) → Emitter
Drips falling from an edge with tiny plops where they land.
| arg | type | description |
|---|---|---|
| pos | Vec | |
| opts | { [string]: any }? |
bubbles(pos: Vec, opts: { [string]: any }?) → Emitter
Rising bubbles from a point under water.
| arg | type | description |
|---|---|---|
| pos | Vec | |
| opts | { [string]: any }? |
warmKey(kind: string, look: string) → string
| arg | type | description |
|---|---|---|
| kind | string | |
| look | string |
realPending( ) → boolean
True while the last splash played for real has not been built yet (at most 5 s): warming steps aside so that one goes first, without being starved by a game that splashes all the time.
waitBuilt(p: any, limit: number) → void
| arg | type | description |
|---|---|---|
| p | any | |
| limit | number |
runWarmJob(job: any) → void
Builds the plays one after another (each one still playing far below the world while the next is built, so each is a play of its own), then stops them all: stopped, each goes back to the entry's pool, ready in this look. Never more than one build in flight from here.
| arg | type | description |
|---|---|---|
| job | any |
runStartJob(job: any) → void
| arg | type | description |
|---|---|---|
| job | any |
nextJob( ) → any
The next job: the lowest `prio` first (1 the first ready play of each everyday splash, 2 an emitter's start, 3 the rest of the warming), in the order they came.
warmWorker(version: number) → void
| arg | type | description |
|---|---|---|
| version | number |
kickWorker( ) → void
enqueueWarm(kind: string, look: string, count: number, prio: number?, refill: boolean?) → void
| arg | type | description |
|---|---|---|
| kind | string | |
| look | string | |
| count | number | |
| prio | number? | |
| refill | boolean? |
warm(kinds: { string }?, count: number?, opts: { [string]: any }?) → void
Get plays ready ahead of time so the first splash of each kind shows at once: `kinds` (default all one-shots), `count` ready plays of each (default 1; more for kinds that burst, such as rain), in `opts.looks` (default the default look). Queued and built one batch at a time while the game runs, behind any real effect played meanwhile. `opts.sizes` is accepted for older callers and ignored: size is a live input, so one ready play serves every size.
| arg | type | description |
|---|---|---|
| kinds | { string }? | |
| count | number? | |
| opts | { [string]: any }? |
prime(look: string?) → void
Get the everyday splashes of a look ready, once per look per play session: one ring, plop, body, rain splash, footstep and droplets first, then a few more of the kinds that come in bursts (rain, rings, plops). Water bodies call it with their own look when they are built; a game with its own look calls it at load.
| arg | type | description |
|---|---|---|
| look | string? |
present(k: string) → boolean
Continuous kinds run until stopped, and a stopped endless play does not go back to the pool (engine issue #26226); the engine's own `warm` of an endless entry did not finish in five minutes on a loaded desktop. So each is readied through the park instead: one is started far below the world, left until it draws, then stopped, which parks it (`park`) for the first real one of its kind and look to take over at once. A kind already running in this look (a waterfall starts its own drips as it is built) is not readied a second time: that emitter parks itself when it stops.
| arg | type | description |
|---|---|---|
| k | string |
warmStatus( ) → void
What the warming queue holds: `queued` jobs still to build, `warmed` ready plays built per kind|look this play session, `parked` stopped continuous plays kept for reuse per kind|look.
equivalentRadius(id: any) → number
| arg | type | description |
|---|---|---|
| id | any |
classify(radius: number, speed: number, minSpeed: number?) → void
What splash an entry makes: `kind` and `size` from the body's size (its volume as a sphere's radius, metres) and how fast it crossed the surface (m/s). A pebble plops, a person makes a body splash; nothing under `minSpeed` splashes.
| arg | type | description |
|---|---|---|
| radius | number | |
| speed | number | |
| minSpeed | number? |
onWaterEvent(e: any, opts: { [string]: any }?) → void
Handle one Physics.onWater event as Splashes does: an entry splashes by size and speed, an exit drips. Only the entity's owner plays it, synced to every peer. `opts`: look, minSpeed, sync (default true), drips (default true), scale.
| arg | type | description |
|---|---|---|
| e | any | |
| opts | { [string]: any }? |
autoSplash(opts: { [string]: any }?) → void
Splash anything that enters water anywhere, scaled by its size and speed, and drip whatever comes out (pebble -> plop, person -> body). Answers a function that turns it off. `opts` as Fx.onWaterEvent, plus `target` (an entity, default every body).
| arg | type | description |
|---|---|---|
| opts | { [string]: any }? |
stats( ) → void
What the effects module has done: plays, synced sends, received, rings, live emitters.
stopAll(filter: { [string]: any }?) → number
Stop live emitters and wakes and answer how many stopped. With no filter, every one; `filter.scene` (a scene name) only those started while that scene was the active one; `filter.owner` (an entity or id) only those that entity owns. A wake's laid foam is stopped too.
| arg | type | description |
|---|---|---|
| filter | { [string]: any }? |
ownerId(v: any) → string
| arg | type | description |
|---|---|---|
| v | any |
activeSceneName( ) → string
watchLifetimes( ) → void
Emitters never outlive what started them: a scene unloading stops the emitters started under it, and an emitter given an `owner` (or a `root`) stops once that entity is gone. One watcher per module version; a reload replaces the old one.
ripple(point: Vec, strength: number?, opts: { [string]: any }?) → boolean
Ask for a ripple: a ring spreading on whatever water is at `point`. `strength` 0..1 (a raindrop ~0.1, a stone ~0.5, a person ~1; up to 4). The ring goes into the GPU ripple field every Tidewater-style water shader samples, and, when `opts.visible` is true (default: when no water material samples the field, so on any other water kit's water), also plays a ring of foam lying on the surface. The point is snapped to the `Physics.water` surface there (`opts.snap = false` keeps it). `opts.sync = true` plays it on every peer; `opts.look`. Answers false when there is no water at the point and `opts.force` is not set.
| arg | type | description |
|---|---|---|
| point | Vec | |
| strength | number? | |
| opts | { [string]: any }? |
setFoamStamper(fn: ((a: vector, b: vector, width: number, amount: number) → void
Register what a wake does to the water itself beyond the foam particles (Tidewater's ocean stamps foam into its foam texture). `fn(fromPoint, toPoint, width, amount)`; nil clears it.
| arg | type | description |
|---|---|---|
| fn | ((a: vector, b: vector, width: number, amount: number |
stampFoam(a: vector, b: vector, width: number, amount: number) → void
Called by wakes each frame with the stretch of water they crossed (see Fx.setFoamStamper).
| arg | type | description |
|---|---|---|
| a | vector | |
| b | vector | |
| width | number | |
| amount | number |
listenToValues( ) → boolean
Start following the named-value route (done when this module loads). Answers whether it is listening.
characterIds( ) → void
watchCharacters(opts: { [string]: any }?) → void
Watch every character (anything with a CharacterController: players, local and remote, and NPCs) and play what it does in water: a footstep splash every stride while wading in puddles and shallows, a body splash when it drops in, and a wake trail with ripples while it swims. Runs on every peer from the replicated transforms, so nothing is sent. opts: `stride` (m, 0.75), `wadeDepth` (m, deeper than this is swimming, 0.75), `look`, `footY` (offset from the entity position to its feet, default auto: 0). Answers a stop function.
| arg | type | description |
|---|---|---|
| opts | { [string]: any }? |
watchRain(opts: { [string]: any }?) → void
Rain splashes on any water round the camera while it rains (weather.rain from any weather kit, or Fx's own weather): small crowns and rings on the surface `Physics.water` reports, on top of the rain rings the ripple field already draws. opts: `radius` (m, 14), `rate` (splashes per second at full rain, 18), `look`. Answers a stop function.
| arg | type | description |
|---|---|---|
| opts | { [string]: any }? |
Vec = { number } | { x: number, y: number, z: number } | vectorEmitter = {Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Showing up to 3 levels deep. Open a part to see what it holds further down.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
Scoped to this part · feeds back into the world's score.