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.

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:

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:

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.

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).

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.

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:

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).
• 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()):

## 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.