Docs · Make it a game

Audio

Sounds in a project

1. Copy your sound files into the project folder with your file manager. A sounds folder keeps them together: a new project has no folders, but any folder inside the project will do.
2. In Assets, press Refresh. A file you have copied in is not listed until you do.
3. Select a sound and press Details in the bar of Assets. Under the list are its length and its waveform, with Play and Stop to hear it. Double-clicking a sound plays it too. One sound plays at a time: a new one stops the last.

Stream

In the same place: how the game holds the sound. Never keeps it whole in memory, 8 bytes for every frame of it (a four-minute track is 85 MB). Always reads it from the file as it plays. Auto, where every sound starts, streams one longer than 3 seconds. A short loop that plays all the time, such as a torch, is cheap to keep whole. A music asset’s tracks, their intros and their layers are kept whole whatever Stream says, so a change of track comes in on time.

A sound in the room

1. Select Room and press + Add node → Audio Source. Name the new node hum, and set its Position to 200 and -40, high on the right.
2. Click its Clip slot and choose your sound from the list, or drag the file from Assets onto the slot. The play button beside the slot plays it.
3. Tick Looping and Autoplay.
4. Under Spatial, set Max Distance to 320 and Min Distance to 64. The next section says what they do.

Clip

The sound Autoplay plays. A script plays the rows of Triggers instead: see Sounds from a script.

Bus

Which volume it answers to: Sfx, Music or Master. See Volume.

Volume

Its own loudness, from 0 to 1, before distance and the bus.

Pitch

The speed it plays at: 2 is twice as fast and an octave higher, and 0.5 half as fast.

Looping

Plays the Clip again each time it ends, until something stops it. A row of Triggers that a script plays with play_sound plays once, whatever Looping says.

Autoplay

Starts it as the room starts: when you press Play, and when an exported game opens.

Max Voices

How many sounds this node plays at once. Past it, a new sound stops the oldest. 0 sets no limit of its own.

Near and far

1. Select player, press Add component and choose AudioListenerComponent. Its one field, Enabled, starts ticked.
2. Press F5 and walk right. The hum is silent at the start. It comes in about a third of the way across, from your right, grows as you near it, and moves to your left once you pass under it.

Max Distance

How far away it can be heard. Farther than that, it is silent.

Min Distance

How near it is at full volume. Between the two, it fades.

Rolloff

The shape of that fade. Quadratic, the default, falls fast near the source and eases into silence at Max Distance. Linear falls evenly all the way, so it is gone at a distance you can point to. Inverse loses most of its loudness in the first steps away, then hangs on faintly to the end, as a real sound does. Logarithmic loses the same number of decibels with every step, which the ear hears as fading at an even pace. Custom follows a curve you draw, from Min Distance to Max Distance.

Blend

How much distance counts: 1 fully, and 0 not at all, so the sound plays at full volume and centred wherever it is.

Pan

Moves it left, toward -1, or right, toward 1, on top of the side it is on.

Positional

Untick it for a sound that is the same everywhere, such as a click. A looping Autoplay on the Music bus is the room’s music, and is never positional.

Sounds from a script

Clips

Other takes of the row’s sound, each a Clip and a Weight. The row’s own Clip is a take too, at Weight 1.

Mode

The order the takes come in. Shuffle, where a row starts, plays each take once a round, and never one twice running. Random draws one at each play, by Weight, and may draw the same again. RandomNoRepeat draws by Weight, but never the take just played. Sequential plays them in the list’s order, the row’s own Clip first.

Weight

How often a take comes up against the others, under Random and RandomNoRepeat. Shuffle and Sequential pass over it. 0 leaves a take out in every Mode.

A row’s Pitch and Volume

A range, Min to Max, that each play’s pitch or volume is multiplied by, picked afresh every time.

/// A pickup that chimes as it is taken.
component Chime : Area {
    fn on_enter() {
        play_sound("chime");
        destroy_self();
    }
}

1. Make a script called chime the way Rengy Script makes one, with the text above.
2. Select Room, add a node with + Add node → Area, and name it bell. Set its Position to 40 and 148, on the floor just past the steps, and its Shape’s Size to 16 and 16. Give it a Shape the same size, as Rengy Script did for the coin.
3. Press Add component and choose AudioSourceComponent. Leave its Clip empty, and add a Triggers row named chime with a short sound as its clip.
4. Press Add component again and choose Chime.
5. Press F5 and walk through it. It chimes, and is gone.

