First Light: Goura
README.md
sound — the night has a sound
Everything First Light: Goura makes a noise with: the bed under the forest floor, the score, the shared one-shot library the other slices fire, the mix, and the narrator.
Nothing here is a recording of the real world, and nothing here is made at
runtime. Every clip was baked once at author time into a .soundClip under
clips/; the component only resolves them. A player's machine does no DSP,
reaches no generation service and downloads no audio that is not part of the
world.
What is in here
| File | What it is |
|---|---|
Soundscape.component | The runtime. Mounted once on mount_sound. Runs the bed, the music deck, the mix, the one-shots and the narrator, and publishes the sound surface. |
dsp.module | The signal work: oscillators, filtered noise, envelopes, mono folding, trims, normalise, limit, and the seam crossfade that makes a loop a loop. |
recipes.module | One entry per clip — how long, what rate, whether it loops, the text audio_gen is asked for, and the pure-Luau synthesis that stands in when generation is not available. |
lines.module | The narrator's script: every spoken line's words, its clip, and how far the mix ducks under it. The words are the durable half. |
bake.module | The author-time baker. Bake.all() re-makes every clip in this folder. |
clips/ | 25 baked .soundClip assets — two beds, two music cues, twelve one-shots, nine narrator lines. |
The layers
The bed is two loops running at once, mixed against FL.light():
fl_bed_night (insects, tree crickets, distant frogs, a wall of them) fades
down as fl_bed_dawn (the dawn chorus — whistles, trills, the insects thinning)
comes up. Both are shipped as uncompressed PCM, because a loop is the one
thing a lossy codec cannot be trusted with at the seam, and because a
.soundClip's loopStart / loopEnd are stored and read by nothing — so a
bed that must loop is built to loop. The last 1.6 s of each take is
crossfaded over its first 1.6 s and then dropped, which makes the sample after
the last one literally the sample that followed it in the source. Measured on
the shipped bytes, the jump at the wrap is smaller than the average step
between two neighbouring samples anywhere else in the clip.
The score is one deck with two cues. fl_title holds the menus and the
opening beat; fl_score enters once the light is above scoreLight and
carries the rest of the run and both endings. The deck takes the level to
nothing before it swaps the clip and brings it back up on the new one, so the
change reads as a cue rather than a splice.
The furniture is the shared library every other slice fires through
sound.play(name) — ui_move, ui_confirm, ui_back, call, answer,
failance, seen, caught, roost, step, flurry, boom. Most are
wired to the FL event bus here, so a slice that emits boom or seen gets
its sound without asking for it. Pass position to have a shot heard from a
world point rather than flat: the caller's boom comes from the side of the
lane the caller is standing on.
The mix is four channels — ambient, music, sfx, voice. They are
not equal. The boom, the eagle and the strike are the loud things; the
footfalls and the interface live a long way underneath. While a line is being
spoken the bed and the score drop to a third and the effects to two thirds,
and come back over about half a second.
The narrator
Nine lines, all spoken, generated once through audio_gen.speech and cached
as clips — a hot reload, a re-bake or another agent's play round never buys
the script again. There is one reading voice because the operation declares
only text; the lines are separated by what they say and how they are placed,
not by a voice picker that does not exist.
Every spoken line is also on screen. sound.say(id) plays the read and
returns the words, and while a line is speaking this slice draws it as a
caption at the foot of the frame, laid out from the live ui.screenSize().
That caption is what carries the line to a muted player, through a noisy room,
and past a generation that failed — the text ships in lines.module whatever
happens to the audio. Another slice that would rather draw the words itself
calls sound.captions(false) and reads sound.speaking(), and the
narration event on the FL bus fires { id, text, seconds } on every line.
The surface — FL.get("sound")
local sound = FL.get("sound")
sound.play("ui_confirm") -- a shared clip
sound.play("call", { position = callerPos }) -- heard from a world point
sound.play("step", { volume = 0.8, pitch = 1.1 })
sound.duck(2.0, 0.4) -- hold the bed and score down
local words = sound.say("first_seen") -- speak a line, get its text
sound.text("won") -- the words without speaking
sound.speaking() -- { id, text, remaining } or nil
sound.captions(false) -- another slice draws the words
sound.mix() -- what the mixer is running at
Re-baking
In edit mode, from an execute:
local Bake = require("game.sound.bake")
Bake.synth() -- the floor: every clip, computed on the CPU
Bake.generate() -- replace what audio_gen makes better
Bake.speak() -- the narrator; already-cached lines are skipped
Bake.report() -- audio.info on every finished clip
The order is the point. synth first means every clip exists and has sound in
it before a service is called at all, so a generation that fails, times out or
returns nothing leaves the game with the computed take instead of silence.
generate re-authors in place and keeps each clip's guid, which is the
identity every reference already holds.
Bake.report() reads each clip's ZAUD header without decoding it. A duration
of zero, a single frame or the wrong channel count is a clip that would ship
silent, and that read is what catches it.
Reaching in from another slice
Fire an event on the FL bus and the sound follows. Nothing needs to know
this component exists. If a slice makes a noise of its own, it owns that
noise — this is the bed and the furniture, not a monopoly.