# vehiclesKit
Walk up to a vehicle, get in, drive, sail or fly it, get out: fourteen drivable vehicles for any multiplayer Zero world, each one component and one setting away from the next.
## First example
In a new world, install vehiclesKit from ZeroMind (search "vehiclesKit", or run this in the engine shell):
```sh
zero zeromind installAsset 2972bd58-17af-4ef4-b2e5-5c62c8b8337a
```
That one install brings the kits vehiclesKit builds on with it: controlsKit, interactKit, barsKit and soundstage, and gaugeClusters, engineVoices, driveCams and torqueCars from Torque Valley (with the small kits those use). Do not install them again on their own: a second copy of a kit collides with the one vehiclesKit brought.
A new world's `scenes/main.scene/build.luau` already has a ground and a player. Add these lines at the end of its `content()` function:
```lua
-- ── vehiclesKit first example ───────────────────────────────────────
ground.localScale = { 400, 0.2, 400 } -- room to drive: the template's floor is 50 m across
local Vehicles = require("~vehiclesKit.api")
Vehicles.spawn("sportsCar", { 6, 0, 2 }, { look = "realistic", paint = "red", yaw = 180 })
Vehicles.spawn("kart", { -6, 0, 2 }, { look = "toy", yaw = 180 })
```
Save, and press **Play**. Walk to the red car. The prompt says **Drive**: press **E** (the gamepad's X / Square, or the on-screen Interact button on a phone). You sit in the seat, the camera swings behind the car and the speedometer and boost meter come up. **W / S** drive and brake (hold S at a stop to reverse), **A / D** steer, **Shift** boosts, **Ctrl** drifts on the handbrake, **C** changes the camera (chase, cockpit, bonnet), **H** honks, **E** gets you out. The first line widens the template's 50 m floor to 400 m so you don't drive off its edge in the first few seconds; in your own scene, drop it and drive on your own ground.
Swap the car for a helicopter by changing `"sportsCar"` to `"helicopter"`. That is the whole idea of the kit.
No code at all: add the `vehiclesKit.Vehicle` component to a synced entity. With no settings it is a low-poly sports car with two seats and a Drive prompt; set `preset`, `look` and `paint` in the inspector.
## The vehicles
| `preset` | Vehicle | Moves on | Seats | Drift / special | Engine voice |
|---|---|---|---|---|---|
| `kart` | Go-Kart | VehicleController, direct drive, locked rear axle | 1 | handbrake drift | kart two-stroke |
| `sportsCar` | Sports Car | VehicleController: V6, 6-speed automatic, ABS, traction and stability control | 2 | handbrake drift | turbo |
| `muscleCar` | Muscle Car | VehicleController: V8, ABS and stability, traction control off | 2 | handbrake drift, burnouts | V8 |
| `monsterTruck` | Monster Truck | VehicleController: V8, all-wheel drive, locked diffs, traction and stability control, 2.1x wheels, air control | 2 | handbrake drift, steers in the air, rights itself | V8 |
| `buggy` | Dune Buggy | VehicleController: turbo four, automatic, stability control, locked rear, long travel | 2 | handbrake drift, air control | four |
| `deliveryTruck` | Delivery Truck | VehicleController: diesel, automatic, every assist on | 2 | | diesel |
| `bus` | City Bus | VehicleController: big diesel, automatic, every assist on | 38 (driver + 37) | | diesel |
| `tank` | Tank | VehicleController on hidden road wheels + skid steering | 2 | turns on the spot, turret follows the camera | diesel |
| `hovercraft` | Hovercraft | four air springs over land and water | 2 | handbrake slides sideways | turbo fan |
| `speedboat` | Speedboat | Buoyancy on the engine's water, propeller, rudder, keel | 4 | handbrake carves a hard banked turn, planes at speed | V8 |
| `rowboat` | Rowboat | Buoyancy, oars in strokes | 2 | handbrake carves, boost is a sprint stroke | silent |
| `arcadePlane` | Arcade Plane | LiftSurface wings, tail and fin; tricycle gear | 2 | takes off, flies, lands; brakes | four (prop) |
| `helicopter` | Helicopter | rotor lift with height hold | 4 | hovers, tilts to fly | turbo |
| `spaceship` | Spaceship | thrusters, gravity held off | 2 | strafes, climbs, boost x2 | electric |
**Looks** (`look`): `toy` (chunky, rounded, glossy), `lowPoly` (faceted, flat-shaded) and `realistic` (detailed, panel lines, chrome, lamps). The five road cars use torqueCars' bodies, wheels and paint; the other nine are generated by `vehiclesKit.modelgen` with torqueCars' meshkit in the same three looks.
**Paints** (`paint`): `auto` (the preset's own), `red`, `orange`, `yellow`, `green`, `teal`, `blue`, `purple`, `pink`, `white`, `silver`, `black`, `brown`.
The **gallery** scene (`vehiclesKit.gallery`) lines up all 14 kinds in all three looks, labelled. The **island** scene (`vehiclesKit.island`) is Joyride Island, a small playable showcase with a kart, boats, a plane on a runway, a hovercraft and a helicopter.
## Getting in and out
Every vehicle carries an interactKit prompt: **Drive** when the driver's seat is free, **Ride** for a free passenger seat, nothing when it is full or you already sit somewhere. E / gamepad west button / the touch Interact button. Seated:
- the rider's own body sits in the seat (a seated pose made from the body's rig: hands on the wheel for the driver, in the lap for passengers), on every player's screen;
- the camera becomes a driveCams camera on the vehicle: chase (field of view widening with speed), cockpit and bonnet for the driver (chase and cockpit for aircraft), chase and orbit for passengers; the camera button steps through them;
- controls switch to the kit's controlsKit scheme (below), and the HUD shows a gaugeClusters speedometer and rev counter, a barsKit boost meter and button prompts for the device in hand (on a phone the speedometer moves to the top middle, clear of the touch buttons, and the key prompts give way to the buttons' own labels);
- getting out (E / west / the touch Exit button) gives back the walking camera and controls and stands you beside your door. A land vehicle or aircraft is given up as soon as it has come to rest: it belongs to nobody until the next player gets in. A boat or hovercraft stays with its owner (the host claims one nobody owns), because an entity nobody owns is simulated by no peer and would freeze on moving water.
Stuck? **Recover** (R, View on a pad, the touch Reset button) always frees you: the vehicle stands upright, facing the way it faced, where it is if the ground there is level, otherwise a body-length back, forward or aside on the most level ground; a boat goes back to water deep enough to float in, and an aircraft over the sea is put back in the air.
From code: `Vehicles.enter(vehicle, seat?)`, `Vehicles.exit()`, `Vehicles.mine()`.
## Controls
| | Keyboard | Gamepad | Touch |
|---|---|---|---|
| **Driving** (cars, truck, bus, tank, hovercraft, boats) | W/↑ throttle, S/↓/Space brake (reverse at a stop), A/D/←/→ steer, Shift boost, Ctrl handbrake / drift / carve, R recover, H horn, C camera, E get out | RT throttle, LT brake, left stick steer, Y/LB boost, B/RB handbrake, View recover, L3 horn, R3 camera, X get out | a floating steering stick (put your thumb down anywhere on the left half and drag: the further, the harder it steers), Gas and Brake pedals, Boost and Drift buttons, corner Exit, Cam, Horn and Reset; swipe up boosts |
| **Flying** (plane, helicopter, spaceship) | W/S stick forward / back, A/D bank and turn, ←/→/Q rudder (strafe in the spaceship), Space/↑ throttle up or climb, Ctrl/↓/Z throttle down or sink, Shift boost, B brakes, H horn, C camera, E get out | left stick, right stick X rudder, RT / LT throttle, LB boost, RB brakes, L3 horn, R3 camera, X get out | floating stick, Up and Down buttons, Boost and Brake buttons, corner Exit, Cam and Horn |
| **Passenger** | C camera, E get out | R3 camera, X get out | corner Exit and Cam |
Every touch button carries a short label (Gas, Brake, Drift, Boost, Exit, Cam, Horn, Reset, Up, Down) so it reads in full on a small phone.
How each flies: the **plane** has a throttle lever (Space raises it, Ctrl lowers it, it stays where you leave it); roll down the runway to about 100 km/h and pull back (S) to take off; let go of the stick and it flies level, holding its height. Hold A or D and it banks (up to 55 degrees, never further) and turns round without losing height; let go and the wings come level. To land, line up with the runway and pull the throttle back below a third: hands off, it glides down at about 5 m/s and flares by itself in the last few metres, so it settles onto the runway; then hold Ctrl at idle and B to brake. It will not lift its nose when it is too slow to fly. The **helicopter** holds its height by itself: Space climbs, Ctrl sinks, W/S tilts it forward and back, A/D turns. The **spaceship** hovers with gravity held off: W/S thrust, A/D turn, Space/Ctrl up and down, arrows strafe.
## Boost and drift
Every vehicle has a **boost** (Shift / Y / swipe up) that drains a meter (`boostCharge`, shown by the barsKit bar) while held and refills after: more drive and top speed on the cars (the VehicleController's own boost), more thrust everywhere else. **Drift**: the handbrake locks the rear wheels of the cars into a slide (counter-steer assists keep it catchable), lets the hovercraft slide sideways round a turn, and makes the boats carve: the keel digs in, the turn tightens and the hull leans harder into it. Boats always lean into their turns, hold a steady trim at speed and stay upright through hard turns and carves. Boats float on whatever water the world has: the Tidewater water kit's `Buoyancy` when it is installed, else the engine's `FluidForces`. In water shallower than the hull, the propeller only pushes back toward deeper water, so you can reverse off a sandbank but never drive up a beach.
## Multiplayer
The world is always multiplayer, and players come from the scene's player prototype; the kit builds no players of its own.
- **The owner decides seats.** A prompt press goes to the peer that owns the vehicle (interactKit's request path), which hands out the seat in `occupants`, so two players pressing at once never share a seat. A vehicle nobody owns is decided by the world's host.
- **Ownership follows the driver.** When a player takes the driver's seat, the owner releases the vehicle and the driver's peer claims it: that peer simulates it (VehicleController, Buoyancy, wings) from its own controls with no round trip.
- **Getting out gives it up.** Once every seat is empty and the vehicle has come to rest, its owner releases it, so it belongs to nobody until the next player gets in, and that player's machine claims it. A boat counts as at rest once it only drifts on the swell. A driver who leaves the world frees their seat.
- **A new preset for everyone.** Changing `preset` on a driven vehicle is done by its driver's machine; on a parked vehicle nobody owns, the host takes it, sets it up as the new preset and gives it up again once it is at rest. Either way every player gets the same new vehicle, and everyone aboard a driven one stays in their seat.
- **Smooth for everyone else.** Every other peer draws the vehicle from the poses its driver sends, with the engine's own interpolation (`sync.interpolation_delay`, `multiplayer.setSmoothing`), at full speed, catching up after a hiccup instead of snapping. Seated riders' bodies are placed in their seats by every peer, so passengers ride exactly with the vehicle on every screen.
- The driving values (`car.rpm`, `car.gear`, boost, horn) replicate, so every player hears every engine and horn.
## Settings
`Vehicle` component fields: `preset`, `look`, `paint`, `passengers` (allow riders, default true), `enterRange` (metres from the vehicle's edge, 0 = 1.6), `cameraModes` (driveCams modes for the camera button, e.g. `"chase cockpit hood tv"`). State the owner writes: `occupants` (seat -> peer id, seat 1 is the driver), `boostCharge`, `boosting`, `horn`, `builtFor` (the preset its physics is set up for).
Methods: `enter(seat?)`, `exit()`, `driver()`, `seats()`, `info()` (preset, look, paint, speed, km/h, rpm, gear, boost, occupants, owner), `set({ preset, look, paint })` (a live swap: change the preset of a running vehicle, parked or driven, and it rebuilds as a brand-new one of that preset, with the same weight, gearbox, driving aids and seats. The driver stays in the driver's seat and keeps driving, and passengers stay in their seats. A passenger whose seat number the new preset doesn't have moves to a free seat, and gets out only if none is free. The controls, HUD and camera switch to the new preset without getting out: the camera frames the new vehicle exactly as getting into a brand-new one does (a small kart close behind, a bus or monster truck further back and higher), and never from inside its body), `setIntent({ throttle, brake, steer, handbrake, boost, recover, pitch, roll, yaw, up, down })` (drive from code: AI, autopilot, tests; give only the controls you need, e.g. `setIntent({ throttle = 1 })`, and the rest count as zero / off; `nil` hands back), `recover()` (the Recover button's work, on the owner), `rig()`, `isParked()`.
HUD: `Vehicles.hud({ gauge = "analog", bar = "segmented", units = "mph", hints = true })`; `gauge` is any gaugeClusters style (`analog`, `digital`, `rally`, `retro80s`, `scifi`, `minimal`, `arcade`, `pixel`, `hud`, `truck`) or `"none"`, `bar` any barsKit look or `"none"`.
## API
`local Vehicles = require("~vehiclesKit.api")`
| Call | Does |
|---|---|
| `spawn(preset, pos, opts?)` | A shared drivable vehicle. `opts`: `look`, `paint`, `yaw` (degrees), `name`, `parent`, `passengers`, `cameraModes`, `synced` (default true). Returns the entity. Works in a scene's `build.luau` and at runtime. |
| `display(preset, look?, paint?, pos?, opts?)` | A showroom model: the look alone, no physics or seats (galleries, menus, garages). |
| `presets(filter?)` | Preset names; `filter` = any of `{ domain = "land"|"water"|"air", game = "racing", class = "car"|"tank"|"hover"|"boat"|"plane"|"heli"|"space", scheme = "drive"|"fly" }`. |
| `looks()`, `paints()` | The look and paint names. |
| `describe(preset)` | `{ label, blurb, domain = "land"|"water"|"air", domains (everything it can travel on: the hovercraft is water and land), games (the kinds of game it suits), class, scheme, seats, mass, topSpeed (m/s), topSpeedKmh, drift, boost, voice, paint, assists = { antiLock, tractionControl, stability, gearbox } }`. |
| `of(target)` | The Vehicle for any way of naming one: a vehicle from `all()`, its entity, an entity id or a name. |
| `all(filter?)` | The registry of every live vehicle on this peer, optionally filtered: `{ preset, look, domain = "land"|"water"|"air", class, free = true }` (free: nobody in the driver's seat). |
| `nearest(position, filter?)` | The live vehicle nearest a point, matching `filter`, and its distance in metres. |
| `mine()` | The Vehicle the local player sits in, and the seat. |
| `enter(vehicle, seat?)`, `exit()` | Seat / unseat the local player. `vehicle` is anything `of` takes: `Vehicles.enter(Vehicles.all()[1])` works. |
| `hud(opts?)` | Read or set the driving HUD. |
| `component()` | The Vehicle component type. |
## Works with the driving kits
Every vehicle publishes torqueCars' driving contract (`torqueCars.package/CONTRACT.md`) on its root entity: `car.rpm`, `car.load`, `car.throttle`, `car.gear`, `car.shiftCount`, `car.boost`, `car.limiter`, `car.skid`, `car.impactCount`, `car.rpmIdle/Redline/Max`, `car.voiceId` (replicated), `car.speed`, `car.kmh`, `car.gears`, `car.brake`, `car.steer`, `car.mountSeat/Hood/Bumper`, `car.size`, and `player.vehicle` on the local player's avatar and camera while they sit in it. So **gaugeClusters** gauges, **engineVoices** engine sound and **driveCams** cameras read a vehiclesKit vehicle exactly as they read a torqueCars car, and anything else written against the contract (aiDrivers, driveProgress) can too.
## Guides
Two guides ship inside the package. Open them with the `guides` tool or `zero guides read <address>`:
- **How to add a drivable car (or boat, or plane) to my game**, `vehiclesKit.package/how-to-add-a-drivable-car-boat-or-plane-to-my-game`: adding a vehicle, getting in and out, switching vehicle type and look, boost and drift, controls, multiplayer.
- **Example: a small island with a kart, a boat and a plane**, `vehiclesKit.package/example-island-with-a-kart-a-boat-and-a-plane`: building Joyride Island step by step.
## How it behaves
- Vehicles are built on every peer from `preset`, `look` and `paint`; their parts are temporary and never saved into a scene, so a scene stays small and a swap is one field.
- A vehicle nobody drives that has come to rest parks: its controller and per-step work sleep, and its engine voice is taken off, until someone gets in or it is pushed. A boat on the waves never stands still, so it counts as at rest once its drift across the water is under 1 m/s.
- Wheeled vehicles keep their body at least 25 cm clear of the ground, so on a kerb or a step the wheels meet it first and the suspension lifts the body over.
- No vehicle ever moves faster than its own top speed with boost (plus a margin) or spins faster than a few turns a second, so a hard crash can't fling it across the map.
- Glass on the closed cabins (plane, helicopter, spaceship, bus windscreen) is drawn opaque from outside, so riders in those cabins are seen from inside only; the bus's side windows are open frames so its passengers show.
## Tests
`tools.use("tests", "run", { suite = "vehiclesKit" })` in edit mode. It checks the catalogue, every layout, the models, building every preset in every look (driven rig and showroom model), root components per class, the controlsKit schemes and their touch layouts, the seated-pose maths, seat bookkeeping (including who keeps which seat through a preset switch) and the API. Three tests then enter play on their own, in the engine's test scene with a player, and leave it again. The first switches a parked kart to a monster truck and checks it has exactly what a brand-new monster truck has, field for field on its Physics, VehicleController, Buoyancy and every wheel. The second has the player drive a monster truck and switch it to a kart, back to a monster truck, to a kart and to a monster truck again while rolling. After every switch it checks, frame by frame through the switch, that the camera never stands inside the vehicle's body. It then checks that the player is still the driver and still sitting in the seat, and, with the vehicle stopped, that the camera frames it exactly as getting into a brand-new vehicle of that preset does: the same chase distance and height, the same spot behind and above it, and every part of the vehicle looked through. Finally it checks that the vehicle pulls away again and matches a brand-new vehicle of the new preset. The third checks that a speedboat floats at its waterline, and that after its driver gets out on the waves it parks yet stays owned, so it keeps floating. Driving, floating, flying and seating were also checked in play by hand.
## Known limits
- Each car-physics vehicle is expensive, more so in the browser (#22245); parked vehicles sleep, but keep the number of wheeled vehicles in one place modest.
- Getting out at sea leaves you walking on the sea floor: players have no swimming (#20618).
- The engine no longer ships an ocean of its own. Boats float with the Tidewater water kit's `Buoyancy` when the world holds Tidewater, otherwise with the engine's `FluidForces`; either floats on every water `Physics.water` answers (a Tidewater sea or lake, a terrain lake, a `Water` box).
- Two engines signed in to the same account collide as one player (#14448), which is why the multiplayer hand-over was checked with one engine and the engine's replication diagnostics rather than with two players side by side.
## Dependencies
Installing vehiclesKit brings all of these; the table is what each is for.
| Kit | Why |
|---|---|
| controlsKit (`889ac3ad-87d6-427a-8bc4-3e955943fa6c`) | Driving, flying and passenger schemes on keyboard, gamepad and touch; prompt glyphs |
| interactKit (`f7af5474-4cb3-48d3-96e6-15f897ccce4f`) | The Drive / Ride prompt and the owner-decides seat requests |
| barsKit (`c154eb07-ce7c-48ca-8232-4ce1a8754214`) | The boost meter |
| soundstage (`9558df1d-cc37-4a79-9171-6ecfdaa98591`) | The horn |
| gaugeClusters (`41d423e0-3c3a-4ff6-8196-60961343e447`) | Speedometer and rev counter |
| engineVoices (`7a598b58-ffef-40e6-a5e6-4dc7157cfbc0`) | Engine sound |
| driveCams (`551b2bab-8534-470a-8be4-70e78694ac25`) | Chase, cockpit and bonnet cameras |
| torqueCars (`eab0ff7b-a5f6-4670-8448-2fb26440a082`, comes with driveCams) | Car bodies, wheels, paint and meshkit |
## What's inside
`Vehicle.component` (the vehicle), `api` (front door), `catalog` (the 14 kinds as data), `layouts` (seats, wheels, colliders), `build` (model, physics and parts), `drives` (how each class moves), `controls` (controlsKit schemes), `hud` (gauge, boost bar, prompts), `pose` (seated pose), `registry`, `models` / `modelData` / `modelgen` / `modelbake` (the nine generated vehicles, 48 meshes in `meshes/`), the `gallery` and `island` scenes, two guides and `vehiclesKit.testSuite`.
## Changes
- **1.1.7**: depends on torqueCars 1.2.9 (was 1.2.8), so a world that installs a newer torqueCars beside vehiclesKit runs one copy of it, not two. torqueCars 1.2.9 adds only opt-in body options (cylindrical wheel wells, per-axle well depth, dropping zero-area triangles); stock bodies are unchanged.
- **1.1.8**: two players now always agree on who is in the driver's seat. The owner seats a new driver and keeps the vehicle until that driver's own machine shows it in the seat and asks for it (a `takeOver` request through interactKit); only then is it released and claimed. Before, the owner released it on the next frame, the new driver could claim it before the seat write arrived, and its empty seats then became the truth on every machine: the driver sat in no seat on their own screen, could not get out, and the old owner's writes were refused.
- **1.1.10**: boats float again now that the engine ships no ocean of its own: they use the Tidewater water kit's `Buoyancy` when the world holds Tidewater, else the engine's `FluidForces` on the hull (same density and hull box), with no hard dependency on either kit. `vehiclesKit.build` gains `floater()`, `submersion(e)` (reads either) and `sea(e, opts)`; Joyride Island and the tests lay their sea with it (Tidewater's ocean, else an engine `Water` box with a flat water surface). An idle boat stays with its owner instead of being released, so it keeps floating; getting out gives the walking controls back (not a twin-stick map).
- **1.1.9**: getting into another player's car works at once, every time. No machine writes to another player's character any more: switching walking off and on (Locomotion) and moving the drawn body onto the seat are done only for the local player's own character or a body that is not synced, where before every other machine tried each frame and was refused (thousands of refusals a session). Every seat write carries a revision, and the owner sends the seats again once a second for four seconds after a change and until a seated driver has taken the vehicle over, so a rider whose machine missed the change still gets in.
- **1.1.6**: holding the interact button (E, gamepad X, touch Interact) to get in no longer gets you straight back out. Interact and exit share a button, and the press that seated a player was read again as "exit" once the seat's controls went live, so a press held for about 0.4 s entered and left at once. The seat now arms its exit only after that button has really been let go (0.1 s up after it was seen down, or 0.6 s after getting in when it was never down); a fresh tap gets you out as before. `vehiclesKit.controls` gains `held(action)`. Tested 6 of 6 held entries stay seated and 6 of 6 taps get out.
- **1.1.5** (1.1.3 and 1.1.4 were draft heads of this release's pull request): depends on driveCams 1.1.4, so the chase and orbit cameras ignore a car's crash shell (a crashCars-style soft body held beside the car): the camera no longer pulls inside the body of a car that has one. The fix had been sent here by mistake in 1.1.2's pull requests while vehiclesKit kept installing driveCams 1.1.3 from Torque Valley; it now comes from driveCams' own release. Carries the 1.1.2 control-scheme fix unchanged. Wheels can also state an opt-in `restCompression` (metres the spring compresses under the vehicle's own weight): the wheel is mounted that much lower, so once the spring takes the weight the wheel stands at its layout position and the car sits at its designed ride height. Left out it is 0, so the 14 stock vehicles are unchanged.
- **1.1.2**: the driving, flying and riding control schemes come back after controlsKit reloads. vehiclesKit registered them once behind a flag of its own, so when controlsKit's scheme registry was emptied (a hot reload, or an install moving the world to another controlsKit release) every seated vehicle failed with "no scheme 'vehiclesKit_drive'" and stopped driving. It now registers whatever controlsKit lacks each time a rider begins. Depends on controlsKit 1.3.2; the test suite passes (36/36).
- **1.1.0**: presets made by other kits. `Catalog.addResolver(prefix, fn)` lets a kit (a car generator, a garage of player-built cars) turn any preset name starting with its prefix into a vehicle kind, on every peer, from the name alone, so a synced `preset` string is all a peer needs to build the identical vehicle. A resolved kind can bring its own `layout` (seats, wheels, hull, and `colliders`: several boxes that together are the body, so a pickup's bed stays open), its own body mesh and material (`body = { source = "custom", build, wheel, dress }`), its own wheel meshes, a `dress` hook that adds parts (interior, lamps) on every peer, and its own `centerOfMass`. `preset` is now a string field so such names can be set. The 14 built-in presets are unchanged and the test suite passes.
- **1.0.11**: the driving HUD can be placed by the game around it: `Hud.configure` takes `gaugeAnchor`, `gaugeSize`, `gaugeOffsetX`/`gaugeOffsetY` for the speedometer, `barAnchor` for the boost bar, and `hintsLeft`/`hintsTop`/`hintsMaxWidth` for the control prompts (they wrap to fit). Left out, everything sits where it always has.
- **1.0.10**: a vehicle that changed kind (a kart picked as a buggy at a kart select) and then passed to another player's machine drives again. Its drivetrain had been built on the first machine and named wheels the new owner does not hold, so the car sat at full throttle without turning a wheel. The owner now takes such a drivetrain off and the VehicleController builds one for its own wheels.
- **1.0.9**: a new store-listing description in package.yaml: what the kit gives your game, and how to install it and spawn your first vehicle. No change to how the kit works.
- **1.0.8**: after a preset switch while you drive, the camera frames the new vehicle exactly as getting into a brand-new one does, from small to big and big to small. Before, a kart switched to a monster truck kept the kart's low, close camera, which ended up inside and under the truck. The camera never passes through the new vehicle's body during the switch. The driven-switch test now checks the camera on every switch.
- **1.0.7**: switching the preset of a vehicle you are driving keeps you in the driver's seat, still driving, every time and in both directions (1.0.6 let everyone out). The controls, HUD and camera views change to suit the new vehicle, and passengers keep their seats or move to a free one. The Drive / Ride prompt now follows the new vehicle's size. The driven-switch test now switches four times, back and forth, and checks the driver is still seated after each switch.
- **1.0.6**: switching the preset of a parked or driven vehicle gives it everything a brand-new one of that preset has (a parked kart switched to a monster truck used to keep the kart's weight, gearbox and driving aids); boats left on the water are given up after you get out, like any other vehicle; the JOYRIDE RACEWAY sign shows only its own side's lettering; in the first example both vehicles face open ground; tests for both fixes.
- **1.0.5**: the one field that picks the vehicle is `preset` (was `kind`), and the names are `buggy`, `arcadePlane` and the look `lowPoly` (were `duneBuggy`, `plane`, `lowpoly`), so a scene written for 1.0.4 changes those words; `Vehicles.presets()` replaces `kinds()`. `describe` now says whether a preset is a land, water or air vehicle and which kinds of game it suits, and `presets()` filters by both. The registry is the registry of live vehicles (`all(filter)`, `nearest`, lookup by vehicle, entity, id or name) with nothing else in it. `setIntent` takes only the controls you give it, the rest count as zero, and `Vehicles.enter` takes a vehicle straight from `Vehicles.all()`. The JOYRIDE RACEWAY sign reads the right way round from both sides.
- **1.0.4**: touch steering is a floating, proportional stick anywhere on the left half; short touch labels and the speedometer at the top on phones, clear of the buttons; kerbs climbable (25 cm body clearance) and a Recover that always frees you (the island's kerbs are sloped too); getting out gives the vehicle up once it is at rest; the speedboat leans into turns, holds its trim and stays upright, and can be reversed off a sandbank; the plane holds a bank without losing height, glides down and flares to land with the throttle back, and no vehicle can be flung faster than its top speed.
- **1.0.3**, the first example tried in a brand new world: one install brings every kit it needs (the README no longer asks for separate installs, which collided), and the example widens the template floor so the car has room.
- **1.0.2**, Joyride Island: a paved plaza under the spawn, so players never arrive before the terrain and fall into the sea.
- **1.0.1**, docs: the assists each car has, vehiclesKit's own guid in the install steps.
- **1.0.0**, first release.
# Tidewater: water for Zero games
Oceans, lakes, ponds, swimming pools, rivers, streams, waterfalls, puddles and wet streets,
shorelines and the view under the surface, plus the little water effects that make it feel
real. Every kind of water comes in **seven looks** (realistic, crystal clear tropical, cartoon,
painted ink, low-poly retro, pixel art and toy plastic), and they all work the same way, so a lake becomes a
cartoon lake, or a pond becomes a river, by changing **one setting**. The Zero engine ships no
ocean of its own: Tidewater is the water, and the engine floats things on every kind of it
natively (`FluidForces` on any water `Physics.defineWater` declares; Tidewater declares them all).
## An ocean in your world in five minutes
1. **Install Tidewater.** In the editor's ZeroMind panel search for "Tidewater water kit" and
press Install, or in the agent shell run
`zero zeromind installAsset 59484771-e730-4d73-ab7b-6afb09ab129e` (that is Tidewater's guid).
The splash and ripple effects (`tidewaterFx`) come with it, and so do the material packages
its ready-made scenes use (`groundMaterials`, `woodsMaterials`, `stoneMaterials`,
`organicMaterials`, `materialLibraryKit`): in an empty world the install takes about two
minutes (about 18,000 files).
2. **Add the sea.** A brand-new world has no scene yet: make one first (in the agent shell,
`zero scene create sea flat --opts '{"startup":true}'`). The flat template's ground sits at
height 0, right on the waterline, so the sea's shore foam washes over it. The ground is made
by the scene's `build.luau`: delete its `ground` lines there, or lower its `localPosition`, for
open sea. Then, in the editor, select any entity (or make an empty one at height 0), press
*Add component* and pick **WaterBody**. Set `kind` to `ocean` and `preset` to
`tropicalLagoon`. The sea appears out to the horizon at once. (From the agent shell, use the
code below instead: there is no shell command for *Add component*.)
3. **Float something.** A box with a dynamic body (`Physics` with `kind = "dynamic"`) and a
collider (`BoxCollider`), plus the **Buoyancy** component (`tidewater.components.Buoyancy`, `density = 0.5` floats it half
under). Press Play: it rides the waves, and it splashes when you drop it in. Add the **Wake**
component and it leaves a foam trail as it moves (from about 1.5 m/s; `width` sets the trail
width).
4. **Change the look.** Set the WaterBody's `look` to `cartoon`, `crystal`, `painted`,
`lowpoly`, `pixel` or `toy`. Change `kind` to `lake` and give it a `size` for a lake instead: the
entity's height is the lake's surface, and its sculpted bed is drawn, not solid, so add a
collider under it if players or boats can reach the bottom (the dock guide's `lakeFloor`).
The same in code. A scene made with `zero scene create` builds itself in its `build.luau`, inside
`function content()`; put these lines there (`entity.spawn` in a build is saved with the scene):
```lua
-- in your scene's build.luau, inside content()
local sea = entity.spawn("Sea")
sea.component.add("tidewater.components.WaterBody", { kind = "ocean", preset = "tropicalLagoon" })
local lake = entity.spawn("Lake", { position = { 120, 4, 0 } })
lake.component.add("tidewater.components.WaterBody", { kind = "lake", look = "realistic", preset = "alpineClear", size = { x = 60, y = 40 }, depth = 6 })
-- later: lake.component.get("tidewater.components.WaterBody").look = "cartoon"
-- or: lake.component.get("tidewater.components.WaterBody").kind = "pond"
-- a boat on the lake: a dynamic body, a collider, Buoyancy and a Wake
local boat = entity.spawn("Boat", { position = { 120, 4.5, 0 } })
boat.component.add("Physics", { kind = "dynamic", mass = 160, angularDamping = 0.5 })
boat.component.add("BoxCollider", { half = { 0.7, 0.3, 1.7 } })
boat.component.add("tidewater.components.Buoyancy", { density = 0.4 })
boat.component.add("Wake", { width = 1.4, length = 3.4 })
```
From a script that runs in play (not a build), use `entity.spawnSynced` instead, so every player
gets the same water and boat.
## What you get
| Kind | What it is | Presets |
|---|---|---|
| `ocean` | The spectral FFT sea out to the horizon: calm glass to a gale, foam where waves break and along the shore, a seabed seen through it, shoaling turquoise over a reef. Can also be a bounded tile (`extent`). | calmClear, darkChop, darkRolling, heavySwell, whitecapped, murkyGrey, paleSwell, glassyDark, gale, tropicalLagoon, northernGale, harbourCalm, moonlitSwell |
| `lake` | A still sheet in any outline over a sculpted bed: clear turquoise shallows to dark deep water, sky, sun and surroundings reflected, the bed and its caustics seen through it, shore foam. | alpineClear, tropicalLagoon, murkyPond, glacierMilky, darkPeat, nightStill |
| `pond` | The small, murkier lake. | lilyPond, murkyPond, greenAlgae, koiPond, swampy, clearSpring |
| `pool` | A tiled swimming pool with coping, deck, strong caustics and optional underwater lights. | outdoorPool, backyardPool, indoorPool, nightPoolLit |
| `river` | A ribbon along a `path` that visibly flows downhill, faster where steeper, white water through rapids; its current carries what floats. | forestRiver, mountainRapids, lazyLowland, muddyFlood, glacialMeltwater, canal |
| `stream` | The narrow, shallow, clear river with pebbles and riffles. | brook, mossyCreek, alpineRill |
| `waterfall` | A sheet falling from a lip, tearing into streaks, into a churning plunge pool with mist, spray and drips. | tropicalCascade, grottoVeil, alpineRibbon, wideCurtain, trickle |
| `puddles` | Puddles that form only in the low spots of a street while it is wet, mirror-like, ringing in the rain, drying away after. | cityStreet, muddyTrack, cobblestone |
| `shoreline` | Water meeting a long, gentle beach, a slow swell lapping up the slope and a wide band of surf wash along the waterline. | sandyBeach, pebbleCove, rockyShore |
| `hotspring` | A small mineral basin of milky warm water with steam rising off it. | milkyBlue, emeraldSpring, mineralTerrace |
| `underwater` | A deep basin made to be swum in: strong underwater fog, caustics on the floor, light shafts and bubbles rising from the bed. | kelpCove, deepBlue, murkyHarbour |
Eleven kinds, seven looks: **77 combinations**, shown side by side in the `gallery` scene.
**Looks:** `realistic`, `crystal` (tropical crystal clear: low absorption, turquoise
shallows, the bed sharp through it), `cartoon`, `painted` (ink linework over a colour wash),
`lowpoly` (flat-lit facets, retro), `pixel` and `toy` (glossy moulded plastic for toy-style games: two candy bands, a hard glossy highlight; also `plastic`, `toybox`, `bathtub`). The environment kits' names are accepted too
(`real`, `tropical`, `clear`, `toon`, `painterly`, `retro` and friends).
**Underwater**, for every kind: murky fog coloured by the water, moving caustic light on the
floor, light shafts, the surface rippling overhead, and a waterline split when the camera
straddles it.
**Effects** come from **Tidewater FX** (`tidewaterFx`), its own package that installs with
Tidewater and works without it: 15 effects, each in the seven looks. Tidewater's
`Water.splash` / `Water.ripple` and the `Wake` and `Splashes` components reach it, and other
kits can ask it for a ripple or splash with no dependency at all (see its README).
| One-shot | | Continuous (runs until stopped) | |
|---|---|---|---|
| `plop` | a pebble or thrown stone | `bow` | bow spray off a moving boat |
| `body` | a person or crate jumping in | `spindrift` | spray blown off breaking waves |
| `droplets` | a body climbing out, shaking off | `mist` | mist and spray rising off a waterfall or hot spring |
| `spray` | a burst of spray in the wind | `drips` | drips falling from eaves, a lip, a hull |
| `footstep` | a foot landing in a puddle or the shallows | `bubbles` | bubbles rising under water |
| `fishJump` | a fish leaving the water and falling back in | `wake` | the foam trail behind a boat or swimmer |
| `rainSplash` | one heavy raindrop: tiny crown and ring | `foam` | a drifting patch of foam in an eddy or under a fall |
**Splashes happen by themselves.** From the moment any Tidewater water exists, anything that falls
into it splashes, sized to what it is: a pebble plops, a person makes a big splash, something
climbing out drips. Each splash is played by the owner of the body and synced, so every player
sees it once. `Water.autoSplash(false)` turns it off for a game that plays its own.
## Floating, flow and asking the water
Every kind declares itself to the engine's water physics (`Physics.defineWater`), so the
engine's `FluidForces` and Tidewater's `Buoyancy` component float anything on any water, a
river's current carries it downstream, and `Physics.onWater` hears it splash in.
```lua
local Water = require("tidewater.modules.water")
Water.heightAt(x, z) -- the TOPMOST water's surface height there, or nil
Water.heightAt(x, z, y) -- the water at height y instead (a lower one of stacked waters)
Water.flowAt(x, z) -- { x, y, z } m/s: the river's current, the waves' motion
Water.normalAt(x, z) -- unit { x, y, z } the surface faces (tilted on a wave's face)
Water.surfaceAt(x, z) -- Surface? { height, flow, normal, depth?, water? } in one typed answer
Water.tideAt(x, z) -- TideState? { offset, rising, high, low }, nil where that water has no tide
Water.sample({ x, y, z }) -- the engine's whole answer: surface, depth, normal, velocity, floor, body
lake:heightAt(x, z) -- this lake's own surface there, nil off it (never another water)
lake:surfaceAt(x, z) -- also lake:flowAt, lake:normalAt, lake:tideNow()
e.component.get("tidewater.components.WaterBody"):heightAt(x, z) -- and :flowAt, for water saved with the scene
crate.component.add("tidewater.components.Buoyancy", { density = 0.45 }) -- floats 45% under, rides the waves
boat.component.add("Wake", {}) -- foam trail, bow spray, ripples
```
The module exports the types `Surface`, `TideState` and `Handle` (`Water.Surface` and friends
in strict code), and every `nearY` argument (the optional third one) picks between stacked
waters the way `heightAt`'s does. `normalAt`, `surfaceAt` and `tideAt` were added in this
round; `heightAt` and `flowAt` are unchanged.
Where waters overlap from above (a lake out over the sea, a pool on a ship's deck), `heightAt`
and `flowAt` with no height answer the top one, and a body asked about itself answers only for
itself: checked with a lake at height 10 over the showcase sea, `Water.heightAt` gives 10 over
the lake and the sea's height beside it, `heightAt(x, z, 0)` gives the sea under the lake, the
lake's own `heightAt` gives 10 over it and nil off it, and the sea's own gives the sea's height.
Measured: a 400 kg, 1 m box on the `tropicalLagoon` sea stays within 4 cm of the surface with
`Buoyancy` (6 cm with the engine's plain `FluidForces`); on a lake it settles 40% submerged, as
its density says. On rough seas `Buoyancy` holds a body to the water by itself: the rougher the
water under the hull moves, the harder it couples the hull to it (still water and gentle seas keep
the `damping` you set exactly). Measured over 60 s with a 1 m box at density 0.5: in a `gale` its
centre stays on average 0.15 to 0.45 m under the local surface and dips at worst 0.8 to 2 m in the
steepest troughs (before: 3 to 5 m); in a `northernGale` 0.16 to 0.29 m on average, 0.8 to 1.25 m
at worst.
## Puddles that follow the weather
Puddles fill in about ten seconds as the ground gets wet and dry away over `dryTime` (90 s by
default) after the rain stops, even when a weather kit leaves its wetness at 1. A dry street
declares no water and draws nothing. Pictures of the same street wet and dry are in
`documentation/media/` (`puddles_wet.jpg`, `puddles_dried.jpg`).
## Tide
An `ocean`, `shoreline` or `lake` can rise and fall like a tide. Two `WaterBody` fields:
`tide`, the range in metres from low water to high water (0 = none, the default), and
`tidePeriod`, the seconds from one high water to the next (600 = ten minutes, the default).
```lua
sea.component.add("tidewater.components.WaterBody", { kind = "ocean", preset = "harbourCalm", tide = 2, tidePeriod = 900 })
local t = Water.tideAt(x, z) -- { offset = metres above mean, rising, high, low }, nil without a tide
local t2 = handle:tideNow() -- the same for one water you made with Water.create / Water.attach
```
`Water.create` and `Water.attach` take `tide` as a number (the range, 600 s period) or a table
`{ range, period, phase }`. The tide follows the session's shared water clock
(`Physics.waterTime()`), so every player sees the same water at the same height and a late
joiner sees it where everyone else does; nothing is sent over the network. On the ocean the
drawn sea, the shoaling against the `ground`, the underwater pass and the physics water all
follow it; on a lake or shoreline the surface and its physics move while the bed and banks stay
put. The water follows in 2 cm steps, so a slow tide re-declares its physics only every few
seconds, and a water with no tide pays nothing. The maths alone is
`require("tidewater.modules.tide")` (`Tide.spec(value)`, `Tide.at(spec, time?)`).
## Named varieties
Every kind has named varieties (`preset`); `Water.presets(kind)` lists them, default first, and
the kinds table above names them all. Plain words resolve too, matched without case, spaces,
dashes or underscores, the way a person asks for one:
| Kind | Plain words |
|---|---|
| ocean | glassy, calm, stormy / storm, rough, choppy, swell, grey, harbour / harbor |
| river | lazy, slow, rapids, whitewater, flood, meltwater |
| pool | backyard, garden, indoor, olympic, night, outdoor |
| waterfall | curtain, wide, ribbon, thin, veil, cascade, trickle |
| lake | alpine, clear, lagoon, murky, glacier, peat, night |
| pond | lily, koi, swamp, algae, spring |
| hotspring | onsen, milky, emerald, terrace |
| stream | creek, rill |
| puddles | city, mud, cobbles |
| shoreline | beach, sand, pebbles, rocks, rocky |
| underwater | kelp, deep, harbour |
`backyardPool` (an 8 x 4 m garden pool, 0.9 to 1.6 m deep, wooden deck) is new in this
round. A name a kind does not have falls back to its default with a warning naming the real ones.
## Rain and other kits
Tidewater rings its water in the rain from any weather kit that writes the named values
`weather.rain`, `weather.wetness` and `weather.wind` on an entity. **Cloudburst** does, so its
raindrops ring your lakes and puddles with no wiring and no dependency either way. Without a
weather kit: `Water.setWeather({ rain = 0.6 })`. Any kit can make rings and splashes:
`Water.ripple(pos, strength)`, `Water.splash("plop", pos)`.
## Multiplayer
`WaterBody` fields replicate and every peer builds the same water from them; waves run on the
engine's shared water clock, so two players see the same swell. A floating boat is a synced
body (its owner simulates it, others see it where it is) and its wake is drawn on every peer
from its motion. Effects take `{ sync = true }`; automatic splashes are played by the owner and
synced, never doubled.
Checked live with two players in the showcase (2026-11-15, two clients in one play session,
readings taken at the same instants on the shared water clock):
- **Same waves:** the sea at a fixed point agreed within 0.7 to 2.4 cm.
- **Same boat height:** the rowboat's hull, owner against second player, at matched moments:
-0.055 / -0.019 to -0.048 m, +0.099 / +0.100 m, +0.171 / +0.177 m, +0.106 / +0.134 m (0 to
4 cm apart; the second player draws the boat the usual 0.1 to 0.5 s behind).
- **Two players, checked live:** a synced splash thrown on either client was received on the
other, and the second player's client draws the wake (5 foam segments in 18 s while the owner
rowed, after the fix; 0 before).
- **Checked again on 2026-11-16, twice, the second time after both players left play and came
back in** (the user's editor and a second client, one play session, the showcase rowboat rowed
out from its berth with W by the first player). Every frame both clients recorded the boat's
position against the shared water clock; the second player's track was then matched to the
owner's at the network delay that fits best (about 0.25 s):
- Run 1: 8 m rowed, 90 matched samples: heights 3.4 cm apart on average (horizontal 1.8 cm).
- Run 2, after the reload: 30 m rowed, 533 matched samples: heights 4.3 cm apart on average
(horizontal 3.4 cm). The largest single gaps (31 to 34 cm) come from sampling a 0.4 m swell at
3 to 6 frames a second on a busy machine, not from the boat being elsewhere.
- Wake on the second player: its client laid 35 wake foam segments of its own while the owner
rowed (run 2), and the wake shows in its view (`documentation/media/r11_second_player_wake_run2.jpg`).
- Splashes and ripples: a synced splash and a ripple ring thrown on either client arrived on the
other in both runs (run 2: 4 of 4 from the second player to the owner, 8 from the owner to the
second player). One single splash in run 2 arrived late, after more than 3 s, while the owner's
client was busy sending its own stream of automatic splashes.
- Three bugs this found are fixed: an idle boat nobody owned was simulated by no one and froze on
the waves (vehiclesKit now keeps an idle boat owned, sent upstream), the `Wake` loop stopped on
every player but the boat's owner (a refused status write ended it), and the wake's foam waited
behind 80 or more queued splashes on a player who had just joined, so it laid none (it is now
built on the spot, at most once a second per boat, until the pool is ready).
## Ready-made scenes
`tidewater.scenes.*`: `tropicalLagoon`, `northernGale`, `mountainLakeDawn`, `forestRiver`,
`rainyStreet`, `waterfallGrotto`, and `gallery` (all 77 kinds and looks, labelled, with walkways;
`Gallery.setTime("dawn" | "day" | "dusk" | "night")` relights it).
## Cost
Measured with the kit's own bench (`tidewater.modules.costBench`, also the pause menu's
"Measure water cost on this device"). It builds each kind at an empty spot far from the scene,
looks at it through its own camera, and takes the median of rounds of water off against water
on. Each run is saved in `documentation/costs/`. A delta smaller than about 2 ms is lost in the
frame's own noise and reads as "about 0".
| Water | Desktop, native (frame / GPU) | Browser, desktop Chrome (frame / GPU) | Android tablet |
|---|---|---|---|
| Ocean (default quality) | +22.9 ms (second run +25.2) / +5.3 ms | +20.21 ms / +2.37 ms | not measured |
| Lake | about 0 / +1.2 ms | +1.93 ms | not measured |
| Swimming pool | about 0 | +1.94 ms | not measured |
| River | about 0 | +0.62 ms | not measured |
| Underwater pass | +3.8 ms (second run +8.8) | +5.13 ms | not measured |
| Puddles | about 0 | GPU +7.46 ms | not measured |
| Waterfall | +6.5 ms | about 0 | not measured |
| Hot spring | +3.6 ms | about 0 | not measured |
| Pond | about 0 / +0.3 ms | about 0 | not measured |
| Shoreline, stream | about 0 | about 0 | not measured |
- **Desktop, native**: Linux, 1920 x 1080, dev build, runs of 2026-11-15 22:40 and 23:34 UTC, on a
machine running two or three engine clients at once (a frame was already 30 to 90 ms before
any water).
- **Browser**: desktop Chrome, measured by the world's owner with the same bench (60 frames,
2 rounds); the bare frame was 48.52 ms with 20.42 ms of GPU.
- **Android tablet: not measured on a device yet.** A tablet is attached to the machine this kit
is built on, but another project was using it, and from inside the editor there is no way to
reach an attached device at all: engine #25931. So the column stays empty rather than guessed.
Open the world on the tablet, press Escape and choose "Measure water cost on this device"; the
run saves itself beside the others in `documentation/costs/` and fills this column. A desktop stand-in was tried
(the whole bench under the engine's `low` quality tier, the defaults a 4 GB tablet draws with:
`Bench.run({ tier = "low" })`, runs of 2026-11-16 in `documentation/costs/`), but on a desktop
shared by two engine clients the bare frame swung from 100 to 200 ms between rounds, so its
per-kind deltas are noise and are not quoted here. What carries over to a tablet is the shape:
the ocean is the one kind with real fixed work (its FFT and surface passes), and since this
version that work stops entirely whenever nothing moves; puddles and the underwater pass are
full-screen GPU work that scales with the tablet's lower render resolution; every other kind is
one transparent surface. For a phone or tablet pick lakes, ponds, pools, rivers, streams and
shorelines freely, keep one ocean at `quality = "low"`, and use puddles and underwater where
they matter.
**1.2.0 runs, twice at each tier** (native desktop, Linux, 2026-11-21 19:15 UTC, 120 frames a
side, 3 rounds; the bare frame was already 20 to 22 ms because the editor, the owner's client
and a sub-client shared one GPU, and this machine gave no GPU timestamps that day, so these are
frame-time deltas only):
| Water | High tier, run 1 / run 2 | Low tier (the tablet defaults), run 1 / run 2 |
|---|---|---|
| Ocean | +7.9 / +1.0 ms | +8.0 / +3.2 ms |
| Underwater pass | +5.9 / about 0 | +2.9 / about 0 |
| River | +5.0 / about 0 | +0.9 / about 0 |
| Puddles | +3.1 / about 0 | about 0 / about 0 |
| Stream | +2.6 / +1.2 ms | +3.4 / +0.9 ms |
| Lake, pond, pool, shoreline, hot spring, waterfall | under 2.5 ms in every run, mostly about 0 | under 3.2 ms in every run, mostly about 0 |
The ocean is again the one kind whose cost shows in both runs; everything else moves between
"about 0" and a couple of milliseconds from one run to the next, which is this machine's noise.
The tablet column above still needs a device: no phone or tablet was connected to this editor
during the 1.2.0 work, so the tablet costs, the browser-on-tablet costs and the ten-minute
battery-saver run on a tablet were not measured. The bench and the pause-menu entry are there
to take them on the device.
**Battery saver.** With the Graphics Presets kit installed, its Battery Saver and Low steps put
every `auto` water on the low tier by themselves (`Water.setQuality("batterySaver")` does the
same without the kit); a still lake or pond costs a single transparent surface, and a sea that
nothing moves skips its whole step.
Most of the ocean's frame time is its CPU side (the clipmap and the wave spectrum's
bookkeeping), which is why it costs far more frame time than GPU time.
**A still sea costs nothing (1.1.9).** In a paused editor, or in any frame where neither the water
clock nor the camera moved, the ocean now skips its whole step: measured on the main scene with
the editor paused, 175 skipped steps in 3 s and not one GPU dispatch. When only the camera moves
it re-places the surface from the waves it already has, without re-running the wave simulation.
The ocean also no longer copies the lit scene into textures of its own every frame (it reads the
engine's `zero::scene_color` / `zero::scene_depth`) and no longer re-mirrors its surface mesh
every frame. The table above predates these savings; they were carried over from the engine's old built-in
`oceans` package (see Where the sea came from).
**The showcase, measured** (native desktop, 1920 x 1080, 2026-11-16 about 01:15 UTC, a busy
machine with two engine clients):
- In the editor with the showcase open: median 49.8 ms a frame, 95th percentile 58.6 ms,
99th 80.1 ms. Under 100 ms throughout.
- Playing it (on the pier, after it finished loading): median 40.6 to 47.6 ms, but 95th
percentile 144 ms and 99th 296 ms. The GPU's timed work in play was about 79 ms a frame at the
median, mostly an engine compute group (29 ms), the transparent pass (21 ms, where water
surfaces and particles draw) and the engine's weather surface pass (12 ms); Tidewater's own
ocean passes were each under 1 ms. A player on a busy machine sees those spikes, as the world's
owner did (155 to 210 ms a frame).
## Where the sea came from
The Zero engine no longer ships an ocean of its own: Tidewater is the water, and its
components are `tidewater.components.WaterBody`, `tidewater.components.Ocean` and
`tidewater.components.Buoyancy`. Tidewater's spectral sea started as a port of the engine's old
built-in `oceans` package (the spectral sea, its foam, its seabed, things floating on it, its
nine sea presets and its tests) and keeps all of it. A world written for the old package moves
over by installing Tidewater and changing its require (rebuild the scene after, so a sea it
already made is made again):
```lua
local Ocean = require("tidewater.modules.ocean")
```
or, better, by replacing that sea with a `WaterBody` of `kind = "ocean"` (its `preset` takes the
same sea states), which adds the seven looks, the tide, the shared underwater view and the
light fix.
**History: the same sea, on screen and in cost.** While the old package still shipped, both
were measured side by side. A sea attached through `Ocean.attach` or the `Ocean` component with no `tidewater` option was drawn exactly as the built-in package drew it, and cost what it cost: Tidewater carries the built-in package's two last savings. A sea nothing moves costs nothing (the waves are evolved only when the moment drawn changes, the surface is re-placed only when the viewer moves, a frame on which neither happened dispatches no GPU work at all, and a paused editor's sea holds still), and the surface reads the scene behind it straight from the engine's own `zero::scene_color` and `zero::scene_depth` instead of copying the lit scene into textures of its own every frame. Tidewater adds one saving of its own on top: the surface mesh is no longer re-mirrored from the GPU every frame. Add `tidewater = true` to `Ocean.attach` (or use `WaterBody` with `kind = "ocean"`, which always has it) for Tidewater's light fix: lit by the real sky, no teal glow at dusk, dark with a moon path at night, glowing crests. The waves were the same: with the same preset, `Physics.water` heights matched the built-in sea exactly (a `gale` at high quality: RMS 13.38 m, 1% of points under -31.2 m, 1% over 28.6 m, on both). The two packages also ran side by side in one world, each sea alive and moving: Tidewater names its bodies of water, GPU resources and surface markers `twocean<N>_...`, where the built-in package used `ocean<N>_...` (`documentation/media/compare_builtin_vs_tidewater_*.jpg`: built-in on the left, a Tidewater tile on the right, at day, sunset and night). Everything else new (looks, bounded seas, wake foam, foam against piers, the moon path, tides) is opt-in.
## What's new in 1.1.13
- **Water effects cost nothing while parked or warming** (tidewaterFx 1.0.10): the splash and mist loops a water body
primes and parks far below the world (y -5000) used to keep simulating every frame; they are now paused until
used, and the first real splash still shows at once.
## What's new in 1.1.12
- **Clearer river docs** (issue #11): the how-to guide's river section says where the water lies (its own bed, the component's `ground` field, or a channel of your own with `options = '{"bed":false}'`), that `bed`, `groundOffset` and the bank and rapids settings go in `options`, and that `path` is a string (with a sample that joins a Luau table). The `path` and `ground` field descriptions say the same. Contributed through lanternStair PR #6.
- Built on the current engine library (33551d3).
## Guides inside
- *How to add water to my game*: every kind, looks, varieties, floating, tides, queries, performance.
- *How to add an ocean with waves breaking on the shore*, *How to add a lake or pond*, *How to add a river that carries things downstream*, *How to add a waterfall with spray and mist*, *How to add a swimming pool or hot spring*, *How to add puddles that fill when it rains*, *How to add a tide that comes in and goes out*: one kind or feature each, with copy-paste code.
- *How to make a boat float*: vehiclesKit boats on Tidewater, and your own hull with `Buoyancy`.
- *How to change the look of water*: the seven looks and every named variety.
- *How to make water run well on phones and tablets*: the quality field, `Water.setQuality`, battery.
- *Example: build a small harbour level*: a harbour sea with a tide, a pier, boats, floating crates and buoys, a river over a waterfall, swimming and rain.
- *Example: a fishing dock on a lake with a boat*: from an empty world to a lake you can row on.
- *Oceans*: the sea in depth, covering sea states, what each control does, the seabed, buoyancy, cost.
- Swimming is the **tidewaterSwim** package's guide, *How to let the player swim*.
## Credits
Tidewater's sea is built on the Zero engine's former built-in **`oceans`** package (`@builtin::systems.oceans`,
by the Zero engine team, which the engine no longer ships): its spectral wave simulation, cascades and Gerstner swell, Jacobian
foam, Beer-Lambert water colour, procedural seabed and caustics, buoyancy, sea presets and test
suites are that package's work, carried here as the starting point and extended. Its later
savings are carried over too, with thanks to the same team: "a sea nothing moves costs nothing"
(evolve only when the moment changes, re-place only when the viewer moves, a paused editor's sea
holds still) and reading the scene behind the water through the engine's own `zero::scene_color`
and `zero::scene_depth` rather than a copy of its own. Thank you.
## The parts
| Part | What it is |
|---|---|
| `components/WaterBody` | Any kind of water, saved with the scene: `kind`, `look`, `preset` and its shape |
| `modules/water` | The one API: create / attach / setKind / setLook, presets, heightAt, flowAt, normalAt, surfaceAt, tideAt, sample, setQuality, ripple, splash, setWeather |
| `modules/looks` | The seven looks as shader parameters |
| `modules/tide` | The tide: a water's level rising and falling on the shared water clock |
| `modules/kind_*` | One builder per kind (ocean, shoreline, lake, pond, pool, hotspring, river, stream, waterfall, puddles, underwater) |
| `modules/fx`, `modules/ripples`, `modules/weatherLink` | One-line bridges to `tidewaterFx` (effects, the GPU ripple field, weather) |
| `modules/underwater` | The view from below the surface, for every kind |
| `components/Ocean`, `components/Buoyancy`, `modules/ocean*`, `modules/buoyancy` | The spectral sea and floating (started as a port of the engine's old built-in `oceans` package) |
| `shaders/*`, `shaderModules/twCommon`, `computeShaders/*` | The water surfaces, the shared shading library, the GPU passes |
| `scenes/*` | Ready-made scenes and the gallery |
| `tests/*` | ocean, buoyancy, oceanLooks, underwater, surfaces, rivers |
## Known limits
Honest list, as of this version. Where the cause is in the engine, the engine's issue number is
given as **engine #NNNNN**; those are the numbers to look up and follow. Where this world's own
issue tracker also follows it, its number is given as *(world tracker #N)*.
- **An effect played before the kit has readied it shows late: engine #26227.** A new effect
play draws nothing until a long hidden warm-up through its whole graph finishes. Tidewater
readies every effect in the background as soon as a water is built (`Fx.prime`): measured on a
busy desktop, every one-shot was ready 0 to 8 s after the water was built and every continuous
effect (mist, bubbles, drips, foam, spindrift, bow spray) 30 to 38 s after. From then on every
effect draws within 0.05 s of being triggered, the first time and every time after (all 13 kinds
measured, twice). An effect triggered in the first seconds after load, before that, waits for
the engine's warm-up: on the same desktop more than 8 s. Call `Fx.prime(look)` at load, behind a
loading screen if you can, for a look of your own. *(world tracker #1)*
- **Stopping an endless effect does not hand it back for reuse: engine #26226.** Tidewater works
around it: a stopped mist, drips, bubbles, foam, spindrift or bow spray is parked (its emission
turned to zero) and the next one of its kind and look takes it over at once. *(world tracker #2)*
- **After a shader edit, existing materials and pooled effects keep the old shader: engine #26228.**
Rebuild the water (reload the scene, once it has finished loading) to see a change.
- **Reloading a scene while it is still loading never returns: engine #26225.** Let a ready-made
scene finish loading (the showcase takes up to a minute) before reloading it.
- **The ocean's top quality foam is over a GPU size limit: engine #9336.** At `ultra` the foam
texture is larger than some GPUs allow; `high` and below are not affected.
- **Opening a scene with no edits makes a clean world look changed: engine #26351.** Opening a
ready-made scene can write an empty record into it; `zm restore <scene>` takes it back.
- **Publishing a one-file change in a world with many kits takes minutes and freezes the editor:
engine #25764.** Expect this when you push a world that installs Tidewater beside other kits.
- **A helper editor session doing scene work grows 2 to 3 GB in an hour: engine #26230.** On a
long session with the showcase open, restart helper clients now and then.
- **Effects only move in Play.** The engine runs effect timelines on the gameplay clock, so
splashes, mist and spray stand still while editing; water surfaces, ripples and waves do animate
in the editor. *(world tracker #3)*
- **The install is large**: about 18,000 files and a minute, mostly material and prop libraries
the ready-made scenes use. The water itself needs none of them. *(world tracker #4)*
- **Ripple rings are drawn within 64 m of the camera**; a splash's own ring particles still show
further out. *(world tracker #5)*
- **Very shallow lagoon water over pale sand reads too bright at night**; the open sea goes dark
with a moon path. *(world tracker #6)*
- **The ocean's `ground` option** (shoaling against a terrain) can leave a lip of raised water on
a very steep coast. Leave `ground` empty if you see one. *(world tracker #7)*
- A faint green fleck can show on near wave crests with a very low sun, inherited from the
old built-in sea it was ported from; the low-poly ocean has no moon glint at night. *(world tracker #8)*
- **No longer applies: a scene running both seas could look milky.** While the engine still
shipped its own sea, a camera low enough to dip under the built-in swell had that package's
underwater fog wash the whole frame, Tidewater's sea included, to a pale teal (measured alone at
noon from the same camera, the two seas matched). The engine ships no sea of its own now, so a
world cannot run both. *(world tracker #9)*
- **The Android tablet cost is not measured on a device yet: engine #25931.** A tablet is attached,
but it was in use by another project, and the editor has no way to reach an attached device at
all. Desktop and browser are measured, and the pause menu's bench fills the gap in one run on
the tablet (see Cost).
*(world tracker #10)*
- **The gallery's small ocean tile reads flat** (a stepped cyan slab in its 20 m box at day and
dusk), unlike the open sea, which reads as water in every light (`documentation/media/kinds/
r8_kinds_{day,dusk,night}_{1,2}.jpg`: every kind in the realistic look, checked twice at each
time). A bounded ocean wants room: give it 100 m or more.
- **At night the sea mirrors your scene's sky**, so a sky that stays lit after dark gives a pale,
milky night sea. The engine's procedural sky still renders a light grey after midnight, and a
day-night clock may hand over to a bright moon (worldClockKit's is 0.65, a sixth of noon). The
showcase eases its sky exposure to 0.15 and its moon and ambient to 0.15 and 0.07 through
twilight (its `entrypoint.luau`, `holdSky`), which takes the sea at 22:30 from a pale cyan
(brightness 134 of 255) to a dark moonlit blue (69): `documentation/media/playtest/r8_sea_night_2.jpg`
and `r8_sea_dusk_2.jpg`. Do the same in your own scene if its nights read milky.
- **A scene rebuilt during play can drop a boat another player owns** on the client that
rebuilt; leaving and re-entering play brings it back.
- **Not every ready-made scene was re-checked by eye in this version.** The lagoon, the gale and
the rainy street were rebuilt and looked at; the forest river, mountain lake and waterfall
grotto load and run, but were not re-captured after their last changes.
# sc_bed_afterRain
[[describe]] Say what this sound is and what it is for.
# sc_bed_pierLap
[[describe]] Say what this sound is and what it is for.
# sc_bed_waterfall
[[describe]] Say what this sound is and what it is for.
# Vehicle
A vehicle anyone can walk up to, get into, drive (or sail, or fly) and get out of. Put it on an entity (`vehiclesKit.api.spawn` does this for you, on a synced entity so every player shares the one vehicle) and set three fields: `preset` (kart, sportsCar, muscleCar, monsterTruck, buggy, deliveryTruck, bus, tank, hovercraft, speedboat, rowboat, arcadePlane, helicopter, spaceship), `look` (toy, lowPoly, realistic) and `paint` (auto or a paint name). It needs no sibling components: it adds its own `Physics` body, the engine's `VehicleController` (cars, tank) or a float for boats (the Tidewater water kit's `Buoyancy` when the world holds it, else the engine's `FluidForces`), and builds its model, colliders, wheels, seats and moving parts as local children on every peer. Changing `preset` rebuilds it as the other vehicle, with everything a brand-new one of that preset has (weight, gearbox, driving aids, floats, seats), parked or driven: the owner sets its physics up afresh, and the host takes a parked vehicle nobody owns long enough to do it. `builtFor` records the preset the physics was set up for. Whoever is aboard stays aboard through the change: riders keep their seats (one whose seat the new preset lacks moves to a free seat, and gets out only if none is left), and a seated rider's controls, HUD and camera switch to the new preset. The camera is framed afresh, exactly as getting in frames it: in the frame of the switch it lets go of its rig and holds still (moved out behind and above the new body if that spot is inside it), and a frame later it gets a fresh driveCams camera fitted to the new body.
- **Getting in**: an interactKit prompt ("Drive", or "Ride" for a free passenger seat) on E, the gamepad's west button or the touch Interact button. The vehicle's owner decides who gets which seat (`occupants`), then hands ownership to the driver's peer, which simulates it while every other peer draws it from the poses it sends.
- **Seated**: the rider's body is posed in the seat on every peer; the driver's camera switches to driveCams (chase, cockpit, bonnet; the camera button cycles), controls switch to the kit's controlsKit driving or flying scheme, and the HUD shows a gaugeClusters speedometer, a barsKit boost meter and button prompts. Getting out (E / west / touch Exit) restores the walking camera and controls and stands the player beside the door.
- **Boost** drains `boostCharge` while held and refills after; **drift** is the handbrake for cars, a slide for the hovercraft and a hard carve for boats; **horn** plays on every peer.
- It publishes torqueCars' driving contract (`car.rpm`, `car.gear`, `car.kmh`, `player.vehicle`, mount points...) so gaugeClusters, engineVoices and driveCams work with it unchanged; an engineVoices voice is attached while it is driven.
- A vehicle nobody drives that has come to rest parks: its controller and per-step work sleep until someone gets in or it is pushed. On land that is under 0.3 m/s; a boat, which the swell never lets stand still, rests once its drift across the water (smoothed over about a second and a half) is under 1 m/s. Once every seat is empty and it is at rest, its owner releases it, so it belongs to nobody until the next player gets in (the host decides that seat, and the new driver's peer claims it). A boat or hovercraft is kept instead (the host claims one nobody owns), so it goes on floating.
- **Recover** (R, View, touch Reset, or `recover()` on the owner) stands it upright, facing the same way, on level ground where it is or a body-length away; boats go back to deep water and aircraft over the sea back into the air.
- Wheeled kinds keep their body collider at least 25 cm off the ground, so the wheels climb kerbs; no vehicle is ever moved faster than its top speed with boost (plus a margin) or spun faster than 6 rad/s.
Fields: `preset`, `look`, `paint`, `passengers` (allow riders), `enterRange` (metres beyond the vehicle's edge, 0 = 1.6), `cameraModes` (driveCams modes the camera button steps through); owner-written state: `occupants`, `boostCharge`, `boosting`, `horn`, `builtFor`. Methods: `enter(seat?)`, `exit()`, `driver()`, `seats()`, `info()`, `set({ preset, look, paint })`, `setIntent(t)` (drive from code; any controls left out count as zero / off), `recover()`, `rig()`, `isParked()`.
# Splashes
Makes things splash when they hit water. Put it on one entity in a scene (a manager, the
water itself) with `everything = true` and every body in the world splashes when it falls
in, scaled by its size and how hard it hits: a pebble plops, a crate makes a solid splash, a
person jumping in throws a crown, a column and a foam patch. Put it on a single body with
`everything = false` and only that body splashes. Whatever comes out of the water drips.
Built on `Physics.onWater`, so it works on every water the engine knows (Tidewater water,
`Water` components, oceans, terrain lakes). Each splash is played by the peer that owns the
body and sent to every other peer, so it is seen once per player, never doubled.
Fields: `everything`, `look` ("" = the water's own look), `minSpeed` (m/s below which nothing
splashes), `scale`, `drips`, `sync`.
`characters` (default on): every character with a `CharacterController` (players, local and
remote, and NPCs) splashes a footstep each stride while wading in puddles and shallows, makes a
body splash when it drops in, and leaves a wake with ripples while it swims; all of it runs on
every peer from the replicated transforms. `rain` (default on): while any weather kit says it
rains (`weather.rain`, which Cloudburst publishes), small crowns splash on the water round the
camera, on top of the rain rings the ripple field draws. The component warms the splashes it
plays when it starts, so the first one shows at once.
# Wake
Put it on anything that moves through water (a boat, a jet ski, a swimmer, a duck) and it
leaves a wake: a V of foam patches laid on the surface behind it that spread and fade over
`fade` seconds, white bow spray thrown off both sides once it goes faster than `spraySpeed`,
and rings in the ripple field ahead of it. Everything scales with speed, follows the water's
height, and stops when the body leaves the water (or slows below `minSpeed`).
It runs on every peer from the body's replicated motion, so nothing extra is sent: each
player sees the same wake behind the same boat. On a Tidewater ocean it also stamps the
ocean's persistent foam (`Ocean.stampFoam`) when that is available.
Fields: `look` ("" = the water's own look), `width` (beam in metres, 0 = measured from the
body), `length` (hull length, 0 = measured), `minSpeed`, `spraySpeed`, `fade`, `bowSpray`,
`ripples`, `intensity`.
```lua
boat.component.add("Wake", { width = 2.2, spraySpeed = 4 })
```
# Cloudburst
The scene's weather, shared by every player. Put one on a synced entity:
```lua
local e = entity.spawnSynced("Weather")
e.component.add("Cloudburst", { preset = "light_spring_rain" })
```
`preset` picks a named weather (one field swaps a light shower for a night storm). Clear it and
`kind` + `intensity` pick one directly, with `rainLook`, `snowLook`, `lightning`, `splash` and
`fogBank` choosing how it looks. A change fades in over `changeSeconds` identically on every
machine; `cycle` ("clear_day:3, night_storm_town:4") runs a forecast by itself. Any player can
call `setWeather(opts, seconds)`; it reaches the entity's owner, who writes it. Switches turn
sound, wet surfaces, storm lighting, fog and clouds on or off, and `quality` scales drop counts.
# Buoyancy
Floats the entity's rigid body on any water: every Tidewater kind (sea, lake, river, pool, ...), a `Terrain`'s lakes and
rivers, a `Water` component's pool, a body `Physics.defineWater` declares.
```lua
entity.find("barrel").component.add("tidewater.components.Buoyancy", { density = 0.4 })
```
The entity needs a dynamic `Physics` body. Position and orientation stay the
physics world's: this component adds the forces water exerts, inside every
physics step, so a floating body still collides, still takes impulses, still
falls when it is lifted clear of the water, and floats the same way at any
frame rate.
| Field | What it does |
|---|---|
| `density` | Relative to water: that share of the hull rides under still water, so the lower it is the higher the hull floats, and a body denser than water sinks. It holds whatever mass the body was given. 0 releases the body. |
| `damping` | How quickly water settles the hull's bobbing and rolling: the factor on the waves its motion makes at the surface. 1 settles it within a few swings, 0 leaves it bobbing. |
| `hull` | What the hull is measured from: `"colliders"` (the default), the body's own solid colliders, or `"model"`, the box around what the entity draws. |
| `sizeX`/`sizeY`/`sizeZ` | A box that displaces water in place of the colliders or the model, centred on the entity's origin. All three at 0 measures the hull as `hull` says. |
The colliders are what the hull is by default (a box, a ball, a capsule, a
convex hull, a closed mesh, or several on the body and its children), so an
invisible collision proxy under detailed art floats by the proxy. A body with
nothing to measure (no dynamic `Physics` body, only sensor colliders, a model
hull that draws nothing) is refused a second after it is attached, with a
warning that names the entity and what to add, and floats as soon as it has
it.
`barrel:submersion()` reads how much of the hull was under water on the last
physics step, and `barrel:waterline()` reads the world Y the surface stood at
under it, wave motion included.
Forces reach a rigid body only while the scene is playing, so a hull sits where
it was placed in edit mode and settles onto the water when play starts.
# Forest
Drop a whole temperate deciduous forest into a scene with one component: size, density, seed, stream, path, clearings, forest type, season, look and quality, each a single synced field, so every player who joins builds the same forest from the same settings. Put it on any entity: its position is the forest's centre.
```luau
local e = entity.spawnSynced("MyForest")
e.component.add("forestKit.Forest", {
size = 160, density = "normal", seed = 42, stream = true, path = true,
clearings = 2, forestType = "oakWoodland", season = "default", look = "real",
})
```
Change any field and the forest rebuilds to match, about 0.4 s after the last edit. Needs nothing else on its entity: it calls `ForestBuilder.build` itself and owns everything it spawns (temporary, local, torn down with the component). For your own path, clearings or hand-placed hero props, call `ForestBuilder.build` directly instead: see the package README.
# Swimmer
Lets a character swim. Goes on the body a scene's `PlayerPrototype` names (next to the built-in `CharacterController`, which the built-in humanoid avatar brings), or on an NPC body that walks on a `CharacterController`. It adds climbKit's `ClimbMover` to the body in play when it is missing, for climbing out.
```luau
body.component.add("tidewaterSwim.Swimmer", { feel = "arcade" })
```
## What it does
| State | When | What happens |
|---|---|---|
| `walking` | feet dry (water under 0.15 m) | the controller as it was |
| `wading` | 0.15 m up to the feel's `swimDepth` | the controller walks slower the deeper it is (down to `wadeMin` of its speed), sprint fades out |
| `swimming` | deeper than `swimDepth`, or falling in | the controller is switched off and this component moves the body: camera-relative strokes on the surface, collision by capsule sweep |
| `treading` | swimming with no input for 0.35 s | upright, head out, bobbing |
| `diving` | under the surface (dive control held, or below floating depth) | swim down and up, buoyancy brings it back |
| `climbing` | pushing into a quay edge or a ladder at the surface | climbKit's `tryMantle` (quay, ledge up to its reach) or `tryClimb` (a wall marked `climbable`, such as a ladder) runs the move; walking up a bank is plain wading out |
Water is read with `Physics.water`, so any water works: Tidewater kinds, an engine `Water` component, terrain lakes and rivers. A current (`velocity` of the water) carries the swimmer by the feel's `current` share.
## Fields
| Field | Default | |
|---|---|---|
| `feel` | `arcade` | `arcade`, `realistic`, `heavy`, `cartoon` (numbers in the package README), or one registered with `tidewaterSwim.feels` |
| `climbOut` | true | climb out at quays and ladders through climbKit |
| `breathLimit` | true | use the feel's breath (realistic 45 s, heavy 25 s; arcade and cartoon have none) |
| `splashes` | true | splash on entry and ripples while swimming, through Tidewater FX when installed |
| `cameraKick` | true | a light camera shake on a hard entry, through juiceKit when installed |
| `poseNode` | "" | the visual the procedural pose tips; empty finds the child under the body's facing anchor |
| `swimClip` / `treadClip` | none | the avatar's own clips; played with `ClipPlayer` instead of the procedural pose |
Telemetry: `state` (synced), `vertical` (-1/0/1, synced), `breath` (0..1, synced), `depth`, `speed`, `climbHow`.
## Events (synced)
`onStateChanged { from, to }`, `onEnterWater { speed }`, `onClimbOut { how }` (`quay`, `ladder`, `bank`), `onOutOfBreath {}` (the game decides the cost).
## Methods
`setFeel(name)`, `getState()`, `isSwimming()`.
## Controls
The player's own `move`, `jump` and `sprint` (the controller's input map), plus `tidewaterSwim.swim` (`swimUp`, `swimDown`) held only while in deep water. When a controlsKit scheme is live, its `move`, `jump`/`ascend`, `crouch`/`descend` and `sprint`/`dash` are read instead. NPCs: the controller's input bus (`inputX`/`inputZ` as the stroke, `inputJump` up).
## Multiplayer
Only the peer that owns the body moves it; the body position replicates as usual. `state` and `vertical` are synced, and every peer draws the swim pose, the splash and the ripples from them.
# WaterBody
Any kind of Tidewater water, saved with the scene. Two fields decide what it is:
- `kind` (11 kinds): ocean, shoreline, lake, pond, pool, hotspring, river, stream, waterfall, puddles, underwater
- `look` (7 looks): realistic, crystal, painted, cartoon, lowpoly, pixel, toy (glossy plastic for toy-style games)
Change either and the water rebuilds in place. `preset` picks a named variety of that kind
(empty = its default). The rest are the shape: `size` (x, z metres) and `depth` for lakes,
ponds, pools and puddle areas; `path` (points "x,y,z; x,y,z; ...", in the entity's space) and
`width` for rivers, streams and waterfalls (a waterfall's path runs from the lip down to the
pool); `tide` (metres, low to high water, 0 = none) and `tidePeriod` (seconds, default 600) give an ocean, shoreline or lake a tide on the shared water clock; `quality` (`auto`, `low`, `medium`, `high`, `ultra`) sets how finely it is resolved; `options` takes any kind-specific override as JSON. Its full name is `tidewater.components.WaterBody`.
The entity's transform places the water. The fields replicate, every peer builds the same
water from them, and the waves run on the shared water clock, so every player sees the same
surface.
```lua
local e = entity.spawnSynced("Lake", { position = { 0, 2, 0 } })
e.component.add("tidewater.components.WaterBody", { kind = "lake", look = "realistic", size = { 60, 40 }, depth = 6 })
e.component.get("tidewater.components.WaterBody").look = "cartoon" -- same lake, cartoon
e.component.get("tidewater.components.WaterBody").kind = "pond" -- now a pond
e.component.get("tidewater.components.WaterBody"):heightAt(5, 3) -- this water's own surface there, nil off it (never another water)
```
`heightAt(x, z)` and `flowAt(x, z)` answer for this body of water alone, even where another
water lies above or below it. To ask for whatever water is on top at a spot, use
`Water.heightAt(x, z)` from `tidewater.modules.water`.
# Ground
The forest's land, as pure functions of a seed: `Ground.site(opts)` builds a `Site` from size, seed, relief and an optional meandering stream (banks, a carved channel, a monotonically-falling water level), footpath and clearings, and the site answers height, terrain surface (forest floor, leaf litter, moss, dirt, wet mud, stream bed, long/short grass), footstep surface (leaves, moss, mud, path, grass, water), distance to the stream or the path, and whether a point sits inside the walkable square. Two sites built from the same options always agree, everywhere (see `tests/forestKit.testSuite`).
```luau
local Ground = require("~.Ground")
local site = Ground.site({ size = 160, seed = 21, stream = true, path = Route.path(2) })
site:height(x, z); site:surface(x, z); site:footSurface(x, z); site:stream(x, z); site:water(x, z)
```
`Ground.setActive(site)` / `Ground.active()` / `Ground.surfaceAt(x, z)` / `Ground.streamDistance(x, z)` let code elsewhere (forestKit's `Footsteps`, the showcase's route check) answer for "the forest that's live right now" without passing a site around. `Ground.terrainSource(site)` gives `ForestBuilder` the `TerrainStream` layer/height source; `Ground.layers()` names the terrain layer textures, found on disk from whichever installed ground-material collection provides them, so nothing here resolves a computed asset name on the gameplay path.
# api
The front door of vehiclesKit: `local Vehicles = require("~vehiclesKit.api")`. `spawn(preset, pos, { look, paint, yaw, name, passengers })` puts a shared, drivable vehicle in the world; `display(preset, look, paint, pos, opts)` a showroom model with no physics; `presets(filter)`, `looks()`, `paints()` and `describe(preset)` read the catalogue (whether a preset is a land, water or air vehicle, the kinds of game it suits, seats, assists, top speed, boost, drift); `all(filter)`, `nearest(position, filter)`, `of(target)` and `mine()` read the registry of live vehicles (`of` takes a vehicle from `all()`, its entity, an id or a name); `enter(vehicle, seat?)` and `exit()` seat and unseat the local player from code; `hud(opts)` sets the driving HUD (gauge style, boost bar look, units, prompts); `component()` is the `Vehicle` component type. Game code calls it; the `Vehicle` component does the work.
# fk_bed_stream
A 22-second loop of a small shallow brook trickling over pebbles. forestKit's Ambience plays it as a spatial source at the nearest point of the stream when the listener is within about 28 m.
# fx
Tidewater's water effects are their own package, **tidewaterFx** (`/tidewaterFx.package`), so any
game or kit can use them without Tidewater. This module re-exports it unchanged:
```lua
local Fx = require("tidewater.modules.fx") -- same table as require("tidewaterFx.modules.fx")
Fx.splash("plop", { x, y, z })
Fx.ripple({ x, y, z }, 0.5)
```
Requiring it through Tidewater also registers two hooks: the look of a Tidewater water at a point
(`Fx.setLookProvider("tidewater", Water.lookAt)`), so a splash on a cartoon lake is cartoon, and
the ocean foam stamp wakes leave in the sea (`Fx.setFoamStamper`). See the tidewaterFx README.
# water
The one way to put any kind of water in a scene and ask it questions.
```lua
local Water = require("tidewater.modules.water")
-- a lake 60 x 40 m whose surface stands at y = 2
local lake = Water.create({ kind = "lake", look = "realistic", position = { 0, 2, 0 }, size = { 60, 40 } })
lake:setLook("cartoon") -- same lake, cartoon look
Water.setKind(lake.entityId, "pond")
Water.heightAt(10, 4) -- surface Y of the TOPMOST water at x=10, z=4 (nil where there is none)
Water.heightAt(10, 4, 0) -- the water at height 0 instead (a lower one of stacked waters)
lake:heightAt(10, 4) -- this lake's own surface there, nil off it (never another water)
Water.flowAt(10, 4) -- { x, y, z } how the surface moves there (river current, waves)
Water.sample({ 10, 1, 4 }) -- the engine's full answer: surface, depth, normal, velocity, floor
Water.normalAt(10, 4) -- unit { x, y, z } the surface faces there
Water.surfaceAt(10, 4) -- Surface? { height, flow, normal, depth?, water? } in one typed answer
Water.tideAt(10, 4) -- TideState? { offset, rising, high, low }, nil where that water has no tide
lake:surfaceAt(10, 4) -- also lake:normalAt, lake:flowAt, lake:tideNow()
Water.presets("river") -- the named varieties, default first; plain words resolve ("rapids", "lazy")
Water.setQuality("low") -- the tier every `auto` water follows, for the whole game
Water.ripple({ 3, 2, 1 }, 0.6) -- a ring
Water.splash("plop", { 3, 2, 1 }) -- plop | body | bow | spray | spindrift | mist | drips | bubbles
Water.setWeather({ rain = 0.7 }) -- rain rings everywhere, without a weather kit
```
`kind` (11 kinds): ocean, shoreline, lake, pond, pool, hotspring, river, stream, waterfall, puddles, underwater (`pool` is a swimming pool, `hotspring` a hot spring, `puddles` puddles and a wet street, `underwater` a basin made to swim in).
`look` (7 looks): realistic, crystal, painted, cartoon, lowpoly, pixel, toy (`crystal` is tropical crystal clear, `toy` glossy moulded plastic).
Every kind declares its water to the engine (`Physics.defineWater`), so `FluidForces`, the
`tidewater.components.Buoyancy` component, `Physics.water` and `Physics.onWater` work on all of them, and a river's
current carries what floats in it. For water saved with a scene, use the `WaterBody` component:
its fields are exactly `Water.create`'s options.
# 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)
1. Put a `Splashes` component on any one entity in your scene (a manager, the water):
```lua
entity.find("GameManager").component.add("Splashes", { look = "" }) -- "" = the water's own look
```
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.
2. Put a `Wake` on each boat (its +Z is the bow):
```lua
boat.component.add("Wake", { width = 1.6, length = 4.5 })
```
3. Call effects yourself:
```lua
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()
```
4. 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:
```lua
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.prime` skips 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). `look` is 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 calls `Fx.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 calls `Fx.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 water `Fx.ripple` plays 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 texture` warning 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 within `radius` of 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: 4` plays 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 with `Fx.warm(kinds, n, { looks = {...} })` so `n` plays are ready.
# Cloudburst: rain, snow, storms and fog for your game
**Weather that reads as weather.** Not white lines on the screen: soft, see-through drops lit by
your sky, your sun and your street lamps. They glint against a dark doorway and go darker against
a bright sky, streak with their speed and with your own movement, crowd thick around you and turn
into grey curtains down the lane before they fade into the fog.
The world answers the rain. Drops splash on the street and on the roofs, ring the pond and the
puddles, drip from the eaves and the branches. The ground darkens and shines as hard as it rains,
and under a roof it stays bone dry. Snow tumbles down and settles on everything that faces up,
hail bounces, sleet falls as neither. Wind leans all of it and gusts come and go. Fog lies in
banks in the low ground. Lightning lights the street without blinding anyone, and the thunder
arrives later the further away the strike was. Step inside and the rain sounds duller.
Every player sees the same weather at the same moment: the same strike, the same change from
clear to storm and back, including someone who joins in the middle of it.
## Make it rain in two minutes
1. Install **Cloudburst** from ZeroMind into your world.
2. Add the weather to your scene, in `build.luau` (or once from the console). A brand-new world
has no scene yet: make one with ground, light and a player first with
`zero scene create --startup main player` in the shell, then open
`scenes/main.scene/build.luau` and add these two lines before its last `end`:
```lua
local w = entity.spawnSynced("Weather")
w.component.add("Cloudburst", { preset = "steady_rain" })
```
3. Press play. That's rain.
**Change one word to change the weather:** `preset = "alpine_snow"`, `preset = "night_storm_town"`.
That is the whole switch from rain to snow to a thunderstorm.
Any single setting can change while a preset runs: set `rainLook = "pixel"` (or `snowLook`,
`lightning`, `splash`, `fogBank`, `kind`, `wind`) and the weather keeps everything else the preset
had and changes just that, live, for every player. Or clear `preset` and pick a `kind` (`clear`,
`cloudy`, `drizzle`, `rain`, `showers`, `downpour`, `thunderstorm`, `snow`, `sleet`, `hail`, `wind`,
`dust`, `leaves`, `ash`, `fog`, `mist`) with one `intensity` dial from 0 to 1. A kind picked on its own comes in at its own natural
strength (rain 0.6, downpour 0.85, ...), whatever the weather before it, and while a preset runs the
fields always show the preset's own kind and looks, so picking a kind always brings that weather.
`wind` is a dial from 0 (still) to 1 (a gale), or
-1 for whatever the kind brings; picking a new kind brings its own wind back unless you set `wind`
in the same change. Changes fade in over `changeSeconds`. A name the kit does not know
is warned about once and falls back to clear.
From code, on any player:
```lua
local Weather = require("cloudburst.weather")
Weather.preset("night_storm_town", 30) -- fade into a storm over 30 s
Weather.set({ kind = "snow", intensity = 0.8, snowLook = "fluffy" })
Weather.cycle({ { "clear_day", 3 }, { "steady_rain", 2 }, { "night_storm_town", 4 } })
```
## What's new in 1.5.4
- **Quiet scene reloads.** The atmosphere no longer calls `entity(id)` on scene lights that are already gone, so a scene reload or play flip no longer logs `entity(...) returned nil` errors (issue #7). The light reads check `entity.exists(id)` first, the way the flash light already did.
- Built on the current engine library (33551d3).
## What's new in 1.5.3
- **Fog banks that float as clouds.** `FogBank.cloud` (0-1) and the new `cloud` bank kind: a round, noise-ragged footprint and a puffy profile that thins toward the top and the underside, so a bank hanging in the air reads as a soft cloud from near and far instead of a pale box. Every other bank keeps its look, with its square corners now rounded.
## What's new in 1.5.2
- **The package's own description is current.** The one-paragraph description ZeroMind shows for
the package now lists all 16 kinds, 31 presets and 5 fog banks, and says how to install it and
make it rain. The kit's code is the same as 1.5.1.
## What's new in 1.5.1
A look pass over hail, mist and lightning, from near and far, at noon, dusk and night:
- **Lightning keeps the night dark.** A strike used to lift the whole scene to a flat grey: even a
far one turned a night street into an overcast afternoon for a moment. A flash now tints the
fog a cold blue and lifts the sky light less, so a far strike is a blue-white blink and a near
one still lights the street. Daylight flashes still read.
- **No hail bubbles on the lens.** A hailstone falling right in front of the camera used to fill
the frame as a large blurry grey ball. Stones now fade out before they reach the lens; the ones
bouncing at your feet stay.
- Hail, mist and fog were checked at every distance and time of day and needed no change.
## What's new in 1.5.0
- **A downpour reads as a wall of rain from far away.** Across a field in daylight, heavy rain and
thunderstorms now stand as soft grey shafts of falling rain, darker than the sky behind them,
instead of fading into flat fog. The fog in heavy rain is thinner, so the rain itself greys out
the distance. Close up nothing changed, and no hard streaks came back.
- **Four new kinds:** `showers` (passing showers that build, pour and clear on a shared loop),
`dust` (sandstorms and dust storms that turn the air tan), `leaves` (autumn leaves tumbling on the
wind) and `ash` (ash falling under a dim sky). Sand, leaves and ash never settle like snow.
- **Eight new presets:** `light_drizzle`, `passing_shower`, `tropical_monsoon`, `foggy_harbour`,
`autumn_leaves`, `dust_storm`, `sandstorm`, `ash_fall`. Each is the same one-field swap as the
rest, and a new `dust` fog bank goes with the sandstorm.
- **A better default.** A `Cloudburst` with nothing set now starts on `steady_rain`, rain you
clearly see in daylight, instead of the faint `light_spring_rain`.
- **Pick a preset.** A table below gives every preset with what it looks like and when to reach
for it, and the guides say what you should see after each step and show a storm intro that runs
once with `Weather.lastChange()`.
## What's new in 1.4.12
Review fixes on top of 1.4.11 (docs only, no kit code changes):
- **`lastChange()` examples are safe for a player who has just joined.** A joining player can run
its scripts a moment before the shared weather reaches it, so the README and the how-to guide now
ask again after a short wait before starting a storm, as the village example already did.
- **Forecasts are spelled out.** The steps of a running forecast do not count as changes for
`lastChange()`; setting the forecast with `Weather.cycle` does.
## What's new in 1.4.11
Contributed back by a world that installed Cloudburst (pull request #4). 1.4.10 was never released
on its own; its change ships here.
- **Ask whether the weather already changed this session.** `Weather.lastChange()` (and the
component's `lastChange()`) answers nil until someone changes the weather in this session, then
when the change started, its fade and how far along it is. A change saved with the scene or made
in edit mode before play does not count, and neither do the steps of a running forecast (setting
the forecast with `Weather.cycle` does). A storm intro now runs once, and a player who joins
mid-storm no longer starts it over.
- **The village example reaches dusk without worldClockKit.** Step 4 said its lamp-post code turned
the scene's sun down, and it did not, so the storm came in under an afternoon sky. It now dims the
starter scene's sun, ambient and sky, and gives the values for a full night.
## What's new in 1.4.9
- **Play and stop are quiet.** Pressing play or stop prints nothing from Cloudburst. The storm
lighting no longer reaches for a scene light that is not there yet (two red "returned nil"
errors at every start), and the landing map now goes only to the shaders that read it (rain,
snow and splashes; `Weather.bind` hands it to your material only when its shader declares a
`landmap` texture), so the curtain, mist, clouds, pond and puddle no longer warn about it.
- **Issue links you can follow.** The known limits name the Zero engine's GitHub issues,
[zero#25852](https://github.com/OrigoZero/zero/issues/25852) and
[zero#24706](https://github.com/OrigoZero/zero/issues/24706) on OrigoZero/zero.
Earlier, in 1.4.7 and 1.4.8:
- **Stopping play is clean.** Leaving play or the world no longer fills the log with red clean-up
errors: the weather checks a light or the lightning bolt still exists before handing it back.
- **A picked kind brings its own wind.** Choosing `wind` after a calm preset now gives a real gale
(before, the preset's light breeze stayed behind). Set `wind` in the same change to override it.
- **Honest docs.** A Known limits section with the issue to follow for each, the downpour cost
measured again with the true drop counts for each quality setting, and both guides matching
what the kit does today.
## What's in it
| | |
|---|---|
| **Kinds (16)** | `clear`, `cloudy` (overcast), `drizzle`, `rain`, `showers` (passing showers that come and go), `downpour`, `thunderstorm`, `snow`, `sleet`, `hail`, `wind` (wind and gusts), `dust` (sandstorm / dust storm), `leaves` (autumn leaves on the wind), `ash` (ash fall), `fog`, `mist` |
| **Rain looks** | realistic, cinematic heavy (glints round lamps), soft painterly, cartoon, pixel, ink / woodblock |
| **Snow looks** | soft realistic, big fluffy cartoon, fine powdery blizzard, pixel |
| **Carried on the wind** | blowing sand and dust, tumbling autumn leaves in red, orange, gold and brown, soft grey ash |
| **Lightning** | storm (forked and in-cloud), close forked strike, flash inside the clouds, distant silent heat lightning |
| **Splashes** | realistic crown, misty spray, cartoon, pixel, ink, none |
| **Fog banks** | valley fog, ground mist, sea fog, town haze, dust and sand: as the weather's own fog, or placed where you want one with the `FogBank` component |
| **Water** | `cb_pond` and `cb_puddle` materials that ring where drops land; `Weather.bind(material)` for your own |
| **Sound** | drizzle and steady rain beds, rain drumming on the roof when you stand under cover, thunder near and far; the wind beds come from **Soundstage**, which installs with Cloudburst |
| **Presets (31)** | see *Pick a preset* below |
Every preset is the same handful of settings, so swapping one for another is one change. With no
`preset` set at all, a new `Cloudburst` starts on `steady_rain`.
## Pick a preset
Set `preset` to the name in the first column. The list is also the order the Weather Lab and
`Weather.presets()` give them in.
| Preset | What it looks like | Reach for it when |
|---|---|---|
| `clear_day` | A bright, breezy day with a few clouds. | The weather should step aside; the calm between storms. |
| `light_drizzle` | The faintest fine rain under a pale grey sky; the ground darkens slowly. | A damp, quiet mood without a storm. |
| `light_spring_rain` | Soft, fine rain under a bright grey sky; puddles slowly form. | A gentle, fresh rain in daylight. |
| `steady_rain` | An ordinary wet afternoon: rain you clearly see, splashes on the street. | The default. Any game that just needs rain. |
| `passing_shower` | A shower builds, pours for a minute, then clears to a brighter break, over and over. | Open worlds and long sessions: rain that comes and goes by itself. |
| `autumn_drizzle` | Grey, gusty, cold drizzle blown in sideways. | Bleak moors, coasts, a cold walk home. |
| `tropical_downpour` | Warm, vertical, deafening rain; the far side of the street disappears. | A sudden cloudburst; jungles and hot cities. |
| `tropical_monsoon` | Warm rain blown in sheets off the sea, gusting hard, the horizon gone grey. | Monsoon season, typhoons, island and harbour levels. |
| `night_storm_town` | Lamps glinting through sheets of rain, lightning over the roofs, thunder rolling in. | The big set piece: a thunderstorm at night. |
| `noir_rain` | Hard rain in streetlight, every lamp haloed in falling glints. | Detective streets, neon alleys, moody cut scenes. |
| `hailstorm` | Hailstones bouncing off the cobbles, with close strikes. | A violent summer storm; a hazard players feel. |
| `sleet_squall` | A cold, sharp shower of icy rain. | Late autumn and early spring; the edge of winter. |
| `alpine_snow` | Big quiet flakes drifting down, snow settling on roofs and fences. | Winter villages, mountains, Christmas. |
| `blizzard` | Fine snow driven sideways by a howling wind; you can barely see the next house. | Survival, mountain passes, getting lost. |
| `misty_dawn` | Still air, low sun, mist lying in the low ground. | Mornings, graveyards, the start of a level. |
| `valley_fog` | Fog filling the low ground while the hilltops stand clear. | Hills and valleys; climbing out of the fog. |
| `sea_fog` | A cold grey fog rolling in off the water. | Coasts, cliffs, a ship coming in. |
| `foggy_harbour` | Thick, wet sea fog over the quay; masts and lamps fade a few boats out. | Ports, fishing villages, smugglers. |
| `town_haze` | A warm, smoky evening haze over the rooftops. | Dusk in a town; summer evenings. |
| `gale` | Dry and wild: trees thrashing, gusts coming in waves. | Coasts, heaths, a storm that never breaks. |
| `autumn_leaves` | A crisp, breezy afternoon with red and gold leaves tumbling past on the gusts. | Autumn forests, parks, harvest towns. |
| `dust_storm` | A dry, gusty wind lifting dust off the road, the light gone hazy and warm. | Westerns, farmland in a drought, dirt roads. |
| `sandstorm` | A wall of blowing sand: the sun a pale disc, the air tan, the far dunes gone. | Deserts; a storm that forces players to shelter. |
| `ash_fall` | Grey ash drifting down from a fire or a volcano, the sun dim and orange. | Volcanoes, burning cities, after a battle. |
| `summer_heat_lightning` | A warm, dry night with silent flashes far off on the horizon. | Summer nights; unease without rain. |
| `painted_showers` | Soft brush-stroke rain for storybook worlds. | Painterly and storybook art styles. |
| `cartoon_rain` | Chunky blue dashes and bouncy splashes. | Cartoon and toon-shaded games. |
| `cartoon_snow` | Big round flakes drifting down on a cosy evening. | Cosy and cartoon winters. |
| `pixel_rain` | Rain that steps like sprites. | Retro and pixel-art games. |
| `pixel_snow` | Square flakes for retro winters. | Retro and pixel-art games. |
| `woodblock_rain` | Long, even, inked lines of rain in the manner of an ukiyo-e print. | Ink, woodblock and Japanese-print styles. |
## Why it looks right
- **Each drop is a little lens.** It shows the scene behind it, bent, and keeps a visible contrast
against it: a touch brighter over a dark wall or tree, a touch darker over a bright sky. Sun,
lamps and lightning add their own glint on top, so drops sparkle round a street lamp without the
whole curtain turning white.
- **No two drops alike.** Sizes, brightness, speed and streak length vary per drop, and each one
rides its own eddy of the wind. A near drop never smears into a scratch across the screen.
- **Thick near, curtains far.** A dense near layer, a wider far layer, then grey sheets of rain
standing in the distance that melt into the fog.
- **Soft where it meets things.** Drops fade out where they meet a wall or the ground instead of
being cut off by it, and they fade in from the lens so nothing pops in your face.
- **Overcast means overcast.** A rain deck takes the sun's hard shadows away and the sky light
carries the scene; storms darken it further.
## How it works (and why it is cheap)
- **All falling weather lives on the GPU.** Each layer is a static mesh of quads whose motion is in
its shader; per drop there is no CPU work at all. A downpour costs the same CPU as a drizzle.
- **The engine's own weather does the surfaces.** Wetness, settled snow and dry ground under cover
come from `@builtin::systems.weather`; fog from the engine's height fog; wind from the engine's
`Wind` (so foliage and physics lean with the rain). Cloudburst keeps no second copy.
- **The landing map** (`cloudburst.landing`) is the one piece the engine lacked: the height of the
top surface a drop meets coming down, cast around the camera a few rows a frame. Drops stop on
roofs (none indoors), splashes sit on what they hit, and drips are found at every eave.
- **Multiplayer**: the weather is a few synced fields plus the shared session clock. Lightning
comes from a seeded schedule on that clock. Nothing streams per frame.
- **Flash safety**: two lightning strikes never start less than 2.6 s apart (a strike that would
land sooner after the one before is skipped, the same on every player's screen), so there is
never more than one flash in any 2.6 s. Each is a single soft pulse with capped
brightness. `Weather.setFlashComfort(0..1)` lowers it further per player.
- **Quality**: `quality = "low" | "medium" | "high"` on the component scales the drop counts for
phones and tablets.
## What a downpour costs
Measured on Cloudburst 1.4.6 with engine library @builtin 28ef193, in the showcase village street (1.5.0 adds a few shader instructions to the distant curtains and new particle types, but no per-frame script work; the drop counts are unchanged)
in the tropical downpour preset (the heaviest rain), camera on the street, 1920x1080, development
build of the editor on a Linux desktop (Intel Arc B-series GPU), 6 to 8 seconds of frames each.
| Setting | Rain drops drawn | Cloudburst's own CPU per frame | Whole engine CPU per frame |
|---|---|---|---|
| Clear sky, for comparison | none | 0.94 ms | 17.1 ms (median 17.2) |
| Downpour, `quality = "high"` (desktop) | 64,000 + 3,600 splash slots | 1.27 ms | 18.5 ms (median 18.0) |
| Downpour, `quality = "medium"` (what a browser gets) | 45,500 | 1.11 ms | 20.1 ms (the desktop was busy: the engine waited for a core for half the frame) |
| Downpour, `quality = "low"` (what a phone or tablet gets) | 26,600 | 0.96 ms | 18.3 ms |
- The rain itself costs the CPU almost nothing: every drop moves on the GPU, so going from a clear
sky to the heaviest downpour adds about a third of a millisecond of script time. The whole-frame
difference, about 1 ms, is the size of the run-to-run noise on this machine.
- `quality = "auto"` (the default) picks `medium` in a browser and `low` on phones and tablets by
itself. A heavier look draws more than its share (the downpour uses the cinematic look, 1.25 times
the drops), which is why the medium and low rows are more than 60% and 35% of 64,000.
- These are the browser's and the tablet's **settings** run on a desktop, not those devices
themselves (see Known limits).
## Known limits
Things you will run into, said plainly. Each names the open issue to follow on the Zero engine's
GitHub tracker, [OrigoZero/zero](https://github.com/OrigoZero/zero/issues):
- **Stepping under a roof switches to a second recording rather than muffling the storm**
([zero#25852](https://github.com/OrigoZero/zero/issues/25852) on OrigoZero/zero: audio has no
low-pass filter). The engine cannot muffle (low-pass) a playing sound on its own yet, so Cloudburst fades
the outdoor rain down and a recorded clip of rain drumming on a roof up. It sounds right under a
roof or porch, but it is the roof clip's rain you hear, not a duller copy of the storm outside,
and thunder and wind are only turned down, not dulled. When the engine gains a filter, the kit
will use it.
- **Frame time in a real browser and on a real Android tablet has not been measured**
([zero#24706](https://github.com/OrigoZero/zero/issues/24706) on OrigoZero/zero: reading frame
time in a browser engine). The cost table above runs those devices' settings on a desktop. How long a frame takes
on the devices themselves, and what the rain passes cost the GPU on their own (this build's GPU
timer does not break those passes out), is still to be measured. If you measure it, please leave
the numbers in a comment on the kit.
- **Roofs you move while playing** keep their old shelter for a moment: the landing map re-casts by
itself when things are added or removed, but a roof that slides needs
`require("cloudburst.landing").rebake(cameraPosition)` (see the how-to guide).
- **Skyclock brings the Cloudburst it was released with.** Skyclock (worldClockKit) 1.7.1 was
released alongside Cloudburst 1.4.5, so a world that installs only Skyclock gets 1.4.5 with it.
Install Cloudburst itself to get this version. Skyclock asks for Cloudburst by name, so in this
showcase both run on the one copy of Cloudburst 1.5.0.
- **Rain follows the active camera.** Drops are drawn in a box around whichever camera is drawing
the screen; a camera far from the player sees rain around itself, not around the player.
## For other kits
- `Weather.now()`: the weather this frame (rain, snow, wind, fog and the rest from 0 to 1, wetness,
wind vector).
- **Named values**, for kits that should not depend on Cloudburst: every frame the weather entity
holds `weather.rain`, `weather.snow`, `weather.wetness` (0 to 1) and `weather.wind` (vector, m/s).
`values.get(id, "weather.rain")` on any entity `values.entities()` lists reads it; a water kit
rings its lakes and puddles from it with no require of Cloudburst.
- `Weather.lastChange()`: the change of weather made this session (`at`, `seconds`, `ago`,
`progress` 0 to 1, `settings` it is changing to), or nil when nothing has changed since the
session began. The same answer on every player, a late joiner included, so a storm intro runs
once. A player who has just joined may run its scripts a moment before the shared weather reaches
it, so ask again after a short wait before changing anything:
`task.delay(5, function() if Weather.lastChange() == nil then Weather.preset("night_storm_town", 60) end end)`.
The steps of a running forecast do not count as changes; setting the forecast does.
- `Weather.onStrike(fn)`: every lightning strike, on every peer at once.
- `Weather.landsAt(x, z)`, `Weather.isSheltered({x,y,z})`, `Weather.landings(centre, r, dt)`:
where rain lands.
- `#include "cloudburst.shaderModules.cb_common"` and `cb_ripples(...)` in your water shader;
`Weather.bind(material)` keeps its `cb_rain` input current. `cb_pond` and `cb_puddle` are ready-made.
## Guides inside
- *How to make it rain in my game*: adding weather, picking a kind, changing it over time,
presets, shelter, sound, multiplayer.
- *Example: a village thunderstorm at night*: step by step from an empty world to a lamp-lit
street going from dusk into a storm.
## Works with
**Skyclock** (worldClockKit) for day, night and street lamps: its rain, snow and storms are drawn
by Cloudburst, and storms dim whatever sun it sets. Cloudburst needs no clock kit of its own.
# forestKit
**Drop a temperate deciduous forest into any world.** Pick a size, a density and a seed, each one setting, and ask for a stream if you want one: forestKit builds the ground (forest floor, leaf litter, moss, a footpath, muddy banks), carves a stream with stepping stones, fills it with oak, beech, birch and maple of every age, shrubs, ferns, long grass, wildflowers, moss, fungi, logs, stumps and rocks by a set of woodland rules, and draws it all as a handful of instanced draws with levels of detail. On top: dawn, midday, dusk and night plus rain on worldClockKit's shared clock, a colour grade for each, haze and sun shafts through the canopy, forest ambience that follows the time of day and the stream, and footsteps that sound like leaves, moss, mud, the path, grass, logs, stone or shallow water.
**Install and use:** install forestKit from ZeroMind (it brings forestProps and forestMaterials with it), then put a `forestKit.Forest` component on any entity and set its size, density and seed, or paste the first example below into a scene. Add `forestKit.atmosphere.ForestAtmosphere` for the time of day, rain, ambience and footsteps. `ForestBuilder.build` does the same from code, with your own paths, clearings and hand-placed trees.
Every player builds the same forest from the same settings, sees the same time of day and weather, and hears the others' footsteps.
Version 0.2.27: corrects the 0.2.25 note below. 0.2.26: the opening says how to install and use the kit. 0.2.25: on built-in library 5e6f9ec, the one current engines run. 0.2.24: on built-in library abf2b3b. 0.2.23: on built-in library b605ddd; the editor's long queue of preview pictures after re-baking many props is fixed in the engine, so it is out of the known limits. 0.2.22: the time-of-day looks can no longer be changed in place by anything that reads them (they are frozen and every look is handed out as a copy), so the atmosphere tests pass whatever the weather; the first example's numbers are measured again. 0.2.21: every known limit names its open issue (#5087, #22759, #22760 added). 0.2.20: The same seed and settings give the same forest on every machine, desktop and browser alike: the same props in the same places with the same trunks, rocks and logs to collide with, on ground sampled every half metre everywhere. The browser used to fill 70% as densely and sample its ground every metre, so two players saw trees in different places; now it only draws less far. `forest.stats.fingerprint` (and `ForestBuilder.fingerprint(instances)`) gives a short code two machines can compare. The `webDensity` build option is gone. 0.2.19: its footstep tests read soundstage's prefixed surface ids. 0.2.18: The forest's footstep surfaces are registered with soundstage under prefixed names (forestPath, forestLog and so on), so plain words like "Path" or "Log" elsewhere in a world keep the meaning soundstage ships; on worldClockKit 1.4.7. 0.2.17: declares soundstage 2.1.3. 0.2.16: A player who spawns under the forest floor (on a starter floor, say) is set on top of it; forest footstep words no longer change soundstage's shared word list; on Skyclock worldClockKit 1.4.6 and soundstage 2.1.3, whose tests pass beside forestKit. 0.2.13: Walkable from the first example (the ground is solid under every player), no rebuild on Play, lighter on the web, and the 24 new forestProps kinds in the fill rules (elder, hawthorn and dog rose in the shrub layer; bilberry, tussock grass, ivy, two mosses and two fungi as ground cover; branch litter, twigs and leaf litter on the floor; nettles and cow parsley at edges; rushes, bulrushes and pebbles on the banks; split logs, fallen branches, root plates and ivy stumps as deadwood).
## First example
```luau
-- in scenes/main.scene/build.luau, inside content()
local forest = entity.spawn("Forest")
forest.component.add("forestKit.Forest", { size = 120, density = "normal", seed = 7, stream = true })
local Atmosphere = require("@root::forestKit.Atmosphere")
-- the shared day/night clock (one synced entity), lit with the forest's sky look
Atmosphere.ensureClock({ startHour = 11, skyMode = "engine" })
-- light, air and sound on every machine (it also provides the sky when the scene has none)
entity.spawn("ForestAtmosphere").component.add("forestKit.atmosphere.ForestAtmosphere", {})
```
Save: the ground rises, the stream fills, and the trees and undergrowth fill in. Change `seed`, `density` (`sparse`, `light`, `normal`, `dense`, `lush`), `forestType` (`oakWoodland`, `beechForest`, `birchGrove`, `mixedMaple`, `autumnWood`), `season` or `look` (`real`, `painted`, `toon`) and it rebuilds. `Atmosphere.setTime("dusk")` and `Atmosphere.setWeather("rain")` change the hour and weather for everyone.
Guides: **how to make a forest for my game** (`guides/how-to-make-a-forest.guide`) and **add trees and a stream to my world: a forest walk from an empty world** (`guides/forest-walk-from-an-empty-world.guide`).
## What's inside
| Part | What it does |
|---|---|
| `Forest` component | The one-component forest: size, density, seed, stream, path, clearings, forestType, season, look, quality. Synced fields; every machine builds the same forest. |
| `ForestBuilder` | `ForestBuilder.build{ ... }` from code, with your own path, clearings, spots kept clear and hand-placed hero props (`extras`). Returns the forest (`site`, `instances`, `stats`, `update()`, `destroy()`). |
| `Ground` | The land as pure functions of a seed: rolling relief, a meandering stream in a shallow valley with low muddy banks, the path, clearings, the terrain layer and the footstep surface at any point. `Ground.surfaceAt(x, z)` and `Ground.streamDistance(x, z)` answer for the active forest. |
| `Rules` | How a forest fills in: canopy, understory, deadwood, rocks and stream stones, stepping stones at crossings, shrubs, ferns, grass, flowers (under trees, at edges, in clearings, by the water), moss and fungi. |
| `ForestTypes` | Five ready woodlands, and `define()` for your own. |
| `ForestRender` | Draws the placement as instanced draws (one per prop part per level of detail) and re-sorts instances into near/mid/far as the camera moves, a few groups a frame. |
| `StreamWater` | The stream's flowing water surface (Flux and Flicker's clear river), following its falling level. |
| `ForestAtmosphere` component, `Atmosphere`, `Ambience`, `Footsteps` | Light, air and sound on worldClockKit and soundstage (see `atmosphere/README.md`). |
## How it stays smooth
- Draw calls: one per prop part per level of detail present, a few hundred for the 160 m showcase however many plants it holds.
- Levels of detail by distance: trees 34 / 80 / 900 m, shrubs and logs ~22 / 50 / 120 m, ferns, grass and flowers vanish past ~40 m. `quality` scales them all.
- Shadows: trees cast through their mid-detail mesh, logs, stumps and rocks only up close, ground cover not at all.
- Colliders: one compound for every trunk, one for every rock and stepping stone, a box per log (marked `forestSurface = "log"`).
- Solid ground under every player: the forest makes its ground stand (and collide) under every body that carries a character controller, local or joining later, so the first example above is walkable in a world with nothing else set up. While the ground under a player is still missing it loads with a larger per-frame budget (24 ms instead of 4).
- Built once per session: every ground sample is remembered, so pressing Play (which loads the scene again) stands the same forest from memory. In the showcase the ground under the player stood 0.1 s after Play and the whole forest was back in under a second (desktop).
- Same forest on every machine: what stands and what you can bump into never depends on the machine. On the web build the forest only draws lighter: draw distances are capped at `quality = 0.6`, so far trees switch to their simpler meshes sooner and ground cover fades out nearer. `webQuality` in the build options changes that cap. Compare `forest.stats.fingerprint` on two machines to see that they stand the same forest.
## Measured performance
Desktop: the 160 m showcase walk with the whole forest drawing (about 8,200 placed props in about 1,080 instanced draws, near, middle and far detail levels all in use), walking the marked route in play with real key input for 25 s while the profiler recorded every frame. Native desktop app, debug build, freshly started engine.
| Where | Avg fps | Frame time avg / median / 90th / 99th pct | Hitches | Graphics memory |
|---|---|---|---|---|
| Desktop (`quality = 1`) | 30.4 | 32.9 / 26.1 / 56.8 / 112.2 ms | 215 of 768 frames | 732 MB |
| Desktop with browser settings (`quality = 0.7`, browser shadow settings), measured before the new undergrowth | 32.5 | 30.7 / 28.9 / 46.2 / 64.6 ms | 116 of 815 frames | 815 MB |
| A real browser tab (the showcase, a player standing on the ground, measured by a player) | about 26.6 to 30.2 | | | |
- **In a browser:** the showcase runs at about 26.6 to 30.2 frames a second once it stands, but it takes about 171 seconds to appear, because loading each tree and prop model is slow in the browser build (engine issue #22751). The ground is not the wait any more: it stands under the player first, with a larger per-frame budget while it is missing, and pressing Play stands the forest again from memory. For a web game, a smaller forest (about 120 m at `normal` density) has fewer kinds and ages to load.
- Graphics memory is the whole editor process (scene, editor and tools), not the forest alone.
- The largest script cost while walking is the engine's own walking controller for the player (about 17 ms per frame in a dense forest on desktop). Everything forestKit runs per frame costs under 0.5 ms.
- The first example above (120 m, normal density, seed 7, with a stream) places 4,966 props drawn in 910 instanced draws from the editor's starting view. On a fresh install its first build takes about 3.9 s on desktop, most of it loading and uploading every tree and prop model once; built again in a session that already holds those models, it takes about 1 s (0.96 s measured).
## Multiplayer
Two players walking together see the same forest and the same time and weather:
- **Same forest:** the forest is not sent over the network. Every player builds it from the same settings in the scene, on a desktop or in a browser alike, and the build is deterministic: `tests/forestKit.testSuite` checks the ground and the placement come out the same from the same settings, and that a web build places exactly what a desktop build does. `forest.stats.fingerprint` is the same short code on every machine that stands the same forest (the showcase: `8069-2792b58a`).
- **Same time and weather:** worldClockKit's `WorldClock` is one synced, world-wide entity; its clock, weather and sky are replicated fields.
- **Each other's footsteps:** soundstage plays other players' steps where they walk and forestKit picks the surface under each walker. This was checked with a simulated second walker in one engine, not with two people: a live two-player walk was not possible here (#14448), so treat it as untested with real players.
## Known limits
- **#14448**: two engines on one account collide as one player, so nothing here was tried with two real players.
- **#20946**: the agent that built this cannot open the browser build itself, so the browser numbers above come from a player's own test in a browser tab.
- **#22751**: loading each tree and prop model is slow in the browser, so the showcase takes about 171 seconds to appear there.
- **#21420**: installs with several dependencies are slow; a full forestKit install brings about 11,000 files.
- **#22451**: an install can leave an unused older copy of a dependency (the material library kit lands at two releases beside the collections).
- **#19258**: a package's description on ZeroMind can lag a release, so the store listing may show the previous version's text for a while.
- **#5087**: the engine sky stays clear blue in rain while the forest itself greys and darkens.
- **#22759**: the engine's built-in walking controller costs about 17 ms per frame in a dense forest, the main source of the hitches measured above.
- **#22760**: a long editor session grows by about a gigabyte of memory each time it switches worlds with a forest loaded, until the editor needs a restart. Players are not affected.
## Depends on
forestProps and forestMaterials (this world), Terra Firma (groundMaterials), Heartwood (woodsMaterials), Bedrock (stoneMaterials), Scale and Feather (organicMaterials), Flux and Flicker (animatedMaterials), worldClockKit (Skyclock), soundstage.
## Tests
`tests/forestKit.testSuite` (ground is deterministic, the stream flows downhill in a carved channel, footstep surfaces, placement respects water and path and lays stepping stones, density, forest types, build and teardown) and `tests/atmos.testSuite` (presets, weather, footstep surface mapping).
# 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**:
```luau
body.component.add("tidewaterSwim.Swimmer", { feel = "arcade" })
```
3. 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
```luau
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"`.
# director
Runs the weather every frame on every peer. It evaluates the `Cloudburst` component's synced
settings (a preset, or a kind and intensity, the record of the change in progress, an optional
cycle of presets) on the shared session clock into one blended weather frame, then drives the
landing map, the falling layers, splashes and drips, curtains, clouds and ground mist,
lightning, the world's answer (wetness, snow, fog, light, wind) and sound from it. Every input is
synced or derived from the session clock, so every player sees the same weather, the same
strikes and the same changes, and a player joining mid-storm arrives in it.
`director.current()` is what other kits read to react to the weather.
# catalog
Everything Cloudburst can make, as data. **Kinds** (clear, overcast, drizzle, rain, downpour,
thunderstorm, snow, sleet, hail, wind and gusts, fog, mist), each with one `intensity` dial.
**Looks**: six rain looks (realistic, cinematic heavy, soft painterly, cartoon, pixel, ink /
woodblock), four snow looks (soft realistic, big fluffy cartoon, fine powdery blizzard, pixel),
four lightning styles (storm, close forked strike, flash inside the clouds, distant silent heat
lightning), six splash styles and four fog banks (valley fog, ground mist, sea fog, town haze).
**Presets**: 23 named weathers built from the same settings the `Cloudburst` component has, so a
world swaps one for another by changing one field. `definePreset` / `defineKind` add your own.