synth
<!-- zero:scaffolded-readme --> <!-- Replace the line below with what this module provides and who consumes it, then delete both comment lines. -->
synth
<!-- 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.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2game.audio.synth — CPU sound synthesis for Verdigris Cloister. Everything the game hears that is not a spoken line is computed here, as interleaved f32 PCM, and handed to `asset.create("soundClip", …)`. Pure CPU: it works headless, it never asks the network for anything, and it cannot run out of credit. The one idea worth holding: a LOOP IS SEAMLESS WHEN EVERY PERIODIC PART OF IT COMPLETES A WHOLE NUMBER OF CYCLES INSIDE THE LOOP. `lock(freq, loopSec)` rounds a frequency to the nearest multiple of 1/loopSec, which moves it by less than a twentieth of a hertz and makes the last sample join the first exactly. Anything aperiodic (noise, a reverb tail) is folded instead — `wrapTail` and `seamless` wrap the overhang back over the head. Engine loop points are not used anywhere: they are stored and never read, so a bed is authored seamless END TO END and looped with the Audio component's own `looping` field.
osc(cycles: number) → number
--!desc Sine of a phase measured in CYCLES (1.0 = one full turn). --!arg cycles Phase in turns; any real number, wrapped internally. --!return The sine value, -1..1. --!example local s = Synth.osc(0.25)
| arg | type | description |
|---|---|---|
| cycles | number |
buf(n: number) → void
--!desc A silent mono buffer of n frames. --!arg n Frame count. --!return A table of n zeros. --!example local b = Synth.buf(16000)
| arg | type | description |
|---|---|---|
| n | number |
lock(freq: number, loopSec: number) → number
--!desc Round a frequency so it completes a whole number of cycles in a loop. --!arg freq The wanted frequency in Hz. --!arg loopSec The loop length in seconds. --!return The nearest frequency that loops seamlessly. --!example local f = Synth.lock(146.83, 16)
| arg | type | description |
|---|---|---|
| freq | number | |
| loopSec | number |
arc(base: number, peak: number, turns: number, offset: number?) → void
An envelope is a function of NORMALISED time (0..1 across the buffer). Two families: `arc` for looping material, which starts and ends at the same value so a loop joins itself, and `hit` for one-shots, which starts at full and decays away. --!desc A looping swell: rises and falls back to `base` over the whole loop. --!arg base Level at the loop boundary, 0..1. --!arg peak Level at the crest. --!arg turns How many swells fit in one loop (a whole number keeps it seamless). --!arg offset Phase offset in turns, so layers breathe out of step. --!return An envelope function of normalised time. --!example local e = Synth.arc(0.5, 1.0, 1, 0.25)
| arg | type | description |
|---|---|---|
| base | number | |
| peak | number | |
| turns | number | |
| offset | number? |
hit(attack: number, decay: number) → void
--!desc A one-shot envelope: attack, then exponential decay, then a tail fade. --!arg attack Attack as a fraction of the buffer, 0..1. --!arg decay Decay constant — bigger falls faster. --!return An envelope function of normalised time. --!example local e = Synth.hit(0.01, 6)
| arg | type | description |
|---|---|---|
| attack | number | |
| decay | number |
flat(level: number) → void
--!desc A flat envelope at a constant level. --!arg level The level. --!return An envelope function of normalised time. --!example local e = Synth.flat(1)
| arg | type | description |
|---|---|---|
| level | number |
partial(buf: { number }, sr: number, freq: number, amp: number, env: ((number) → void
--!desc Add a sine partial across the whole buffer. --!arg buf The buffer to add into. --!arg sr Sample rate. --!arg freq Frequency in Hz. --!arg amp Peak amplitude. --!arg env Envelope over normalised time, or nil for flat. --!arg phase Starting phase in turns. --!example Synth.partial(b, 16000, 220, 0.2, nil, 0)
| arg | type | description |
|---|---|---|
| buf | { number } | |
| sr | number | |
| freq | number | |
| amp | number | |
| env | ((number |
vibrato(buf: { number }, sr: number, freq: number, amp: number, env: ((number) → void
--!desc Add a sine partial that is slowly detuned by a looping vibrato. --!arg buf The buffer to add into. --!arg sr Sample rate. --!arg freq Centre frequency in Hz. --!arg amp Peak amplitude. --!arg env Envelope over normalised time, or nil for flat. --!arg rate Vibrato rate in Hz — lock it to the loop for a seamless bed. --!arg depth Vibrato depth as a fraction of the frequency. --!arg phase Starting phase in turns. --!example Synth.vibrato(b, 16000, 220, 0.2, nil, 0.25, 0.004, 0)
| arg | type | description |
|---|---|---|
| buf | { number } | |
| sr | number | |
| freq | number | |
| amp | number | |
| env | ((number |
rnd( ) → number
seed(seed: number) → void
--!desc Reseed the deterministic noise source. --!arg seed Any integer. --!example Synth.seed(7)
| arg | type | description |
|---|---|---|
| seed | number |
noise(buf: { number }, amp: number, env: ((number) → void
--!desc Add white noise across the whole buffer. --!arg buf The buffer to add into. --!arg amp Peak amplitude. --!arg env Envelope over normalised time, or nil for flat. --!example Synth.noise(b, 0.3, Synth.hit(0.002, 9))
| arg | type | description |
|---|---|---|
| buf | { number } | |
| amp | number | |
| env | ((number |
lowpass(buf: { number }, sr: number, cutoff: number) → void
--!desc One-pole low-pass, in place. Softens a noise burst into a material. --!arg buf The buffer. --!arg sr Sample rate. --!arg cutoff Cutoff in Hz. --!example Synth.lowpass(b, 16000, 900)
| arg | type | description |
|---|---|---|
| buf | { number } | |
| sr | number | |
| cutoff | number |
highpass(buf: { number }, sr: number, cutoff: number) → void
--!desc One-pole high-pass, in place. Takes the mud out of a mix. --!arg buf The buffer. --!arg sr Sample rate. --!arg cutoff Cutoff in Hz. --!example Synth.highpass(b, 16000, 120)
| arg | type | description |
|---|---|---|
| buf | { number } | |
| sr | number | |
| cutoff | number |
resonate(buf: { number }, sr: number, freq: number, q: number, mix: number) → void
--!desc A resonant ring at one frequency — how metal and glass get their pitch. --!arg buf The buffer. --!arg sr Sample rate. --!arg freq Resonant frequency in Hz. --!arg q Resonance; 20 rings briefly, 400 rings for a long time. --!arg mix How much of the ring joins the dry signal, 0..1. --!example Synth.resonate(b, 16000, 1840, 180, 0.7)
| arg | type | description |
|---|---|---|
| buf | { number } | |
| sr | number | |
| freq | number | |
| q | number | |
| mix | number |
wrapEcho(buf: { number }, sr: number, timeSec: number, feedback: number, mix: number) → void
--!desc A circular echo — the delay line wraps, so the tail lands back on the --! head and a looping bed keeps its space without a seam. --!arg buf The buffer. --!arg sr Sample rate. --!arg timeSec Delay time in seconds. --!arg feedback How much each repeat feeds the next, 0..0.95. --!arg mix How loud the echoes sit under the dry signal. --!example Synth.wrapEcho(b, 16000, 0.37, 0.55, 0.35)
| arg | type | description |
|---|---|---|
| buf | { number } | |
| sr | number | |
| timeSec | number | |
| feedback | number | |
| mix | number |
seamless(buf: { number }, n: number, fade: number) → void
--!desc Fold the overhang of an aperiodic buffer back over its head, so a --! noise bed or a reverb tail joins itself. --!arg buf The buffer (longer than `n` by at least `fade`). --!arg n The wanted loop length in frames. --!arg fade Crossfade length in frames. --!return A new buffer of exactly n frames that loops without a seam. --!example local bed = Synth.seamless(raw, 256000, 8000)
| arg | type | description |
|---|---|---|
| buf | { number } | |
| n | number | |
| fade | number |
normalize(buf: { number }, peak: number) → number
--!desc Scale a buffer so its loudest sample sits at `peak`. --!arg buf The buffer. --!arg peak Target peak, 0..1. --!return The buffer's measured peak before scaling. --!example Synth.normalize(b, 0.8)
| arg | type | description |
|---|---|---|
| buf | { number } | |
| peak | number |
saturate(buf: { number }, drive: number) → void
--!desc Soft saturation — rounds peaks over instead of clipping them square. --!arg buf The buffer. --!arg drive How hard it is pushed in; 1 is gentle, 4 is obvious. --!example Synth.saturate(b, 1.6)
| arg | type | description |
|---|---|---|
| buf | { number } | |
| drive | number |
gain(buf: { number }, g: number) → void
--!desc Multiply the whole buffer by a gain. --!arg buf The buffer. --!arg g The gain. --!example Synth.gain(b, 0.5)
| arg | type | description |
|---|---|---|
| buf | { number } | |
| g | number |
mixInto(dst: { number }, src: { number }, at: number, g: number, wrap: boolean?) → void
--!desc Add one buffer into another at a gain and a frame offset, wrapping. --!arg dst Destination buffer. --!arg src Source buffer. --!arg at Frame offset into dst (1-based). --!arg g Gain. --!arg wrap When true an overhang wraps to the head, keeping a loop seamless. --!example Synth.mixInto(bed, drip, 4000, 0.4, true)
| arg | type | description |
|---|---|---|
| dst | { number } | |
| src | { number } | |
| at | number | |
| g | number | |
| wrap | boolean? |
deClick(buf: { number }, frames: number) → void
--!desc Fade the first and last few frames to silence — a one-shot that starts --! or ends mid-waveform clicks, and this is the cure. --!arg buf The buffer. --!arg frames How many frames each ramp covers. --!example Synth.deClick(b, 48)
| arg | type | description |
|---|---|---|
| buf | { number } | |
| frames | number |
note(semis: number) → number
--!desc The frequency `semis` semitones above D2. --!arg semis Semitones above D2; negative goes below. --!return The frequency in Hz. --!example local a = Synth.note(19) -- A3
| arg | type | description |
|---|---|---|
| semis | number |
Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
Scoped to this part · feeds back into the world's score.