audio.Clips

The shared sound library of The Eighth Ketyl. Any slice can make a noise through it, and any slice can replace the noise it makes.

local Clips = require("audio.Clips")

Clips.play("sfx_drip", { position = p, volume = 0.5 })   -- make a noise
Clips.register("sfx_drip", myOwnClip)                     -- and replace it

play needs no entity from the caller: the library keeps a pool of voices under the sound slice's host and cycles them. An id with no clip warns once and stays silent — never an error, so a slice can call it before the library has loaded.

The ids

sfx_discharge · sfx_surge · sfx_plate · sfx_clear · sfx_riser · sfx_ascend · sfx_growth_hurt · sfx_growth_burn · sfx_drip · sfx_splash · sfx_soak · sfx_sodium · sfx_seal · sfx_quench · warn_low · warn_wet · ui_move · ui_confirm · ui_back · ui_open

The sound slice registers a clip for every one of them at start, and the Score component already plays most of them off the event bus. Authoring your own is for when your slice wants a better noise for its own thing, not for making it audible at all.

Registering

• register(id, ref) — take an id over, replacing whatever held it.
• registerDefault(id, ref) — take it only if nothing holds it yet. The sound slice seeds its whole library this way, so a slice that got there first keeps its own clip.
• get(id) / has(id) / ids() — what is registered.
• setPoolParent(ref) — where the pooled voices live.

The spoken script, read through the library

Staging cues a line by id and never writes the words; it asks here for them.

• text(id) — the written form of a spoken line.
• speaker(id) — "chemist" or "column".
• duration(id) — how long the line runs, measured off the clip that says it, falling back to a reading estimate when a line has no audio. That is what lets a caption leave the screen with the voice rather than on a guess.
• lines() — the whole script as id → text.

The words themselves live in audio.Script, which is the one place they are written.

Play options

Clips.play(id, {
  position = { x = 0, y = 0, z = 0 },  -- play it there; makes it spatial
  volume = 1, pitch = 1,
  channel = "sfx",                      -- or "ui"
  spatial = true, maxDistance = 34,
})