# lavic <!-- zero:scaffolded-readme --> <!-- Replace the line below with what this module provides and who consumes it, then delete both comment lines. --> TODO: describe this module.

# game.sound.sfx — the sound library Everything in FIRST LIGHT that makes a noise goes through here. ```lua local sfx = require("game.sound.sfx") sfx.play("helm_off") -- a one-shot, heard flat sfx.play("footstep", { at = footEntity }) -- a one-shot, heard from where it is sfx.play("lava_bubble", { at = { x, y, z }, pitch = 0.8, volume = 0.6 }) local hold = sfx.loop("free_hold") -- a sustained sound sfx.loop("free_hold", { pitch = 1.2 }) -- same source, moved sfx.stop(hold) sfx.bed("rim_wind") -- crossfade the ambience sfx.duck(2.5) -- get out of a spoken line's way sfx.music("music_dawn") -- crossfade the score ``` Guard the require if your slice must survive the library being absent: ```lua if asset.exists("game.sound.sfx", "module") then sfx = require("game.sound.sfx") end ``` ## The bank | name | when | |---|---| | `ui_move` `ui_confirm` `ui_back` | menu focus, a control taken, a card closed | | `helm_off` `helm_on` | the one verb — the world arriving, and shutting | | `footstep` `jump` `land` | the pilgrim on the rock | | `crust_crack` `plate_collapse` | a plate warning, and a plate going | | `ember_hit` `fumarole` | ember weather on a bare head, gas out of the rock | | `knight_free` `lava_bubble` | one of the lost released; the tide, close | | `win_sting` `lose_sting` | first light, and being taken back | | `narrator_bed` | a floor for a voice to stand on | | `lava_rumble` `rim_wind` `free_hold` | looping beds | | `music_title` `music_climb` `music_dawn` `music_drone` | the score | `sfx.clip(name)` hands back the `.soundClip`; `sfx.missing()` lists any the bank could not resolve, so a caller can tell a complete library from a partial one. ## The mix Every clip carries a default level, so a caller that passes no `volume` still lands in a mix rather than at full scale. The helm, the knights and the ends of a round are loud; footsteps, ambience and interface sit under them. One-shots overlap freely, but the same clip will not start twice inside a short window — three copies of a two-second vent running together is one waveform at three times the amplitude, which is a comb filter and a peak rather than a louder vent. Interface ticks and footsteps are effectively unguarded; the long textural clips hold each other off for a fraction of their length. A refused start returns `false` from `sfx.play`. The master sits at 0.72 rather than 1, because `audio.levels().peak` is measured after the master and the loud moments of a full mix — the score, two beds, a sting and a spoken line at once — go over full scale without it. It is stated once and never re-asserted, so a settings screen can set its own. Three mixer channels are in play. `music` and `ambient` are owned here and move with the round — they fall to about a quarter under `duck`. The `sfx` channel is deliberately left at unity, because that is where a spoken line plays and it is the thing the duck exists to make room for. ## What owns what `game.sound.Sound` (mounted on `mount_sound`) ticks this library and drives the automatic mix from `L.state` — the tide below rising with the lava's proximity, the air at the rim rising with `L.dawn()`, the score following the phase. It re-states that mix every frame, which is what makes a hot reload harmless. An explicit `sfx.bed(name)` from another slice therefore holds the ambience for a few seconds before the automatic mix takes it back; `sfx.play`, `sfx.loop`, `sfx.duck` and `sfx.music` are not overridden at all. The emitters live under a temporary `SoundEmitters` entity and are found by name, so a hot reload re-attaches to the sources already standing instead of spawning a second set. ## Where the sound comes from Every clip is synthesised on the CPU by `game.sound.synth` and baked into a `.soundClip` under `game/sound/clips/`; the three scored tracks are generated, then trimmed and folded into seamless loops by the same module. Loops are stored as `codec = "pcm"` so the head of the clip survives decoding and the seam does not click.

