Log inGet started
World

First Light: Goura

Branchmain
Branchesmain
Commite917faa950

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

FileWhat it is
Soundscape.componentThe 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.moduleThe signal work: oscillators, filtered noise, envelopes, mono folding, trims, normalise, limit, and the seam crossfade that makes a loop a loop.
recipes.moduleOne 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.moduleThe 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.moduleThe 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.