Verdigris Cloister
README.md
Audio — the score, the room, and the voices
Everything Verdigris Cloister is heard through. One component, five modules and
a library of 67 .soundClip assets: 32 synthesised, 35 spoken.
No other slice needs to know how a sound is made. Emit a signal.
local Core = require("game.core")
Core.sfx("ui_click") -- a UI sound
Core.sfx("move_step", Core.cellCenter(3, 4)) -- a board sound, at a tile
Core.bark("vespera", "attack") -- a monk speaks, aloud and on screen
Core.emit(Core.SIGNAL.playMusic, { cue = "tension" })
Core.emit(Core.SIGNAL.playSfx, { name = "burn", at = pos, volume = 0.8 })
Core.emit(Core.SIGNAL.playBark, { unit = "anselm", event = "kill" })
The conductor also listens to the game's own signals and answers them without
being asked — roundBegan, phaseChanged, unitMoved, unitActed,
unitDamaged, unitDied, plantGrew, blightGrew, tileChanged (elevation)
and missionEnded. A slice that already emits those gets its audio for free.
The sound effects it answers to
| group | names |
|---|---|
| UI | ui_click ui_hover ui_confirm ui_back ui_deny |
| board | tile_select unit_select move_step tile_heave |
| weapons | attack_anselm attack_meridia attack_cassian attack_vespera |
| combat | hit_flesh hit_crystal miss unit_death overwatch_arm |
| garden | plant_grow blight_grow sow burn flood |
| flow | round_begin phase_garden phase_blight |
| endings | sting_victory sting_defeat |
It also answers to the names the other slices actually invented.
weapon_anselm, step_stone, step_crystal, garden_sow / _burn /
_flood / _grow / _heave, ui_undo, ui_page, shot_miss, shot_hit,
blight_strike, blight_spread, overwatch_fire, round_end, turn_begin,
victory, defeat all resolve to a real clip (Mixer.ALIAS), and the cues
catalogue, codex, menu, reveal, intro, combat, ending:won,
ending:lost, won, lost, none, off all resolve to a real cue
(Mixer.CUE_ALIAS). A playSfx name of the form narrator:<mission>:<n> is
answered as narration rather than as a missing sound. Add to those tables
before telling another slice to rename anything — a service that only replies
to its own vocabulary is a service nobody can use.
playSfx warns on a name that resolves to nothing rather than going quiet
without a word, and mix().lastSfx reports the clip that was heard, so an
alias is visible.
The score
Three 16-second beds play at once and never stop: music_calm (a D-minor
choir over a low pedal), music_swell (the same chord, bowed) and
music_sour (a minor second, a tritone, and a unison split by a fifth of a
hertz so it beats). The score does not change track — it curdles. A cue
sets the three levels; state.blightShare then bends them, taking the
consonant layer down and bringing the sour one up, on a curve that is slow at
first so one blighted tile is not a catastrophe and eight of them are.
Cues: silence title briefing mission tension garden blight
victory defeat.
The greenhouse's own bed — air over cracked glass, the mains knocking, water finding its way down the brass — runs under all of it.
The voices
The four monks and the narrator all speak, and every spoken line is on screen
as it is spoken. game.audio.lines holds the written script and is the
source of truth: a line whose audio failed to generate is still said in
writing, marked no audio, never deleted. The room and the score duck about
10 dB under anybody speaking.
They currently share one voice, and that is a limitation, not a choice.
Each character carries a real, distinct ElevenLabs voice id, but the service
meters the id and ignores it: the same sentence generated under two different
ids and under no id at all came back at 175.8, 170.2 and 164.9 Hz median
pitch — no further apart than two runs of the same id. Until that is
honoured, the four are told apart by the writing and by the caption, which
names the speaker in their own colour every time they open their mouth. The
ids stay in lines.module; the cast separates the day the service uses them.
The caption plate is registered as the screen audio_caption at layer 7000 —
above the in-mission HUD, and deliberately below the modal campaign screens at
8000, which carry the narrator's text themselves while they are up. No other
slice should claim that name.
The files
| path | what |
|---|---|
Conductor.component/ | the one moving part: emitters, mix, ducking, captions, signal wiring |
mixer.module/ | the mix as data — emitters, cues, the blight curve, the caption plate |
synth.module/ | CPU synthesis: oscillators, envelopes, filters, a wrapping echo, seamless-loop helpers |
score.module/ | the recipe for every synthesised clip, and bake(name) |
lines.module/ | the written script, the voice ids, the bark lookup |
voice.module/ | buying the spoken lines once and caching them |
clips.module/ | static resolution for all 67 clips (generated) |
clips/, voice/ | the .soundClip assets themselves |
Two things worth knowing before you change any of it
Beds are codec = "pcm", and they loop by being seamless end to end. Loop
points are stored and never read, and an Opus clip loses its first few
milliseconds on decode, so an Opus bed ticks at the seam. Every periodic part
of a bed is locked to a whole number of cycles per 16 seconds
(Synth.lock), anything aperiodic is folded back over its own head
(Synth.seamless, Synth.wrapEcho), and the compression settings go in
asset.create's settings — setting them afterwards re-encodes through Opus
and undoes the choice.
A one-shot is its own short-lived source. Measured off a recording of the
master mix in this engine, Audio:playOneShot produced digital silence in
three separate takes while the looping bed sat at −23 dB; an Audio created
with autoplay = true was heard. So playSfx spawns an aud_shot_* entity
per sound and the conductor reaps it by age.
Rebuilding the library
local Score = require("game.audio.score")
for _, n in ipairs(Score.names()) do Score.bake(n) end -- a bed takes ~13 s
local Voice = require("game.audio.voice")
Voice.generate(6) -- buys up to six missing lines, paced; the service 429s in bulk
Voice.sweep() -- harvests anything already generated, free
35 lines at 2 credits each is 70 credits for the whole cast. Voice.cost()
says so before you spend it.