Log inGet started
World

Verdigris Cloister

Branchmain
Branchesmain
Commit65770846aa

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

groupnames
UIui_click ui_hover ui_confirm ui_back ui_deny
boardtile_select unit_select move_step tile_heave
weaponsattack_anselm attack_meridia attack_cassian attack_vespera
combathit_flesh hit_crystal miss unit_death overwatch_arm
gardenplant_grow blight_grow sow burn flood
flowround_begin phase_garden phase_blight
endingssting_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

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