# core soundstage's shared plumbing: the per-frame tick the other modules register with, the auto-spawned host, kit-owned Audio voices, the world and player stores (swappable for tests), the listener position, and position conversion. Game code rarely needs it directly.

# clips The table of every shipped soundClip (259 of them), resolved by literal asset reference so it works wherever the package is installed. `Clips.get(name)`, `has`, `names` and `seconds` are used by the other soundstage modules, and by game code that wants a raw clip.

# mix Volume groups (music, sfx, ui, voice, ambience), each mapped to the engine mixer channel of the same name so settings screens such as menusKit's sliders control them. Also ducking envelopes and voice lines that duck the music under dialogue. Used by every other soundstage module and by game code.

# 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. ## 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")`. 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 not separate instrument stems, because the generator writes finished mixes (see [Known limits](#known-limits)). ## 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. ## 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. ## Known limits These come from the engine, not the kit. Each one is filed with the Zero platform under the id given, so it can be followed up. - **Music is not beat-locked between players** (`01M54S59VRHGKFVXC3KJEHGNBQ`). The `Audio` component has no start offset or seek, and there is no clock all players share. 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. - **Intensity crossfades whole takes, not layers** (`01M54S59VXXHSS4ZGWS783WQMM`). The engine's music generation writes finished mixes with no stems, so each state has a low and a high take that are crossfaded, with a volume swell. Going past 0.55 intensity sounds like the piece changing, not an instrument joining. - **A new track can take a moment to start** (`01M54S59W2BD7KRZHX9GY8871Q`). Nothing signals when a newly assigned clip begins playing. 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. - **In the browser, sound starts on the first click, tap or key** (`01M54S59W6DQCG3HR66E1JEEGZ`). Browsers keep audio locked until the player interacts, and `audio.device()` cannot tell content it is still locked. Music and ambience started in `onLoad` are already running and become audible at that first input. - **Relay handlers cannot be removed** (`01M54S59WAAQDZEMTK7X4NDMH6`). `multiplayer.on` has no unsubscribe, so `Sfx.broadcast` listens once per session and ignores messages after a reload or reset. You never see this, but a hot reload in the editor keeps one idle handler. - **Two clients cannot be run from one engine** (`01M54S59WFC5XQQ7TZXMH8GGEH`). The tests check the multiplayer behaviour with stand-in stores and avatars. To hear it for real, open the world in a second browser. ## 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, the catalog and this README's Quick start. Run it with `tools.use("tests", "run", { suite = "soundstageTests" })`. ## 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.0.0.