# soundstage
**soundstage** gives a world complete, ready-made sound: adaptive music in eight genre sets, sound effect banks with random takes, jitter and per-sound cooldowns, footsteps that change with the floor and the footwear, ambience zones that blend as you walk, and a mix with volume groups and ducking. Every clip (291 of them: 40 music tracks, 8 ambience beds, 147 effect takes, 96 footsteps) was generated with the engine's audio generation, mastered for clean loops, and ships inside the package, so it works anywhere it is installed. It is multiplayer-aware from the start.
## Guides
Two guides ship inside the package:
- **How to use Soundstage**: how the kit fits together. Picking a music set and switching states, intensity, sound effect banks, footsteps per surface and footwear (marking floors, the player, NPCs), ambience beds and zones, volume and mixing, and who hears what in multiplayer. Open it with `guides path="soundstage.package/guides/how-to-add-combat-music-footstep-sounds-and-ambient-sound.guide"`.
- **Example: a small level with music that reacts to danger, footsteps per surface and ambience per area**: a step-by-step build from an empty world, with combat music that starts when an enemy gets close and calms down when it is gone, footsteps on grass, stone, wood and metal (and a barefoot enemy pacing on the wooden pier), and ambience that changes from area to area. Open it with `guides path="soundstage.package/guides/example-level-combat-music-footsteps-on-surfaces-ambience-by-area.guide"`.
In the shell, `man /source/soundstage.package/guides/how-to-add-combat-music-footstep-sounds-and-ambient-sound.guide` and `man /source/soundstage.package/guides/example-level-combat-music-footsteps-on-surfaces-ambience-by-area.guide` open the same guides.
## Quick start
Install the package, then paste this into your scene's `entrypoint.luau` (or any script that runs in play). The music and the ambience start working at once; nothing has to be placed in the scene.
```lua
local Music = require("soundstage.music")
local Ambience = require("soundstage.ambience")
local Footsteps = require("soundstage.footsteps")
function onLoad()
Music.start("cozy") -- cozy set, "explore" state (joins the world's music if it is already playing)
Ambience.setBase("forest") -- forest ambience wherever no zone is
Footsteps.setDefault("grass") -- unmarked floors sound like grass
end
-- call this from your own game when a fight begins
function onFight()
Music.set("action") -- crossfades to the action music
Music.setIntensity(0.8) -- swells, and the high-intensity take crossfades in
end
```
Then give the player footsteps: add the **`Footsteps` component** to the player's body (the entity your `PlayerPrototype`'s `body` field points at, or the `PlayerPrototype` entity itself) and pick its `footwear` there: `shoe`, `boot` or `barefoot`. In the editor that is Add Component on the body. In a scene built in code it is one line:
```lua
body.component.add("Footsteps", { footwear = "boot" })
```
Every player then hears their own steps, and other players' steps where those players are. Floors you have not marked sound like the default set above (grass here). Add the same component to an NPC to give it footsteps too. Footsteps are opt-in: with no `Footsteps` component anywhere there are none. A world with no body entity to edit can call `Footsteps.everyPlayer()` once instead, which gives every avatar footsteps in the default footwear.
Changing the whole world to another genre is one word: `Music.start("scifi")`.
In a browser, sound starts at the player's first click, tap or key press, because browsers keep audio locked until then. Music and ambience started in `onLoad` are already running and become audible at that first input.
Everything is also reachable from a single require:
```lua
local S = require("soundstage.kit") -- S.Music, S.Sfx, S.Footsteps, S.Ambience, S.Mix, S.Catalog, S.Clips
S.Sfx.play("ui.click")
```
## Music: `soundstage.music`
Each set has three states, `menu`, `explore` and `action`. `explore` and `action` each have a low-intensity take and a high-intensity take.
| Call | What it does |
| --- | --- |
| `Music.use(set, opts?)` | Switch to a set, keeping the current state (or starting on `explore`). `opts.state`, `opts.fade`. |
| `Music.start(set, state?)` | Call once when the scene loads. With other players here it joins the music they hear; alone it starts `set` and, after `Music.JOIN_WINDOW` seconds (3) without finding anyone, makes it the world's. |
| `Music.set(state, opts?)` | Change state with a crossfade (`opts.fade` seconds, default 2.5). |
| `Music.setIntensity(0..1)` | Swells the track. Above 0.55 the high take crossfades in; below 0.45 the low take comes back. Cheap to call every frame. |
| `Music.stop(opts?)` | Fade out and stop. |
| `Music.current()` | `{ set, state, intensity, tier, clip, decks }`. |
| `Music.sets()`, `Music.states(set)`, `Music.clipFor(set, state, tier)` | Browse what is available. |
| `Music.define(name, { explore = { low = clip, high = clip }, ... })` | Add your own set from your own soundClips. |
| `Music.configure{ shared, fade, tierFade, volume }` | `shared = false` makes music local to this client. |
Every crossfade is equal-power, so the music keeps its loudness through the change. It also waits for the incoming track: the new track's stream can take a frame or two to start, so the new deck stays silent and the outgoing one holds its level until the stream is playing (or `Music.READY_TIMEOUT` seconds, 3, have passed), and only then do they cross. A long frame, such as a hitch or a tab coming back, cannot jump a fade.
All the built-in music is mastered to one loudness (menu and explore at −14 LUFS, action at −13), so swapping sets or states never jumps in volume. Every track and bed loops on a seamless wrap point.
Intensity works with two whole takes per state: they are crossfaded and the volume swells with the intensity. They are whole takes rather than separate instrument stems because every track is a finished mix, so going past 0.55 sounds like the piece moving up a gear rather than an instrument joining. Your own sets defined with `Music.define` work the same way.
## Sound effects: `soundstage.sfx`
`Sfx.play("bank.sound", opts?)` picks one of the sound's takes at random and adds a little random pitch (±6%) and volume (±10%) to each play. It returns the clip name of the take it played. The draw is a shuffle bag: the takes a sound played most recently (the last half of them) sit out, so a sound with four takes never plays one again within two plays, and a sound with three never plays the same take back to back. Each sound keeps its own history.
The built-in takes are levelled: the takes of one sound sit within about 1 dB of each other, and `Sfx.TRIM_DB` holds small per-sound trims so no bank jumps out of the mix. Sounds you add with `Sfx.define` play at the level you made them.
- `opts.at`: a position or an entity, for a 3D sound that gets quieter with distance (`opts.maxDistance`, default 30).
- `opts.volume`, `opts.pitch`: scale the jittered values.
- `Sfx.broadcast(name, opts)`: plays it here and for every other player in the session (positioned when `at` is given). It travels over the multiplayer relay and is not stored, so a player who joins later never hears an old one.
- `Sfx.define("doors.creak", { clipA, clipB, clipC })`: add your own sounds with their own takes.
- `Sfx.configure{ pitchJitter, volumeJitter }`, `Sfx.banks()`, `Sfx.sounds(bank)`, `Sfx.takes(name)`, `Sfx.has(name)`, `Sfx.onPlay(fn)`.
UI sounds play flat on the `ui` group. Everything else plays on `sfx`.
### Cooldowns
Every sound can have a cooldown: after it plays, the same sound cannot play again until that many seconds have passed, so a pickup collected ten times in a frame or a door spammed by a trigger plays once. A play that is still cooling down is skipped and returns nil.
```lua
local Sfx = require("soundstage.sfx")
Sfx.setCooldown("pickups.coin", 0.15) -- one sound
Sfx.setCooldown("impacts", 0.08) -- every sound in a bank
Sfx.setCooldown("pickups.coin", nil) -- back to the bank's (or the default)
Sfx.play("impacts.wood", { key = door.id }) -- each door keeps its own cooldown
Sfx.play("ui.error", { force = true }) -- ignore the cooldown this once
Sfx.play("magic.cast", { cooldown = 0.5 }) -- this play's own cooldown
```
- A sound uses its own cooldown, else its bank's (`setCooldown("bank", …)`), else the bank's built-in default in `Sfx.BANK_COOLDOWN`, else `Sfx.configure{ cooldown }` (0). The built-in defaults are 0.05 s for `ui` and `pickups` and none for the other banks. Footsteps keep a separate cooldown per walker, so two players' steps never block each other.
- `Sfx.define(name, takes, { cooldown = 0.3 })` gives a custom sound its cooldown. `Sfx.cooldown(name)` reads the one in force; `Sfx.ready(name, { key })` says whether it would play now.
- Cooldowns apply in play. In edit mode every call plays, so auditioning is never blocked.
- `Sfx.broadcast` does not send a sound that is still cooling down here, and every player's client applies the cooldown again to what it receives.
## Footsteps: `soundstage.footsteps` and the `Footsteps` component
Footsteps belong to whoever walks. Add the **`Footsteps` component** to the player's body (or the `PlayerPrototype` entity) and to any NPC, and pick the `footwear` on it: `shoe` (light), `boot` (heavy) or `barefoot`. `volume` (default 1) scales its steps. Each walker steps in rhythm with its speed, faster when it sprints, stops when it stands still, and a hard landing makes a heavier step. Each client hears its own steps flat and other players' and NPCs' steps in 3D where they are.
From code, `Footsteps.track(entity, { footwear = "boot", volume = 1 })` does the same as adding the component, and `Footsteps.untrack(entity)` undoes it. `Footsteps.everyPlayer()` gives every avatar footsteps in the default footwear without the component (off by default); `Footsteps.walkers()` lists who has footsteps.
The kit reads what each floor is made of from the first of these that it finds:
1. a **`Surface` component** on the floor or any parent (field `material`), or `Footsteps.mark(entity, "metal")`;
2. a **`surface` attribute** on the floor or a parent;
3. a **surface word in the name** of the floor or a parent;
4. a surface word in its **material** name;
5. the **default**: `Footsteps.setDefault("grass")`, or stone if it is never set.
Ground that none of these marks, such as a starter world's plain floor, sounds like the default. Naming a folder "Wood Floors" marks every floor inside it.
Names are read as whole words, split at spaces, punctuation, digits and camelCase, with plurals and -y, -en, -ed endings: "Grass Patch" → grass, "MetalGrate" and "metal_floor" → metal, "WoodenPlanks" → wood, "Snowy Field" → snow, "Cobblestone Road" → stone, and the keywords in `Footsteps.KEYWORDS` such as "Beach" → sand, "Puddle" → water, "Plank" → wood. A word never matches inside another word, so "Settings", "Tiny Room", "Sandbox", "Path", "ground" and an engine material such as `@builtin::materials.default` name nothing and use the default. Only the last part of a material's name is read. Teach it your own words with `Footsteps.addKeyword("carpet", "wood")`, and check a floor with `Footsteps.surfaceOf(entity)`.
Footwear:
- The `Footsteps` component's `footwear` is what a walker wears, and changing it while playing takes effect on the next step.
- `Footsteps.setFootwear("barefoot")` lets this player change footwear while playing (a wardrobe, a menu). It is shared, so everyone hears it, and it beats the component until `Footsteps.setFootwear(nil)` hands back to the component.
- `Footsteps.setDefaultFootwear(kind)` sets the footwear for walkers that name none. `Footsteps.footwear(id?)` reads what a player or walker wears.
Also:
- `Footsteps.play{ surface, footwear, at, volume }` plays one step by hand.
- `Footsteps.disable()` / `enable()` silences or restores every automatic step.
- `Footsteps.configure{ stride, localVolume, remoteVolume, maxDistance }`: the volumes are 0.9 by default, and others' steps carry 25 m.
- `Footsteps.onStep(fn)` runs for every step with `{ who, surface, footwear, at, own, landing, take }`.
Every surface is levelled to the same loudness, a boot a little heavier than a shoe and bare feet a little softer, so walking from grass onto metal changes the sound and not the volume.
When the floor cannot say what it is (a terrain, a procedural ground), content supplies the surface with a **resolver**: `Footsteps.setResolver(key, function(point, entityId, who) return "moss" end)` answers a surface name for a step at `point`, or nil to leave it to the floor. Resolvers are asked first, in the order their keys were first set; setting a key again replaces it and nil removes it. `Footsteps.surfaceAt(point, entityId?, who?)` is the answer every walker step and `play{ at }` uses: the resolvers, then `surfaceOf`, then the default.
## Ambience: `soundstage.ambience`
Add an **`AmbienceZone` component** to any entity (fields: `bed`, `radius`, `size` for a box, `fade` metres, `volume`). The bed plays at full volume inside the zone and fades out over `fade` metres beyond its edge. Nearby zones crossfade into each other, and each client hears the zones around its own player.
- Beds: forest, city, cave, wind, rain, station, shore, night. Each one loops seamlessly, and all of them are mastered to the same loudness (−16 LUFS). A bed that is just starting waits for its stream the same way music does, so walking into a new zone never dips through silence.
- `Ambience.setBase(bed)`: the bed heard wherever no zone is. It gives way as zones fade in.
- `Ambience.zone(bed, { at = posOrEntity, radius, size, fade, volume })` adds a zone from code and returns its id; remove it with `Ambience.removeZone(id)`.
- `Ambience.play(bed)` / `Ambience.stop(bed?)` play a bed everywhere. `Ambience.levels()` and `Ambience.weightsAt(p)` show what is heard.
- `Ambience.define(name, clip)` adds your own looping bed. `Ambience.configure{ smooth, volume }`.
## Mix: `soundstage.mix`
Groups: `music`, `sfx`, `ui`, `voice`, `ambience`. Each group plays on the engine mixer channel of the same name, so any settings screen that sets those channels controls the kit.
- `Mix.setVolume(group, 0..1)` sets the kit's own level for a group. `Mix.setPlayerVolume(group, v)` sets the player's preference on the mixer channel.
- `Mix.duck(groups?, { amount = 0.35, attack, release, hold })` dips groups (by default music and ambience) and returns a handle. `Mix.release(handle)` brings them back. Overlapping ducks take the deepest.
- `Mix.voice(clipOrName, opts?)` plays a dialogue line on `voice` and ducks the music and ambience under it for its length.
- `Mix.setAmbienceFollows("sfx")` makes ambience also follow another channel's slider; this is the default, so an "effects" slider covers ambience too. Pass nil to stop it.
### With menusKit
The menusKit settings screen (Press Start Studio) works with no wiring. Its **Music** slider sets the `music` channel, its **Effects** slider sets `sfx` and `ui` (and with them the ambience, which follows `sfx`), its **Voice** slider sets `voice` (and `dialogue`), and **Master** sets the master volume.
menusKit applies the player's saved levels when its menu host starts, which is when a menu first opens. A world that opens no menu at start should apply them itself in its scene's `onLoad`, as this world's gallery does:
```lua
local Settings = require("menusKit.settings")
function onLoad()
Settings.load() -- the saved Music / Effects / Voice levels apply from the first frame
end
```
## Multiplayer
- **Music** is shared state in the world store: whoever calls `use`, `set` or `setIntensity` changes it for everyone. Drive those calls from game events in one place (a round starting, a boss appearing) rather than from every client's own view of the game.
- **Joining**: `Music.start` hears what the players already here hear. A joiner's player list can fill in a moment after its scene loads, so `start` keeps looking for `Music.JOIN_WINDOW` seconds before it claims the music for its own set. Alone, music stored by a past session is ignored.
- **Two changes at once** settle on one: every change carries a revision, the newest wins on every client (a tie goes to the same player everywhere), and a client whose change lost puts the winner back in the store.
- Each client plays the music itself, so two players hear the same set, state and intensity, but not sample-locked to the same beat (see [Known limits](#known-limits)).
- **Effects** from `Sfx.play` are local to the caller; `Sfx.broadcast` plays them for everyone in the session over the relay. Cooldowns are kept per client.
- **Footsteps** run on every client for every walker (each `Footsteps` component or tracked entity): your own steps are flat, other players' and NPCs' steps are spatial. A player's footwear comes from the `Footsteps` component on their body, which syncs, or from their own `setFootwear` choice, which is stored per player, so everyone hears the same boots.
- **Ambience** is computed on each client from that client's own player, so everyone hears where they are standing.
## Components
- `Footsteps`: gives the player's body, or an NPC, footsteps (`footwear`: shoe, boot or barefoot; `volume`).
- `Surface`: says what a floor is made of (`material`).
- `AmbienceZone`: gives an area its own background bed.
- `SoundstageHost`: the kit spawns it on its own the first time it is used; you never add it yourself.
The package also holds one material, `soundstage.examples.pier_wood` (weathered oak planks), which the example level guide uses for its wooden pier. The kit itself never needs it.
## Known limits
These come from the engine or the platform, not the kit. Each one names the open GitHub issue that tracks it.
- **Music is not beat-locked between players** (#2577, #18604). A playing sound has no seek or start offset (#2577), and players share no clock (#18604). Everyone hears the same set, state and intensity, but each from where their own stream started, so two players side by side can be a few bars apart.
- **A new track can take a moment to start** (#19413). Nothing says when a newly assigned clip starts sounding. The kit polls the voice and holds the outgoing track at full level until the new one plays, waiting at most `Music.READY_TIMEOUT` (3 s), so a slow load delays a crossfade rather than dipping through silence.
- **A short one-shot sometimes starts extra voices** (#15080). The engine can start more than one voice for a short one-shot. Sound effects and footsteps are short one-shots, so a fast run of them can use more of the mixer's voices than it plays.
- **Relay listeners cannot be removed** (#19267). `multiplayer.on` has no way to remove a listener, so `Sfx.broadcast` listens once per session and a replaced listener ignores what it hears. A hot reload in the editor leaves one idle listener behind; players never notice it.
- **Two engines on one account are one player** (#14448). To hear the multiplayer behaviour for real, open the world as two different accounts. The tests check it with stand-in stores, relays and avatars.
- **The ZeroMind description can lag a release** (#19258). Right after a new version is published, its ZeroMind listing can still show the previous description. The README inside the package is always the current one.
- **The guides are not found by library search yet** (#22181, ZeroMind#3099), **and open by folder path only** (#22286). They ship inside the package. Open them with `guides path="soundstage.package/guides/how-to-add-combat-music-footstep-sounds-and-ambient-sound.guide"` and `guides path="soundstage.package/guides/example-level-combat-music-footsteps-on-surfaces-ambience-by-area.guide"`, or with `man /source/soundstage.package/guides/<name>.guide` in the shell.
## Catalog: `soundstage.catalog`
Every set, track, bank, sound, surface, footwear and bed, with tags and descriptions, so a person or an agent can browse it:
- `Catalog.kinds()` gives `{ "sets", "tracks", "banks", "sounds", "surfaces", "footwear", "beds" }`.
- `Catalog.list("sounds", "magic")` lists the entries of a kind, optionally narrowed to one set or bank. Pass `true` as the third argument to get names only.
- `Catalog.find("8-bit")` searches tags, names and descriptions. `Catalog.describe("weapons.laser")` returns one entry, and `Catalog.text()` returns the whole listing.
The full listing (`Catalog.text()`):
```text
## sets
fantasy [orchestral, medieval, epic, rpg, adventure] Orchestral fantasy: harps, horns, choir and war drums.
scifi [synth, electronic, space, cyberpunk, futuristic] Synth sci-fi: pads, sequencers and pulsing bass.
cartoon [whimsical, comedy, kids, playful, orchestral] Cartoon: pizzicato, xylophone, brass and slapstick percussion.
horror [dark, tension, drone, scary, ambient] Horror: drones, dissonance and dread.
chiptune [8-bit, retro, pixel, arcade, chiptune] Retro chiptune: square waves, triangle bass and noise drums.
cozy [lofi, acoustic, folk, relaxing, farming] Cozy: lofi keys, acoustic guitar and folk fiddle.
synthwave [80s, neon, outrun, retro, electronic] Synthwave: 80s analog synths, gated drums and neon nights.
western [frontier, guitar, cowboy, desert, dusty] Western: twangy guitar, harmonica and whistling.
## tracks
fantasy.menu [orchestral, medieval, epic, rpg, adventure] majestic orchestral fantasy main menu theme, warm french horns and choir pads over soft strings, harp arpeggios, 80 bpm, legendary and inviting
fantasy.explore_low [orchestral, medieval, epic, rpg, adventure] pastoral orchestral fantasy exploration music, wooden flute and harp over soft strings, light frame drum, 90 bpm, peaceful journey across green hills
fantasy.explore_high [orchestral, medieval, epic, rpg, adventure] orchestral fantasy exploration with rising tension, low cello ostinato, timpani rolls, uneasy horns, harp, 90 bpm, danger nearby
fantasy.action_low [orchestral, medieval, epic, rpg, adventure] orchestral fantasy battle music, driving string ostinato, heroic brass stabs, war drums, 140 bpm, heroic
fantasy.action_high [orchestral, medieval, epic, rpg, adventure] epic orchestral fantasy boss battle music, full choir, pounding taiko war drums, furious string runs, blazing brass, 160 bpm, desperate climax
scifi.menu [synth, electronic, space, cyberpunk, futuristic] ambient sci-fi main menu music, lush analog synth pads, slow sequenced arpeggio, deep sub bass, spacious reverb, 90 bpm, vast and mysterious
scifi.explore_low [synth, electronic, space, cyberpunk, futuristic] calm ambient sci-fi exploration music, shimmering synth pads, soft arpeggiated sequencer, deep sub bass, 90 bpm, drifting through a space station
scifi.explore_high [synth, electronic, space, cyberpunk, futuristic] tense sci-fi exploration music, dark pulsing synth bass, ticking hi-hats, dissonant pads, 100 bpm, something is wrong
scifi.action_low [synth, electronic, space, cyberpunk, futuristic] sci-fi combat music, driving electronic drums, aggressive synth bass, arpeggiated synth leads, 130 bpm, cyberpunk
scifi.action_high [synth, electronic, space, cyberpunk, futuristic] intense sci-fi boss fight music, heavy industrial drums, distorted synth bass, soaring synth leads, 140 bpm, relentless
cartoon.menu [whimsical, comedy, kids, playful, orchestral] bouncy cartoon main menu theme, pizzicato strings, glockenspiel, clarinet melody, tuba bass, whimsical, 110 bpm
cartoon.explore_low [whimsical, comedy, kids, playful, orchestral] playful cartoon exploration music, marimba, ukulele, flute, light percussion, 110 bpm, cheerful and silly
cartoon.explore_high [whimsical, comedy, kids, playful, orchestral] sneaky cartoon tiptoe music, pizzicato strings, bassoon, wood block, comic suspense, 100 bpm
cartoon.action_low [whimsical, comedy, kids, playful, orchestral] zany cartoon chase music, fast brass, xylophone runs, snare rolls, 160 bpm, frantic fun
cartoon.action_high [whimsical, comedy, kids, playful, orchestral] big band cartoon showdown music, full brass hits, frantic drums, swirling strings, 170 bpm, slapstick climax
horror.menu [dark, tension, drone, scary, ambient] dark horror main menu music, slow out of tune music box melody, eerie low drones, distant piano, unsettling
horror.explore_low [dark, tension, drone, scary, ambient] horror exploration music, low drones, sparse detuned piano notes, creaking textures, quiet dread, very slow
horror.explore_high [dark, tension, drone, scary, ambient] rising horror tension music, dissonant string clusters, slow heartbeat pulse, scraping metal textures, building dread
horror.action_low [dark, tension, drone, scary, ambient] horror chase music, pounding low drums, screeching violins, frantic pulse, 140 bpm, terror
horror.action_high [dark, tension, drone, scary, ambient] extreme horror climax music, chaotic dissonant orchestra, aggressive percussion, shrieking strings, 150 bpm, panic
chiptune.menu [8-bit, retro, pixel, arcade, chiptune] 8-bit chiptune title screen theme, catchy square wave melody, pulsing arpeggios, triangle bass, 120 bpm, press start nostalgia
chiptune.explore_low [8-bit, retro, pixel, arcade, chiptune] 8-bit chiptune overworld exploration theme, cheerful square wave lead, bouncy triangle bass, noise drums, 130 bpm, adventurous
chiptune.explore_high [8-bit, retro, pixel, arcade, chiptune] 8-bit chiptune dungeon theme, minor key square wave arpeggios, tense triangle bass, 130 bpm
chiptune.action_low [8-bit, retro, pixel, arcade, chiptune] 8-bit chiptune battle theme, fast square wave lead, driving noise drums, 160 bpm, energetic
chiptune.action_high [8-bit, retro, pixel, arcade, chiptune] 8-bit chiptune final boss theme, frantic square wave arpeggios, intense triangle bass, fast noise drums, 170 bpm, epic retro
cozy.menu [lofi, acoustic, folk, relaxing, farming] cozy lofi main menu music, warm rhodes piano chords, gentle vinyl crackle, soft brushed drums, 75 bpm, comforting
cozy.explore_low [lofi, acoustic, folk, relaxing, farming] cozy acoustic exploration music, nylon guitar, soft rhodes piano, brushed drums, upright bass, 80 bpm, homely and warm
cozy.explore_high [lofi, acoustic, folk, relaxing, farming] cozy acoustic music with more energy, strummed guitar, shaker and bongos, bright glockenspiel, 95 bpm, a little adventurous
cozy.action_low [lofi, acoustic, folk, relaxing, farming] cheerful upbeat acoustic folk, quick fingerpicked guitar, fiddle, hand claps, 120 bpm, lively
cozy.action_high [lofi, acoustic, folk, relaxing, farming] energetic folk hoedown, fast fiddle, banjo, stomping percussion, 140 bpm, exciting but friendly
synthwave.menu [80s, neon, outrun, retro, electronic] retro 1980s synthwave title theme, lush analog pads, gated reverb drums, 100 bpm, nostalgic neon night
synthwave.explore_low [80s, neon, outrun, retro, electronic] chill synthwave cruising music, warm synth arpeggios, mellow drum machine, 100 bpm, night drive
synthwave.explore_high [80s, neon, outrun, retro, electronic] driving synthwave music, pulsing analog bass, gated reverb snare, soaring lead synth, 110 bpm, neon city chase at night
synthwave.action_low [80s, neon, outrun, retro, electronic] driving synthwave action music, fast arpeggiated bass, punchy gated drums, 128 bpm, outrun chase
synthwave.action_high [80s, neon, outrun, retro, electronic] aggressive darksynth, distorted synth bass, pounding drums, screaming synth leads, 140 bpm
western.menu [frontier, guitar, cowboy, desert, dusty] spaghetti western main theme, twangy reverb electric guitar, whistled melody, distant trumpet, 90 bpm
western.explore_low [frontier, guitar, cowboy, desert, dusty] dusty western exploration music, acoustic guitar strumming, harmonica, gentle clip clop percussion, 95 bpm, wide open prairie
western.explore_high [frontier, guitar, cowboy, desert, dusty] tense spaghetti western music, twangy reverb electric guitar, whistling melody, rattling percussion, 100 bpm, showdown approaching
western.action_low [frontier, guitar, cowboy, desert, dusty] western gallop chase music, driving acoustic guitar, galloping drums, trumpet, 150 bpm
western.action_high [frontier, guitar, cowboy, desert, dusty] epic western showdown music, full orchestra, mariachi trumpets, pounding drums, 150 bpm, climactic
## banks
ui [interface, menu, button] Interface clicks, hovers, confirms, backs, errors and notifications.
footsteps [footsteps, movement, foley] Footsteps on eight surfaces in a light shoe, a heavy boot or bare feet (used by soundstage.footsteps and the Footsteps component).
impacts [hit, collision, foley, physics] Hits on wood, metal, stone and glass, punches and heavy thuds.
weapons [combat, fantasy, scifi, shooter] Swords, bows, a pistol, a laser, a reload and an explosion.
magic [fantasy, spell, rpg] Spell casts, fire, ice, lightning, healing, teleport and buffs.
pickups [collect, reward, arcade, platformer] Coins, gems, power-ups, health, keys and items.
vehicles [car, racing, scifi, transport] Engine start, horn, tyre skid, door, hover fly-by and boost.
creatures [monster, animal, enemy] Growls, roars, critters, birds, zombies, slimes, wolves and insects.
## sounds
ui.back (3 takes) [interface, menu, button] a soft short descending user interface back or cancel blip
ui.click (3 takes) [interface, menu, button] a crisp short user interface button click, plastic tick
ui.close (3 takes) [interface, menu, button] a smooth user interface menu panel closing swish
ui.confirm (3 takes) [interface, menu, button] a bright positive user interface confirm chime
ui.error (3 takes) [interface, menu, button] a short buzzy negative user interface error sound
ui.hover (3 takes) [interface, menu, button] a very soft subtle short user interface hover tick
ui.notify (3 takes) [interface, menu, button] a friendly two note user interface notification ping
ui.open (3 takes) [interface, menu, button] a smooth user interface menu panel opening whoosh with a soft chime
impacts.glass (3 takes) [hit, collision, foley, physics] a glass bottle shattering
impacts.metal (3 takes) [hit, collision, foley, physics] a heavy clang hitting a metal plate
impacts.punch (3 takes) [hit, collision, foley, physics] a meaty punch impact
impacts.stone (3 takes) [hit, collision, foley, physics] a heavy rock hitting a stone floor
impacts.thud (3 takes) [hit, collision, foley, physics] a heavy body falling on the ground with a thud
impacts.wood (3 takes) [hit, collision, foley, physics] a solid hit on a wooden crate
weapons.arrow_hit (3 takes) [combat, fantasy, scifi, shooter] an arrow thudding into a wooden target
weapons.bow_shot (3 takes) [combat, fantasy, scifi, shooter] a bow string release and an arrow whizzing away
weapons.explosion (3 takes) [combat, fantasy, scifi, shooter] a big explosion with a deep boom and debris
weapons.laser (3 takes) [combat, fantasy, scifi, shooter] a sci-fi laser blaster shot pew
weapons.pistol (3 takes) [combat, fantasy, scifi, shooter] a single pistol gunshot
weapons.reload (3 takes) [combat, fantasy, scifi, shooter] a gun magazine reload with mechanical clicks
weapons.sword_clash (3 takes) [combat, fantasy, scifi, shooter] two steel swords clashing with a ringing metallic clang
weapons.sword_swing (3 takes) [combat, fantasy, scifi, shooter] a fast sword swinging through the air whoosh
magic.buff (3 takes) [fantasy, spell, rpg] a power up buff spell, ascending magical shimmer
magic.cast (3 takes) [fantasy, spell, rpg] a magic spell being cast, shimmering sparkle whoosh
magic.fireball (3 takes) [fantasy, spell, rpg] a fireball spell launching with a roaring fiery whoosh
magic.heal (3 takes) [fantasy, spell, rpg] a gentle healing spell, soft warm chimes rising
magic.ice (3 takes) [fantasy, spell, rpg] an ice spell, crackling freezing crystals forming
magic.lightning (3 takes) [fantasy, spell, rpg] a lightning spell, sharp electric crackle and zap
magic.teleport (3 takes) [fantasy, spell, rpg] a magical teleport, swirling warp whoosh with a pop
pickups.coin (3 takes) [collect, reward, arcade, platformer] a video game coin pickup, bright metallic ding
pickups.gem (3 takes) [collect, reward, arcade, platformer] picking up a crystal gem, sparkling glassy chime
pickups.health (3 takes) [collect, reward, arcade, platformer] a health pickup, soft warm rising tone
pickups.item (3 takes) [collect, reward, arcade, platformer] picking up an item, a soft satisfying pop with a bright sparkle
pickups.key (3 takes) [collect, reward, arcade, platformer] picking up a jingling metal key
pickups.powerup (3 takes) [collect, reward, arcade, platformer] a video game power up pickup, rising arpeggio jingle
vehicles.boost (3 takes) [car, racing, scifi, transport] a vehicle turbo boost, rising jet whoosh
vehicles.door (3 takes) [car, racing, scifi, transport] a car door closing with a solid thunk
vehicles.engine_start (3 takes) [car, racing, scifi, transport] a car engine starting and revving once
vehicles.horn (3 takes) [car, racing, scifi, transport] a car horn honk
vehicles.hover_pass (3 takes) [car, racing, scifi, transport] a futuristic hover vehicle passing by fast, whooshing hum
vehicles.skid (3 takes) [car, racing, scifi, transport] car tires skidding and screeching on asphalt
creatures.bird (3 takes) [monster, animal, enemy] a single bird chirp call
creatures.critter (3 takes) [monster, animal, enemy] a small cute critter squeak
creatures.growl (3 takes) [monster, animal, enemy] a low menacing monster growl
creatures.insect (3 takes) [monster, animal, enemy] a large insect buzzing and clicking
creatures.roar (3 takes) [monster, animal, enemy] a huge beast roar
creatures.slime (3 takes) [monster, animal, enemy] a wet squishy slime creature blorp
creatures.wolf (3 takes) [monster, animal, enemy] a wolf howling
creatures.zombie (3 takes) [monster, animal, enemy] a zombie groaning moan
footsteps.grass_shoe (4 takes) [footsteps, grass, shoe, soft] light shoe footstep on grass
footsteps.grass_boot (4 takes) [footsteps, grass, boot, soft] heavy boot footstep on grass
footsteps.stone_shoe (4 takes) [footsteps, stone, shoe, hard] light shoe footstep on stone
footsteps.stone_boot (4 takes) [footsteps, stone, boot, hard] heavy boot footstep on stone
footsteps.wood_shoe (4 takes) [footsteps, wood, shoe, hollow] light shoe footstep on wood
footsteps.wood_boot (4 takes) [footsteps, wood, boot, hollow] heavy boot footstep on wood
footsteps.metal_shoe (4 takes) [footsteps, metal, shoe, ringing] light shoe footstep on metal
footsteps.metal_boot (4 takes) [footsteps, metal, boot, ringing] heavy boot footstep on metal
footsteps.gravel_shoe (4 takes) [footsteps, gravel, shoe, crunchy] light shoe footstep on gravel
footsteps.gravel_boot (4 takes) [footsteps, gravel, boot, crunchy] heavy boot footstep on gravel
footsteps.sand_shoe (4 takes) [footsteps, sand, shoe, soft] light shoe footstep on sand
footsteps.sand_boot (4 takes) [footsteps, sand, boot, soft] heavy boot footstep on sand
footsteps.water_shoe (4 takes) [footsteps, water, shoe, splashy] light shoe footstep on water
footsteps.water_boot (4 takes) [footsteps, water, boot, splashy] heavy boot footstep on water
footsteps.snow_shoe (4 takes) [footsteps, snow, shoe, crunchy] light shoe footstep on snow
footsteps.snow_boot (4 takes) [footsteps, snow, boot, crunchy] heavy boot footstep on snow
footsteps.grass_barefoot (4 takes) [footsteps, grass, barefoot, soft] barefoot footstep on grass
footsteps.stone_barefoot (4 takes) [footsteps, stone, barefoot, hard] barefoot footstep on stone
footsteps.wood_barefoot (4 takes) [footsteps, wood, barefoot, hollow] barefoot footstep on wood
footsteps.metal_barefoot (4 takes) [footsteps, metal, barefoot, ringing] barefoot footstep on metal
footsteps.gravel_barefoot (4 takes) [footsteps, gravel, barefoot, crunchy] barefoot footstep on gravel
footsteps.sand_barefoot (4 takes) [footsteps, sand, barefoot, soft] barefoot footstep on sand
footsteps.water_barefoot (4 takes) [footsteps, water, barefoot, splashy] barefoot footstep on water
footsteps.snow_barefoot (4 takes) [footsteps, snow, barefoot, crunchy] barefoot footstep on snow
## surfaces
grass [footsteps, soft] Footsteps on grass (soft).
stone [footsteps, hard] Footsteps on stone (hard).
wood [footsteps, hollow] Footsteps on wood (hollow).
metal [footsteps, ringing] Footsteps on metal (ringing).
gravel [footsteps, crunchy] Footsteps on gravel (crunchy).
sand [footsteps, soft] Footsteps on sand (soft).
water [footsteps, splashy] Footsteps on water (splashy).
snow [footsteps, crunchy] Footsteps on snow (crunchy).
## footwear
shoe [light, sneaker, casual] A light shoe or sneaker: soft, quick steps.
boot [heavy, armour, soldier] A heavy boot: weighty, solid steps.
barefoot [barefoot, quiet, natural] Bare feet: soft, fleshy steps.
## beds
forest [nature, outdoor, birds, fantasy] forest ambience, gentle wind through leaves, scattered distant birdsong, soft rustling foliage
city [urban, traffic, crowd, modern] busy city street ambience, distant traffic hum, passing cars, faint crowd murmur, occasional far horn
cave [underground, dungeon, drips, dark] deep cave ambience, dark low rumble, slow water drips echoing, hollow reverberant air
wind [weather, mountain, outdoor, cold] strong howling wind ambience on an open mountain, gusting, whistling
rain [weather, storm, outdoor, calm] steady rain ambience, rain falling on leaves and ground, soft distant thunder rumble
station [scifi, space, interior, machinery] space station interior ambience, low electrical hum, air recyclers, soft machinery drone, distant beeps
shore [beach, ocean, waves, outdoor] ocean shore ambience, gentle waves washing on sand, soft surf, distant seagulls
night [nature, crickets, outdoor, calm] summer night ambience, chirping crickets, soft frogs, light breeze
```
## Tests
`soundstageTests` covers the clip table, the mix and ducking, music states, tiers and shared state, the effect banks and their cooldowns, footstep surface lookup (plain ground uses the default), cadence and footwear, the `Footsteps` component and NPC walkers, ambience blending, a second play session getting fresh voices, the catalog and this README's Quick start. Run it with `tools.use("tests", "run", { suite = "soundstageTests" })`.
## Changes in 2.1.3
- Tests read the package's own files wherever it is installed (also as another package's dependency), check that the eight shipped surfaces are present rather than that a world defines no others, and the kit index states the package version (it had stayed at 2.1.1).
## Changes in 2.1.2
- Footsteps: surface resolvers (`setResolver`, `resolver`, `surfaceAt`), so content can say what a walker stands on where the floor has no mark, attribute or telling name. Walker steps and `play{ at }` ask them first. Nothing changes for a world that sets none.
## Changes in 2.1.1
- The example level's Prowler now paces across the middle of the wooden pier, so its bare feet are heard on wood. Before, it stood on the edge between the pier and the metal deck and its steps read as metal.
- The example's pier looks like wood: weathered oak planks, a tiling PBR material that ships in the package as `soundstage.examples.pier_wood`.
- The two guides have names and descriptions that say what they are for, so they carry the words people search with: `how-to-add-combat-music-footstep-sounds-and-ambient-sound` and `example-level-combat-music-footsteps-on-surfaces-ambience-by-area`.
## Changes in 2.1.0
- Fixed: from the second play session in the same editor session, music, ambience beds, sound effects and voice lines could stay silent, because the kit reused voices that had gone away when play stopped. The kit now checks each voice it keeps and builds a new one when it is gone.
- Fixed: editing the kit's `core` module in a world (which reloads it in place) stopped music fades, ambience, footsteps and ducking until the other kit modules reloaded too. The kit's per-frame steps now survive a reload.
- New: two guides, a how-to and a step-by-step example level (see [Guides](#guides)).
## Upgrading from 1.x
- Footsteps are now opt-in. Add the `Footsteps` component to your player's body (or call `Footsteps.everyPlayer()` once) to keep them.
- Unmarked ground now sounds like your default surface. In 1.x an engine material name could make it read as metal.
- New: per-sound cooldowns (`Sfx.setCooldown`), bare feet, and footwear chosen on the `Footsteps` component.
Version 2.1.3.
# menusKit
Every menu a game needs, as one styled screen stack: **title, pause, settings, game over, victory, loading and credits**. One call puts a finished screen up, and the game listens for what the player picked. There are **8 looks** (sci-fi, fantasy parchment, cartoon, pixel retro, minimal, military, horror, cozy) and **4 layouts** (centred list, side rail, card carousel, radial). One `setTheme` or `setLayout` call restyles every screen at once. It works with **keyboard, gamepad and touch**, and ships in **English, Brazilian Portuguese and Spanish**.
**One-step install:** install menusKit from ZeroMind and you are done. It brings controlsKit (button prompts, input reading and rebinding) along by itself and spawns its own menu host, so there is nothing to place in a scene. See *Install and use*.
It is built for multiplayer worlds:
- Pause is **per player**. Escape, Start or the on-screen pause button pauses only that player's game and stands their character down, while the world and everyone else carry on.
- Settings are per player. They apply immediately and are saved with the player, so they are back when the player rejoins.
- It works with keyboard, gamepad and touch, down to phone-sized screens. Each screen is a fixed screen-space area at the window's corner, so its backdrop covers the whole display, under the notch and the home bar, while its text and buttons stay inside the safe area (plus any `insets` the game asks for). This was checked with simulated safe areas in the editor, not on a real phone; see *Known limits*.
- Every word on screen comes from a string table. English, Brazilian Portuguese and Spanish ship with it, the language follows the player, and settings has a picker.
Version **1.4.0**, built against controlsKit 1.3.2.
**Guides:** two guides ship inside the package. *Main menu, pause menu and settings screen for my game* explains how the pieces fit together and what to do first; *How to add a pause menu to my game* walks from an empty world to a playable game with menusKit and controlsKit. Once the kit is installed, open them from `menusKit.package/guides/` in the Docs panel or with the `guides` tool (for example the path `menusKit.package/guides/how-to-add-a-pause-menu-to-my-game`).
## Install and use
Install menusKit and you are done. It is one install:
```lua
tools.use("zeromind", "installAsset", "61aaf7c0-6b6e-4451-9141-a5ef7a087272") -- menusKit
```
menusKit uses **controlsKit** (from Thumbstick Studio, guid `889ac3ad-87d6-427a-8bc4-3e955943fa6c`) for the button-prompt glyphs, keyboard and pad reading, and the button-rebinding screen. You don't install it yourself:
- **It comes in by itself.** controlsKit is a declared dependency, so the install brings it along, at `/source/deps/<id>/controlsKit.package`. If your world already has controlsKit, that copy is used.
- **Any folder works.** Install menusKit wherever you like (`/source`, `/source/games/myGame`, ...). The two kits find each other by asset name (`menusKit.menus`, `controlsKit.controls`), not by path, so nothing has to sit in a particular place.
You can also search ZeroMind for "menusKit" (home world: *Press Start Studio*, guid `37a0d1f9-9896-4626-b140-43fea7fbedeb`) and install it from there.
Then paste this at the end of your main scene's entrypoint (`/source/scenes/main.scene/entrypoint.luau` in a new world; the rest of that file is comments, so it can stay). It runs as written, in edit and in play, with no other code:
```lua
local Menus = require("menusKit.menus")
-- Your game's own actions. Replace the prints with your code.
local function startRun()
print("Start the run")
end
local function restartLevel()
print("Restart the level")
end
local function leaveGame()
print("Leave the game")
end
-- onLoad runs when the scene starts in play.
function onLoad()
Menus.on("play", startRun) -- the menu closes by itself
Menus.on("retry", restartLevel)
Menus.on("quit", leaveGame)
Menus.showTitle({ title = "My Game", theme = "pixel" })
end
```
Pressing Play prints "Start the run" and closes the menu. The same calls work from any script or component. A handler added while play is running lasts until play stops, so registering in `onLoad` each time play starts never doubles up; one added in edit mode (a module's top level) stays. Later, from your game:
```lua
local Menus = require("menusKit.menus")
Menus.showGameOver({ score = 12040, best = 15500 }) -- Retry calls restartLevel
Menus.showVictory({ score = 48210, time = 271, stars = 2 })
Menus.setTheme("horror") -- every screen restyles at once
Menus.setLayout("radial") -- every screen re-arranges at once
```
That is all a game needs. Pause, settings, the touch pause button, sounds, transitions, saving and translation all work without further code. The kit spawns its own local host (`MenusHost`) the first time it is used in play, so there is nothing to place in a scene.
`Menus.show(name, opts)` opens any screen by name (`"title"`, `"pause"`, `"settings"`, `"gameover"`, `"victory"`, `"loading"`, `"credits"`) with the same options as its own call. For settings, `opts.tab` picks the tab.
### Add it in the editor
With no code at all, add the **`menusKit.MenusScreen`** component to any entity in a scene, or to the player prototype. Its inspector fields are:
| Field | What it picks | Default |
|---|---|---|
| `theme` | the look, from a dropdown of all 8 | `scifi` |
| `layout` | the layout, from a dropdown of all 4 | `list` |
| `startScreen` | the screen it opens when play starts: `title`, `loading`, `settings`, `credits`, `gameover`, `victory`, `pause` or `none` | `title` |
| `title` | the game name on the title screen (blank shows "menusKit") | blank |
When play starts it styles every screen and opens the start screen for the local player. Changing `theme` or `layout` while playing restyles every open screen at once. On a player prototype only the local player's copy runs. Your game still listens for choices in code, with `Menus.on("play", fn)`.
## Looks
`Menus.themes()` lists them (it returns the same list as `Menus.looks()`; each entry's `name` is what `setTheme` takes), and `Menus.describe(name)` returns one. Every look styles all 7 screens with its own fonts, colours, frames, focus treatment, enter/exit transitions, ambient motion and four synthesised UI sounds (move, confirm, back, open).
| Name | Look | What it is like | Fonts (title / body) | Mood | Fits | Best input |
|---|---|---|---|---|---|---|
| `scifi` | Sci-Fi | Holographic HUD panels, chamfered glass, cyan glow and a scanning line. | Archivo Black / JetBrains Mono | sleek, tense, high-tech | shooter, space, strategy, racing | gamepad, keyboard |
| `fantasy` | Fantasy Parchment | An illuminated scroll on dark oak: serif ink, gilt rules, a wax-red ribbon for the chosen line. | EB Garamond / Gelasio | epic, storybook, warm | rpg, adventure, strategy, card | mouse, keyboard, touch |
| `cartoon` | Cartoon | Thick ink outlines, candy colours, chunky drop shadows and everything bounces. | Archivo Black / Comic Neue | playful, bright, silly | party, platformer, kids, casual | touch, gamepad |
| `pixel` | Pixel Retro | 8-bit arcade: stepped frames, chunky shadows, a blinking cursor and CRT scanlines. | Cousine / Cousine | nostalgic, arcade, upbeat | platformer, arcade, roguelike, puzzle | gamepad, keyboard |
| `minimal` | Minimal | Quiet editorial white: one typeface, hairlines, generous space and a single red accent. | Arimo / Arimo | calm, elegant, focused | puzzle, narrative, indie, sports | mouse, touch, keyboard |
| `military` | Military | Tactical briefing: olive drab, stencil caps, hazard stripes, numbered orders and an amber cursor. | Anton / Cousine | gritty, serious, tactical | shooter, strategy, survival, simulation | gamepad, keyboard |
| `horror` | Horror | Candle-dark and wrong: blood-red serif, a vignette that breathes, drifting fog and lights that flicker. | PT Serif / Tinos | dread, dark, unsettling | horror, survival, thriller, mystery | keyboard, gamepad |
| `cozy` | Cozy | Warm cottage afternoon: soft rounded cards, peach and sage, floating petals and a gentle bob. | Bricolage Grotesque / Arimo | warm, gentle, relaxing | farming, life-sim, puzzle, crafting | touch, mouse, gamepad |
Aliases work everywhere a name does: `sci-fi`, `parchment`, `toon`, `retro`, `8bit`, `pixel retro`, `clean`, `army`, `spooky` and `warm`.
## Layouts
`Menus.layouts()` lists them. A layout arranges the choice screens (title, pause, game over, victory) on top of any look. Settings, loading and credits keep their own arrangement, which adapts to the screen shape.
| Name | Layout | What it is like | Mood | Fits | Best input |
|---|---|---|---|---|---|
| `list` | Centred List | Title on top, a framed column of choices in the middle. The classic; reads instantly on any device. | classic, clear | any | any |
| `rail` | Side Rail | A tall panel down the left edge holds the title and choices; the rest of the screen stays open for the game behind it. | cinematic, modern | action, shooter, racing, open-world | mouse, keyboard |
| `carousel` | Card Carousel | Big illustrated cards slide sideways with the focused one centred and its neighbours peeking in. Made for thumbs and shoulder buttons. | playful, showcase | party, casual, mobile, fighting, kart | touch, gamepad |
| `radial` | Radial Menu | Choices ring a central hub; point the stick at one to pick it, the hub names it. Fast and satisfying on a gamepad. | dynamic, tactile | action, shooter, adventure, console | gamepad |
Aliases: `centered`, `centred`, `column`, `side`, `sidebar`, `cards`, `card`, `wheel`, `ring`, `pie`.
### Picking one by tags
```lua
local best = Menus.match({ mood = "dark", genre = "survival", input = "gamepad", kind = "look" })
Menus.setTheme(best[1].name) -- "horror"
local all = Menus.catalogue() -- { version, looks, layouts, screens, events, languages, settings }
```
## Screens
| Screen | Call | Default choices | Notes |
|---|---|---|---|
| Title | `showTitle{ title, subtitle, version, canContinue, items, theme, layout, credits }` | play, continue, settings, credits, quit | Continue is greyed out unless `canContinue = true`. Replaces whatever was open. |
| Pause | `showPause{ items, restart }` | resume, settings, mainMenu, quit | Opens by itself on Escape / P / Start / the touch button. `restart = true` adds Restart. |
| Settings | `showSettings(tab)` | tabs: audio, controls, graphics, language | Opened from the Settings choice of title or pause. Back returns there. |
| Game over | `showGameOver{ score, best, time, title, subtitle, items }` | retry, mainMenu | `time` is in seconds and shown as mm:ss. |
| Victory | `showVictory{ score, best, time, stars, maxStars, stats, title, subtitle, items }` | next, retry, mainMenu | `stats = {{ label, value }}` adds lines. Stars are out of 3 by default. |
| Loading | `showLoading{ title, tips, progress, tipSeconds }` | none | Tips rotate every `tipSeconds` (4.5). `progress = nil` shows a looping bar. Drive it with `setProgress(p)`. |
| Credits | `showCredits{ title, sections, speed, thanks, loop }` | none | `sections = {{ title = "Design", names = { "Ada Park" } }}`. It scrolls at `speed` pt/s (46) and ends by itself. |
`items` replaces a screen's choices. Each one is an id string, or `{ id, text, desc, icon, disabled }`. `text` is a string key or plain text, and choosing it emits an event named after its id.
```lua
Menus.showPause({ items = { "resume", { id = "shop", text = "Shop", icon = "storefront" }, "settings", "quit" } })
Menus.on("shop", openShop)
```
## Events
`Menus.on(event, fn)` returns a handle for `Menus.off(handle)`. `fn(info)` receives `info = { id, screen, opts, ... }`.
```lua
Menus.on("settingsChanged", function(info)
print(info.key, info.value) -- e.g. "music", 4
end)
```
| Event | When |
|---|---|
| `play`, `continue`, `settings`, `credits`, `quit` | The title's choices. |
| `resume`, `restart`, `mainMenu` | The pause menu's choices. `resume` also fires whenever pause closes. |
| `retry`, `next` | Game over and victory. |
| `pause` | This player paused (any way). |
| `back` | The player went back one screen (`info.screen` is the one that closed). |
| `select` | Any choice was picked (`info.id`, `info.screen` = the screen it was picked on). It fires last: after the choice's own event and after any screen change the choice causes. Picking Settings fires `show`, `settings`, `select`; Main Menu fires `mainMenu`, `show`, `select`; Play fires `play`, `hide`, `select`. |
| `show` / `hide` | A screen was pushed or shown (`info.screen`) / every menu closed. |
| `settingsChanged` | A setting really changed (`info.key`, `info.value` = the new value). It fires for every way a setting changes: keyboard, gamepad or touch on the settings screen, Reset to defaults (once per setting it changed), the game calling `setSetting` / `setLanguage`, and a saved copy that arrives late. Setting a value it already has (or one that clamps to it) fires nothing. Rebound buttons fire it with `info.key = "bindings"` and the bindings now in use (`{ scheme, bindings }`), when the rebinding screen closes and when the controls tab is reset. |
| `creditsEnd` | The credits finished (`info.skipped = false`) or the player backed out (`true`). It fires exactly once. |
| `loadingDone` | `setProgress` reached 1. It fires once per loading screen. |
| `theme` / `layout` | The look or layout changed (`info.name`). |
**Event names are checked.** `Menus.on` raises at once on a name that doesn't exist, so a typo can't leave a game that never reacts. The error lists every event name that exists and suggests the closest one:
```
menusKit.on: unknown event 'settingChanged'. Did you mean 'settingsChanged'? Events: play, continue, ... For a custom menu choice, show it on a screen first or declare it with Menus.addEvents("settingChanged").
```
**Custom choices** are events named after their id. `on` accepts one once a screen has shown it (as in the Shop example under *Screens*), or once the game has declared it with `Menus.addEvents("shop")`. Declare it first when you subscribe before opening the screen:
```lua
Menus.addEvents("shop")
Menus.on("shop", openShop)
-- later
Menus.showPause({ items = { "resume", { id = "shop", text = "Shop" }, "settings", "quit" } })
```
**Old name.** `setting` was the 1.2.0 name of `settingsChanged`. It still works in 1.x as an alias (`Menus.EVENT_ALIASES`): `Menus.on("setting", fn)` gets the same events and prints a warning once telling you to switch to `settingsChanged`. It will be removed in 2.0.
With the default `autoClose = true`, picking play, continue, retry, next or restart closes the menus. mainMenu, and quit from anywhere but the title, returns to the last title screen. Settings and credits open their screens. Your game only has to react.
## Settings
Each player has their own settings. A change applies the moment it is made and is saved to that player's own data (`runtime_data.player`), so it is restored when they come back, whichever session of the world they land in.
How the saved copy behaves:
- One leaf per setting under `menusKit/settings/` (`menusKit/settings/music`, …). Only what the player changed is written; a setting they never touched is never saved, so a later default change reaches them.
- A saved copy that reaches the machine after the menus opened (the player's data can arrive a moment after they join) is taken up when it arrives and applied. It is never overwritten by the defaults that stood in for it.
- A player identity that arrives late is picked up too: what was changed before it is saved once it exists.
- Rebound buttons are saved as `menusKit/settings/bindings`, together with the scheme they belong to. They are imported when that controlsKit scheme is active, or as soon as it becomes active; menusKit never switches the game's scheme to apply them.
- The single table menusKit 1.0.0 saved at `menusKit/settings` is still read. A leaf wins over it.
- `MenusHost` drives all of this by calling `Settings.tick(dt)` every frame. A game that only uses `menusKit.settings` without the host calls `Settings.load()` once and `Settings.tick(dt)` from its own update.
| Key | Values (default) | What it changes |
|---|---|---|
| `master` | 0 to 10 (8) | Master volume. |
| `music` | 0 to 10 (7) | The `music` channel. |
| `effects` | 0 to 10 (8) | The `sfx` and `ui` channels. |
| `voice` | 0 to 10 (8) | The `voice` and `dialogue` channels. |
| `sensitivity` | 1 to 10 (5) | Camera look speed. `Menus.lookScale()` gives the multiplier (1.0 at 5, 2.0 at 10) for games with their own camera. |
| `invertY` | true / false (false) | Inverts the camera's vertical look. |
| `prompts` | auto, keyboard, xbox, playstation, switch, generic (auto) | Which controlsKit glyph set the prompts show. |
| `quality` | auto, low, medium, high (auto) | The renderer's quality tier. |
| `language` | auto, en, pt-BR, es, … (auto) | The menus' language. `auto` follows the player's own. |
The controls tab also has **Rebind buttons**, which opens controlsKit's rebinding screen for the scheme the game uses. It is greyed out when the game has no controlsKit scheme active. Each tab has **Reset to defaults**.
```lua
Menus.setSetting("music", 3)
print(Menus.getSetting("quality"), Menus.settings().language)
```
### A setting another system owns, and rows of your own (1.4.0)
The settings rows are no longer a fixed set. `menusKit.settings` takes two calls:
- `Settings.provide(key, provider)` hands one setting to another system. menusKit then neither applies nor saves it: the provider does both, and the row shows the provider's values, words and, when it has one, its own control. `Settings.provide(key, nil)` hands it back, and menusKit applies its own value again.
- `Settings.addRow(tab, key, provider)` adds a row of your own to a tab (before its reset button); `Settings.removeRow(tab, key)` takes it off. `Settings.keys(tab)` lists what a tab shows.
A provider is `{ get, set, choices, valueText, label, hint, kind, wide, reset, step, control }`: `get` and `set` are required; `choices()` lists what left / right, the arrows and a press cycle through; `kind` is `"choice"` (default), `"toggle"`, `"slider"` or `"button"`; `wide` puts the control under its label at the row's full width; `reset()` is what the tab's reset button does to it; `control(ctx)` returns the widget the row draws, where `ctx = { width, theme, look, focused, compact, uid, idFor(value), cycleId(dir) }` and a click on `idFor(value)` sets that value. `Settings.refresh(key)` redraws an open settings screen after the value changed elsewhere.
```lua
local Settings = require("menusKit.settings")
Settings.addRow("graphics", "outlines", {
kind = "toggle", label = "Outlines",
get = function() return Outlines.enabled end,
set = function(v) Outlines.setEnabled(v == true) end,
valueText = function(v) return if v then "On" else "Off" end,
})
```
**Graphics Presets** (`graphicsPresets`, formerly graphicsSettingsKit) uses this for the `quality` row: with it installed, `Gfx.setup` provides `quality`, so the Graphics row shows the game's own graphics steps (Auto, Low, High, ...) drawn as the kit's picker (switch, segmented bar, cards or slider) in the menu's look, and every change goes through the kit, which applies and saves it. Without a provider the row is menusKit's Auto / Low / Medium / High as before.
## Input
| | Keyboard | Gamepad | Touch / mouse |
|---|---|---|---|
| Pause / back out | Escape, P | Start | the pause button (top right, touch only) |
| Move focus | arrows, WASD | left stick, d-pad | tap / hover; swipe the cards sideways (carousel) |
| Choose | Enter, Space | A (south) | tap / click |
| Back | Backspace | B (east) | the on-screen back button |
| Settings tab | Q / E | LB / RB | tap the tab |
| Radial layout | arrows | point the stick at a choice | tap |
On the card carousel a sideways drag on the cards moves one card per step (with a finger or a held mouse button), and lifting the finger at the end of a swipe never counts as a tap. A tap without a drag picks the card drawn under the finger. While the cards slide to a new focus (0.34 s), a tap goes to the card whose resting place is under the finger, which can be the neighbour of the card drawn there mid-slide.
Prompts along the bottom show the right glyphs for the device in use (from controlsKit) and hide on touch. While any menu is open, `Menus.inputBlocked()` is true. The kit's input map stands gameplay input down for that player, and the player's controlsKit controller is released, so a controlsKit-driven character stops. A game reading devices itself should check `Menus.inputBlocked()`.
The `pause` option of `setup` turns Escape/Start pausing off, and `pauseButton = "auto" | true | false` controls the touch pause button.
### With controlsKit
menusKit uses controlsKit for prompt glyphs, pause/back/confirm and the rebinding screen. It arrives with menusKit as a dependency and is found by name wherever it lands. One thing to know when your game also drives its character with a controlsKit scheme:
- **One pause button on touch.** Every controlsKit scheme draws its own touch-corner pause button, and menusKit doesn't listen to it. Register a copy of your scheme without it, so a phone shows menusKit's button only:
```lua
local Schemes = require("controlsKit.schemes")
local s = Schemes.get("platformer") -- a fresh copy, safe to change
s.touch.corner = {}
Schemes.register("myGame", s)
require("controlsKit.controls").use("myGame")
```
Or keep controlsKit's button and call `Menus.setup({ pauseButton = false })`.
## Languages
All text comes from string tables in `menusKit.strings`: English (`en`), Brazilian Portuguese (`pt-BR`) and Spanish (`es`). Open screens re-translate the moment the language changes.
```lua
Menus.setLanguage("es") -- or "auto" to follow the player
Menus.addLanguage("fr", "Français", { ["menu.play"] = "Jouer", ["menu.quit"] = "Quitter" })
Menus.text("result.best", { best = "15,500" }) -- "Best: 15,500"
Menus.showTitle({ title = { en = "Star Forge", es = "Forja Estelar" } }) -- inline translations
```
Missing keys fall back to English. `require("menusKit.strings").keys()` lists every key a translation should cover.
## API
### `menusKit.menus`: what games use
**Constants**
- `VERSION` (`"1.4.0"`), `SCREENS`, `EVENTS`, `DEFAULT_ITEMS`.
- `EVENT_ALIASES`: old event names that still work, and the name each stands for (`{ setting = "settingsChanged" }`).
- `SCREEN` / `PAUSE_SCREEN`: the ui screen ids `menusKit_menu` and `menusKit_pauseBtn`.
- `LAYER` (950): the ui layer the menu screen registers at. Its root is a screen-space `area`, so a game's own screens at layer 1000 or above draw over the menus, and anything below 950 draws under them. The touch pause button sits at `LAYER - 10`.
**Screens**
- `showTitle(opts)`, `showPause(opts)`, `resume()`, `showSettings(tab?)`, `showGameOver(opts)`, `showVictory(opts)`.
- `showLoading(opts)`, `setProgress(p)`, `showCredits(opts)`.
- `show(name, opts?)`: any of the above by name; `opts.tab` picks the settings tab. Raises on an unknown name, listing the screens.
- `hide()`: closes everything.
- `back() -> boolean`: false on a screen with nothing behind it.
**State**
- `current() -> string?`, `stack() -> {string}`.
- `isOpen()`, `isPaused()`, `inputBlocked()`.
**Events**
- `on(event, fn) -> handle`, `off(handle) -> boolean`. `on` raises on an event name that doesn't exist.
- `events() -> {string}`: every name `on` accepts right now (`EVENTS`, then the custom choice ids shown or declared).
- `addEvents(...)`: declare custom choice ids (strings or lists of strings) so `on` accepts them before a screen shows them.
**Style**
- `setTheme(name, quiet?)`, `setLayout(name, quiet?)`, `theme()`, `layout()`.
- `setup(cfg)` (alias `configure`) with `{ theme = "scifi", layout = "list", pause = true, pauseButton = "auto", sounds = true, soundLevel = 1, autoClose = true, credits = nil, transitions = true, insets = nil }`. `insets = { top, left, right, bottom }` keeps that many extra points clear on every screen and around the touch pause button, for a game HUD that must stay visible.
- `config()`: a copy of the current options.
**Catalogue**
- `looks()`, `themes()` (the same list as `looks()`), `layouts()`, `describe(name)`.
- `match{ mood, genre, input, kind }`: sorted best first, each entry with a `score`.
- `catalogue()`.
**Settings and text**
- `settings()`, `getSetting(key)`, `setSetting(key, value)`, `lookScale()`. `getSetting("bindings")` returns a copy of the controlsKit bindings in use (`{ scheme, bindings }`), or nil with no scheme active.
- `text(key|table, vars?)`, `addLanguage(tag, name, strings)`, `setLanguage(tag)`, `language()`.
**Navigation** (what the host calls; handy for tests and custom input)
- `navigate("up"|"down"|"left"|"right") -> boolean`.
- `focus(i) -> boolean`, `focused() -> (index, id)`, `items()`, `select()`.
- `tab(dir|name)`, `togglePause()`.
- `handle(uiId) -> boolean`: the screens' click ids, `mk:item:<i>`, `mk:back`, `mk:set:<key>:inc` and so on.
**Rendering** (what the host draws)
- `build(w, h, safe?, { prompt, touch }) -> tree?`.
- `buildPauseButton(w, h, safe?) -> tree?`.
Functions starting with `_` are internal.
### Supporting modules
These are mostly internal, but stable enough to extend:
- **`menusKit.themes`**: the 8 looks.
- `list()`, `get(name)`, `canonical(name)`, `describe(name)`.
- `fitTitle(look, ctx, text, size)`, `helpers`.
- `ICONS`: the icon each default choice uses. `icon(ref, size, color)` draws an icon node (the same as `Icons.node`).
- `fonts(name) -> {string}`: the font families a look uses. MenusHost checks they are registered and re-registers the builtin fonts if a web build's font loading raced the first frame, so every look shows its own font.
- **`menusKit.icons`**: the kit's own 32 SVG icons, drawn in the text colour. They need no icon font, so they show the same in the editor, a native build and the web player.
- `names()`, `aliases()` (for example `storefront` draws `shop`), `has(ref)`.
- `svg(ref, opts?) -> string?`, `node(ref, size, color?, opts?) -> tree?`.
- An item's `icon` can be any of these names, an alias, or an inline `<svg>` document.
- **`menusKit.layouts`**: the 4 layouts.
- `list()`, `get(name)`, `canonical(name)`, `describe(name)`.
- Each layout has `compose`, `nav` and `stepKeys`. The carousel also has `metrics(ctx, n, reserve?)`; the radial has `angle`, `pick` and `metrics(ctx, n, hasTitle, subH?)`. The optional height is the room the screen keeps for its title, score block and prompts, so the cards or the ring shrink to fit.
- **`menusKit.screens`**: builds each screen's widget tree.
- `NAMES`, `TABS`, `context(w, h, safe?, extra?)`, `build(name, state)`.
- `context` returns `w`/`h` (the space content may use), `fullW`/`fullH` (the whole screen), `compact`, `portrait`, `safe`, `extra` and `inset` (safe + extra on each side). A screen's root is a fixed `area` at the window's origin (screen space, not moved by the safe area); inside it a full-screen stage draws the backdrop to the screen edges, and the content sits at `inset`.
- One builder per screen, plus `promptStrip`, `tipText`, `pauseButton`.
- Credits: `defaultCredits()`, `creditsHeight(sections)`.
- **`menusKit.settings`**: per-player settings.
- `KEY`, `DEFAULTS`, `PROMPTS`, `QUALITY`, `TABS`.
- `get`, `all`, `set`, `step`, `reset(tab?)`, `choices`, `onChange` / `offChange`.
- `save()` (false when the player has no identity to save under), `load()` (true when a saved copy was found), `isLoaded`, `tick(dt)` (takes up a late saved copy or identity; MenusHost calls it).
- `applyAll`, `applyCamera`, `sensitivityScale`.
- `rows(tab)`, `valueText`.
- Test hooks: `_useStore(fn)` saves and loads through `fn()` instead of the player's data (`_useStore(nil)` puts the live session back); `_forget()` starts over as a player who has just joined.
- **`menusKit.strings`**: string tables.
- `BUILTIN`, `t(key, vars)`, `has`, `keys`.
- `register(tag, name, strings)`, `languages()`, `language()`, `setLanguage`, `resolve`.
- `number(n, decimals)`: locale digit grouping.
- **`menusKit.sounds`**: UI sounds.
- `KINDS`, `clip(look, kind)`, `play(look, kind)`, `setEnabled(on, level)`, `isEnabled()`.
- `synth`, `bake`, `clipName`. The 32 clips are pre-baked under `sounds/`.
- **`menusKit.MenusHost`** (component): spawned automatically. It draws the screens, reads keys, pads and swipes, and routes clicks.
- **`menusKit.MenusScreen`** (component): the editor set-up described in *Add it in the editor*.
- **`menusKit.menuInputBlock`** (inputMap): the map that stands gameplay input down while a menu is open.
## Tests
`menusKitTests` covers every public call: the screen stack, events, looks and layouts, settings, languages, navigation, drawing every screen × look × layout on desktop and phone shapes, and each module. Run it in edit mode with `tools.use("tests", "run", { suite = "menusKitTests", onWorker = true })` (121 tests). `onWorker` runs it on a fresh module graph; without it, it runs on the engine thread against the modules already loaded. The suite saves and loads through a stand-in store and pins its own language, so it passes the same on any engine whatever the player running it has saved, and never touches their real settings.
## Changelog
- **1.4.1**: the docs name the graphics kit by its new name, Graphics Presets (`graphicsPresets`, formerly graphicsSettingsKit). No code change.
- **1.4.0**: settings rows are no longer a fixed set. `Settings.provide(key, provider)` hands a setting to another system, which applies and saves it and may draw the row's own control; `Settings.addRow(tab, key, provider)` / `removeRow` add rows of the game's own; `Settings.keys(tab)` and `Settings.refresh(key)` go with them. A row control's click `mk:set:<key>:pick:<value>` sets that value. graphicsSettingsKit provides the `quality` row this way, so the Graphics tab shows the game's graphics steps through the kit. Nothing changes for a game that provides nothing: the same rows, values, saving and callbacks as 1.3.20. @builtin upgraded to 7f5b405.
- **1.3.20**: the API list names the real `VERSION` (it said "1.3.5"); `VERSION`, `package.yaml` and the test agree on 1.3.20. Behaviour is unchanged.
- **1.3.19**: MenusHost, themes and settings are published again so their controlsKit references record controlsKit 1.3.2. A file records the releases it names only when a commit takes that file, and in 1.3.18 MenusHost still named controlsKit 1.3.1 and themes 1.3.0, so an install still landed three controlsKit releases. Every controlsKit name menusKit uses now records one release. No behaviour changed.
- **1.3.18**: menusKit now really runs one controlsKit release. This world held an empty leftover `controlsKit.package/controls.module` folder from an old local copy, so MenusHost, menus and settings recorded `controlsKit.controls` at that empty folder while `controlsKit.rebindScreen` came from the installed controlsKit, and an install landed controlsKit 1.3.2 plus the 1.3.1 and 1.3.0 copies. The leftover is gone and controlsKit 1.3.2 is installed fresh, so every controlsKit name menusKit uses records the same release. No behaviour changed.
- **1.3.17**: built against controlsKit 1.3.2, the first controlsKit release that installs as one copy (1.3.1 still pointed some of its own files at 1.3.0), and menusKit now names its own input map relatively (`asset.resolve("~.menuInputBlock", "inputMap")`), so a menusKit release never points at an older menusKit. Installing menusKit lands one menusKit and one controlsKit. The world moved to the current engine library. No behaviour changed.
- **1.3.16**: every menu screen holds the pointer (`holdsPointer` on its root), so in a game whose camera captures the mouse the cursor comes free while a menu is up and clicks reach its buttons. Before, a victory or game over screen opened mid-game could not be clicked at all (Castaway Isle's dawn screen).
- **1.3.15**: a finger's tap works the choice under it on the title, pause, game over and victory menus. In some engine builds a tap does not reach a `button` widget as a click at all (it does not even hover it), so a touch-only player could not pick "Keep surviving" or "Main menu" on a victory screen. MenusHost now reads short taps from `input.events()` itself, finds the choice under the finger (`Menus._itemAt(x, y)`, from each row's layout rect) and focuses and selects it, unless the engine delivered the tap as a click already. Checked in play (Castaway Isle): a real dawn shows the victory screen, a simulated tap on "Keep surviving" closes it; Enter and pad A still do.
- **1.3.13**: built against controlsKit 1.3.1 (was 1.2.8), the release economyKit and towerDefenseKit ship with, so a world that installs menusKit beside them holds one controlsKit. No code change.
- **1.3.12**: the camera settings no longer cost a frame with a crowd. `Settings.applyCamera` (run every 2 s) read two camera components on every entity in the scene each time, about 19 ms a frame in a tower defense with 150 enemies and their shots. Now each entity is checked once for a camera controller, entities that are gone are forgotten, and a camera is written only when look sensitivity or invert Y changed. Same behaviour for players. Fixes #4.
- **1.3.11**: built against controlsKit 1.2.8, the release every package that ships with sideScrollerKit moves to together. A package's dependency on controlsKit resolves to the release controlsKit's world ships, so a menusKit built against an older one still landed two controlsKit copies in a fresh world; built against the newest, it lands one. No change to menusKit itself.
- **1.3.10**: one controlsKit release throughout. menusKit is built against the published controlsKit 1.2.4, the release twoDKit, sideScrollerKit, abilitiesKit and saveKit are built against, so a world that installs them together holds one copy of controlsKit and every file reads that same copy. The controls module change 1.3.7 carried (later published as controlsKit 1.2.6) only reworded a comment, so controlsKit needed none of it. No change to menusKit itself.
- **1.3.9**: installs again. 1.3.8 recorded controlsKit's controls module as an empty file; 1.3.9 holds it exactly as controlsKit 1.2.6 publishes it.
- **1.3.8**: installs again. 1.3.7 was published against a copy of controlsKit's controls module that only this world held, so every install of menusKit (and of saveKit, which brings it) failed reading it. That build is now published as controlsKit 1.2.6, and 1.3.8 is built against it. No change to menusKit itself.
- **1.3.7**: the number drawn beside each choice ([01], [02], ...) picks it. Keys 1 to 9, on the top row or the number pad, choose that choice on the title, pause, game over and victory menus, exactly as moving the focus there and pressing select would (the choice's own event, then `select`). A disabled choice ignores its number. Before, the numbers were only labels. `Menus.numberKey()` answers which number was pressed this frame. `Menus.VERSION` and the version line at the top of this README read the package version again (they had stayed at 1.3.4 and 1.3.5).
- **1.3.5**: a game's own look. `require("menusKit.themes").define(name, spec)` adds a look built on a builtin one (`spec.base`, default fantasy): every field the spec leaves out comes from the base, the spec's own `backdrop`, `title`, `item`, `pal` and so on replace it, and the base's ornament fonts are loaded for it. `Menus.setTheme(name)` then uses it like any other look.
- **1.3.4**: the `select` event documented as it really fires, and no long dashes left.
- **`select` order.** The events table said `select` fires before the choice's own event. It fires last, after the choice's own event and after any screen change the choice causes (for example Settings fires `show`, `settings`, `select`, and Main Menu fires `mainMenu`, `show`, `select`). The table now says so. The behaviour is unchanged; a new test pins the order (121 tests).
- **No long dashes.** The comments at the top of the kit's scripts and the names of the test groups used long dashes; they now use ordinary punctuation, as do the gallery and the scenes. No behaviour changed.
- **1.3.3**: docs only.
- **With controlsKit.** The note about the builtin touch controls coming back over controlsKit's on a second editor Play is gone. controlsKit 1.1.0, which a menusKit install brings, keeps its takeover across Play, Stop and Play (checked over three rounds in a fresh world). The code is the same as 1.3.2 apart from the version number.
- **1.3.2**: two guides, and a check on today's engine.
- **Guides.** Two guides now ship inside the package, so they arrive with every install: *Main menu, pause menu and settings screen for my game* (how the screen stack, per player pause, saved settings, rebinding, looks and languages fit together, what to do first and where to read on) and *How to add a pause menu to my game* (a worked example, Coin Dash, from an empty world to a playable game with a title, pause, settings and game over with Retry, installing menusKit and controlsKit from ZeroMind). The example was followed step by step in a brand new world.
- **Checked on today's engine, nothing broken.** In a fresh world with menusKit installed on its own, the first example above ran as pasted (the title showed and Play fired). Pause stopped only the player who pressed it while the world carried on, `setTheme` restyled the open screen and the title behind it, the menus answered touch and a gamepad, and the tests passed 120 of 120 twice in a row. The world's built-in library was already current. A fresh install now brings controlsKit 1.1.0, and every check above ran against it.
- **Docs.** Known limits now name only problems that are still open, with their issue numbers. No code changed apart from the version number.
- **1.3.1**: the first README example works when pasted.
- **Self-contained example.** The first example used `startRun`, `restartLevel` and `leaveGame` without defining them, so the strict checker flagged three unknown names and the world refused to enter play or publish. It now defines all three, says where to paste it (the main scene's entrypoint), shows the title from `onLoad`, and keeps the Game Over, Victory, theme and layout calls in a second snippet. It was checked in play, with the strict checker on.
- **Handlers no longer pile up between play runs.** A handler added with `Menus.on` while play is running now ends when play stops. Before, registering in `onLoad` added another copy every time play started, so Play fired twice on the second run, three times on the third, and so on. Handlers added in edit mode are kept as before.
- **Tests.** 4 new: play-session handlers, no pile-up across runs, and the README's first example both passing the strict checker and running as written (Play, Retry and Quit reach the game's own functions).
- **1.3.0**: `settingsChanged`, and event names are checked.
- **`settingsChanged`.** The settings event now has the name it was asked for. It fires on every real change, whether by keyboard, gamepad or touch on the settings screen, by Reset to defaults, or from code, with `info.key` and the new `info.value`. Rebound buttons now fire it too (`key = "bindings"`); before, a rebind or a controls reset was saved without any event. `getSetting("bindings")` reads the bindings in use.
- **Old name kept.** `setting` still works as a documented alias that warns once (`EVENT_ALIASES`). It will be removed in 2.0.
- **Unknown event names raise.** `Menus.on("settingChanged", fn)` used to be accepted and never fire. It now raises at once, listing the event names and suggesting the closest one. A non-string name or a non-function `fn` raises too.
- **Custom choices.** Their ids are still events. `on` accepts one once a screen has shown it, or after `Menus.addEvents(id)`. **Upgrading:** a game that called `Menus.on("shop", fn)` before any screen showed a Shop choice now gets an error; add `Menus.addEvents("shop")` first. `Menus.events()` lists every accepted name.
- **Gallery.** The gallery's settings toast listens to `settingsChanged`.
- **Tests.** 116 tests (9 new: each way a setting changes, the alias, unknown names, custom ids, `addEvents`, rebinds).
- **1.2.0**: the themes list, the title keeps its theme, and two 1.1.0 promises made true.
- **Themes list.** Adds `Menus.themes()`, the same catalogue entries as `looks()` under the name `setTheme` uses. `looks()` is unchanged.
- **Main Menu keeps the current look.** A `theme` or `layout` passed to `showTitle` is applied once and no longer stored with the title. Before, Main Menu (or Quit from pause) brought the title back in the look it was first opened with, undoing any `setTheme` since.
- **Full-bleed backdrop, for real.** 1.1.0 said the backdrop covered the area under the notch and home bar, but on a phone-shaped screen it stopped at the safe area: the stage reached out under the top bar, but the band under the home bar was never painted. Each screen's root is now a fixed `area` at the window's origin, and the backdrop covers the whole screen. Because of this, `LAYER` moves from 1100 to 950, so a game's overlays at 1000+ stay above the menus.
- **Carousel taps.** 1.1.0 said taps worked as before, but a tap on a card picked its neighbour: the card row was moved with a transform, which touches don't follow. The row is now placed by layout and only the slide animation uses a transform, so a tap picks the card under the finger.
- **Room for the score.** The radial ring and the carousel cards now leave room for the game over and victory score block and the prompt strip. Before, the radial's lower choice and its caption ran off the bottom on most screen heights. Screens also go compact below 520 pt of height (was 480).
- **Gallery.** The gallery title shows the kit's current version.
- **Tests.** 107 tests.
- **1.1.0**: phones, touch, fonts and the editor.
- **Safe area.** The backdrop now covers the whole screen, under the notch and home bar, and content stays inside the safe area plus the game's `insets`. Before, a strip at the bottom was bare, and with a large safe area the radial's lower button and the foot of the credits panel were cut off.
- **Radial hub.** The centre is now a disc capped at 220 pt and kept clear of the ring in any window shape. Before, a tall window turned it into a large rounded square running into the choices. The focused choice is named once: by the hub, or by a caption when the hub is too small.
- **Carousel swipe.** Swiping the cards sideways moves the focus on touch and with a held mouse button. Taps work as before.
- **Icons and fonts.** The kit draws its own SVG icons instead of the editor's icon font, so icons no longer show as empty boxes in a play session. MenusHost re-registers the builtin fonts when a look's font is missing, so the pause screen keeps its look's font.
- **Editor.** Adds the `MenusScreen` component (theme, layout, start screen, title) and `Menus.show(name, opts)`.
- **Input map.** The input map is renamed `menuInputBlock` (was `menus`).
- **Tests.** The tests no longer depend on the running player's saved language or settings; 102 tests.
- **Install docs.** The install notes now say where controlsKit lands: it arrives as a dependency under `/source/deps/`, or the world's own copy is used.
- **1.0.1**: settings survive a rejoin however late the player's data arrives.
- Each setting is now its own leaf, and only changed settings are written. Before, defaults that loaded ahead of the saved copy could be written over it.
- A late saved copy or a late player identity is taken up (`Settings.tick`).
- Rebound buttons are kept per scheme and imported when that scheme becomes active.
- The 1.0.0 table is still read.
- The tests use a stand-in store; 89 tests.
- **1.0.0**: first release.
## Known limits
Problems that are still open, with their issue numbers where the cause is outside the kit.
- **Phones are checked in the editor only, and the editor's play view can clip under the insets (#19210).** The backdrop reaching the screen edges and the content staying inside the safe area plus `insets` were measured in the editor with simulated safe areas (a notch, a home bar and a side inset). It has not been tried on a real phone, and the simulated safe area has no effect in a play session. While playing inside the editor with phone safe-area insets, a menu element under the insets (for example the backdrop under the notch or home bar) can show clipped; that is the engine's editor play view, not the kit's layout.
- **Short screens.** At 1280 pt wide, a few screens still run past the bottom of the safe area. With the keyboard or gamepad prompt strip showing, the strip ends up to 44 pt below it on the list victory screen at about 540 pt of usable height (and 8 to 15 pt on the list title in the cartoon and military looks), up to 32 pt below on the carousel victory and game over screens at about 360 pt, and 5 to 28 pt on the side-rail title at about 360 pt. On touch, where there is no prompt strip, only the list victory screen at about 540 pt (9 pt in fantasy, 14 pt in military) and the carousel victory screen at about 360 pt (2 pt) overflow. Where the screen has a bottom inset the overflow lands under the home bar; with none it is clipped at the screen edge. The radial layout fits at every height measured.
- **Carousel taps mid-slide.** While the cards slide to a new focus (0.34 s), a tap lands on the card whose resting place is under the finger, which can be the neighbour of the card drawn there.
- **Per-player pause was checked in one engine (#14448).** Two engines signed in to one account collide as one player, so the check ran in one engine: while one player was paused, a stand-in second player's body and a falling physics body kept moving, and the engine never paused or changed time scale. A check with two real players on two accounts has not been run.
- **The web build was not run (#20946).** An agent inside the engine cannot start a browser engine, so the web player was not checked for this release; the 1.1.0 font fix for the web build was checked in editor play and by reading the code.
- **A fresh install takes about 20 seconds (#21420).** Installing menusKit on its own brings controlsKit and copies of a few engine files with it, about 540 files in all.
- **The guides do not show in ZeroMind library search yet (ZeroMind#3099).** They ship inside the package and are found by the engine's `guides` tool and the Docs panel once the kit is installed.
- **The ZeroMind description can lag a release (#19258).** For a while after a release, ZeroMind may show the previous version's description; the README inside the package is current.
- Rebinding needs the game to use a controlsKit scheme.
- A guest with no player identity can't keep settings between visits. Their choices apply for the session and `save()` returns false.
- A game with its own character controller must read `inputBlocked()` itself if it doesn't go through input maps or controlsKit.