/// Hums until a plate wired to it is pressed, then falls quiet.
component Generator {
    fn on_signal() {
        if heard("pressed") {
            stop_sound();
        }
    }
}

1. Make a script called generator with the text above, and add it to hum.
2. Select plate. Press + beside its Signal’s Connections, and set the new row to Signal pressed and To hum, as Characters and physics wired the door.
3. Press F5 and step on the plate. The door opens, and the hum stops.

Music

/// Plays calm music, and tense music once a plate wired to it is pressed.
component Soundtrack {
    fn on_create() {
        play_music("calm");
    }

    fn on_signal() {
        if heard("pressed") {
            play_music("tense");
        }
    }
}

1. Copy two tracks into the project, a calm one and a tense one, and press Refresh in Assets.
2. Select Room, press + Add node → Audio Source, and name the node music. Leave its Clip empty and Autoplay unticked.
3. Add two Triggers rows: calm, with the calm track as its clip, and tense, with the tense one.
4. Make a script called soundtrack with the text above, and add it to music.
5. Select plate and add one more row to its Connections: Signal pressed, To music.
6. Press F5. The calm track plays from the start. Step on the plate, and the tense one takes over.

Volume

set_master_volume(level)

Sets Master. See set_master_volume.

set_music_volume(level)

Sets Music. See set_music_volume.

set_sfx_volume(level)

Sets Sfx. See set_sfx_volume.

/// Turns the music down while something stands in this area.
component Hush : Area {
    /// How loud the music is in here, from 0 to 1.
    #[range(0.0..1.0)]
    quiet: f32 = 0.3,

    fn on_enter() {
        set_music_volume(quiet);
    }

    fn on_exit() {
        set_music_volume(1.0);
    }
}

1. Make a script called hush with the text above.
2. Select Room, add a node with + Add node → Area, and name it hush. Set its Position to 80 and 95, under the ledge, and its Shape’s Size to 160 and 70.
3. Press Add component and choose Hush.
4. Press F5 and walk under the ledge. The music drops while you are there, and comes back as you walk on.

The mix

Effects

Each bus’s chain: Master, Music and Sfx, each a list of Slots the sound passes through in order. A slot is an Effect, with settings of its own, and Enabled, which switches it on. The kinds are LowPass, HighPass, BandPass, Delay, Distortion, Gain, Compressor, Reverb and Panner.

Snapshots

Named mixes, such as paused or cave: for each bus a Volume and a switch for each of its slots, and the Send Amounts. A zone or a script asks for one by name, and the mix slides to it. Until then the room plays the mix as its slots are set.

Ducking

Rules that hold one bus down while another is loud. While the Trigger bus is over Threshold, in decibels, the Target bus comes down by Amount decibels; Attack and Release set how quickly it comes on and lets go, in seconds. The Trigger is heard before its bus’s volume, so the volume sliders do not move where it crosses. A rule whose Trigger is its Target, or Master, would hear itself, and is refused, with a row in Problems.

Sends

Each row feeds some of the From bus, after its effects and its volume, through the To bus’s effects and volume, at Amount, from 0 to 1: music sent into Sfx rings in a reverb on Sfx. A snapshot’s Send Amounts change them, row by row.

Music that reacts

Tracks

The pieces of music, each a Name that scripts and rules call it by, a Clip, and Looping: on, it plays until another track takes over; off, it plays once. An Intro plays once, straight into the loop with no gap.

Rules

How to get from one track to another: From, empty for any track, To, and How. Immediate cuts. CrossFade fades the one out as the other comes in, over its Seconds. AtEnd lets the playing track reach the end of its loop, then starts the next with no gap.

Default Transition

The How for a change no rule names. On a new asset it is a CrossFade of 1 second.

A track’s Layers

Clips that play in step with the track’s own, each a Name, a Clip as long as the track’s, and the Volume it starts at. set_music_layer fades one by name, so a heartbeat can swell as a ghost comes near. A track with layers takes no intro.

Playlist

Clips played one after another under the tracks, from the level’s opening, or alone in an asset with no tracks. Shuffle plays them in a new order each time round.

Hearing what plays

Next