# worldClockKit
**worldClockKit gives your world a shared day/night clock that every player sees at the same hour, with a sun, moon and stars that cross the sky and lighting that follows them; eight sky looks with deep starry nights; nine weathers that fade in, from clear skies and light mist up to a thunderstorm whose lightning and thunder every player sees and hears at the same moment, with the rain, snow, splashes, wet ground and lightning drawn by the Cloudburst weather kit (lit, see-through drops that stop under roofs, tumbling snow, forked lightning and distance-delayed thunder); eleven lamp styles (street lamp, lanterns, torches, a campfire, neon, sci-fi and pixel) that switch themselves on at dusk and off at dawn; eight on-screen clocks (digital, analog, pixel, sci-fi, a fantasy sundial and a moon dial among them); a ready-made time and weather controls panel; a one-line way to make any fire, light or sound follow the time of day; and rain, wind and thunder sound from Cloudburst, with night and sandstorm beds through Soundstage.** To start in a new world, install worldClockKit (Cloudburst and Soundstage come with it), then in your scene's build.luau add `entity.spawnSynced("WorldClock").component.add("WorldClock", { dayLengthMinutes = 10 })` and press play.
Version 1.7.7 · depends on **Soundstage** (installed with it) · multiplayer from the start · runs in the browser.
## Install and use
Install the package (it brings Soundstage with it): search ZeroMind for "worldClockKit" and install it, or run this in the editor's shell:
```sh
zero zeromind installAsset da911599-3bdf-4c1e-a4c3-ce13364692bf
```
Then add one clock to your scene and use the calls from any script.
In your scene's `build.luau` (inside `content()`), or once from the editor:
```lua
-- the clock: ONE per scene, on a synced entity so every player shares it
local clock = entity.spawnSynced("WorldClock")
clock.component.add("WorldClock", { dayLengthMinutes = 10, startHour = 7, sky = "realistic" })
-- a lamp that lights itself at dusk
local lamp = entity.spawn("Lamp")
lamp.localPosition = { 4, 0, -3 }
lamp.component.add("WorldLamp", { style = "streetLamp" })
```
In any script (a scene entrypoint, a component, a tool):
```lua
local Kit = require("worldClockKit.kit")
local Clock, Weather, Sky = Kit.Clock, Kit.Weather, Kit.Sky
function onLoad()
Kit.Displays.show("digital", { anchor = "topRight" }) -- a clock on screen
Clock.on("dusk", function(e) print("Evening of day " .. e.day) end)
Clock.on("newDay", function(e) print("Day " .. e.day .. " begins") end)
Weather.set("storm") -- fades in over a few seconds, for everyone
Sky.set("pastel") -- swap the whole look; nothing else changes
end
```
That is all a world needs: the sky, the sun and moon, the scene's lighting, fog, wet ground, rain, lightning, thunder and the ambience all follow from the clock. The scene's own directional and ambient lights are driven in play if it has them (in the editor they keep the values you gave them, see Living beside the engine's own sky and weather); if not, the kit brings its own, and takes them away again once the scene has its own.
## Guides
Two guides install with the package (open them with `guides`, `man`, or the Docs panel):
- **How to add a day night cycle, weather, rain and fog to your game** (`worldClockKit.package/guides/how-to-add-a-day-night-cycle-weather-rain-and-fog-to-my-game.guide`): setting up the cycle, the length of a day, setting and changing the time of day, the weathers and how to switch them, the sky looks and the three sky modes, how lighting, lamps, sound and the dawn, dusk and storm events hook in, and how every player sees the same hour and weather.
- **Example: add rain and fog to your game, through a full day** (`worldClockKit.package/guides/example-a-full-day-with-morning-fog-rain-and-a-lamp-that-lights-at-dusk.guide`): thick fog at dawn that lifts, rain rolling in with wet ground, a short thunderstorm and a clearing evening, with a lamp that lights at dusk, taken through dawn, noon, dusk and night step by step.
Using a forest, mountain or island? forestKit, alpineKit and tropicalKit set this clock up for you; their guides (`how-to-make-a-forest`, `how-to-make-mountains`, `how-do-i-add-a-tropical-island-and-beach-to-my-world`) are linked from both.
## What you get
- **A world clock everybody shares.** `dayLengthMinutes` sets how long a day is in real minutes. Every player sees the same hour, sun, weather and lightning, including someone who joins mid-afternoon. A day counter, four seasons (summer days run longer, winter days shorter), and pause / set time.
- **A sky that moves.** The sun rises in the east, crosses high in the south and sets in the west; the moon follows with its phase on an eight-day cycle; stars come out after dusk. The light, the ambient fill and the fog follow it: warm low dawn, white noon (capped so it never blows out), orange dusk, and a blue moonlit night that is dark but still readable.
- **Weather that fades.** `Weather.set("rain")` blends over a few seconds. The rain, snow, splashes and lightning are drawn by the **Cloudburst** weather kit, which comes with worldClockKit: soft, see-through drops lit by your sky and lamps that stop under roofs and splash where they land, tumbling snow, forked lightning and thunder delayed by distance. The clock stays in charge: it picks the weather, fades it and seeds the lightning, so every player sees the same storm. The ground goes wet and shiny or white (dry under a roof), fog thickens, and clouds roll in and darken the sky. Blown sand in a sandstorm is still the kit's own layer.
- **Lamps that switch themselves.** On at dusk, off at dawn, and early when a storm darkens the sky. Each lamp waits a moment of its own so a street lights up one lamp after another; windows and bulbs light one by one; the neon sign stutters on; torches and lanterns flicker.
- **Events** for dawn, noon, dusk, midnight, a new day, each hour, phase and season changes, weather changes, storms starting and ending, and every lightning strike.
- **Sound**: rain, wind and thunder come from Cloudburst while it draws the weather (muffled under a roof); the night bed from Soundstage and the kit's own sandstorm bed play beside it, and a strike called by hand with `Weather.strike` plays the kit's own thunder (three takes by distance). Beds and thunder play through voices the kit owns, checked every frame and rebuilt whenever a play session took them away. Beds fade over 1.5 s; both follow Soundstage's ambience and sound-effects volumes.
- **Nights that read as night** in every look and every weather: a deep sky, stars and a moon that lights the scene. Fog and mist never wash the night sky pale (the fog is kept no brighter than the night horizon behind it, so a sky seen through a forest canopy stays dark too), and stars still show through light mist.
- **A controls panel** to drop in with one line: dawn, morning, midday, sunset and night buttons, pause, speeds from ½x to 12x, and the weathers. Optional; nothing appears unless you show it.
- **Anything can follow the time of day.** A campfire that burns higher as the light falls, a lamp, a cricket sound: `TimeOfDay.drive(...)` in one line, or the `DayNight` component with no code.
The defaults give a good-looking scene the moment the clock is added: 08:00 on a clear morning, the realistic look, a 20-minute day.
## Step by step
### Add the controls panel and a clock display
In your scene's `entrypoint.luau` (or any script), after the clock is in the scene:
```lua
local Kit = require("worldClockKit.kit")
Kit.Controls.show() -- time, speed and weather buttons, on the left
Kit.Displays.show("sundial", { anchor = "bottomRight" })
```
`Kit.Controls.show({ side = "right", sections = { "time", "weather", "sky" } })` picks a side and the sections ("time", "speed", "weather", "sky"); `Kit.Controls.hide()` takes it away. The panel's buttons are also calls: `Kit.Controls.press("time:sunset")`, `press("weather:mist")`, `press("speed:4")`, so your own keys or menu can do the same. Swap a display for another by changing its name: `digital`, `analog`, `arc`, `minimal`, `pixel`, `scifi`, `sundial`, `moondial`.
### Wire a fire, lamp or sound to the time of day
`TimeOfDay.darkness()` is 0 in full day and 1 at night; it rises through dusk, falls through dawn, and a dark storm counts as dusk (the same rule the lamps use). Every player computes the same value from the shared clock.
```lua
local TimeOfDay = require("worldClockKit.timeofday")
-- a campfire: a point light that burns higher as the light falls
local fire = entity.spawn("campfire")
fire.component.add("Light", { kind = "point", intensity = 2, radius = 10 })
TimeOfDay.drive(fire, "Light", "intensity", 2, 9) -- 2 by day, 9 at night, eased
-- anything else: a sound bed, a particle rate, a material value
TimeOfDay.follow(function(v) print("crickets at", v) end, { from = 0, to = 0.8, fade = 4 })
-- on at night, off by day, flipping when the lamps do
TimeOfDay.follow(function(v) print(if v > 0.5 then "lantern on" else "lantern off") end, { mode = "switch" })
```
With no code: add the `DayNight` component next to the light, `fire.component.add("worldClockKit.DayNight", { component = "Light", field = "intensity", dayValue = 2, nightValue = 9 })`. For a whole lamp, the `campfire`, `torchPost` and `lanternPost` lamp styles already light at dusk. In play, driven values go back when play stops; in the editor a saved entity keeps the value you gave it (only temporary entities follow there).
### Add your own weather
```lua
local Weather = require("worldClockKit.weather")
Weather.define("drizzle", {
label = "Drizzle", tags = { "realistic", "cozy" },
description = "A fine light rain under thin grey cloud.",
cloudCover = 0.7, cloudDark = 0.3, rain = 0.2, wind = 0.15, fog = 0.15, wetness = 0.5,
sunDim = 0.4, darkness = 0.12, rainBed = 0.35,
})
Weather.set("drizzle")
```
Any channel you leave out is taken from `clear` (the channels are listed under Weather below). Define it before the clock starts it (at the top of your entrypoint), and on every machine: define it from code every player runs, not from one player's console. A defined weather fades in and out like the presets, shows on the controls panel and in `Catalog`, and the kit's tests pass with it in the world: they check that the nine shipped weathers are there, not that there are only nine.
### Two copies of the kit in one world
A world that installed worldClockKit itself and also has forestKit, alpineKit, tropicalKit, desertKit or arcticKit can hold two copies of the kit, at different versions (#23698). Each copy has its own clock, so a call on one copy does nothing to a scene whose clock came from the other.
1. **Tell whether it happened.** Since 1.5.8 a call on the copy without the scene's clock logs a warning once: `the scene's WorldClock is another copy of worldClockKit (deps.….worldClockKit.WorldClock)`. You can also ask directly: `require("worldClockKit.state").foreignClock()` returns the other copy's component name, or nil when the scene's clock is yours.
2. **Use the copy you installed yourself** (`require("worldClockKit.…")`, the newest release). Add the scene's clock from your own build with `entity.spawnSynced("WorldClock").component.add("WorldClock", { ... })` instead of through the environment kit's helper (such as `forestKit.Atmosphere.ensureClock`), so the clock is this copy's.
3. **Point the environment kit at the same copy.** In its installed files, change its `require("worldClockKit.…")` lines to `require("@root::worldClockKit.…")` until that kit is republished on this release.
4. **Check.** Press play, call `Weather.set("rain")`: it rains, and no warning appears.
## Styles
Every style is one setting away. Read them in code with `Kit.Catalog` (below); the family tags are realistic, cartoon, cozy, sci-fi, pixel, horror, fantasy and minimal, plus finer ones.
### Sky looks: `Sky.set(name)` or the WorldClock's `sky` field
| name | look | tags |
| --- | --- | --- |
| `realistic` | Natural sky: deep blue noon, orange dawn and dusk, stars and moon | realistic, natural, survival, farming, open-world |
| `toon` | Saturated bands, bold sun disc, hard-edged puffy clouds | cartoon, stylised, kids, platformer, bright |
| `pastel` | Peach mornings, lavender evenings, lilac night | cozy, cute, farming, hangout, soft |
| `alien` | Teal and magenta sky, two suns rising one after the other, a huge green moon | sci-fi, alien, space, exotic, fantasy |
| `eternalNight` | The sun never rises: a cold moon and a sky full of stars | horror, spooky, night, mystery, halloween |
| `lockedSunset` | Golden hour forever, the sun just above the horizon | cozy, romantic, hangout, vaporwave, chill |
| `overcast` | A low grey lid of cloud all day, flat light | moody, realistic, horror, drama, northern |
| `pixel` | Chunky pixel gradient, ordered dither, square sun | pixel, retro, 8-bit, arcade, platformer |
Locked looks (`eternalNight`, `lockedSunset`) hold the sky and light still while the clock, days and events carry on.
### Weather: `Weather.set(name)` or the WorldClock's `weather` field
| name | what happens |
| --- | --- |
| `clear` | Blue sky, a few wisps of cloud |
| `cloudy` | Broken grey cloud, softer light, a breeze |
| `rain` | Steady rain, wet shining ground, low cloud, rain ambience |
| `storm` | Heavy driven rain, near-black cloud, lightning flashes and thunder, lamps on early |
| `snow` | Drifting flakes, the ground turns white |
| `blizzard` | Snow driven sideways, thick white-out fog, howling wind |
| `fog` | Thick still fog that swallows the distance |
| `sandstorm` | A wall of blown orange sand, the sun a dull disc, roaring sand wind |
| `mist` | Light mist or haze: soft distance, low haze over the ground, the sun stays out and the stars still show |
### Lamps: the `WorldLamp` component's `style`
| name | what it is | tags |
| --- | --- | --- |
| `streetLamp` | Cast-iron post with a curved arm and a sodium lantern that warms up | realistic, urban, victorian, horror, city |
| `hangingLantern` | Wooden gallows post with a brass candle lantern | cozy, fantasy, medieval, farming, rustic |
| `wallTorch` | A burning torch in an iron bracket on a stone wall | medieval, fantasy, horror, dungeon, survival |
| `neonSign` | Pink and cyan tube lettering on a dark board (`text` sets the words) | sci-fi, cyberpunk, urban, synthwave, retro |
| `glowingWindows` | A cottage front whose windows light one by one | cozy, realistic, urban, horror, hangout, village |
| `stringLights` | Coloured festoon bulbs sagging between two posts | cozy, festive, hangout, party, farming |
| `torchPost` | A standing torch on a tall pole in a few stones | medieval, fantasy, survival, tribal, camp |
| `lanternPost` | A square lantern with an iron roof on a wooden post | cozy, fantasy, farming, village, rustic, japanese |
| `campfire` | Crossed logs in a ring of stones; the fire builds up as the light falls | camp, survival, cozy, forest, fantasy, tribal |
| `sciFiPylon` | A dark metal pylon with cyan light strips and a glowing ring | sci-fi, space, cyberpunk, futuristic, base |
| `pixelLamp` | A blocky post with a square head that snaps on and off | pixel, retro, 8-bit, arcade, platformer, voxel |
Every style is placed the same way (`Lamps.spawn(style, opts)` or the `WorldLamp` component), so swapping one for another is a change of name.
`WorldLamp` fields: `style`, `mode` (`auto` follows the sky; `on` / `off` force it), `brightness`, `text` (the neon sign's words; letters A-Z, digits and spaces draw as tubes, anything else as a plain label).
### Clock displays: `Kit.Displays.show(style, opts)`
| name | what it is |
| --- | --- |
| `digital` | A panel with the time in big digits, the day, the season and the weather |
| `analog` | A round dial with hour and minute hands and the day |
| `arc` | A horizon arc the sun travels along by day and the moon by night |
| `minimal` | Just the time, small, in a corner |
| `pixel` | A retro 8-bit clock: chunky pixel digits, a pixel sun or moon, the day in capitals |
| `scifi` | A glowing cyan HUD readout in corner brackets with a 24-segment bar through the day |
| `sundial` | A carved stone sundial, Roman hours VI to XVIII; the gnomon's shadow follows the sun, a moon rests on it at night |
| `moondial` | The moon in its phase with its name, the eight phases round the rim and the night's progress |
Every display takes the same options (`anchor`, `scale`, `twelveHour`, `margin`, `layer`), so a world swaps one for another by changing its name.
## Calls
All of these work from any player; a change made by someone who is not the clock's owner is sent to the owner and reaches everybody from there.
### `Kit`: `require("worldClockKit.kit")`
`Kit.Clock`, `Kit.Weather`, `Kit.Sky`, `Kit.Lamps`, `Kit.Displays`, `Kit.Catalog`, `Kit.Controls`, `Kit.TimeOfDay`, `Kit.on(event, fn)`, `Kit.EVENTS`, `Kit.VERSION`. Each module is also reachable on its own: `require("worldClockKit.clock")`, `.weather`, `.sky`, `.lamps`, `.displays`, `.catalog`, `.controls`, `.timeofday`.
### Clock: `worldClockKit.clock`
| call | returns / does |
| --- | --- |
| `Clock.hour()` | Hour of the day, 0 to <24 with fractions |
| `Clock.minute()` | Minute within the hour, 0-59 |
| `Clock.day()` | Day counter, from 1 |
| `Clock.totalHours()` | Game hours since day 1, 00:00 |
| `Clock.dayProgress()` | 0 at midnight to 1 |
| `Clock.format(twelveHour?)` | `"14:05"` or `"2:05 PM"` |
| `Clock.season()` | `{ name, index, dayOfSeason, progress, year, daysPerSeason }` (spring, summer, autumn, winter) |
| `Clock.seasonAt(totalHours)` | The same table for any moment, given as game hours since day 1 (what `totalHours()` returns): for looking back over skipped time or ahead |
| `Clock.sunTimes()` | Sunrise and sunset hours today |
| `Clock.sunTimesAt(totalHours)` | Sunrise and sunset hours on the day holding that moment |
| `Clock.solarHour(h?)` | The hour mapped so sunrise is 6 and sunset 18 |
| `Clock.phase()` / `Clock.phaseAt(h)` | `"night"`, `"dawn"`, `"day"` or `"dusk"` |
| `Clock.isNight()`, `Clock.isDay()` | Booleans |
| `Clock.phaseAtHours(totalHours)`, `Clock.isNightAt(totalHours)` | The phase, and whether it is night, at any moment, with that day's own sunrise and sunset |
| `Clock.daylight()` | 0 (night) to 1 (full day), from the sun's height |
| `Clock.sunDirection()`, `Clock.moonDirection()` | Unit vectors `{x, y, z}` toward each |
| `Clock.sunDirectionAt(solarHour)` | The same for any solar hour (x, y, z) |
| `Clock.moonPhase()` | 0 new, 0.5 full |
| `Clock.dayLengthMinutes()`, `Clock.isPaused()` | Current settings |
| `Clock.setTime(hour, day?)` | Set the hour (stays on today unless `day` is given) |
| `Clock.setDay(day)` | Jump to a day, keeping the hour |
| `Clock.advance(hours)` | Move forward (or back) |
| `Clock.pause()`, `Clock.resume()` | Stop and restart the clock (the weather keeps fading) |
| `Clock.setDayLength(minutes)` | Change the speed, keeping the hour |
| `Clock.on(event, fn)`, `Clock.once(event, fn)` | Subscribe; returns a connection with `:Disconnect()` |
### Weather: `worldClockKit.weather`
| call | returns / does |
| --- | --- |
| `Weather.set(name, { fade = seconds }?)` | Change it for everyone; fades over `weatherFade` (6 s) unless given; `fade = 0` snaps |
| `Weather.current()`, `Weather.previous()` | The weather now (or fading in), and the one fading out |
| `Weather.blend()` | How far the fade has got, 0-1 |
| `Weather.params()` / `Weather.paramsAt(t)` | The numbers now: `cloudCover, cloudDark, rain, snow, sand, wind, fog, wetness, snowCover, lightning` (strikes/min)`, sunDim, darkness, tint, rainBed, windBed, sandBed` |
| `Weather.isStorm()`, `Weather.isRaining()`, `Weather.isSnowing()` | Booleans |
| `Weather.list()` | Every preset name |
| `Weather.define(name, def)` | Add a preset (any channels above, plus `label`, `tags`, `description`) |
| `Weather.strike({ at = {x, z}, strength }?)` | Call down one lightning strike for everyone |
| `Weather.strikesBetween(t0, t1)` | The scheduled strikes in shared seconds (what every peer computes) |
| `Weather.stormCenter()`, `Weather.stormRadius()` | Where lightning lands (the WorldClock's position, `stormRadius`) |
### Sky: `worldClockKit.sky`
| call | returns / does |
| --- | --- |
| `Sky.set(name, { fade = seconds }?)` | Switch the look for everyone (3 s cross-fade) |
| `Sky.current()`, `Sky.looks()` | The look now; every look |
| `Sky.define(name, def)` | Add a look: `night`, `dawn`, `day`, `dusk` palettes plus style knobs (see `worldClockKit.skies`) |
| `Sky.lightLevel()` | How lit the world is, 0-1, clouds included |
| `Sky.isDark()` | Whether lamps should be on |
| `Sky.environment()` | Everything the kit computed this frame: light, ambient, fog, palette, sun and moon |
### Lamps: `worldClockKit.lamps`
`Lamps.styles()`, `Lamps.has(name)`, `Lamps.get(name)`, `Lamps.describe(name)`, `Lamps.spawn(style, { position, yaw, mode, parent })`, `Lamps.list()` (live lamps `{ id, style, mode, on }`), `Lamps.setMode("on" | "off" | "auto")` (every lamp), `Lamps.define(name, def)` (parts, lights, warmup, flicker), `Lamps.canTube(word)`.
### Displays: `worldClockKit.displays`
`Displays.show(style, { anchor, scale, twelveHour, margin, layer })` returns a handle; `Displays.hide(handle)`, `Displays.hideAll()`, `Displays.shown()`, `Displays.styles()`, `Displays.describe(style)`, `Displays.moonPhaseName(phase)` ("New Moon" … "Waning Crescent"). Anchors: `topLeft`, `topRight`, `bottomLeft`, `bottomRight`, `topCenter`, `bottomCenter`.
### Controls panel: `worldClockKit.controls`
| call | returns / does |
| --- | --- |
| `Controls.show(opts?)` | Put the panel up. `side` ("left" / "right"), `edge` ("top" / "bottom"), `margin` (16, or `{ top, right, bottom, left }`, e.g. to sit beside another panel), `sections` (any of "time", "speed", "weather", "sky"; default the first three), `weathers` (names; default clear, mist, rain, then the rest), `speeds` (default ½, 1, 2, 4, 12), `baseDayLength` (the 1x day in minutes; default the clock's day length when shown), `collapsed`, `title`. Again re-shows with the new options |
| `Controls.hide()`, `Controls.isShown()` | Take it down; whether it is up |
| `Controls.press(action)` | What a button does: `"time:dawn"` (`morning`, `midday`, `sunset`, `night`), `"pause"`, `"speed:4"`, `"weather:mist"`, `"sky:pastel"`, `"collapse"` |
| `Controls.timeFor(name)` | The hour a quick-time button jumps to today (from today's sunrise and sunset) |
| `Controls.baseDayLength()` | The 1x day the speed buttons scale |
Everything goes through the shared clock, so every player sees the change. In play, Tab frees the mouse to use the panel.
### Time of day: `worldClockKit.timeofday` and the `DayNight` component
| call | returns / does |
| --- | --- |
| `TimeOfDay.darkness()` | 0 in full day to 1 at night; a dark storm counts as dusk |
| `TimeOfDay.lightLevel()` | How lit the world is, 0-1 (what the lamps read) |
| `TimeOfDay.isNight()` | Night by the lamps' rule |
| `TimeOfDay.follow(fn, { from, to, fade, mode })` | Call `fn(value)` as the darkness changes, eased over `fade` seconds (2); `value` runs from `from` (day, 0) to `to` (night, 1). `mode = "switch"` flips between the two when the lamps do. Returns `{ stop() }` |
| `TimeOfDay.drive(entity, component, field, day, night, opts?)` | The same for one component field, e.g. `TimeOfDay.drive(fire, "Light", "intensity", 2, 9)`; stops by itself when the entity goes |
| `TimeOfDay.stopAll()`, `TimeOfDay.count()` | Stop every follower; how many run |
`DayNight` component fields: `component`, `field`, `dayValue`, `nightValue`, `mode` (`smooth` / `switch`), `fadeSeconds`. Followers run every frame the scene's WorldClock ticks. `require("worldClockKit.director").onTick(key, fn)` runs your own `fn(dt, env)` in that same frame (`env` as `Sky.environment()` returns it); the same key again replaces it, nil removes it.
### Catalog: `worldClockKit.catalog`
| call | returns |
| --- | --- |
| `Catalog.kinds()` | `{ "skies", "weathers", "lamps", "clocks" }` |
| `Catalog.list(kind, tag?, namesOnly?)` | Entries `{ kind, name, label, tags, description }`, optionally only those tagged |
| `Catalog.find(text)` | Every style whose name, label, tags or description mention it |
| `Catalog.get(kind, name)` | One entry |
| `Catalog.tags()`, `Catalog.FAMILIES` | Every tag in use; the style families |
| `Catalog.forFamily(tag)` | `{ skies = {...}, weathers = {...}, lamps = {...}, clocks = {...} }` for a game's style |
| `Catalog.text()` | The whole catalog as text |
```lua
local Catalog = require("worldClockKit.catalog")
print(Catalog.forFamily("horror").skies) -- { "eternalNight", "overcast" }
```
### Diagnostics and sound
| call | returns / does |
| --- | --- |
| `require("worldClockKit.probe").ask(seconds?)` | Every player's report side by side, with `agree` and `problems` (see With several players) |
| `Probe.report()` | This machine's report: hour, weather, look, lamps lit, `perf`, `notes` |
| `Probe.drawState()` | This machine's frame rate (`fps, avgMs, p95Ms, worstMs`), platform, sky type and fallback, whether rain/snow/sand draw, its screens and cameras |
| `Probe.note(key, value)`, `Probe.notes()` | Attach a fact of your own to what this machine reports |
| `require("worldClockKit.director").frameStats()` | `{ fps, avgMs, p95Ms, worstMs, samples }` over the last ~300 frames |
| `Director.skyFallback()` | Whether the engine's sky is standing in until the kit's sky shader compiles |
| `Director.bindings()` | What the clock drives right now: `{ sky, sun, ambient }` entity ids, plus `sunStandIn` / `ambientStandIn` while the kit's own light stands in |
| `Director.refresh()` | Look for the scene's sky, sun and ambient light again now (it also does this by itself) |
| `require("worldClockKit.audio").onThunder(fn)` | `fn({ name, volume, played })` after every thunderclap |
| `Audio.playing()` | The level each weather bed is asked for: bed name → 0-1 |
| `Audio.sounding()` | What each bed sounds like on this machine: bed name → `{ level, voice, audible }`, `audible` being the engine mixer's own verdict |
### Events: `Clock.on(name, fn)` / `Kit.on(name, fn)`
| event | payload |
| --- | --- |
| `dawn`, `noon`, `dusk`, `midnight` | `{ hour, day, time }` |
| `newDay` | `{ hour, day, time }` (the new day) |
| `hour` | `{ hour, day, time, hourOfDay }` |
| `phase` | `{ phase }`: night, dawn, day, dusk |
| `season` | `{ season }` |
| `timeSet` | `{ from, to }`: the clock jumped (setTime, a joiner catching up) |
| `weatherChanged` | `{ from, to, fade }` |
| `stormStarted`, `stormEnded` | `{ weather }` |
| `lightning` | `{ t, position = {x, 0, z}, distance, strength, variant }` |
| `skyChanged` | `{ from, to }` |
Events fire on every player's machine at the same moment, so use them for what each player sees and hears. For a change to the shared world (spawning a crop, ending a round), act only on one machine, for example the clock owner: `require("worldClockKit.state").isAuthority()`.
## Settings: the `WorldClock` component
| field | default | meaning |
| --- | --- | --- |
| `dayLengthMinutes` | 20 | Real minutes per game day |
| `startHour`, `startDay` | 8, 1 | Where the clock starts each session |
| `daysPerSeason` | 7 | Game days per season |
| `startSeason` | spring | The season of day 1 |
| `seasonalDaylight` | 1.5 | Hours sunrise/sunset move across the year (0 = always 6:00-18:00) |
| `sunBearing` | 0 | Compass bearing the sun's whole path is turned by, degrees (0 rises in the east, +X; 90 a quarter round) |
| `sunTilt` | 28 | How far the sun's path leans away from overhead, degrees (0 overhead at noon; 60 low all day) |
| `ambientBoost` | 1 | Multiplies the kit's fill light (0-4) |
| `sky` | realistic | The look |
| `weather` | clear | The weather |
| `weatherFade` | 6 | Seconds a weather change takes |
| `paused` | false | Clock stopped |
| `skyMode` | kit | `kit` draws the kit's sky; `engine` keeps the scene's own `ProceduralSky` and drives its hour; `off` leaves the sky alone |
| `drivesLighting` | true | Drive the sun/moon and ambient light |
| `precipitation` | true | Rain, snow and lightning drawn by Cloudburst, plus the kit's blown sand. With a `Cloudburst` component in the scene, the clock's owner writes each weather change into it; set this false to let that component run its own weather |
| `sound` | true | Weather ambience and thunder (Cloudburst's rain, wind and thunder; Soundstage's night bed; the kit's sandstorm bed) |
| `lightning` | true | Storms throw lightning |
| `stormRadius` | 160 | How far from the WorldClock entity lightning lands (m) |
| `autoWeather` | false | Change weather by itself on a shared forecast |
| `forecastMinutes` | 4 | Minutes between forecast changes |
| `forecast` | clear,clear,cloudy,rain,clear,storm | What the forecast draws from (repeat one to make it likelier) |
| `persist` | false | Save day, hour, weather and look between sessions (world data) |
| `persistHour` | true | With `persist`: carry on at the saved hour. Off: start each session at `startHour` of the saved day (the next day when the saved hour was later), so players arrive in the morning |
| `persistWeather` | true | With `persist`: start in the saved weather. Off: start in `weather`, and the forecast changes it from there |
## With several players
- **One source of truth.** The `WorldClock` sits on a synced entity. Its owner (the first player in, handed on when they leave) publishes a shared timeline twice a second along with three small records: the clock anchor, the weather fade and the sky look. Every player computes the hour, the sun, the fade and the lightning from those, so nothing drifts and nothing per-frame crosses the network.
- **Late joiners** receive the records and the latest shared time, snap to it, and see exactly what everyone else sees: the same hour, the same half-faded storm.
- **Lightning** is a schedule every machine derives from the same seed and the same shared time, so each strike flashes and thunders for everybody at the same moment (to within one network latency) without a message per strike. While Cloudburst draws the weather, its schedule runs on the clock's seed and storm rate, and every strike it throws fires the kit's `lightning` event. `Weather.strike()` sends one message that every machine plays.
- **Anyone can change things.** `Weather.set`, `Sky.set`, `Clock.setTime` and the rest go straight to the record when called on the owner's machine and are forwarded to the owner from anyone else.
- **Lamps** decide on/off from the shared sky on each machine, so every player sees the same lamps lit.
- **Checking it.** `require("worldClockKit.probe").ask()` asks every player's machine what it computes: the hour at one agreed instant, the weather and its fade, the sky look, the lightning schedule, the strikes it showed, and how many lamps are lit. It returns the answers side by side with `agree` and a list of `problems`. Run it from a script or the console while two players are in the world.
## Living beside the engine's own sky and weather
The kit uses the engine's height fog (`@builtin::systems.atmosphere`) and surface weather (`@builtin::systems.weather`) rather than its own, and drives the scene's existing directional and ambient lights. A scene that already has a `ProceduralSky` can keep it with `skyMode = "engine"` (the kit then sets its hour and leaves its look alone), or let the kit draw the sky with `skyMode = "kit"`. With `drivesLighting = false` and `skyMode = "off"` the kit only keeps time, weather, events and lamps.
**Nothing the clock does is an edit to your scene.** The clock never writes its own settings fields: the hour, weather, look, pause and day length it is running live in the clock, not in the fields, which stay the settings a session starts from (setting one in the inspector still switches the clock). In the editor it also leaves the scene's own saved sun, ambient light and sky entity exactly as you authored them, so leaving the editor open with the clock running piles up no unsaved edits; the kit's sky, the fog and the wet ground still follow the hour there, and so does the kit's stand-in sun and ambient light in a scene without lights of its own. In play the scene's own lights and sky follow the clock as before. What happens in play stays in play: changing the weather or the time of day during play does not count as a change you made to the scene, stopping play just works, and back in the editor the clock is at the hour and in the weather it had when play started.
**A scene that rebuilds itself.** The clock always drives the sky and lights the scene holds right now. Before each write it checks that the `ProceduralSky`, sun and ambient light it drives are still there; when one has been removed or replaced (a scene rebuild, a level swap), it finds the current one and drives that from the next frame, quietly. Twice a second it also looks for a sky or light the scene has added. When the scene has no sun or ambient light, the kit puts in a stand-in of its own, and takes it away again as soon as the scene has its own, so a scene never ends up with two suns. `require("worldClockKit.director").bindings()` says what it is driving; `Director.refresh()` makes it look again at once.
## Performance
Built for the browser at 30+ fps: the sky is one fullscreen pass; rain and snow are Cloudburst's GPU layers (no script work per drop) and sand is one fixed 2,400-grain mesh wrapped around the camera (cost does not grow with the world); the kit writes a light or material value only when it changed; lamps write only while they fade. Each lamp style casts one or two shadowless point lights. When the clock starts, the kit draws its sand and the lightning bolt for a hand-called strike once, invisibly, so the first sandstorm does not stall while their GPU pipelines are built.
**Never a black sky.** Until the kit's sky shader has compiled, the kit shows the engine's own procedural sky in the kit's current colours, then switches over (`require("worldClockKit.director").skyFallback()` reads which is showing).
**Lighting your own scenery.** The kit drives the scene's lights; your meshes need lit materials to follow them. A Model tint (`Model:setTint`) blends a flat colour over the lit result, so a heavily tinted floor looks the same at midnight as at noon. Colour scenery with a material's `base_color` instead (the gallery's `gallery/materials` are examples).
## Known limits
Each is an open issue in the engine's repository, [OrigoZero/zero](https://github.com/OrigoZero/zero), that the kit cannot fix on its own.
- **A world that got worldClockKit through another kit cannot move it to a newer release yet** ([OrigoZero/zero#23698](https://github.com/OrigoZero/zero/issues/23698)). When worldClockKit arrived as part of another kit's install (forestKit, alpineKit, tropicalKit, desertKit or arcticKit bring it along), that world keeps the release the other kit was published with, and cannot update worldClockKit on its own. It gets the newer release when that kit is republished on it. A world that installed worldClockKit directly updates as usual.
- **Two copies of the kit in one world do not see each other** ([OrigoZero/zero#23698](https://github.com/OrigoZero/zero/issues/23698)). Installing worldClockKit directly into a world that also has forestKit, alpineKit, tropicalKit, desertKit or arcticKit leaves two copies at different versions, each with its own state. Scripts that `require("worldClockKit.kit")` reach the directly installed copy, while the other kit's code (and a clock it adds, such as `forestKit.Atmosphere.ensureClock`) uses its own. Calls on the copy without the scene's clock change nothing anyone sees, and since 1.5.8 they log a warning naming the other copy. To run everything on one copy: add the scene's `WorldClock` from your own build (`entity.spawnSynced("WorldClock").component.add("WorldClock", {...})`) instead of through the other kit, and change the other kit's `require("worldClockKit.…")` lines to `require("@root::worldClockKit.…")` until that kit is republished on this release.
- **A guide's link to another package's guide only opens once that package is installed** ([OrigoZero/zero#22513](https://github.com/OrigoZero/zero/issues/22513)). Both guides link the forest, mountain and island guides; in a world without forestKit, alpineKit or tropicalKit those links do not open. Search ZeroMind for the kit and install it to read its guide.
- **Two editors signed in to one account count as one player** ([OrigoZero/zero#14448](https://github.com/OrigoZero/zero/issues/14448)). To check the shared clock with `Probe.ask()`, the second player has to be a different account (or a guest on the published page); two engines on one account collide, and the probe sees one machine.
- **Shared time is the owner's, to one network latency** ([OrigoZero/zero#18604](https://github.com/OrigoZero/zero/issues/18604), no network-wide clock). Every player follows the timeline the clock's owner publishes. Measured with two players 43 ms apart: the hour, weather fade and lightning schedule were identical at the same shared instant; a scheduled strike showed within 30-55 ms on the joining player, and a strike called with `Weather.strike()` (which travels to the owner and back) within about 0.2 s.
- **The published player page lost its render device while loading** in Chrome on a machine also running the desktop editor ([OrigoZero/zero#19397](https://github.com/OrigoZero/zero/issues/19397)), and then stays dark. Not reproduced elsewhere; the same world runs in the browser editor on that machine.
## By design
- **One WorldClock per scene.** A second one stands by and logs why.
- **In the editor, a reloaded scene keeps its clock where it was.** When the scene's WorldClock is unloaded in edit mode and the same clock comes back within five minutes with the same settings (a scene reload, or a test run, which sets the scene aside while it runs), it carries on at the hour, weather and sky it had. Change one of its settings, such as `startHour`, and it starts its day afresh. Every play session starts from `startHour` as always, and when it ends the editor's clock comes back at the hour and weather it had when play started, however long play ran.
- **Precipitation follows the camera.** Cloudburst draws rain and snow around whoever is looking, thinning into grey curtains in the distance; blown sand is drawn in a 26 m box around the camera.
- **Neon lettering** draws A-Z, digits, spaces and `!` as tubes; any other text falls back to a plain label.
- **Browser audio** starts on the first click or key, as with all browser sound (see Soundstage).
- **The clock follows real time.** Pausing the engine does not stop it; to stop time in your game, call `Clock.pause()`.
## Tests
`worldClockKitTests` runs 68 cases. Run it with `tools.use("tests", "run", { suite = "worldClockKitTests" })`.
It needs nothing set up first: it passes in a world the kit was just installed into, with or without a `WorldClock` in the scene. **It leaves your sky as it found it.** The test runner sets the scene aside for the length of a run; the scene's clock comes back at the same hour, day length, pause, sky mode, sky look and weather (fade included), with the same lightning seed, and runs on from there as if nothing had happened. Every case that changes the clock or the weather puts back exactly what it found, whether it passes or fails, and no case sends anything to the other players in the world, so a run leaves nothing pending in the scene, in your editor or anyone else's.
The cases cover every public call: the clock and its events, seasons, sun and moon; weather fades, storms and the lightning schedule; every sky look's night and noon levels; lamps, lettering and spawning; displays; the catalog; this README's examples and version; the two guides (their links and code); a scene that removes and replaces its sky, sun and ambient light twice in a row, and the stand-in lights giving way to the scene's own; the multiplayer model (forwarded requests, timeline correction, a late joiner); and the hand-back itself: a live clock is noted (hour, day length, pause, sky mode, look, weather and fade, lightning, seed), every clock and weather case is run again on it, once paused and once running, plus a case that fails on purpose after changing all of them, and the note must match after each; a clock unloaded and loaded again carries on where it was; and the clock changing nothing in the scene: its settings fields stay as set while the live weather, look, pause and day length change, a saved sun and ambient light keep their authored values in the editor, a note left for play is never taken or thrown away by the editor, and the editor's clock comes back at exactly the hour it had when play started; another copy of the kit told apart by its clock's name; every look reading as night (a deep sky, stars, the moon lighting the scene) in clear, mist and fog; the mist preset; the controls panel's actions, its options and that hiding it leaves no screen behind; time-of-day followers easing from day to night, the switch mode, a storm reading as dusk and the `DayNight` component driving a campfire light; and every new display and lamp style.
## This world
The world this package lives in is its gallery: a plaza with all eleven lamp styles and a name sign for each, a live time board, all eight clock displays on screen, the kit's controls panel, and the gallery's own panel to switch the sky look and weather (Light Mist included) and scrub the hour. Press play to watch a two-minute day go by.
## Version history
Version 1.7.8.
### What changed in 1.7.8
- **Cheaper every frame, same picture.** A clock that is not moving (paused, or a mood holding one hour) no longer
re-evaluates and re-applies the whole sky 15 times a second: the director skips the work while nothing the
environment is made of changes (clock hours, weather and sky revisions and fades, settings, lightning), still
follows rain and snow round the camera, and re-evaluates at least once a second. A moving clock goes the usual
path, so the sun still moves smoothly.
- **No more light written twice per update.** When a mood hook (lanternStair's) calls `Director.apply` again inside
a tick, only the last apply is written, after the hooks: before, the sun direction, ambient and moon light were
written twice a tick with different values, flip-flopping the sun past the shadow cache's 0.6 degree step and
throwing the cached sun shadows away on every update.
- The WorldClock component rebuilds its config twice a second and on every property change instead of every
frame, and reuses one records table. Measured in Tsukimichi: WorldClock 6.0 ms -> 1.1 ms per update.
Version 1.7.7.
### What changed in 1.7.7
- **Point the sun where your level looks.** Three new WorldClock fields: `sunBearing` turns the sun's whole path round the compass (0 rises in the east as before), `sunTilt` leans the path further from overhead (28 as before; 60 keeps it low all day) and `ambientBoost` scales the fill light (1 as before). A game no longer has to aim the kit's sun or lift its ambient light by hand. Every default keeps the look of 1.7.6.
### What changed in 1.7.6
- `Kit.VERSION` reports the release it is (1.7.6); 1.7.4 and 1.7.5 still reported "1.7.3". Behaviour is unchanged.
Version 1.7.5.
### What changed in 1.7.5
- **Engine library brought up to date, and a release newer than every earlier copy.** A world that once re-published a 1.6.8 copy from inside another kit (Turquoise Cay, through tropicalKit) holds that copy under a later release than 1.7.4, so its installer would not move it on to 1.7.x. This release is newer than both, so such a world can update to it (and drops its second, pinned worldClockKit copy). No behaviour changed.
Version 1.7.4.
### What changed in 1.7.4
- **The moon has a face.** The full moon was a flat white disc with faint noise; it now shows dark maria, a scatter of bright craters and a soft darkened limb, in every sky look but the toon and pixel ones (which keep their flat disc). Seen big behind a torii in the Tsukimichi film.
Version 1.7.3.
### What changed in 1.7.3
- **A restart comes back at the hour it left, earlier or later.** The editor's own clock runs on while the editor is in edit mode, and play only took the saved moment when it was later than the clock carried in, so after time in the editor a restart started at the editor's hour instead (a player left at 17:30 and came back at 07:30). A play session now always starts at the saved moment (with `persistHour` off the morning rule still applies), and the clock saves every 2 seconds instead of every 20, so a session that ends between saves loses at most 2 seconds and a reload mid-session stays put. Checked in play: day 2 at 18:51 saved, editor clock moved to day 5 at 10:00, Play, day 2 at 18:51.
Version 1.7.2.
### What changed in 1.7.2
- **A clock carried into play keeps the saved day.** A clock a scene builds in the editor keeps running when Play starts and never wakes again in play, so it never restored the saved day or saved it. It now notes its play start on its first update in play: it takes the saved moment then (time only moves on) and saves from then on. Before, a world whose clock was carried into play came back on the editor's day after a restart. Checked in play: day 4 at 20:36 saved, Stop, Play, day 4 at 21:00.
Version 1.7.1.
### What changed in 1.7.1
- **Installs cleanly into an empty world.** 1.7.0 pinned Cloudburst 1.4.0, whose wind sounds were borrowed from the arctic and alpine world kits; installing them brought those whole kits along, and the arctic kit depends on this clock kit, so the install looped back on itself and was refused. This release pins Cloudburst 1.4.5, which takes its wind from Soundstage instead, so the clock kit, Cloudburst and Soundstage are all an empty world needs.
- Cloudburst 1.4.5 also makes daytime and windy rain read clearly, makes picking a weather kind always bring that weather, and holds lightning to never less than 2.6 seconds between strikes.
- Engine library brought up to date.
### What changed in 1.7.0
- **Rain, snow and lightning are drawn by Cloudburst.** The kit's own rain and snow (thin bright lines) are retired: when the weather turns to rain, storm, snow or blizzard, the Cloudburst weather kit draws soft, lit, see-through drops that stop under roofs and splash where they land, tumbling snow, wet ground that stays dry under cover, forked lightning and thunder delayed by distance. Cloudburst now comes with worldClockKit (a declared dependency).
- **The clock stays the one source of truth.** It still picks the weather, fades it and seeds the lightning; every frame its blended weather becomes Cloudburst's, so every player sees the same drops and strikes. Each weather maps to a Cloudburst look (`require("worldClockKit.falling").LOOKS`: rain realistic, storm cinematic with forked lightning, blizzard powder snow, fog a valley bank, mist ground mist, sandstorm dry gusts); a weather you define can carry its own with a `cloudburst = { kind = ..., rainLook = ... }` table.
- **Nothing doubled.** Cloudburst plays the rain, wind and thunder and lifts the light for its flashes; the kit's sky flashes with it, its own scheduled strikes, rain bed and wind bed step aside, and its fog, sun dimming and sky clouds stay the kit's. Every Cloudburst strike fires the kit's `lightning` event. `Weather.strikesBetween` is empty while Cloudburst draws.
- **A scene with its own Cloudburst component.** With `precipitation` on, the clock's owner writes each weather change into that component (kind, intensity, looks, fade) and the component draws. With `precipitation` off, the two run side by side as before.
- Blown sand is still the kit's own layer. `Probe.drawState()` reads rain and snow from Cloudburst and says which one draws (`cloudburst = "kit"` or `"scene"`).
### What changed in 1.6.8
- `Clock.hourForSolar(solar)`: the inverse of `Clock.solarHour`, the clock hour today at which the sun stands at a given solar hour (6 sunrise, 12 noon, 18 sunset). Kits that offer "set the time to dawn / dusk" used to carry their own copy of this; they can call it here instead. Nothing else changed.
### What changed in 1.6.4
- **Soundstage brought current.** worldClockKit now references Soundstage 2.1.3, the release the other kits around it use, so a world that installs worldClockKit beside them holds one Soundstage. The world also moved to the current engine library. No worldClockKit code changed; the suite runs 68 of 68.
### What changed in 1.6.3
- **Fixed: the clock broke after a scene swap.** `entity.findAll()` can still list entities that are being despawned, and the director read them while looking for the scene's sun, ambient light and ProceduralSky, so `WorldClock` failed to wake ("entityRef: entity ... does not exist") or errored every frame. Every scan now keeps only entities that still exist, and the clock binds to the new scene's lights and sky. Nothing else changed.
### What changed in 1.6.2
- `Controls.show({ margin = ... })`: the panel's distance from the screen edges, a number or `{ top, right, bottom, left }`, so it can sit beside another panel rather than on top of it. Nothing else in the kit changed.
- The gallery in this world is laid out so nothing overlaps on a 1920 by 1080 screen (the editor's view included): the kit's controls panel sits beside the gallery's own panel, the clocks run in a row above the signs at the top right and along the bottom right, and the opening view stands back far enough to frame every lamp and sign.
### What changed in 1.6.1
- `Controls.show({ edge = "bottom" })` puts the controls panel at the bottom of the screen instead of the top (with `side` it reaches any corner). Nothing else changed.
- The gallery in this world now shows the whole range: all eleven lamps with a name sign each, the eight clock displays, the controls panel under the gallery's own, and Light Mist; its opening view faces the lamps.
### What changed in 1.6.0
- **Nights read as night in every look, in fog and under a canopy.** At night the fog is kept no brighter than the night horizon behind it, so fog, mist and a forest kit's haze no longer wash the sky into a pale grey; the haze overhead thins a little at night so stars show through light mist; the Pastel night is a deeper lilac; the Overcast night's cloud lid breaks a little and lets some stars and the moon through. Every look's night now measures a deep zenith with visible stars in clear, mist and fog (a test checks it).
- **Light Mist**, a ninth weather (`mist`): soft distance and low haze, the sun stays out.
- **A ready-made controls panel** (`worldClockKit.controls`, `Kit.Controls.show()`): dawn, morning, midday, sunset and night, pause, speeds ½x to 12x, the weathers and optionally the sky looks. Optional; nothing changes for a world that does not show it.
- **Things that follow the time of day** (`worldClockKit.timeofday`, `Kit.TimeOfDay`, and the `DayNight` component): `darkness()`, `follow(fn, opts)`, `drive(entity, component, field, day, night)`. `Director.onTick(key, fn)` runs your own code in the clock's frame.
- **More styles.** Clock displays: `pixel`, `scifi`, `sundial`, `moondial` (and `Displays.moonPhaseName`). Lamps: `torchPost`, `lanternPost`, `campfire`, `sciFiPylon`, `pixelLamp`. Same options and the same calls as the existing ones, so a world swaps with one change of name.
- **Fixed: lamp parts could turn invisible** after a world reload or a test run. Their materials were remembered by name only and the renderer let them go; the kit now keeps hold of them and makes them again when needed.
- README: step-by-step sections for the controls panel and a clock display, wiring a fire, lamp or sound to the time of day, adding your own weather, and what to do with two copies of the kit in one world. The defaults (08:00, clear, realistic, a 20-minute day) were checked to give a good first scene and are unchanged.
- Every existing look, weather, lamp and display works as before; the API only grew. Tests: 68 (eight new).
### What changed in 1.5.9
- 1.5.8 came from a pull request (#6) sent by a world that installed the kit; this release adds what its review found. The kit's own WorldClock name is looked up when first needed and never stops the kit from loading, the waits count real seconds, and two new cases (60 now) check that another copy's clock is told apart by its component name and that this copy's own clock never sets the warning off. No other change.
### What changed in 1.5.8
- **A clock that belongs to another copy of the kit is no longer silent.** When worldClockKit is installed directly and another kit (forestKit, alpineKit, ...) brings its own older copy, the world holds two copies with separate state (#23698). A scene whose WorldClock came through the other kit (for example from `forestKit.Atmosphere.ensureClock`) is then out of reach of scripts that `require("worldClockKit.kit")`: `Weather.set`, `Clock.setTime` and the rest changed only an invisible local clock, with no message, so a day plan written from the example guide did nothing. Now the first such call of each kind logs a warning naming the other copy's WorldClock and how to use one copy. New calls: `State.foreignClock()` (that component's name, or nil) and `State.warnForeignClock(op)`.
- Known limits and the example guide say how to keep one copy in a world that also has an environment kit.
- Tests pass in a world that defines its own weather with `Weather.define`: the weather and catalog cases check that the eight shipped presets are there rather than that there are exactly eight (as 1.4.4 and 1.4.6 did for sky looks). The sky-fallback case waits for the switch to the kit's sky (up to 6 s) instead of a fixed 1.2 s, which a heavy scene at 200 ms a frame did not meet.
### What changed in 1.5.7
- Rebuilt on the engine library @builtin 7e13a48 (from d7b4fc5), so the package carries no copies of older engine parts. No change to how the kit behaves: everything 1.5.6 brought is here as it was, and all 58 tests pass.
### What changed in 1.5.6
- **What happens in play stays in play.** Stopping play after changing the weather or the time of day just works: the clock no longer writes the live weather, look, pause and day length into its own settings fields, which the editor counted as changes tuned in play and refused to leave over. Back in the editor the clock is at the hour and in the weather it had when play started, and the scene lists nothing as changed. Before, the play session's weather could carry into the editor and show up as an edit to the scene.
- **The clock running in the editor makes no edits.** In the editor the clock leaves the scene's own saved sun, ambient light and sky entity as authored, instead of writing their colour, brightness and direction (which piled up as unsaved edits). In play they follow the clock as before; the kit's sky, the fog and wet ground, and the kit's stand-in lights in a scene without its own still follow the hour in the editor. Its writes are also kept out of the scene's autosave overlay.
- The WorldClock's `sky`, `weather`, `paused` and `dayLengthMinutes` fields are the settings a session starts from; setting one in the inspector still switches the clock, and `Weather.current()`, `Sky.current()`, `Clock.isPaused()` and `Clock.dayLengthMinutes()` read the live values.
- The example guide leads with adding rain and fog to your game, so it is found when you look for that.
- New call: `Audio.isEnabled()`. Tests: 58 cases (four new, for the above), and the storm-sound case no longer depends on the scene's clock having sound on.
### What changed in 1.5.5
- Running the test suite no longer reaches the other people in your world. The case that plays a guest player asked for rain over the network as a real guest would, so every other editor or player in the world got rain, and the editor then showed a pending weather change on the scene's WorldClock after each run. The case now captures what a guest sends instead of sending it (`State._setSender`, tests only), and checks the request is the right one. After a run nothing is pending in the scene, in the editor that ran it or in anyone else's.
### What changed in 1.5.4
- Known limits list #18604 (no network-wide clock, so shared time is the owner's to one network latency) and #19397 (the published player page losing its render device in Chrome) again; both are still open. The how-to guide cites #18604 again. Nothing else in the package changed.
### What changed in 1.5.3
- Running the test suite no longer changes your world's time and weather. Before, the clock came back from a test run at its start hour with its saved weather and a new lightning seed, and the cases did not put back the timeline, the local clock, or the looks and weathers they defined when they failed. Now every case puts back exactly what it found, pass or fail, and a new case proves it. The scene's clock carries on where it was after a run.
- In the editor, a scene reloaded with the same clock and the same settings keeps the clock's hour, weather and sky (see By design).
- Three cases that quietly did nothing since the test runner began setting the scene aside (the manual strike, the precipitation warm-up, the sky fallback) now run on a clock of their own and check what they claim.
- A rain, wind or night bed whose voice had already gone (a play session ended under it) no longer logs an engine error when it is stopped.
- New call: `Director.host()`, the clock the director drives. Known limits now list the issues still open (#23698, #22513, #14448); the shared-time note moved to By design.
### What changed in 1.5.2
- The test suite passes right after install, before any clock is in the scene. The frame-rate case needed a running clock and failed with nothing to measure; it now checks the empty reading and steps aside on the frame numbers when no clock is ticking, and runs in full when one is. The Tests section says the suite needs nothing set up first. Nothing else changed.
### What changed in 1.5.1
- The install command in both guides and in the README is now `zero zeromind installAsset da911599-3bdf-4c1e-a4c3-ce13364692bf`, which works when copied as written. 1.5.0's guides said `zero zeromind install ...`, which the shell answers with "zeromind has no tool install". Nothing else changed.
### What changed in 1.5.0
- Fixes [OrigoZero/zero#23671](https://github.com/OrigoZero/zero/issues/23671): with `skyMode = "engine"`, a scene that rebuilt itself and replaced its sky left the clock writing the hour to the sky that was gone, logging an error every frame the clock moved, and the new sky never got the hour. The clock now checks the sky, sun and ambient light it drives before every write and moves to the scene's current ones, quietly. The kit's stand-in sun and ambient light are taken away once the scene has its own, so a scene never ends up with two suns.
- New calls: `Director.bindings()` and `Director.refresh()`. Every existing call works as before.
- Two guides ship with the package: how to add a day night cycle, weather, rain and fog to your game, and an example that takes a small scene through a full day.
- Known limits trimmed to the issues still open. No long dashes in any file.
### What changed in 1.4.7
- The catalog test compares the listed looks by name (1.4.6 compared catalog entries with names and failed).
### What changed in 1.4.6
- The catalog test checks the eight shipped looks are listed rather than that there are exactly eight, and the kit index and README state the package version (the kit index had stayed at 1.4.1).
### What changed in 1.4.5
- 1.4.4 republished from this world with every file version uploaded (installing 1.4.4 could fail with VERSION_NOT_FOUND), on @builtin 41af9ae.
### What changed in 1.4.4
- The sky test checks that the eight shipped looks are all there, rather than that the world holds no other look, so a world that adds its own look with `Sky.define` (as forestKit does) passes it.
### What changed in 1.4.1
- Two new WorldClock fields for worlds that keep their clock between sessions (`persist`): `persistWeather` off starts each session in the clock's own `weather` instead of the weather the last session ended in (a session that ended in a storm no longer opens in one), and `persistHour` off starts each session at `startHour` of the saved day, or the next day when the saved hour was later, so players arrive in the morning and time still only moves forward. Both default to on, as before.
### What changed in 1.4.0
- New calls for any moment on the clock, not only now: `Clock.seasonAt`, `Clock.sunTimesAt`, `Clock.phaseAtHours` and `Clock.isNightAt`, each taking game hours since day 1. A system that catches up over time a game skipped (crops growing through a jump of the clock, say) can ask which season and which nights the gap held. `Clock.season()` and `Clock.sunTimes()` are now these at `Clock.totalHours()` and answer exactly as before.
### What changed in 1.3.0
- Each known limit links the GitHub issue that tracks it in [OrigoZero/zero](https://github.com/OrigoZero/zero).
### What changed in 1.2.0
- Rain, wind, night and sandstorm beds play through the kit's own voices, rebuilt each play session. Before, a new session that followed a rainy one could go silent in a storm until clear weather had lasted about four seconds (Soundstage's ambience kept a voice from the session before).
- New call: `Audio.sounding()`.
- No long dashes left in the docs.
### What changed in 1.1.0
- Dawn holds its warm palette from just before sunrise to about an hour after (it used to blend into day by sunrise), and the dawn palettes are warmer through the whole sky, the sun and the fill light, not only at the horizon. Dusk, noon and night are unchanged.
- Thunder is heard in every play session (it played only in the first).
- Lamp parts use lit materials instead of tints, so lamp posts, arms and frames darken at night like the rest of the scene.
- New calls: `Audio.onThunder`, `Director.frameStats`, `Director.skyFallback`, `Probe.drawState`, `Probe.note`, `Probe.notes`. The sky falls back to the engine's sky until the kit's shader compiles; rain, snow, sand and the bolt warm up at load.
**1.6.5**: switching lights off really makes the scene dark. A sun or ambient light someone switched off (its `enabled` switch off, its entity deactivated, or its intensity set to 0 by anything but the clock) is no longer written by the clock, and the clock no longer stands a sun of its own in when the scene's sun is switched off or deactivated. Switching the light on again (enabled, active, or a nonzero intensity) hands it back to the clock.
**1.6.9**: a saved clock (`persist = true`) now really carries over between play sessions. Two things lost it: when Play started, the editor's clock was unloaded with `engine.mode` already reading "play", so its shutdown save wrote the editor's hour over the game's; and a play session's clock that woke with valid records in its synced fields (a clock a scene build spawns carries the editor's) never read the save at all. Now only a clock that ran in play saves, and a play session's first clock takes the saved moment whenever it is further on than the records it woke with (time only moves on; a reload mid-session wakes ahead of the last save, so it does not rewind). Checked in play: day 3 set, Stop, Play, still day 3, three times over.
**1.6.6**: every light switched off now really gives a dark scene. The sky itself is drawn separately from the sun and ambient Light components (it is background, not a light), so with those two off the sky still rendered full daylight behind them. The director now darkens the sky it pushes (zenith, horizon, ground, fog and sun colours, daylight and sun/moon visibility all to zero) whenever both the sun and the ambient light are switched off.
**1.6.7**: cheaper to run. The director evaluates and pushes the environment (lights, sky, fog, surface weather, ambience) 15 times a second instead of every frame, except while a lightning flash is lit, which still updates every frame. The sun's direction is written only once it has turned about 0.6 degrees, all three axes together: every small turn of the sun throws away the renderer's static shadow cache, so moving it a hair every few frames cost a whole shadow redraw each time.
# CastawayGallery
Every survivalCraftKit fire and shelter built for real out of buildPlaceKit pieces in a labelled row: campfire, torch post, signal fire, stone hearth and torch ring; lean-to, palm hut, tent, driftwood cabin and beach pavilion; palm bed, bedroll, hammock and raised cot, each with what it costs and how far it warms, lights or covers. Signs beside the row describe the four modes (castaway, cozy, hardcore, creative) and three island starts (cove, volcano, atoll). Put it on a synced entity in a gallery scene of its own: the host builds the pieces, every player sees them, and buildPlaceKit's saving is turned off for that session so gallery pieces never reach a player's saved camp. Uses `Castaway.buildAt`, the same builder the craft menu uses.
# CastawayGame
The survival rules for a whole island. Put one on a synced entity. On every peer it runs survivalCraftKit's setup for its `mode`, starts the objectives and shows dusk, dawn and danger toasts and the victory screen. On the host it turns every buildPlaceKit campfire, torch and roof into a survivalNeedsKit HeatSource or Shelter (so they warm, light and keep the rain off, also after a reload) and decides when a night has been survived (`isNight`, `nightsSurvived`, `won` are synced). `skipToDusk()` moves the clock for testing.
# CastawayPlayer
One castaway's hands, on the PlayerPrototype's body beside SecondWind's Vitals, survivalNeedsKit's SurvivalNeeds and deathDropKit's DeathDropWatcher. X (pad Y, Swing button) swings at the nearest night creature through SecondWind, or feeds a nearby fire with wood; C (Craft button) opens the castaway craft menu; a torch selected in the hotbar burns in the hand (synced `torchLit`) and nightCreaturesKit creatures keep away from it.
# GatherSpot (survivalCraftKit)
Kept so scenes made with survivalCraftKit 1.0.5 and earlier still load. Gathering now comes from gatherKit: on start this component puts a gatherKit GatherSpot with the same `resource` (and `propScale`) on its entity, which brings the regrowKit Regrowing, the tropicalProps prop and the interactKit prompt, and does nothing else. Put it on a synced entity, the same as before. New scenes should place `gatherKit.GatherSpot` directly, which `Island.build` does.
# ModePreview
Change ONE setting, the survival mode, and watch everything it carries change together. A panel on the right of the screen has a button per mode (castaway, cozy, hardcore, creative); each click is the single call a game makes, `Castaway.setup({ mode = "cozy" })`. That sets the needs HUD layout and theme (survivalNeedsKit), the death drop style, look and marker (deathDropKit) and the night's threat set (nightCreaturesKit) from the mode, and the stand in the world shows the result: the death drop as a player would leave it, with its marker, and the threat set's creatures in a row. Put it on any plain entity in a scene whose player has a SurvivalNeeds; it needs no sibling component. Local to each player; everything it spawns is temporary.
# castaway
survivalCraftKit's wiring. `setup` configures inventoryKit, survivalNeedsKit, deathDropKit, nightCreaturesKit, buildPlaceKit, craftingKit and controlsKit for a mode. `craft`, `placeBlueprint` and `gather` are the castaway actions (paying from the shared bag, placing buildPlaceKit pieces under a permit the build hook checks). `startObjectives` and `objectiveEvent` drive navUiKit's objective list; `saved` and `save` keep progress in saveKit. Called by the survivalCraftKit components and by game scripts.
# island
A whole playable survival island from one call in a scene's `build.luau`: `Island.build({ start = "cove", mode = "castaway" })`. It places the tropicalKit island for the start (cove, volcano or atoll), the worldClockKit clock and weather, SecondWind's health rules and HUD, the player (body with Vitals, SurvivalNeeds, DeathDropWatcher and CastawayPlayer, an orbit camera, a spawn on the first dry sand inland of the pier), the CastawayGame for the mode, the nightCreaturesKit NightDirector on a spawnerKit spawner, gather spots on dry ground and a fresh water spring. Every option has a default, so `Island.build()` alone is a whole game. Called from a scene's `content()`; returns `{ spawn, island }`.
# presets
survivalCraftKit's data: four modes (each naming the rules every installed kit should run), three island starts, five fires, five shelters and four beds (as buildPlaceKit piece blueprints with survivalNeedsKit heat and shelter settings), materials and tools as inventoryKit items, resources to gather, recipes and the first-night objectives. `castaway.setup` and the survivalCraftKit components read it; add an entry to add a mode, fire, shelter, resource or recipe.
# survivalCraftKit tests
This suite has 18 tests. It checks that every mode in survivalCraftKit names presets the needs, drops and creatures kits know (rules, climate, HUD layout and theme, drop rule, style, look and marker, threat set and density) and known start items, that every start, fire, shelter, bed, item, resource, recipe and objective is complete, that costs and recipes only use known items, that every blueprint piece is one buildPlaceKit knows, that RECIPE_ORDER covers RECIPES and every blueprint has a recipe, that setup takes every mode and start by name, sets the other kits to match and refuses an unknown name, that island() copies and overlays a start, the cost and missing math in every mode, craft refusals with the refused event, blueprint tags, and that the version agrees with package.yaml and the README. It restores every setup it changes. It leaves gathering into a real bag, building pieces and the objectives HUD to play testing. Run it with `asset.resolve("survivalCraftKit", "testSuite"):run()`.
# setUpYourOwnSurvivalIsland
Make a survival game where you survive the night on an island: an island survival crafting game built with survivalCraftKit, set up with your own choices from start to a tested first night.
## What it does
1. **Choose.** Asks the creator every choice that shapes the game, with the kit's real values: the scene, the island start (cove, volcano, atoll), the survival mode (castaway, cozy, hardcore, creative), survivalNeedsKit's needs rules and climate, the needs HUD layout and theme, deathDropKit's drop style, look, rule and marker, nightCreaturesKit's threat set, density and whether creatures come at all, the tropicalKit island look, the styleKit art look (saturdayMorning by default, as in the Castaway Isle showcase), and optionally day length and start hour. Picking a mode fills in the rest; any choice can then be changed.
2. **Scene.** Makes the scene (or reads an existing one) and writes its `build.luau` as one call: `Island.build({ start, mode, look, hudTheme, hudLayout, dayLengthMinutes, startHour })` from `survivalCraftKit.island`, then checks the island, clock, CastawayGame, NightDirector, player, spawn, gather spots and spring are there.
3. **Rules.** When the choices are not exactly a preset mode, registers a custom mode in `Castaway.MODES` from the scene's `entrypoint.luau` (needs, climate, drops, drop style and look, threat, density, creatures), so CastawayGame sets up survivalNeedsKit, deathDropKit and nightCreaturesKit with them on every peer. A drop marker other than `both` is set with `Drops.setup({ marker })` on `Castaway.on("setup")`.
4. **Look.** Applies the art look with `StyleKit.applyLook(look)` on the scene's synced StyleStack and checks the HUD still reads.
5. **Play.** Presses Play and proves the first night: gather wood, stones and fiber, craft a stone axe and a torch, build a campfire and a shelter, drink at the spring, speed the clock to dusk, see the creatures keep away from the fire, die and recover the drop, and reach dawn and the "You survived the night" screen. Also checks the touch controls on a phone-sized screen.
6. **Report.** Answers with the scene, the build call, the mode, every choice, the checks, fixes and remaining problems, the controls, and where to change each choice later.
## What it needs
survivalCraftKit and the kits it uses (survivalNeedsKit, deathDropKit, nightCreaturesKit, inventoryKit, buildPlaceKit, SecondWind, worldClockKit, tropicalKit and the rest), and styleKit with toonBlocks for the toon art looks: install survivalCraftKit into the world first (one step; about eight minutes the first time, since it fetches about forty packages), or run this in a fork of the Castaway Isle world, which already holds them all. The first build cooks the island ground, which takes about half a minute.
## Controls the game gets
Keyboard: WASD, mouse, Space jump, E interact and pick up, X swing, C craft, Tab bag, 1 to 8 hotbar. Gamepad: stick, A jump, X interact, Y swing, Select craft. Touch: floating stick with Jump, Swing, Craft and Sprint buttons.
## Starting it
zero workflow start --name setUpYourOwnSurvivalIsland
zero workflow start --name setUpYourOwnSurvivalIsland --args '{"scene":"myIsland","choices":{"start":"volcano","mode":"hardcore","artLook":"saturdayMorning"}}'
`scene` names the scene (default: asks, proposing `myIsland`); `choices` holds any choice already decided, which is then not asked.
# gatherKit
**Gather spots for any survival or crafting game: walk up, press the prompt, get items in your bag; spots run out and grow back.** For creators asking "how do I add resource gathering to my game", "how do I let players punch trees for wood", "how do I make gather nodes" or "how do I let players pick berries in a survival game". Fifteen resources (palms, rocks, berry bushes, driftwood, grass, fishing pools, bananas, mushrooms, clam beds, reeds, flint, fallen coconuts, seaweed, ore veins and ferns), each with what one pick gives, a tool that doubles it, how many picks it holds and how fast it grows back. Works in multiplayer: every pick is decided by the spot's owner, so two players never get the same one.
Version 1.0.4. New in 1.0.4: released from the Castaway Isle main line together with the other survival kits, on the current engine library; no behaviour change. New in 1.0.3: the gallery rebuilds when a resource changes, so a game's mode giving every spot one regrow pace shows at once.
## Quick start
In `build.luau` (or any script that builds your scene), on synced entities:
```luau
local spot = asset.resolve("gatherKit.GatherSpot", "component")
local palm = entity.spawnSynced("Palm1", { position = { 12, 0, 40 } })
palm.component.add(spot, { resource = "palm" })
local bush = entity.spawnSynced("Bush1", { position = { 16, 0, 38 } })
bush.component.add(spot, { resource = "bush" })
-- anywhere, to react to what players gather
local Gather = require("~gatherKit.gather")
Gather.on("gathered", function(item, n, resourceId) print("got", n, item, "from", resourceId) end)
```
Walk up to the palm, press E (pad X, or tap): wood and palm leaves land in your bag and a toast says what you got. After five punches the palm shrinks back and its prompt reads "Grows back soon"; five minutes later it grows back.
## Resources and options
| Resource | Label | One pick gives | Tool (doubles) | Picks | Regrow | Prop |
|---|---|---|---|---|---|---|
| `palm` | Palm tree | 1-2 wood, 0-1 palmLeaf, 1 coconut (35%) | stoneAxe | 5 | slow | palmCoconutStraight |
| `rock` | Loose stones | 1-2 stone | stonePick | 6 | normal | rockBeach |
| `bush` | Berry bush | 1-3 berries, 0-1 fiber | none | 4 | normal | hibiscusBush |
| `driftwood` | Driftwood | 1-3 wood | stoneAxe | 2 | slow | driftwoodLog |
| `grass` | Tall grass | 1-2 fiber | none | 5 | quick | beachGrass |
| `fishing` | Fishing pool | 1 rawFish, 1 crabMeat (30%) | spear | 3 | hourly | a shallow pool |
| `banana` | Banana plant | 1-2 banana, 0-1 palmLeaf | none | 3 | slow | palmYoung |
| `mushroom` | Mushroom patch | 1-2 mushroom, 1 fiber (25%) | none | 3 | normal | tropicalUndergrowth |
| `clamBed` | Clam bed | 1 crabMeat, 0-1 seaweed, 1-2 shell (50%) | spear | 3 | hourly | shellScatter |
| `reeds` | Reeds | 1-2 reed, 1 fiber | stoneAxe | 4 | quick | seaOats |
| `flint` | Flint scatter | 1 flint, 0-1 stone | stonePick | 3 | slow | pebbleScatter |
| `coconutPile` | Fallen coconuts | 1-2 coconut | none | 2 | slow | coconutPile |
| `seaweed` | Seaweed | 1-2 seaweed, 1 fiber (40%) | none | 4 | quick | seaweedLine |
| `oreVein` | Ore vein | 1-2 stone, 1 ore (60%) | stonePick | 4 | daily | rockBasalt |
| `fern` | Fern | 1-2 fiber, 0-1 palmLeaf | none | 3 | quick | fernTropical |
Regrow presets come from regrowKit: `quick` 30 s, `normal` 90 s, `slow` 5 min, `hourly` 1 in-game hour (150 s without worldClockKit), `daily` 1 in-game day (600 s without it), `never`. A resource may give a number of seconds instead.
GatherSpot fields: `resource` (default `palm`), `propScale` (default 1), `prompt` (default true; off leaves the prompt to you). To change how a spot runs out, put your own regrowKit `Regrowing` on the entity before GatherSpot (its `maxCharges`, `regrow`, `spentLook` hide, shrink, fade or none); GatherSpot keeps one that is already there.
Items: gatherKit defines the materials and tools it gives (stone, fiber, palmLeaf, wood, flint, ore, reed, shell, mushroom, stoneAxe, stonePick) in inventoryKit only when no other kit has. Foods (coconut, berries, banana, rawFish, crabMeat, seaweed) are survivalNeedsKit's, so they are edible when it is installed; without it gatherKit adds plain versions.
## API
### gather module
`local Gather = require("~gatherKit.gather")`
| Call | What it does |
|---|---|
| `Gather.VERSION` | `"1.0.0"` |
| `Gather.RESOURCES` | `{ [id] = { label, verb, gives = { { item, min, max, chance? } }, tool?, charges, regrow, prop, category } }` |
| `Gather.RESOURCE_ORDER` | Resource ids in display order. |
| `Gather.define(id, def)` | Add or replace a resource; gives may be `{ item = , min = , max = , chance = }` or `{ item, min, max, chance }`. Errors naming what is wrong. Returns the stored resource. |
| `Gather.roll(id, withTool, rng?)` | One pick, rolled without touching any bag: `{ { id, count } }`. `rng` returns 0..1 (default `math.random`); a chance passes when `rng() < chance`; the tool doubles every count. |
| `Gather.give(id, withTool)` | Roll a pick into the local player's inventoryKit bag (leftovers drop at their feet). Emits `gathered` per item; returns what was given. Does nothing outside play or without inventoryKit. |
| `Gather.hasTool(id)` | Whether the local player carries the resource's tool. |
| `Gather.items()` | Every item id the resources give or use as a tool, sorted; defines the ones inventoryKit lacks. |
| `Gather.describe(got)` | `"+2 Wood +1 Palm Leaf"` for a list from `give` or `roll`. |
| `Gather.on(event, fn)` | Listen; returns unsubscribe. `gathered(item, n, resourceId)`, `picked(resourceId, entityId)`, `empty(resourceId, entityId)`. |
| `Gather.ITEMS`, `Gather.FOOD_FALLBACK` | The item definitions gatherKit adds when missing. |
### Components
| Component | What it does |
|---|---|
| `gatherKit.GatherSpot` | On a synced entity: draws the resource's tropicalProps prop as a child `gatherProp`, adds a regrowKit Regrowing (resource charges and regrow) if there is none, and an interactKit prompt reading the verb, or "Grows back soon" when spent. Using it takes a charge through `regrowKit.take`, then gives the pick, toasts it (navUiKit) and plays juiceKit `dust`. |
| `gatherKit.GatherGallery` | Every resource as a working spot in one labelled row (gives, tool, picks, regrow). Local and temporary; safe in any scene. |
## Multiplayer
Put GatherSpot on synced entities. The prop and prompt are drawn on every peer; the Regrowing charges are synced and written only by the entity's owner. A player pressing the prompt asks the owner through `regrowKit.take`; the owner spends one charge and answers that player alone, and only then does that player's own engine roll the pick into their own bag. Two players pressing at once get one charge each while charges last, never the same one. The spent look and the "Grows back soon" prompt follow the synced charges, so everyone sees the same bush.
## Tests
`asset.resolve("gatherKit", "testSuite"):run()` runs 17 tests: every resource complete with valid items, tools and props; roll with fixed random sources (min, max, chance, tool doubling); define; events; give outside play doing nothing safely; items defining its materials; GatherSpot adding a Regrowing with the resource's charges, its prop and prompt; GatherGallery; and the README and version against the code.
## Guides
- *How do I add resource gathering to my survival game* (`gatherKit.package/how-do-i-add-resource-gathering-to-my-survival-game.guide`): the ideas, the resources, tools, regrowing, multiplayer and your own resources.
- *Example: punch palms and pick berries on an island* (`gatherKit.package/example-punch-palms-and-pick-berries-on-an-island.guide`): a worked example from an empty island to a gathering loop with a stone axe.
## What it installs
Installing gatherKit brings these packages, each from its own world, at the versions it was built and tested with:
| Package | Version |
|---|---|
| inventoryKit | 1.0.26 |
| interactKit | 1.6.3 |
| regrowKit | 1.0.2 |
# deathDropKit
**When a player dies, their things stay where they fell, and they can run back and get them.** For creators asking "how do I make players drop their items when they die", "how do I add a gravestone or loot bag on death" or "how do I let players recover their stuff after dying". Seven drop styles, three looks each, five rules for what drops, and seven markers that lead the way back. Works in multiplayer: every player sees every drop, and only the right player (or anyone, under hardcore) can take it. A drop stays until its owner picks it up, even when they leave play, rejoin or the world restarts, and every death leaves its own drop.
Version 1.0.9. New in 1.0.9: released from the Castaway Isle main line together with the other survival kits, on the current engine library; no behaviour change. New in 1.0.8: a dropped bag stays where you fell and stays yours through a reconnect, a leave and rejoin and a restart (drops carry your stable `ownerId`, a bag still in the world under your old peer id is claimed back, and a saved bag that went away is put back). Built on **SecondWind** (who died), **inventoryKit** (what they carried), **interactKit** (the "E Recover" prompt on keyboard, gamepad and touch) and **navUiKit** (the waypoint and toasts), and keeps drops in **saveKit** (each player's own save).
## Quick start
In `build.luau`, on the player's body (next to SecondWind's Vitals), and in `entrypoint.luau`:
```luau
body.component.add(asset.resolve("deathDropKit.DeathDropWatcher", "component"), {})
-- entrypoint.luau
local Drops = require("~deathDropKit.drops")
function onLoad()
Drops.setup({ style = "lootBag", look = "burlap", rule = "dropAll", marker = "waypoint" })
end
```
Die with something in your bag: a burlap sack sits where you fell, a waypoint points to it, and walking up and pressing E puts everything back. Leave and come back later: the sack is still there.
## Styles and choices
| Setting | Values |
|---|---|
| `style` | `gravestone`, `lootBag`, `backpack`, `spiritOrb`, `scattered`, `crate`, `skeleton` |
| `look` | gravestone: `weathered`, `mossy`, `marble`; lootBag: `burlap`, `leather`, `royal`; backpack: `canvas`, `leather`, `scifi`; spiritOrb: `azure`, `verdant`, `ember`; scattered: `natural`, `sparkling`, `wet`; crate: `driftwood`, `shipwreck`, `cargo`; skeleton: `bleached`, `charred`, `crystal` |
| `rule` | `keepAll`, `dropAll`, `keepHotbar`, `dropHalf`, `hardcore` |
| `marker` | `waypoint`, `beam`, `flare`, `ring`, `icon`, `both`, `none` |
| `expire` | seconds until a drop crumbles away; 0 keeps it |
| `persist` | `true` (default): drops are kept in the owner's saveKit save and come back after play exit, rejoin and restart; `false`: a drop lasts only while its owner is in the world |
| Rule | What happens |
|---|---|
| `keepAll` | Nothing drops; dying only costs the walk back. |
| `dropAll` | Everything drops; only you can pick it back up. |
| `keepHotbar` | What is in your hands stays; the bag drops. |
| `dropHalf` | Half of every stack drops (rounded up); the rest stays with you. |
| `hardcore` | Everything drops and anyone can loot it. |
| Marker | What it shows |
|---|---|
| `waypoint` | A navUiKit waypoint on the compass and screen edge, only for the player who fell. |
| `beam` | A tall pale beam of light over the drop that everyone sees from across the island. |
| `flare` | A pulsing red flare column with embers rising out of it and a warm light on the ground. |
| `ring` | A slowly turning ring of glowing stones on the ground around the drop. |
| `icon` | A skull and the fallen player's name floating and bobbing over the drop. |
| `both` | The waypoint for the owner and the beam for everyone. |
| `none` | No marker: remember where you fell. |
### How taking it back works
The drop is a synced entity owned by the player who died. Pressing E sends a claim to that owner; the owner grants it once, marks it claimed and removes it, and the taker's own engine puts the items in their bag. Two players pressing at the same moment cannot both get the items. The dying player's own engine is the only one that ever takes items out of their bag.
## API
### drops module
`local Drops = require("~deathDropKit.drops")`
- `setup(opts)`: choose `style`, `look`, `rule`, `marker`, `expire` (seconds, 0 = never) and `persist` (default true); call on every peer.
- `config()`: a copy of the current settings.
- `catalogue()`: every style, look, rule and marker, for menus and agents.
- `lookOf(style, look?)`: the look a style uses (its first look when none is chosen).
- `on(event, fn)`: listen to `dropped(drop)`, `recovered(drop, items)`, `looted(drop, items, byPeer)`, `expired(drop)`, `setup(cfg)`; returns a function that stops listening.
- `takeForDeath(rule?)`: take what the local player loses under a rule out of their bag, as `{ { id, count } }`.
- `giveBack(items)`: give items to the local player (what recovering a drop does).
- `encode(items)`, `decode(s)`: turn item lists into the `id:count;id:count` text a drop holds, and back.
- `build(parent, style, look?)`: draw a style's parts under any entity (a preview, a menu).
- `list()`: every drop on this machine, `{ { id, owner, ownerName, style, items, x, y, z } }`.
- `mine()`: the local player's own drops.
- `saved()`: the local player's saved drops still waiting to be picked up, as records `{ id, style, look, marker, items, x, y, z, expireAt, anyone, ownerName }`.
- `restore(spawn?)`: put back every saved drop not already in the world (DeathDropWatcher does this on join); returns the keys it spawned.
- `record(r)`, `decodeRecords(list)`, `addRecord(list, rec)`, `removeRecord(list, id)`: check, read and edit save records.
- `isPresent(key)`, `spawnDrop(rec)`, `newKey()`: find, spawn and name drops by their stable key.
- `dropInReach()`: whether the local player is within reach of a drop they may take (what wins the prompt).
- `VERSION`, `EVENTS`, `DEFAULT_LOOK`, `SAVE_KEY`, `PROMPT_RANGE`: the version, the event names, each style's default look, the save key and the prompt reach.
### Components
**DeathDropWatcher**: on the player body; makes the drop when the player dies, and puts back the player's saved drops when they join.
- `style`, `look`, `rule` (""): override the world's settings for this player; empty follows `Drops.setup`.
- Method: `dropNow()`: leave a drop here now with the local player's things; returns the drop entity or nil.
**DeathDrop**: the drop itself, a synced entity.
- `style` ("lootBag"), `look` (""): what it looks like.
- `items` (""): what it holds, as `id:count;id:count`.
- `ownerPeer`, `ownerName`: who fell here.
- `anyone` (false): whether other players may take it (the hardcore rule).
- `expireAt` (0): `os.time()` when it crumbles away; 0 never.
- `claimed` (false): taken; it is about to disappear.
- `marker` (""): `waypoint`, `beam`, `flare`, `ring`, `icon`, `both` or `none`.
- `dropKey` (""): the drop's stable key in its owner's save.
- `beam` (false): older drops; draws the light beam like marker `beam`.
- Methods: `describe()`: `{ id, owner, ownerName, style, items, x, y, z, claimed, key }`; `takeableBy(peer)`: whether that player may take it now.
**DropGallery**: every style in every look side by side.
- `spacing` (3), `rowGap` (3.4), `labels` (true), `floor` (true).
## The prompt always goes to your drop
Standing within reach of a drop you may take (2.6 m), the "E Recover" prompt and E go to the drop, never to a rock, tree or chest beside it. interactKit has no priority setting (its prompt picks the thing you look at, then the nearest), so deathDropKit tells interactKit that the other usable things are unavailable to you while a drop is in reach. Step away from the drop and everything else works as before.
## Drops survive leaving and restarts
When you die, your own engine writes the drop into your saveKit save under `deathDropKit.drops`: `{ id, style, look, marker, items, x, y, z, expireAt, anyone, ownerName }`, one record per drop, so dying three times leaves three drops, each recoverable. The record is removed when the drop is taken or crumbles away. When you join again (or the world restarts), your engine waits for your save to load, waits a moment longer for drops still in the world to arrive, and puts back every saved drop that is not already there, matched by its `dropKey`, so a drop never appears twice. Everyone sees it again. Expired drops are forgotten instead of coming back.
## What it installs
Installing deathDropKit brings these packages, each from its own world, at the versions it was built and tested with:
| Package | Version |
|---|---|
| SecondWind | 1.4.7 |
| inventoryKit | 1.0.26 |
| interactKit | 1.6.3 |
| navUiKit | 1.3.7 |
## Gallery
Put a **DropGallery** on any entity to see all seven styles in all three looks side by side, labelled, with the rules and markers on a sign.
## Guides
- **How do I make players drop their items when they die** (`deathDropKit.package/how-do-i-make-players-drop-their-items-when-they-die.guide`)
- **Example: survival island, die, run back and get your bag** (`deathDropKit.package/example-survival-island-die-run-back-and-get-your-bag.guide`)
## Tests
24 tests in `deathDropKit.testSuite`. Run them with `asset.resolve("deathDropKit", "testSuite"):run()`.
## Known limits
- A drop belongs to the engine of the player who died; if that player leaves, their drop leaves the world with them and comes back when they return (with `persist` on). Under hardcore, other players can only loot it while its owner is in the world.
- Drops are saved through saveKit; without saveKit installed, or for a guest with no account, drops last only for the session.
- `keepHotbar` keeps exactly the amounts that were on the hotbar; inventoryKit takes items by id, so a kept stack can come back in a bag slot rather than its old hotbar slot.
- Styles are built from simple shapes so they draw on every engine with no assets to load.
# heatSignatures
heatSignatures was called heatKit until 1.0.6; code that required `~heatKit.Heat` now requires `~heatSignatures.Heat`.
Things in your world have their own heat, for a thermal camera to draw and for gameplay to read: people and animals warm, engines and fires hot, metal and water cold, with good defaults found from entity names so a scene reads right without tagging everything.
Install heatSignatures for a heat signature on everything: a thermal vision or thermal scope look (with sensorBlocks), a guard who spots you by your body heat in a stealth game, a heat-seeking missile, a cold zone that freezes the player, or a warm hand print on a door that gives away where someone went in a horror game. Every temperature is in degrees Celsius, the same on every player's machine.
## Five minutes to a sensor look on your own scene
1. **Install.** Search ZeroMind for `heatSignatures` (or "heat signature for thermal camera") and install the package. For the picture, install `sensorBlocks` too (search "thermal vision night vision sensor look"); for goggles a player wears, `sensorGoggles`. styleKit comes with them.
2. **Look at the defaults.** Most scenes already read: anything named `Guard`, `Soldier`, `Person`, `Fox`, `Dog`, `Campfire`, `Torch`, `Generator`, `Engine`, `Car`, `Lamp`, `Server`, `Crate`, `Barrel`, `Stream`, `Ice` and many more gets its class, and every player's body is a warm person.
```luau
local Heat = require("~heatSignatures.Heat")
for _, s in Heat.sources() do print(s.class, s.origin, s.temp) end
```
3. **Pick the weather.**
```luau
Heat.setClimate("desertDay") -- or temperateNight, arctic, factory, horrorLair
```
4. **Give heat where the names miss.**
```luau
entity.find("Reactor").component.add("heatSignatures.HeatSource", { class = "engine", working = true })
Heat.addRule("robot", "electronics") -- every Robot1, Robot2... from now on
```
5. **See it.**
```luau
local Sensors = require("~sensorBlocks.Sensors")
Sensors.use("militaryThermal")
```
6. **Use it in play.**
```luau
if Heat.at(player.position) < 0 then print("freezing") end
print(Heat.of(entity.find("Guard1"))) -- about 33 C, warmer while running
Heat.touch(handPoint) -- a warm print that fades over 30 s
```
## What is inside
| Asset | What it is |
|---|---|
| `Heat` module | The temperature model: `Heat.at`, `Heat.of`, `Heat.give` / `Heat.take`, `Heat.touch`, `Heat.setClimate` / `Heat.climate` / `Heat.climates`, `Heat.addRule`, `Heat.classForName`, `Heat.setAuto`, `Heat.sources`, `Heat.prints`, `Heat.CLASSES`, `Heat.DEFAULT_RULES`. |
| `HeatSource` component | Synced: gives one object its own class, temperature, running temperature, `working` switch and warm-up time. |
| `HeatClimate` component | Synced: the scene's climate and overrides (made for you by `Heat.setClimate`). |
| `HeatField` module + `heatField` render feature | Per machine: packs the climate and the 64 nearest heat shapes into a data texture each frame and publishes it to styleKit as the `heat` input. |
| `heatField` shader module | `hk_temp(uv)`: the temperature of what each pixel shows, in degrees C, for style blocks. |
| `heatClimate` asset type | A climate as a `climate.yaml` (air, ground, sky, water, sun, palette range). |
| `climates/` | `temperateNight`, `desertDay`, `arctic`, `factory`, `horrorLair`. |
| `guides/how-to-give-things-heat.guide` | How to give things heat for a thermal camera or gameplay. |
### The classes
person 33 C (35.5 running), animal 36 C, engine ambient off and 90 C running, vehicle 20 C warming to 60 C as it drives, fire 420 C with radiant warmth around it, lamp 70 C, electronics 32 to 45 C, metal and stone just under the air (metal has low emissivity, so it mirrors the cold sky and reads cold), water at the climate's water temperature, ice -6 C, plant near the air, and plain warm and cold. Moving or working things warm up over their `warmUp` seconds and cool at half that speed.
### How surfaces read
Ground and walls take the climate's ground or air by their facing, warmed where the sun reaches them (dark colours more) and cooled under an open night sky. Green surfaces read as leaves, near the air. Pixels that glow (flames, bulbs, day-glo paint) read hot.
## Stacking with Style Cookbook blocks
heatSignatures draws nothing by itself; sensorBlocks' thermal blocks read it. They sit in styleKit's Colour slot, so a Cookbook ink line, film grain, paper or vignette already in the scene stays in the stack under or over the sensor look, and `Sensors.off()` gives the scene's own look back. Your own blocks can read the heat too: add `"input:heat"` and `"input:heatObj"` to `reads`, declare `in_heat` and `in_heatObj` textures, and include `~heatSignatures.shaders.heatField`.
## Multiplayer
- **Shared by everyone**: the climate (a synced HeatClimate entity), HeatSource components and their `working` switch, warm prints from `Heat.touch` (sent to every player), and the heat found from names and players' bodies (every machine walks the same scene and finds the same).
- **Per machine**: the data texture and the picture, and `Heat.give` (call it on every machine, or use a HeatSource, when every player should agree).
## Readability
Under thermal, players, enemies and pickups are told apart by sensorBlocks' role cues (outline and slow friend-or-foe blink for you and allies, outline and hatching for enemies, shimmer for pickups, dashed outline for hazards), not by temperature alone, so a guard standing by a fire still reads as a guard.
## What it costs
The heat field packs at most 64 shapes into a 65x5 data texture every other frame, on the machine showing a thermal look and only while a block asks for heat. Still things (metal, stone, water) update a slice at a time, about once a second each. Moving and working things update on alternate frames. The nearest 64 in view are picked four times a second, and the scene is scanned for names every ten seconds, a few hundred entities a frame. In the forest showcase with 2,500 extra objects (312 crates and 50 guards picked up by name), a typical frame spends about 0.19 ms of script time on heat. The sensorBlocks README has the measured engine CPU and GPU per look, on desktop and in the browser.
## Known limits
- **Engine bug, custom surface shaders (current engine, @builtin 024ebe5):** a custom surface shader compiled fresh fails with `#include of unknown shader module "zero::projection"` (reported to the platform: 01M7AV5R97GJHWXB4019TT3E65). The heat buffer (`heatObj`) is one. Where the engine already holds its compiled program it draws exact per-object heat; where it fails, thermal falls back to the soft heat shapes, so people, animals and fires still read warm with softer outlines.
- Heat shapes are boxes or ellipsoids fitted to each thing's bounds when first seen; a thing that changes size keeps its first fit.
- At most the 64 heat shapes nearest the camera are drawn (gameplay calls see all of them).
- The data texture falls back to rgba16f where the preferred float format is missing.
- Transparent things (glass, water surfaces) are not in the depth and show the heat of what is behind them; give water a name heatSignatures knows or a HeatSource.
- Offscreen captures, mirrors and render-to-texture cameras do not show the style stack, so they show no heat.
- Players who join late miss warm prints left before they joined.
- Infrared reflectance and foliage are guessed from base colour, not from real material data.
## Version history
- **1.0.9**: `Heat.give` on an entity now takes over from the name rule's record for it, the way a HeatSource component already did. Before, an entity whose name matched a rule (a built "...campfire", a "flame" part) kept its rule's 420 C record beside the script's, so a script could never say that fire had gone out.
- **1.0.8**: built against the current engine library (@builtin 024ebe5); Known limits names the engine bug that can keep the heat buffer's surface shader from compiling, and what thermal falls back to.
- **1.0.7**: the heat pass regroups its objects at most about three times a second when sources change, and once a second otherwise; version history without dates.
- **1.0.6**: renamed from heatKit to heatSignatures (every `~heatKit.` path is now `~heatSignatures.`; components are `heatSignatures.HeatSource` and `heatSignatures.HeatClimate`); with a block reading heat the heat bookkeeping runs five times a second on its own clock, since the GPU heat buffer draws every source's mesh where it stands.
- **1.0.5**: heat drawn on the GPU (heatSignatures's HeatPass: one geometry pass into a heat buffer, each object's heat in a shader-data lane; thermal blocks read `input:heatObj`); scripts keep only soft shapes for prints, radiant warmth and mesh-less sources; heat tick every fourth frame on heatSignatures's own clock; scans, new sources and clean-up spread over frames; climate cached; heatSignatures's render feature restarts itself if the engine stops it; styleKit 1.8.1; SensorBench checks that heat was live in every thermal window.
- **1.0.4**: lighter per-frame work: name scans use the engine's own name search and remember each name stem; moving heat sources and contacts are read from the engine every fourth frame and dead-reckoned in between; the heat tick keeps separate moving and still lists and runs once a second when no look needs heat; 40 heat shapes and 16 contacts drawn (smaller data textures); the climate component no longer runs every frame; SensorBench measures in alternating look-on and look-off windows and reports the median; What it costs updated with desktop and browser numbers.
- **1.0.2**: fixes the gen-3 night vision look, whose look file was damaged in 1.0.1 so styleKit could not read it; heat and contact data are uploaded every other frame; x-ray thickness passes draw at half resolution (the airport scanner went from 4.5 to 0.24 ms of GPU with 2,500 objects); the name scans run every ten seconds; each runtime keeps asking for styleKit until it answers; SensorBench (measure a look's engine CPU and GPU cost on this device); What it costs measured as the engine's own per-system CPU and per-pass GPU time.
- **1.0.1**: a shared clock every machine agrees on for heat prints and pings (ages never step back); per-frame work trimmed (reused arrays, static heat sources updated a slice at a time, only heat shapes in view and worth drawing are packed, lighter night vision shader); `Heat.of` reads player bodies; `Sensors.use(look, { shared = true })` makes the scene's style stack when there is none; What it costs section.
- **1.0.0**: first release. Heat model with fourteen classes and name rules, players as warm people, warming and cooling with work and motion, shared warm prints, five climates, HeatSource and HeatClimate components, the heat input for styleKit and the `hk_temp` shader module.
# nightCreaturesKit
**Things come out of the jungle when the sun goes down. They are scared of your fire, and they leave at dawn.** For creators asking "how do I add monsters that come out at night", "make a survival game where you survive the night" or "enemies that fear fire". Eight creatures, two looks each, four threat sets and three densities, each switched with one setting. Multiplayer: the host decides, every player sees the same creatures.
Version 1.0.13 (built against aiKit 1.3.16 and navKit 1.5.0, so it installs beside them as one release of each). New in 1.0.13: released from the Castaway Isle main line together with the other survival kits, against aiKit 1.3.16; no behaviour change. New in 1.0.12: the night is dangerous off the paths too. A navKit map stops short of beaches, piers and camps, so a creature hunting a player standing there used to wait at the map's edge; now, within 14 m of a player in the dark, it drops its path and runs straight at them (the new `rushed(id)` event), and takes the path again once the player is 30 m away. Firelight and a held torch still turn it away at the edge of the light. Built on **spawnerKit** (each creature is a spawnerKit enemy: spawn effects, pooling, contact damage), **SecondWind** (their health, your damage) and **worldClockKit** (dusk and dawn from the shared clock). Reads firelight from **survivalNeedsKit** HeatSources when it is installed. When **aiKit** is installed, each creature gets an aiKit brain (the `swarm` preset for crabs, bats and wisps, `chaser` for the rest) that hunts players along **navKit** paths, round rocks, trees and buildings: the NightDirector bakes a navKit waypoint map of the island on every peer when play starts (`navMap`, `navSize`, `navSpacing`, `navCell`; about 5 to 12 seconds for the whole island), since a brain with no map never moves. Creatures prowl a clear 2.5 m outside the light. Near firelight the director switches the brain off and walks the creature round the edge of the light on navKit paths, circling for as long as a player stands inside it, and at dawn it walks every creature away into the dark the same way before spawnerKit removes it.
**The dawn rule:** at dawn no new group spawns, every creature walks or flies away from the nearest player into the dark, and any creature still in play `leaveSeconds` (12) after it was sent away is removed by the host through spawnerKit. Nothing stays on the beach in daylight.
## Quick start
In `build.luau`, inside `content()`, and in `entrypoint.luau`:
```luau
local SK = require("spawnerKit.api")
local night = entity.spawnSynced("NightDirector")
SK.addSpawner(night, { pattern = "ring", effect = "auto", autoStart = false })
night.component.add(asset.resolve("nightCreaturesKit.NightDirector", "component"), {})
-- entrypoint.luau
local Creatures = require("~nightCreaturesKit.creatures")
function onLoad()
Creatures.setup({ threat = "island", density = "normal" })
end
```
You need a WorldClock in the scene (worldClockKit) so there is a dusk and a dawn.
## Styles and choices
| Setting | Values |
|---|---|
| `threat` | `island` (crabs, bats, drowned sailors, a jungle cat, wisps), `forest` (wolves, bats, spiders, a panther), `haunted` (stalkers, wisps, a drowned captain, vampire bats, ghost crabs), `arctic` (dire wolves, a smoke stalker, bats) |
| `density` | `calm`, `normal`, `swarming` |
| `enabled` | false keeps nights empty (creative) |
| Creature | Looks | Health | Speed | Group | Fear of fire |
|---|---|---|---|---|---|
| Crab swarm | sand, ghost | 18 | 3.4 | 6 | strong |
| Wolf pack | timber, dire | 45 | 4.6 | 3 | prowls the edge |
| Shadow stalker | void, smoke | 70 | 3.0 | 1 | never enters light |
| Bats | fruit, vampire | 10 | 5.5 (flying) | 5 | strong |
| Drowned sailor | deckhand, captain | 60 | 2.2 | 2 | dares the edge |
| Jungle cat | jaguar, panther | 55 | 5.2 | 1 | prowls the edge |
| Giant spider | huntsman, widow | 50 | 3.8 | 2 | strong |
| Will-o'-the-wisp | marsh, spectral | 20 | 2.6 (ranged) | 2 | none; burns out at dawn |
### How the night runs
1. When the clock's darkness passes `duskAt` (0.55) the host's NightDirector starts night number N: every peer hears `dusk`.
2. Every `interval` seconds it releases a group from the threat set: it moves its Spawner to a dry, dark spot about 30 m from a random player (never inside firelight) and spawns the group there with spawnerKit's ring pattern.
3. Four times a second it steers every creature: one that strays into firelight turns to wander just past the light's edge, so they circle your camp; out in the dark they chase the nearest player (with aiKit, their brain hunts along navKit paths).
4. When darkness falls below `dawnAt` (0.3) no new group is released and every creature walks away into the dark (with aiKit, its brain and navKit agent come off first, so nothing holds it in place); any still in play `leaveSeconds` (12) after it left is sent back to spawnerKit's pool. Every peer hears `dawn`; the host fires `retreat` once and `fled(id)` per creature.
Light comes from `Creatures.lightAt`: survivalNeedsKit HeatSources (campfires, torches) plus anything you register with `Creatures.addLight(entity, radius)`, such as a torch in a player's hand.
## API
### creatures module
`local Creatures = require("~nightCreaturesKit.creatures")`
- `setup(opts)`: choose `threat`, `density` and `enabled`; call on every peer.
- `config()`: a copy of the current settings.
- `catalogue()`: every creature, look, threat set and density, for menus and agents.
- `on(event, fn)`: listen to `dusk(night)`, `dawn(night)`, `spawned(kind, n)`, `fled(id)`, `retreat()`, `setup(cfg)`; spawned, fled and retreat fire on the host. Returns a function that stops listening.
- `darkness()`: how dark it is by the shared clock (0 day, 1 night).
- `addLight(entity, radius)`: register a light creatures fear; returns a function that removes it.
- `lightAt(x, y, z)`: light at a point (0..1): survivalNeedsKit fires plus registered lights.
- `lights()`: every light creatures fear, `{ { x, z, r } }`.
- `build(root, creature, look?)`: draw a creature under any entity (a bestiary, a menu).
- `kindId(creature)`: the spawnerKit enemy kind id (`"night_wolfPack"`).
- `creatureOf(kindId)`: the creature behind a spawnerKit kind id, or nil.
- `defineAll()`: register every creature as a spawnerKit enemy kind (setup calls it).
- `pick(r?)`: pick a creature and look from the threat set by weight.
- `dawnRemovals(sinceDawn, leaveSeconds?)`: the dawn rule as a pure function: given `{ [id] = seconds since it was sent away }`, the sorted ids that must be removed now (default `LEAVE_SECONDS`, 12).
- `VERSION`, `EVENTS`, `DENSITY`, `PREFIX`, `LEAVE_SECONDS`: the version, event names, density table, kind id prefix and default dawn window.
### Components
**NightDirector**: on a synced entity with a spawnerKit Spawner; runs the nights on the host.
- `night` (false): whether the creatures are out (host-written).
- `nightNumber` (0): how many nights have begun (host-written).
- `groupsSent` (0): groups released this night (host-written).
- `spawnDistance` (30): how far from a player a group appears.
- `bringCreatures` (true): off keeps nights empty (creative).
- `leaveSeconds` (12): seconds a creature has to walk away at dawn before the host removes it.
- Methods: `startNight()` (host; for testing and scripted events), `endNight()` (host; sends every creature away).
**CreatureGallery**: all eight creatures in both looks in a turning, labelled lineup.
- `spacing` (3.2), `rowGap` (4), `labels` (true), `floor` (true), `turn` (true).
## What it installs
Installing nightCreaturesKit brings these packages, each from its own world, at the versions it was built and tested with:
| Package | Version |
|---|---|
| spawnerKit | 1.1.8 |
| SecondWind | 1.4.7 |
| worldClockKit | 1.7.3 |
## Gallery
Put a **CreatureGallery** on any entity to see all eight creatures in both looks in a turning, labelled lineup, with each threat set and density on a sign.
## Guides
- **How do I add monsters that come out at night and fear fire** (`nightCreaturesKit.package/how-do-i-add-monsters-that-come-out-at-night-and-fear-fire.guide`)
- **Example: survive the night on an island with a campfire** (`nightCreaturesKit.package/example-survive-the-night-on-an-island-with-a-campfire.guide`)
## Tests
19 tests in `nightCreaturesKit.testSuite`. Run them with `asset.resolve("nightCreaturesKit", "testSuite"):run()`.
## Known limits
- Without aiKit, creatures walk straight at their target over the ground (spawnerKit's movement), so they do not path round cliffs. With aiKit they walk navKit paths; the NightDirector bakes that map itself when play starts (5 to 12 s), and until it is ready the creatures wait at their spawn.
- Creatures are drawn from simple shapes, with no animation rig.
# recipeKit
Recipes and a craft menu for any crafting game. If you are asking "how do I add crafting to my game", this is the small, standalone answer: define recipes (what they need, what they give, whether they need a fire or a workbench, or whether the game places them in the world), and open a craft menu that works with mouse, touch and gamepad. Crafting reads and changes the player's own inventoryKit bag. Ready packs cover survival crafting out of the box: recipes for a stone axe, a torch, a stone pick, a fishing spear, a coconut flask, a campfire, cooking at a fire, and walls, floors and roofs.
Version 1.0.6. New in 1.0.6: released from the Castaway Isle main line together with the other survival kits, on the current engine library; no behaviour change. New in 1.0.5: on a gamepad the d-pad and the left stick move the highlight through every recipe (each row names the row above and below it for the engine's focus moves, so focus never jumps to Close; holding repeats), and the list fits the screen on any size: it shows as many rows as fit in 90% of the screen's height (`MAX_HEIGHT`) and scrolls with the highlight, with "more above / below" markers you can tap or click and a mouse wheel that scrolls. New in 1.0.4: a gamepad drives the craft menu through the engine's own menu navigation (d-pad or stick moves, south crafts, east closes) and the highlighted recipe follows the focused row; while open the menu holds Back, and with menuBackKit installed Escape and Start close it before the pause menu. Gamepad buttons are read through its own padButtons input map first (Menu.padDown), since some clients deliver a pad press only through input maps. On a touch screen the craft menu reads finger taps itself, so tapping a recipe crafts it and tapping Close closes it (a tap can only hover a button in some builds).
## Example
```lua
local Recipes = require("recipeKit.recipes")
local Menu = require("recipeKit.menu")
Recipes.loadPack("survivalBasics")
Recipes.define("rope", { label = "Rope", needs = { fiber = 3 }, result = { "rope", 1 }, category = "tools" })
Recipes.setStationCheck(function(station) return station ~= "fire" or myGame.nearFire() end)
Recipes.onPlace(function(id, recipe) return myGame.placeInFront(recipe.place, function() return Recipes.pay(id) end) end)
-- on the player's body: C or pad Select opens the menu
body.component.add(asset.resolve("recipeKit.CraftMenu", "component"), { theme = "rustic", layout = "list" })
```
## Styles and options
| option | values |
|---|---|
| `theme` | `rustic` (default, brown and gold), `scifi`, `cartoon`, `pixel`, `minimal`, `cozy`. Each sets colours, corner radius and font. |
| `layout` | `list` (one column list, default), `grid` (two column grid) |
| `title` | the menu's title, default `Crafting` |
| `categories` | only show recipes of these categories, e.g. `{ "cooking" }`; nil shows all |
| packs | `survivalBasics` (stone axe, stone pick, torch, fishing spear, coconut flask, campfire to place), `cooking` (cooked fish, grilled crab, roasted root, fish stew, all at a fire), `building` (wall, floor, roof to place) |
| cost scale | `Recipes.setScale(k)`: every cost times k, rounded up; 0 makes everything free |
**Station recipes.** A recipe with `station = "fire"` (or `"workbench"`, or any name) can only be made where your station check says yes. The menu marks it "(at a fire)" and a refusal toasts "Stand by a fire". Without a check every station passes.
**Place recipes.** A recipe with `place = "campfire"` gives no item: once the checks pass, `craft` calls your `onPlace(id, recipe)` handler, which builds it and takes the cost with `Recipes.pay(id)` when it really places. Return `false, "why"` to refuse.
**The menu.** Each recipe is a button with its cost; what you cannot make yet is greyed out; the selected row has a highlight border; a Close button closes it. The mouse pointer is freed while the menu is open and the game gets it back when it closes.
**Controls.**
| input | what it does |
|---|---|
| mouse or touch | click or tap a row to craft it; hovering a row highlights it; Close closes |
| keyboard | Up and Down arrows or W and S move the highlight (Left and Right too in the grid), Enter or E crafts the highlighted row, Escape closes. Held keys repeat after 0.35 s. `menu.keyboard(false)` turns the keys off. |
| gamepad | d-pad moves (left and right too in the grid), south (A) crafts, east (B) closes |
| open and close | C or pad Select with the CraftMenu component, or `menu.toggle()` from your own controls |
## API
### recipes module (`require("recipeKit.recipes")`)
| call | what it does |
|---|---|
| `VERSION` | `"1.0.4"` |
| `define(id, def)` | define or replace a recipe. `def = { label, needs = { item = n }, result = { item, n }?, place = string?, station = string?, category = string? }`; needs a result or a place. Returns the stored recipe. |
| `remove(id)` | remove a recipe; returns whether it existed |
| `get(id)` | the recipe or nil |
| `list(category?)` | recipes in definition order |
| `order` | the id list behind `list` |
| `setOrder(ids)` | put these ids first, in this order |
| `categories()` | categories in use |
| `loadPack(name)` | define a ready pack; returns its ids |
| `setScale(k)`, `scale()` | cost multiplier (ceil, 0 is free) |
| `costOf(id)` | `{ item = n }` after scaling |
| `costText(id)` | `"2 stone, 1 fiber"` or `"free"` |
| `missing(id)` | what the local player lacks: `{ item = n }` |
| `missingText(miss)` | `"Needs 2 stone, 1 fiber"` |
| `canMake(id)` | `(true)` or `(false, why)`, including the station check |
| `setStationCheck(fn)` | `fn(station) -> boolean`; nil restores the default (every station passes) |
| `atStation(station?)` | the station check's answer |
| `onPlace(fn)` | `fn(id, recipe) -> (ok, why?)`, the game's handler for place recipes |
| `pay(id)` | take the scaled cost from the bag; refuses (takes nothing) when short |
| `craft(id)` | check, pay, give the result (`Inventory.give(item, n, true)`) or call the place handler, toast and emit. Returns `(ok, why?)` |
| `on(event, fn)` | listen; returns an unsubscribe function. Events: `crafted(id)`, `refused(id, why)`, `defined(id)` |
| `toast(text, opts?)` | a navUiKit toast when navUiKit is installed |
| `reset()` | remove every recipe and listener and restore the defaults |
### menu module (`require("recipeKit.menu")`)
| call | what it does |
|---|---|
| `THEMES`, `THEME_ORDER`, `THEME_KEYS` | the six themes, their order, and the keys every theme sets |
| `LAYOUTS` | `{ { id = "list", columns = 1 }, { id = "grid", columns = 2 } }` |
| `setup({ theme, layout, title, categories })` | pick the look; unknown names are refused |
| `config()` | the current settings |
| `open()`, `close()`, `toggle()`, `isOpen()` | show and hide the menu |
| `move(delta)` | move the highlight, wrapping at either end |
| `nextIndex(sel, n, delta)` | pure: the row `delta` steps on among `n`, wrapping |
| `dirDelta(dir, columns)` | pure: how far `up`, `down`, `left`, `right` move with this many columns (left and right are 0 in a list) |
| `repeatStep(rec, down, now, delay?, rate?)` | pure: key repeat, true on the press and then every `rate` s once held `delay` s |
| `keyboard(on?)` | turn the menu's keyboard handling on or off; returns the setting |
| `indexOf(id)` | the row a recipe sits on |
| `selected()` | the highlighted row |
| `pick()` | craft the highlighted recipe (a click and a key on the same press craft once) |
| `items()` | the recipes the menu shows |
| `refresh()` | redraw when open |
| `tree()` | the widget tree as it would draw now |
| `step()` | every frame: poll keys and pad (presses fire once, held moves repeat), highlight the hovered row and redraw twice a second |
| `padDown(button)` | whether a pad button is held on any pad |
### packs module (`require("recipeKit.packs")`)
`PACKS[name] = { label, description, order, recipes }` and `ORDER`.
### Components
- **CraftMenu**: on the player's body; only its owner acts. Fields `theme` (`rustic`), `layout` (`list`), `openKey` (`KeyC`, empty for none), `padButton` (`select`, empty for none), `title` (`Crafting`). A game with its own controls (controlsKit actions) sets `openKey = ""` and `padButton = ""` and calls `menu.toggle()` itself.
- **RecipeGallery**: on any entity; opens the menu in each theme in turn with a button panel to switch theme and layout. Local only.
## Multiplayer
Crafting is local to each player's own bag: `missing`, `pay` and `craft` read and change only the local player's inventoryKit inventory, which inventoryKit replicates and saves. The menu is drawn on each player's own screen, and CraftMenu acts only on the engine that owns the body. Recipes are plain data: define the same ones on every peer (from a scene entrypoint or a module every peer requires). What a `place` recipe builds is the game's to replicate.
## Tests
`recipeKit.testSuite` checks defining, listing and ordering, cost scaling (including 0 and rounding up), missing with no bag, the station check, refusals, the place handler, packs, the menu (open, close, move wrapping, grid moves, key repeat, row clicks, the click and key guard, themes) and events. Run it with `asset.resolve("recipeKit", "testSuite"):run()`.
## Guides
- **How do I add crafting recipes and a craft menu to my game** (`recipeKit.package/how-do-i-add-crafting-recipes-and-a-craft-menu-to-my-game.guide`)
- **Example: craft a stone axe and a torch on a survival island** (`recipeKit.package/example-craft-a-stone-axe-and-a-torch-on-a-survival-island.guide`)
## What it installs
Installing recipeKit brings these packages, each from its own world, at the versions it was built and tested with:
| Package | Version |
|---|---|
| inventoryKit | 1.0.26 |
| menuBackKit | 1.0.1 |
# survivalNeedsKit
**Add hunger, thirst, staying warm, rest, stamina, getting soaked, sanity and oxygen to any multiplayer Zero game.** For creators asking "how do I add hunger and thirst to my game", "how do I make players get cold at night" or "how do I make a survival game with food and water". Every player has their own meters on their own body, statuses like Well Fed or Freezing change how they play, and you pick the rules, the climate, the HUD layout and the theme by name.
Version 1.0.13. New in 1.0.13: a burning fire no longer breaks heatSignatures. The fire's own heat record gave heatSignatures `active = true` where it reads a temperature, so heatSignatures' whole tick failed every frame while a fire burned; it gives 420 C now, the same as the fire's built piece. New in 1.0.12: released from the Castaway Isle main line together with the other survival kits, on the current engine library; no behaviour change. New in 1.0.11: status chips (Shivering, Soaked, Well Fed and the rest) stand side by side with room for their names; before, an emoji at the head of each chip's text made it too narrow and the names ran over each other. New in 1.0.10: a fire that went out is cold the moment it dies. heatSignatures cools the stones and sand round a fire over minutes, so what it reads beside a dead fire no longer counts as warmth unless something there is still burning (before, a burnt-out fire kept a player warming for about two minutes). New in 1.0.9: a fire that has gone out is cold everywhere. heatSignatures warmth only counts with something hot in reach, so sun-warmed sand no longer warms you, and a HeatSource's new `piece` field makes the built thing it belongs to (a campfire piece) read hot only while it burns. A fire that runs out goes cold: its warmth and light stop at once, and with heatSignatures installed its heat record goes too (a dead fire no longer warms anyone). Rain comes from worldClockKit's live weather, so a shower soaks you outside, and a Shelter keeps you dry and holds most of the night's cold out (`insulation`). All six HUD layouts are now barsKit bars. Fires can always be brought back: feed one wood, palm leaves, fiber or a coconut, or light it with a torch or a flint once it is out (`feedFire`, `lightFire`, `HeatSource:relight`). Each player's meters are saved with **saveKit** when it is installed, so hunger, thirst and the rest come back as they were left after leaving play, rejoining or restarting the world. Built on **SecondWind** (empty meters hurt, healthy ones heal), **barsKit** (all six HUD layouts), **inventoryKit** (food and drink are bag items) and **worldClockKit** (needs follow the shared day and night). Works with **tropicalKit**'s island for the sea (wading soaks you, diving uses oxygen) and with **abilitiesKit** for status effects.
## Quick start
In your scene's `build.luau`, after the default player setup (`body` is the player's body), and in its `entrypoint.luau`:
```luau
body.component.add(asset.resolve("survivalNeedsKit.SurvivalNeeds", "component"), {})
local fire = entity.spawnSynced("Campfire", { position = { 4, 0, 6 } })
fire.component.add(asset.resolve("survivalNeedsKit.HeatSource", "component"), { radius = 6, warmth = 30 })
local spring = entity.spawn("Spring", { position = { -6, 0, 3 } })
spring.component.add(asset.resolve("survivalNeedsKit.WaterSource", "component"), { label = "Spring" })
-- entrypoint.luau
local Needs = require("~survivalNeedsKit.needs")
function onLoad()
Needs.setup({ rules = "castaway", climate = "tropical", layout = "corners", theme = "realistic" })
end
```
Your scene needs a worldClockKit WorldClock: needs drain by in-game hours, so without a clock they hold still. Press Play: your meters sit on the left edge, drain with the clock, and the spring and fire bring them back.
## Styles and choices
| Setting | Values |
|---|---|
| `rules` | `off` (creative), `cozy`, `standard`, `castaway`, `hardcore`, `horror` |
| `climate` | `tropical`, `temperate`, `desert`, `arctic`, `swamp` |
| `layout` | `corners`, `ring`, `pips`, `silhouette`, `minimal`, `hotbarStrip`: every one is barsKit bars (the theme's look, then barsKit's `ring`, `pips`, vertical `gauge`, `line` and the theme's look again); without barsKit the kit draws its own panels |
| `theme` | `scifi`, `fantasy`, `cartoon`, `pixel`, `minimal`, `realistic`, `horror`, `cozy` |
| Rules | What runs |
|---|---|
| `off` | No needs at all: build and explore freely. |
| `cozy` | Hunger, thirst, warmth, rest, gentle and slow. |
| `standard` | Adds stamina and getting soaked. |
| `castaway` | Adds oxygen; thirst bites and the sea soaks you. |
| `hardcore` | All eight, fast, no natural healing. |
| `horror` | Sanity drains in the dark and away from fire. |
| Climate | Feel |
|---|---|
| `tropical` | Hot days, cool damp nights, sudden showers. |
| `temperate` | Mild days and properly cold nights. |
| `desert` | Scorching sun, freezing nights, thirst doubles at noon. |
| `arctic` | Cold all day, deadly at night: a fire is life. |
| `swamp` | Warm, wet and never quite dry. |
### The needs
- **Hunger, thirst, rest, sanity** drain by the in-game hour, so any day length works.
- **Warmth** moves toward how warm it feels: the climate's day and night air, plus every burning HeatSource nearby, minus a chill when you are soaked. Under a Shelter the roof keeps out `insulation` (0.6 by default) of the night's cold and adds its own `warmth` (6), so a lean-to at night feels far warmer than the open beach (about 62 against 34 on the tropical island).
- **Wetness** rises in the sea and in rain outside a shelter (worldClockKit's blended weather: steady rain soaks you in a few seconds), and dries by the fire and in the sun.
- **Stamina** drains while sprinting and returns faster when fed and rested.
- **Oxygen** drains while your head is under the sea and comes back fast in the air.
A meter at its critical line hurts through SecondWind (`label = "Exposure"`); all meters healthy heal slowly. After a SecondWind respawn the meters refill to `respawnFill` percent.
### Statuses
Seven statuses come from what the meters add up to. They show as small chips on every HUD layout, fire the `statusOn` and `statusOff` events, and with abilitiesKit installed each becomes a real abilitiesKit effect on the body called `survival_<id>`.
| Status | Effect |
|---|---|
| `wellFed` (bonus) | Health comes back slowly and stamina refills 30% faster. |
| `starving` | Your swings deal 30% less damage. |
| `parched` | 15% slower, stamina refills at half speed. |
| `shivering` | 10% slower and you jump lower. |
| `freezing` | 35% slower and you lose health until you warm up. |
| `soaked` | 10% slower and you take 15% more damage. |
| `exhausted` | 25% slower and stamina barely refills. |
### Food and drink
Eighteen inventoryKit items with `useEffect = "event"`: coconut, wild berries, banana, mango, raw fish, cooked fish, crab meat, grilled crab, seaweed, fresh water, coconut water, herbal tea, fish stew, roasted root, jerky, honeycomb, ration bar, bitter coffee. Use one from the hotbar and it feeds the needs it lists. Add your own with `Needs.defineFood`.
## API
### needs module
`local Needs = require("~survivalNeedsKit.needs")`
- `setup(opts)`: pick `rules`, `climate`, `layout`, `theme` by name (any subset); call on every peer, changes apply live. `persist` (default true) saves each player's meters with saveKit; `persist = false` starts every session from the start values.
- `persists()`: whether the meters are saved (`persist` is on and saveKit is installed).
- `savedState()`: the local player's saved meters, `{ v = 1, needs = { hunger = 72.4, ... } }`, or nil when nothing is saved yet, saveKit is missing or the save has not loaded.
- `config()`: a copy of the current settings.
- Fires: `fires({ includeOut = true })` lists every HeatSource, burning or out (without it, only burning ones); `fireNear(x, z, range?)` is the nearest one in reach. `feedFire(fire, item?)` puts one fuel item from the local player's bag on it (`FUEL`: wood 120 s, palm leaf 40, coconut 30, fiber 20; `defineFuel(item, seconds)`), which also lights it again when it was out. `lightFire(fire)` lights a fire that is out with a lighter from the bag (`LIGHTERS`: torch, flint; `defineLighter(item)`), burning on what fuel is left, or on `KINDLING` (45 s) when it burned out. `tendAction(fire)` says which of the two the local player can do there, with prompt words. On the component, from any peer: `HeatSource:addFuel(seconds)` and `HeatSource:relight(kindling?)`.
- `rules()`: the current rule preset table.
- `climate()`: the current climate table.
- `active(need)`: whether a need runs under the current rules.
- `activeNeeds()`: the needs that run, in display order.
- `catalogue()`: every preset, climate, layout, theme, need and food, for menus and agents.
- `on(event, fn)`: listen to an event; returns a function that stops listening. Events: `changed`, `low`, `critical`, `recovered`, `ate`, `drank`, `setup`, `statusOn`, `statusOff`.
- `defineFood(id, def)`: add a food or drink: `{ name, gives = { hunger = 20 }, hp?, rarity? }`.
- `describeFood(id)`: a short text of what a food gives.
- `defineFoods()`: register every food as an inventoryKit item (done for you).
- `consume(foodId)`: apply a food's effect to the local player.
- `get(need)`: the local player's value for a need (0..100), or nil before their body is ready.
- `state()`: every need of the local player, `{ hunger = 72, ... }`.
- `add(need, n)`: change a need of the local player by n points (negative to drain).
- `spend(n)`: spend stamina; returns false when too tired.
- `of(body, need)`: read another player's need from their body (synced).
- `heatAt(x, y, z)`: heat at a point from every burning HeatSource.
- `lightAt(x, y, z)`: firelight at a point (0..1), for creatures that fear fire.
- `fires()`: every burning heat source, `{ { x, y, z, radius, lightRadius } }`.
- `shelterAt(x, y, z)`: the Shelter covering a point, or nil.
- `waterAt(x, y, z)`: the WaterSource within reach of a point, or nil.
- `darkness()`: 0 in full day, 1 at night.
- `rain()`: 0..1, how hard it is raining.
- `waterDepth(x, y, z)`: how far below the sea surface a point stands; 0 on land.
- `temperatureAt(x, y, z, wetness?)`: the felt temperature on the 0..100 comfort scale (50 is comfortable).
### statuses module
`local Statuses = require("survivalNeedsKit.statuses")`
- `define(id, def)`: add or replace a status: `{ label, icon, color, good?, when = { { need, op, value } }, description, effect, heal?, hurt? }`.
- `evaluate(values, running?)`: which statuses a set of need values gives, in order.
- `active()`: the local player's statuses right now.
- `has(id)`: whether the local player has a status.
- `STATUSES`, `STATUS_ORDER`: the status table and its display order.
### hud module
- `draw(c)`: draw the HUD for the local player's SurvivalNeeds component (done for you).
- `restyle()`: tear the HUD down so the next draw builds the chosen layout fresh.
- `teardown()`: remove the HUD.
### Components
**SurvivalNeeds**: one player's meters, on the PlayerPrototype body. Owner-written, synced.
- `hunger`, `thirst`, `warmth`, `rest`, `stamina`, `sanity`, `oxygen` (0..100), `wetness` (0..100, 0 is dry).
- `sprintSpeed` (5.2): ground speed above which the player spends stamina.
- `headHeight` (1.55): how deep the feet must be for the head to be under water.
- `respawnFill` (60): what each meter is set to after a respawn (percent).
- Methods: `value(need)`, `add(need, n)` (owner only), `refill(pct?)`.
**HeatSource**: a fire, torch or brazier on a synced entity.
- `radius` (6): how far the warmth reaches. `warmth` (30): comfort added at the centre.
- `lightRadius` (9): how far its light keeps night creatures away.
- `burning` (true), `fuel` (-1 burns for ever), `maxFuel` (600 seconds).
- `flame` (true), `flameSize` (1), `flameHeight` (0.25): the drawn flame and light.
- Methods: `heatAt(x, y, z)`, `lightAt(x, y, z)`, `describe()`, `addFuel(seconds)` (any peer, relights), `setBurning(on)`.
**Shelter**: inside its footprint rain stops, the roof keeps out `insulation` of the night's cold and adds `warmth`, and standing still restores rest.
- `radius` (2.5), `height` (3), `restBonus` (1).
- Method: `covers(x, y, z)`.
**WaterSource**: press E (pad X, or tap the prompt) to drink.
- `radius` (2.2), `label` ("Spring"), `amount` (35 thirst per drink), `cooldown` (1.2 s).
- `fill` (true): also give a Fresh Water to carry when the bag has room.
- `container` (""): item a player must carry to fill water, such as a flask; empty fills without one.
- `salty` (false): sea water makes you thirstier instead.
- Methods: `reaches(x, y, z)`, `drink()`, `prompt()`.
**NeedsGallery**: a panel to try every layout, theme, rule preset and climate.
- `tour` (true), `tourSeconds` (3), `open` (true).
## Works with heatSignatures
When heatSignatures is installed, every burning HeatSource also registers as a fire in heatSignatures (so a thermal look draws it) and is taken out again the moment it goes out, so a dead fire reads cold there too. The fire's owner gives the scene a heatSignatures climate that matches the needs climate if it has none, and `Needs.heatAt` reads heatSignatures' temperature (`Heat.at`, `HEAT_PER_DEGREE` points per degree above the air) and takes the larger of that and the fire's own falloff. Anything heatSignatures knows to be hot then warms a player too, so a fire drawn by another kit (a buildPlaceKit campfire piece) has to go cold there as well: survivalCraftKit puts the piece out with `Build.setLit` when its HeatSource dies. Without heatSignatures the fires' own falloff is the whole story.
## What it installs
Installing survivalNeedsKit brings these packages, each from its own world, at the versions it was built and tested with:
| Package | Version |
|---|---|
| SecondWind | 1.4.7 |
| barsKit | 1.4.6 |
| inventoryKit | 1.0.26 |
| worldClockKit | 1.7.3 |
## Saving
With saveKit installed (and `persist` left on), the local player's own SurvivalNeeds writes their meters to their saveKit profile under the key `survivalNeedsKit.needs` every 5 seconds when they changed, and once more when the body goes away (leaving play or the world). When the body starts again, the meters wait (at most 8 seconds) for saveKit to load the player's save, then take the saved values back, clamped 0..100, for every need the current rules run, before the first drain. A player who leaves while dead is saved with what a respawn gives them (`respawnFill`, dry, full stamina and oxygen), and a SecondWind respawn still refills the meters as before. Each player's values live in their own saveKit profile, so players never share meters. In saveKit's `checkpoint` mode the values are kept only when saveKit saves at a checkpoint. Without saveKit the kit works as before and nothing is saved.
## Multiplayer
Each player's engine owns and writes their own SurvivalNeeds; the values are synced so anyone can read them. HeatSource `burning` and `fuel` are synced and burned down by the entity's owner; `addFuel` from any peer is sent to the owner. Drinking and eating change only your own meters.
## Gallery
Put a **NeedsGallery** on any entity to step your own HUD through all six layouts and eight themes (buttons, the [ ] and - = keys, or an automatic tour) and to try every rule preset and climate with a click. The Castaway Isle world has a gallery scene with all four castaway galleries side by side.
## Guides
- **How do I add hunger and thirst to my game** (`survivalNeedsKit.package/how-do-i-add-hunger-and-thirst-to-my-game.guide`)
- **Example: island survival, stay fed, watered and warm through the night** (`survivalNeedsKit.package/example-island-survival-stay-fed-watered-and-warm-through-the-night.guide`)
## Tests
32 tests in `survivalNeedsKit.testSuite`. Run them with `asset.resolve("survivalNeedsKit", "testSuite"):run()`.
## Known limits
- Warmth from the sun is a climate number; there is no shade simulation.
- Oxygen needs a sea at height 0 (tropicalKit's island) to know when your head is under.
# regrowKit
Things that get used up and grow back, for any multiplayer Zero game: berry bushes, trees, ore rocks, fishing spots and loot crates. Answers "how do I make bushes and trees grow back after harvesting", respawning resources, regrowing resource nodes and harvestable nodes that refill on a timer. Put a `Regrowing` component on a synced entity, pick a regrow preset and a spent look, and take charges from scripts; the entity's owner decides every take, so two players never get the same charge.
Version 1.0.2. New in 1.0.2: released from the Castaway Isle main line together with the other survival kits, on the current engine library; no behaviour change.
```lua
local Regrow = require("regrowKit.regrow")
local bush = entity.spawn("berryBush", { position = { 4, 0, 2 } })
bush:setSynced(true)
-- children of the bush are its leaves and berries (the part that shrinks)
bush.component.add(asset.resolve("regrowKit.Regrowing", "component"),
{ maxCharges = 3, regrow = "normal", spentLook = "shrink", visual = "berries" })
Regrow.take(bush, function(granted)
if granted then print("you picked a berry") else print("nothing left, come back later") end
end)
Regrow.on("regrown", function(id) print("bush " .. tostring(id) .. " is full again") end)
```
## Styles and options
Regrow presets (`regrow` field, or `Regrow.secondsFor(id)`):
| Preset | Grows back in | Good for |
| --- | --- | --- |
| `quick` | 30 s | grass, pebbles, sticks |
| `normal` | 90 s | berry bushes, small plants (the default) |
| `slow` | 300 s | trees, ore rocks |
| `hourly` | 1 in-game hour on worldClockKit, 150 s without it | fishing spots |
| `daily` | 1 in-game day on worldClockKit, 600 s without it | loot crates, rare nodes |
| `never` | does not come back | one-time loot |
`regrowSeconds` > 0 overrides the preset with real seconds. Add your own with `Regrow.define("seasonal", { label = "Seasonal", seconds = 1200 })` or `{ gameHours = 72, seconds = 1800 }` to follow the in-game clock.
Spent looks (`spentLook` field), applied to every child entity, or only the child named by `visual`:
| Look | While spent | When it grows back |
| --- | --- | --- |
| `shrink` | children scaled to 25% (default) | grow back smoothly over 1.5 s |
| `fade` | children scaled to 60% | grow back smoothly over 1.5 s |
| `hide` | children hidden | shown again |
| `none` | unchanged | unchanged |
Other fields: `charges` (-1 fills to `maxCharges` on start; synced, written by the owner), `maxCharges` (5), `readyAt` (synced `os.time()` when it grows back, 0 while not spent).
To see every preset at once, add the `RegrowGallery` component to a plain entity and press R.
## API
Module `require("regrowKit.regrow")`:
- `M.VERSION: string` is `"1.0.2"`; `M.CHANNEL` is `"regrowKit"`; `M.EVENTS` lists the event names.
- `M.PRESETS: { [string]: { label: string, seconds: number, gameHours: number?, description: string } }` and `M.PRESET_ORDER: { string }`.
- `M.define(id: string, def: { label?, seconds: number, gameHours?, description? }) -> preset` adds or replaces a preset.
- `M.secondsFor(presetOrSeconds: string | number) -> number` real seconds to grow back (-1 is never); reads worldClockKit's day length when the preset has `gameHours`, falling back to `seconds`. An unknown id answers `normal`.
- `M.on(event: string, fn) -> () -> ()` subscribes; returns unsubscribe. Events: `taken(entityId, peer, chargesLeft)`, `spent(entityId)`, `regrown(entityId)`, `refused(entityId, peer)`. They fire on the owner's machine.
- `M.take(e, fn: ((granted: boolean) -> ())?)` asks the entity's Regrowing owner for one charge for the local player; `fn` runs on this machine. When this machine owns the entity (or the owner reads 0), it decides at once and calls `fn` right away. An entity without Regrowing answers `false`.
- `M.state(e) -> { charges: number, max: number, readyAt: number, spent: boolean }?` or nil without Regrowing.
- `M._emit(event, ...)` fires an event (used by the component).
Component `Regrowing` (`asset.resolve("regrowKit.Regrowing", "component")`), public methods on `e.component.get(ref)`:
- `public:take(peer: number) -> boolean` owner only: spends a charge if any, sets `readyAt` when it reaches 0, emits `taken` and `spent`, or `refused`.
- `public:refill()` owner only: fills to `maxCharges`, clears `readyAt`, grows the look back, emits `regrown` if it was spent.
- `public:describe() -> { id, charges, max, readyAt, spent, regrow, seconds, spentLook, look, hidden, growing }`.
Component `RegrowGallery`: fields `spacing`, `charges`, `key` (`"KeyR"`), `labels`; method `public:takeAll()`.
## What it installs
Installing regrowKit brings these packages, each from its own world, at the versions it was built and tested with:
| Package | Version |
|---|---|
## Multiplayer
Put `Regrowing` on a synced entity. `charges` and `readyAt` are synced fields written only by the entity's owner (`entity:owner()`, with owner 0 treated as local), and the owner's `update` refills the node when `os.time()` reaches `readyAt`. A take from another machine travels on the multiplayer channel `regrowKit` as `("take", entityId, peer)`; the owner spends the charge and replies `("grant", entityId, peer, granted)`, which runs the asker's callback. Because only the owner decides, two players tapping the same bush never both get the last berry. Every peer draws the spent look from the synced charges, so everyone sees the same bush. Give the item only inside the `granted` callback.
## Tests
`regrowKit.testSuite` has 15 tests covering presets, `secondsFor`, `define`, spending and refilling, local `take`, events and the spent looks. Run it with `asset.resolve("regrowKit", "testSuite"):run()`.
## Guides
- `how-do-i-make-resources-grow-back-after-players-harvest-them`: the how-to.
- `example-berry-bushes-that-regrow-in-a-survival-game`: a worked example.
# menuBackKit
**Make Escape close your game's menu instead of opening the pause menu.** Version 1.0.2. New in 1.0.2: the press that closes a menu never also pauses, even on slow frames. The app menu's Escape and Start stay stood down until Escape, Start and B are all up and a few frames have passed (`RELEASE_FRAMES`), not only for a fixed `RELEASE_GRACE`: a stood-down control that woke while its key was still down read it as a new press.
In Zero, Escape, a gamepad's Start and the on-screen Menu button open the app's pause menu in every world. A game with menus of its own (a crafting menu, a bag, a build mode, a map, a shop, a dialogue) wants Escape to close the open menu first, and to pause only when nothing is open. menuBackKit does that on keyboard, gamepad and touch with one call per menu.
## Use it
```lua
local Back = require("menuBackKit.menuBack")
local hold
function openMyMenu()
ui.showScreen("myMenu")
hold = Back.hold(function() closeMyMenu() end, { label = "my menu" })
end
function closeMyMenu()
ui.hideScreen("myMenu")
if hold then hold:release() hold = nil end
end
```
While the hold stands:
- **Escape** and a **gamepad's Start** close the menu (the app's pause menu stays shut).
- A **gamepad's B** on the menu and a **phone's back gesture** close it too (the engine's own Back).
- With several menus open, the most recent one closes first (a higher `priority` wins over newer ones).
- Release the last hold and the next Escape opens the pause menu as usual.
A menu from another kit that does not hold Back itself is followed by its open test, every frame:
```lua
function update()
Back.follow("bag", Inventory.isOpen(), function() Inventory.toggle() end)
end
```
## API
- `hold(onBack, { priority?, label? }) -> hold`: take Back for an open menu. `hold:release()`, `hold:held()`. Default priority `PRIORITY` (10), above a pause menu's own claim (0) and the editor's (-1).
- `follow(key, isOpen, onBack, opts?) -> hold?`: hold while `isOpen` is true, release when it turns false.
- `count()`, `labels()`: the holds standing. `keysUp()`: whether Escape and Start are taken from the app menu now.
- `releaseAll()`: drop every hold.
- `VERSION` (`"1.0.2"`), `PRIORITY`, `PRESS_GUARD` (0.15 s), `RELEASE_GRACE` (0.3 s), `RELEASE_FRAMES` (3).
## How it works
A hold is a claim on the engine's Back (`Zin.back.claim`), so a pad's B on a menu and a phone's back gesture already reach it. While any hold stands, the kit's `backKeys` input map is live. It belongs to the `menuBack` group, `suppresses = { "app" }` (the app menu's pause action), and its one control, `back` (Escape, Start), presses Back (`Zin.back.press`), which the engine routes to the newest, highest claim. Nothing is polled and nothing runs while no menu is open.
## What it installs
Installing menuBackKit brings these packages, each from its own world, at the versions it was built and tested with:
| Package | Version |
|---|---|
## Guides
- *How do I make Escape close my menu instead of opening the pause menu?* (`how-do-i-make-escape-close-my-menu-instead-of-opening-the-pause-menu`)
## Versions
- **1.0.1**: released from the Castaway Isle main line at the same time as the other survival kits, on the current engine library; no behaviour change.
- **1.0.0**: hold, follow, the backKeys map; tests and a guide.
# HeatSource
A fire, torch or brazier. Put it on a synced entity. It warms players within `radius` (fading to the edge), casts light within `lightRadius` that night creatures keep away from, can burn `fuel` down (owner-driven, synced) and relight with `addFuel`, and with `flame` on draws its own flickering flame and point light. Any kit can read it through `needs.heatAt`, `needs.lightAt` and `needs.fires`.
# NightDirector
Runs the night on the host. Put it on a synced entity that also has a spawnerKit Spawner (it adds one itself if missing). Watches worldClockKit's darkness; at dusk it releases groups of creatures in the dark near players, keeps every creature out of firelight (they prowl the edge), and at dawn sends them all away to spawnerKit's pool. `night` and `nightNumber` are synced so every peer hears dusk and dawn. `startNight()` and `endNight()` drive it by hand.
# Shelter
A roof. Inside its `radius` and `height`, rain stops soaking the player, the felt temperature rises by 8, and standing still restores rest. Put it on a lean-to, hut, tent or any entity standing where the shelter is; it needs no other component.
# menuBack
The one module of menuBackKit. `hold(onBack, opts)` takes Back for an open menu: while the hold stands, Escape, a gamepad's Start or B and a phone's back gesture run `onBack`, newest and highest hold first, and the app's pause menu stays shut. `hold:release()` gives it up. `follow(key, isOpen, onBack)` keeps a hold by a menu's own open test, for a menu from another kit. `count()`, `labels()` and `keysUp()` say what stands. Called by any kit or game that draws its own menus.
# GatherSpot
A place to gather from by hand: put it on a synced entity with a `resource` (palm, rock, bush, driftwood, grass, fishing, banana, mushroom, clamBed, reeds, flint, coconutPile, seaweed, oreVein, fern or your own from `Gather.define`). It draws the resource's tropicalProps prop as a child named `gatherProp` (a shallow pool when the resource has no prop or tropicalProps is missing), adds a regrowKit `Regrowing` when the entity has none (the resource's charges and regrow preset, spent look acting on the prop), and adds an interactKit `Interactable` whose prompt reads the resource's verb, or "Grows back soon" when it is spent. Pressing it asks the entity's owner for one charge through `regrowKit.take`; when granted the player's own engine rolls the pick into their inventoryKit bag, toasts what they got through navUiKit and plays juiceKit `dust` when those are installed. Fields: `resource`, `propScale`, `prompt`.
# DeathDrop
The drop itself, on a synced entity owned by the player who died. Draws its style and look, adds an interactKit Interactable for the "E Recover" prompt, runs the claim handshake with its owner when someone presses it (owner only, or anyone under the hardcore rule), marks itself with a navUiKit waypoint for its owner, can draw a light beam, pulses when it is a spirit orb, and crumbles at `expireAt`. Spawned by DeathDropWatcher; needs no other component of yours.
# menu
recipeKit's craft menu for the local player. `setup` picks one of six `THEMES` (rustic, scifi, cartoon, pixel, minimal, cozy), one of the `LAYOUTS` (list, grid), the title and optional categories; `open`, `close`, `toggle` and `isOpen` show it; `move`, `pick` and `refresh` drive it. Every row is a button showing the recipe's cost, greyed when it cannot be made, with station recipes marked: a mouse click or tap crafts that row and hovering highlights it, and the mouse pointer is freed while the menu is open. `step` polls the keyboard and gamepad every frame: arrows or W and S (d-pad) move, left and right too in the grid, Enter or E (south, A) crafts, Escape (east, B) closes, and a held key repeats after 0.35 s. `keyboard(on)` turns the key handling on or off. Pure helpers `nextIndex`, `dirDelta` and `repeatStep` hold the movement and repeat rules. Used by the CraftMenu and RecipeGallery components and by games with their own controls.
# creatures
nightCreaturesKit's public surface: `setup` picks the threat set and density and registers every creature as a spawnerKit enemy kind; `lightAt`, `lights` and `addLight` answer where the firelight is; `build` draws a creature; `pick` rolls one from the threat set; `on` listens to `dusk`, `dawn`, `spawned`, `fled` and `retreat`. Called by game scripts and by the NightDirector component.
# gather
gatherKit's public surface: `RESOURCES` and `RESOURCE_ORDER` (fifteen gather spot presets, each with what one pick gives, the tool that doubles it, its charges and its regrow preset), `define` to add your own, `roll` for a pure pick with an optional fixed random source, `give` to put a pick in the local player's inventoryKit bag, `hasTool`, `items` (the item ids it gives, defining missing materials in inventoryKit) and `on` for the `gathered`, `picked` and `empty` events. Called by game scripts and by the GatherSpot component.
# needs
The public surface of survivalNeedsKit: `setup` picks the rule preset, climate, HUD layout and theme by name; `get`, `add`, `spend` and `consume` read and change the local player's meters; `heatAt`, `lightAt`, `fires`, `shelterAt` and `waterAt` answer questions about the world's HeatSource, Shelter and WaterSource components; `on` listens to `low`, `critical`, `recovered`, `ate` and `drank`. Called by game scripts, by the kit's components and by other kits (night creatures read `lightAt`, the castaway kit reads `fires`).
# drops
deathDropKit's public surface: `setup` picks the style, look, rule, marker and expiry; `takeForDeath` and `giveBack` move items between the local player's inventoryKit bag and a drop; `build` draws a style; `list` and `mine` read the drops in the world; `on` listens to `dropped`, `recovered`, `looted` and `expired`. Called by game scripts and by the kit's two components.
# recipes
recipeKit's public surface for recipes: `define`, `remove`, `get`, `list`, `setOrder` and `loadPack` manage what can be made; `setScale` and `costOf` scale costs; `missing`, `missingText` and `canMake` read the local player's inventoryKit bag and the station check (`setStationCheck`); `craft` checks, pays (`pay`) and puts the result in the bag, or hands a `place` recipe to the game's `onPlace` handler; `on` listens to `crafted`, `refused` and `defined`. Toasts go through navUiKit when it is installed. Called by game scripts, by the menu module and by the kit's tests.
# WaterSource
Something to drink from: a spring, a stream, a rain barrel or (with `salty`) the sea. A player within `radius` sees an "E Drink" prompt (gamepad X, or tap it on a touch screen); a drink restores `amount` thirst and, with `fill`, puts a Fresh Water in their bag. Local to each player, so it needs no network. Put it on any entity.
# SurvivalNeeds
One player's eight meters. Put it on the PlayerPrototype's body so every joining player gets their own. Only that player's engine changes the values (synced to everyone). Each frame it drains needs by the in-game hours worldClockKit's clock moved, warms or chills toward the felt temperature, soaks in the sea and rain, spends stamina when sprinting, drains oxygen under water, hurts the body through SecondWind when a meter is critical and heals it when all are healthy, refills after a SecondWind respawn, and draws the HUD. Needs SecondWind on the same body for damage and healing.
# DeathDropWatcher
Goes on the PlayerPrototype's body next to SecondWind's Vitals. When SecondWind reports that body died, the player's own engine takes their inventoryKit items by the rule and spawns a DeathDrop where they fell. `dropNow()` does the same on demand. Fields override the world's style, look and rule for one player.
# GatherGallery
Every gatherKit resource as a working gather spot in one row, labelled with its name, what one pick gives (with chances), its tool, how many picks it holds and its regrow preset. Each spot is a real GatherSpot (prop, regrowKit Regrowing and interactKit prompt), so in play you can walk the row and gather from each one. Put it on any plain entity; it needs no other component and spawns only local, temporary parts, so it is safe in any scene. Fields: `spacing`, `labels`, `prompts`.
# gatherKit tests
This suite has 17 tests. It checks that gatherKit has at least 12 resources, each listed once in RESOURCE_ORDER and complete (label, verb, gives with sane ranges and chances, charges, a regrowKit preset or seconds, prop and category), that every item a resource gives and every tool is an inventoryKit item, a gatherKit material or a survivalNeedsKit food, that every prop is a tropicalProps kind, and that `items` defines the materials inventoryKit lacked. It rolls with fixed random sources to check min, max, chance and tool doubling, defines and removes a test resource and checks bad ones are refused, checks `on` refuses unknown events and unsubscribes, and checks `give` outside play or for an unknown resource changes nothing and does not throw. It puts GatherSpot on temporary entities far from the scene to check it adds a Regrowing with the resource's charges and preset (and keeps one already there), its prop child and its prompt, builds a GatherGallery, and checks the version and README resource table against the code, then removes everything it spawned. It leaves gathering into a real bag in play and the owner handshake between two players to play testing. Run it with `asset.resolve("gatherKit", "testSuite"):run()`.
# DropGallery
Every deathDropKit style in every look, side by side and labelled: one row per style (gravestone, loot bag, backpack, spirit orb, scattered items, washed-up crate, skeleton pile), its three looks along the row, the default look first. A sign at the head lists the five rules and four markers. Put it on any plain entity; it needs no other component and spawns only local, temporary parts, so it is safe in any scene. Pick what you saw with one change: `Drops.setup({ style = "crate", look = "shipwreck" })`.
# deathDropKit tests
This suite has 19 tests. It checks that every drop style in deathDropKit has a label, parts and three looks with a DEFAULT_LOOK among them, that every look colours every part, that every rule and marker in its ORDER list exists with sane fields (markers with a waypoint flag and a world marker kind that the DeathDrop component draws), that setup takes each style, rule and marker by name and refuses an unknown one, that lookOf picks the chosen, default or fallback look, that build draws every style in every look onto a temporary entity (with a light for glowing styles) and that materials are reused, that items survive the encode and decode round trip, and that the version and the README's look table agree with the code. It spawns temporary entities far from the scene and removes them, and restores the setup it changes. It leaves dying, dropping and recovering a real inventory to play testing. Run it with `asset.resolve("deathDropKit", "testSuite"):run()`.
# presets
deathDropKit's data: seven drop styles (each a list of simple shapes and three colour looks), five rules for what drops (keep everything, drop it all, keep your hotbar, drop half, hardcore) and four markers. `drops.setup` picks from here by name.
# CreatureGallery
Every nightCreaturesKit creature in both of its looks, standing in a labelled lineup and slowly turning: crab swarm, wolf pack, shadow stalker, bats, drowned sailor, jungle cat, giant spider and will-o'-the-wisp, each with its health, speed, group size and fear of fire. A sign lists the four threat sets (and which creatures each brings) and the three densities. Put it on any plain entity; it needs no other component and spawns only local, temporary parts. Switch the whole night with one change: `Creatures.setup({ threat = "haunted" })`.
# nightCreaturesKit tests
This suite has 15 tests. It checks that every creature in nightCreaturesKit has sane stats and two looks that colour every part, that every threat set lists only known creatures with positive weights and a real look for each, that every density is complete, that setup takes each threat set and density by name and refuses an unknown one, that pick() follows each threat set's weights, that spawnerKit kind ids round-trip, that build draws every creature in every look onto a temporary entity (with a light for glowing ones), that a registered firelight fades as 1 - (d/r)^2 and is gone once removed, and that the version and the README's creature table agree with the code. It spawns temporary entities far from the scene and removes them, and restores the setup it changes. It leaves the NightDirector's dusk, spawning and dawn retreat to play testing. Run it with `asset.resolve("nightCreaturesKit", "testSuite"):run()`.
# presets
nightCreaturesKit's data: eight creatures (stats, fear of fire, group size, simple-shape parts and two colour looks each), four threat sets (which creatures come where, in which look) and three night densities. `creatures.setup` picks from here by name.
# CraftMenu
Put it on the player's body. Only the body's owner acts: `openKey` (default KeyC) and `padButton` (default select) open and close the recipeKit craft menu, and every frame it calls `menu.step()` so the keyboard (arrows or W and S move, Enter or E crafts, Escape closes) and the pad (d-pad, A, B) drive the menu while it is open; mouse clicks on a row craft it. Fields: `theme`, `layout`, `openKey`, `padButton`, `title`. A game with its own controls sets `openKey` and `padButton` to empty and calls `menu.toggle()` itself, and can call `menu.keyboard(false)` to stop the menu reading keys. Needs no sibling component; define recipes with the recipes module.
# RecipeGallery
Put it on any entity to see the recipeKit craft menu in every theme and layout. On each machine (local only) it opens the menu, shows a button panel to switch theme and layout, and with `cycle` on steps through the themes every `seconds`. When no recipes exist it loads the three ready packs (`loadPacks`). Needs no sibling component.
# packs
recipeKit's ready recipe packs, loaded with `Recipes.loadPack(name)`: `survivalBasics` (stone axe, stone pick, torch, fishing spear, coconut flask, and a campfire to place), `cooking` (cooked fish, grilled crab, roasted root and fish stew, all at a fire) and `building` (wall, floor and roof to place). Plain data: `PACKS[name] = { label, description, order, recipes }` and `ORDER`, the list of pack names.
# recipeKit tests
This suite has 14 tests. It checks that recipes define, list, reorder and remove in definition order and that a recipe with no result and no place is refused; that costOf scales and rounds up, and that a scale of 0 makes everything free; that missing with no bag is the whole cost and missingText reads "Needs 1 fiber, 2 stone"; that canMake runs the station check (and every station passes by default); that craft refuses and takes nothing when ingredients are missing; that a place recipe calls the onPlace handler only after its checks pass; that the crafted, refused and defined events fire and unsubscribe; that loadPack defines every recipe of each pack; that every menu theme sets every key, every theme and layout builds a tree, and the menu opens, closes, toggles and wraps its highlight; and that the version agrees with package.yaml and the README. It snapshots the recipe book, settings and listeners first and restores them, and closes the menu if it opened it. It leaves crafting from a real bag in play to play testing. Run it with `asset.resolve("recipeKit", "testSuite"):run()`.
# NeedsGallery
See every survivalNeedsKit preset on your own HUD. A panel on the right of the screen steps the live needs HUD through all six layouts (corner bars, ring cluster, icon pips, body silhouette, minimal lines, hotbar strip) and all eight themes (sci-fi, fantasy, cartoon, pixel, minimal, realistic, horror, cozy) with its buttons, the `[` `]` and `-` `=` keys, or an automatic tour; it lists the six rule presets and five climates (click one to apply it) and the eighteen foods and drinks. Put it on any plain entity in a scene whose player body has a SurvivalNeeds. Each step is the same single call a game makes: `Needs.setup({ layout = "ring", theme = "pixel" })`. Local to each player.
# hud
Draws the local player's needs in the chosen layout and theme. `corners` and `hotbarStrip` are barsKit bars in the theme's barsKit look (hologram, ornate, bubbly, pixel, line, ghost, blood, stitched); `ring`, `pips`, `silhouette` and `minimal` are widget trees drawn here. Also draws the "E Drink" prompt, which a touch player can tap. Called by the SurvivalNeeds component; `restyle()` rebuilds after `needs.setup` changes the look.
# presets
Plain data for survivalNeedsKit: the eight needs (drain per hour, warn and critical lines, damage), the six rule presets, five climates, eighteen foods, six HUD layouts and eight HUD themes. `needs.setup` picks entries from here by name; add an entry to add a preset.
# statuses
What the local player's needs add up to: seven statuses, each with its own effect. Well fed (hunger and thirst high) is a bonus: health slowly comes back and stamina refills 30% faster. Starving weakens your swings, parched slows you and your stamina, shivering slows you and lowers your jump, freezing slows you hard and hurts, soaked slows you and makes you take more damage, exhausted slows you and stops your stamina refilling. The local player's SurvivalNeeds steps them once a second; the needs HUD shows them as chips, `Needs.on("statusOn" | "statusOff", fn)` reports them, and with abilitiesKit installed each one is a real abilitiesKit effect (`survival_<id>`) whose stat changes apply. Read with `Statuses.active()` and `Statuses.has(id)`; add your own with `Statuses.define(id, def)`.
# survivalNeedsKit tests
This suite has 28 tests. It checks that every need, rule preset, climate, food, HUD layout, HUD theme and status in survivalNeedsKit is complete and consistent (warn and critical lines on the right side of each need, rule presets and foods that only name known needs, every climate with a day and a night, every entry in its ORDER list), that setup takes each rule, climate, layout and theme by name and refuses an unknown one without changing what it had, food descriptions and consume() effects with their ate and drank events, the status rules (well fed, starving, parched, shivering, freezing, soaked, exhausted, filtering by the needs the rules run, and define), the falloff of HeatSource warmth and light, Shelter and WaterSource reach, the felt temperature with fire, shelter and wet chill, the SurvivalNeeds component's owner-only writes and inactive needs, and that the version and the README agree with the code. It spawns temporary entities far from the scene and removes them, and restores the setup it changes. It leaves the per-frame meter drain and the HUD drawing to play testing, since those need a player body. Run it with `asset.resolve("survivalNeedsKit", "testSuite"):run()`.
# RegrowGallery
A local demo of every regrowKit preset side by side: one small berry bush post per preset (quick, normal, slow, hourly, daily, never), each with a Regrowing component in a spent look (shrink, fade or hide) and labels showing its preset, timer and live charges. Press R (the `key` field) or call `takeAll()` to take a charge from every post and watch them use up and grow back. Put it on any plain entity; it spawns only local, temporary parts, so it is safe in any scene.
# Regrowing
A thing that gets used up and grows back: put it on a synced entity (a berry bush, tree, ore rock, fishing spot or loot crate) whose children are its visible parts. It holds `charges` up to `maxCharges`; each take spends one, and when the last goes it sets `readyAt` from its `regrow` preset (quick, normal, slow, hourly, daily, never) or `regrowSeconds`, then refills on its own. While spent its children follow `spentLook`: shrink to 25%, fade to 60%, hide, or none, and grow back smoothly over 1.5 s. The owner decides every take, so two players never get the same charge; take from scripts with `require("regrowKit.regrow").take(e, fn)`.
# Example: berry bushes that regrow in a survival game
A worked example of regrowKit: a patch of synced berry bushes whose berries shrink when picked clean and grow back after 90 seconds, picked with `take` so two players never get the same handful, with worldClockKit day timers and feedback events.
# How do I make resources grow back after players harvest them?
A how-to for regrowKit: build a resource node, add the Regrowing component with a regrow preset and spent look, harvest it with `take` so the owner grants each charge, and react to the spent and regrown events.
# regrow
regrowKit's public surface: the regrow presets (`PRESETS`, `PRESET_ORDER`, `define`, `secondsFor`), events (`on` with taken, spent, regrown and refused), `take` which asks an entity's owner for one charge for the local player and calls back on this machine, and `state` which reads an entity's charges. Used by game scripts that harvest bushes, trees, ore or crates, and by the Regrowing component.
# regrowKit tests
This suite has 15 tests. It checks that regrowKit's six presets (quick, normal, slow, hourly, daily, never) are complete, ordered and timed as documented; that secondsFor reads presets, passes numbers through and follows worldClockKit's day length or falls back to 150 and 600 seconds; that define adds a preset; that a Regrowing on a temporary entity spends charges, sets readyAt from its preset or regrowSeconds and refills; that take on a locally owned entity calls back granted and then refused; that taken, spent, regrown and refused fire and unsubscribe works; that the shrink, fade and hide looks change the children (or only the named visual child); and that the version and README agree with the code. It spawns temporary entities far from the scene and removes them. Taking across two machines is left to play testing. Run it with `asset.resolve("regrowKit", "testSuite"):run()`.
# How do I make Escape close my menu instead of opening the pause menu?
A how-to for menuBackKit: hold Back while a game menu (bag, crafting, build mode, map, shop) is open so Escape, a gamepad's Start or B and a phone's back gesture close it instead of opening the app's pause menu; several menus close newest first; follow a menu from another kit by its open test.
# menuBackKit tests
This suite has 7 tests. It checks that a hold claims the engine's Back and brings the backKeys map up (standing the app menu's pause action down), that releasing the last hold takes it down and gives Back up, that holds list oldest first and the keys stay up while any stands, that a hold without a function is refused, that `follow` holds while a menu is open, lets go when it closes and takes a new hold when the old one was released elsewhere, that the backKeys map suppresses the `app` group and binds Escape and Start, and that the README, package.yaml and VERSION agree. Pressing the keys is left to play testing (inputSim). Run it with `asset.resolve("menuBackKit", "testSuite"):run()`.