# lost The six who stopped, and the ritual that lets them go. ```luau local Lost = require("game.knights.lost") Lost.build(1, { x, y, z }, yaw, "KnightSpot_1") local idx, dist = Lost.nearest(playerPosition) Lost.setProgress(idx, 0.6) -- the approach, 0..1 Lost.free(idx) -- the ending; false if it is already freed Lost.update(dt) -- drive the ritual ``` A lost knight is a pilgrim who put the helm on and never took it off again: the rock took the legs, the bronze went grey, and what is behind the slit is down to its last ember. They stand at the `KnightSpot_N` markers the spire lays out, one per canto band, each with its own lean, twist, arm angle and depth in the stone so no two read as the same statue. ## Freeing one Dishelming a lost knight is the only thing in this game you do to somebody else. It is a HOLD, and it only works with your own helm off — the fiction is that you have to be willing to be seen doing it. `setProgress` is the approach: the ring at the feet brightens, the helm trembles, and the ember behind the slit comes up off its last coal. `free` is the ending — the helm leaves the figure and turns as it rises, a column of light goes up, the statue goes to embers, and a warm light washes the rock for a moment. What is left afterwards is the rock and a cooled scar where the ring was: the mountain keeps the mark. `free` returns `false` for a knight already freed, and `nearest` skips them, so no hold can score the same knight twice. It increments `L.state.freed` and emits `knightFreed(index, entity)` before any of the animation runs. ## Surface | Call | | |---|---| | `build(index, pos, yaw, spotName)` | Stand one up. | | `relocate(index, pos, yaw)` | Move one to its real spot when the spire lays it out. | | `nearest(pos)` | The nearest knight still standing, and its distance. | | `setProgress(index, t01)` | The approach. Emits `freeProgress`. | | `free(index)` | The ending. Emits `knightFreed`. `false` if already freed. | | `update(dt)` | Drive the ritual. Call every frame. | | `get` / `isFreed` / `count` / `remainingCount` / `position` | Reads. | | `clear()` | Take all six down, this module's earlier lives included. |

# pilgrim The helmed bronze pilgrim — the thing the player IS. ```luau local Pilgrim = require("game.knights.pilgrim") Pilgrim.dress(bodyEntity) -- on `bodyReady`; idempotent Pilgrim.setHelm(false) -- take it off: it arcs down to the hip Pilgrim.update(dt) -- drive the arc Pilgrim.teardown() -- hand the body back exactly as the avatar left it ``` The scene gives every body the engine's humanoid avatar: a rig, a walk, and an undressed character mesh. This module turns that into the pilgrim — soot under bronze plate, a cloak the ash has been ground into, and the great helm that is both the armour and the blindfold this game is about. Nothing here replaces the avatar. Every piece is an entity parented to the bone it rides, so the dressing walks, jumps and falls with the animation it was hung on, and `teardown` leaves the body as it was. ## What goes on Head, chest, waist, hips, both shoulders, elbows, hands, thighs, shins and ankles each get a socket, and the parts hang off it in metres. Plates that follow a limb are **spanned** between the two joints they cover, so they sit correctly whatever pose the body is in when the dressing goes on and stay aligned as the limb bends. The character mesh underneath is tinted to soot, so the bronze is the bright thing standing on it. ## The helm, moving The helm is the one part that moves on its own. It lives in one of two homes — worn on the head socket, or riding the hip — and between them it is parented to the body rather than to either, so the change is a real arc through the world with a tumble in it and not a cut. Dishelmed, the sooted coif and the two lit eyes come up in its place, with a lamp looking forward out of them. ## Surface | Call | | |---|---| | `dress(body)` | Dress a composed body. Idempotent. | | `setHelm(on, instant?)` | Take the helm off or put it back; `instant` skips the arc. | | `helmIsOn()` | What the dressing currently shows. | | `update(dt)` | Drive the arc. Call every frame. | | `applyDawn()` | Take the breastplate sigil up with `L.dawn()`. | | `slitPosition()` | Where the burning slit is, for a camera or a caption. | | `isDressed()` / `count()` | Whether anything is dressed, and how many. | | `teardown()` / `clearOrphans()` | Take it all off. | Both the prototype standing in the editor and the clone a round mints get their own dressing, so what an author sees in edit is what a player wears in play.