Tutorials · Sound and Music · Chapter 4

Sounds from a script

The sounds

1. Download RPG Audio from its page below, and use the Impact Sounds you downloaded in chapter 3. Copy these seven files into your project’s audio folder, each from where the list says. Then press Refresh in the Assets panel.
2. Hear each in Details. Leave their Stream on Auto: each is under three seconds, so it is held whole and plays the moment it is asked for.

A key for the lever, and a shut door

1. Choose View → Input map…. Type action into New action and press Add. With action selected, press Record a control and press E. Press Save, and close the window.
2. In Assets, double-click art/tilemap_packed.png. The Sprite sheet tab opens on it. In its Grid band, set Cell to 32 by 16.
3. Click the shut double door, the cell in the sixth column and the fourth row: its top left is 160, 48 on the sheet. It outlines orange.
4. In the Regions band, type door_shut into Name and press Name it.

The input map’s New action and Record a control

The box a new action’s name is typed into, which Add adds to the Actions list; and the button that makes the next key you press one of the selected action’s controls. A script asks for an action by its name, never by its key, so the key can change without the script.

The Sprite sheet tab’s Cell, and Name it

In the Grid band, the size of one cell of the tab’s grid, in the sheet’s pixels: 32 by 16, a double door’s width and one row. In the Regions band, Name it saves the outlined cell as a region of the sheet under the name in Name, which a Sprite then draws by that name.

Doors that creak

1. Select door_cave, in chasm. In its Sprite, set Atlas Region to door_shut.
2. Press Add component and choose ColliderComponent. Set its Size to 32, 32 and its Offset to 0, -8: the doorway’s two rows of cells.
3. Press Add component and choose AreaComponent. In its Shape, set Size to 48, 64 and Offset to 0, -8. Leave its Layer and Mask as they come: each reads 0, the first layer, the knight’s.
4. Press Add component and choose AudioSourceComponent. Leave Clip empty. Set Volume to 0.5 and, in Spatial, Pan to 0.3.
5. Click the + beside Triggers. Name the row swing and set its Clip to doorOpen_1.ogg. Click the + beside its Clips once: set the new row’s Clip to doorClose_2.ogg, its Weight at 1. Set Mode to Sequential.
6. In Assets, click Assets at the start of the path bar over the tree. Create writes into the folder last clicked in the tree, or the folder of the file last clicked, and the path bar names it: Assets / art since you opened the sheet. Assets alone is the project’s top, where its scripts are. Click Create, choose New script, type door and press Enter. In the Code tab, replace everything in door.rgs with the script below, and press Ctrl+S.
7. Select door_cave again, press Add component and choose Door.
8. Do the same for door_well, in well_room, and door_bell, in bell_chamber. Press Ctrl+S.

/// A door between two rooms. Shut, it stops the knight. As he comes up to it
/// it swings open with a creak, and once he has gone through, or turned back,
/// it swings shut behind him. Its one sound, swing, plays its two takes in
/// turn: the creak open, then the bang shut.
component Door : Area {
    fn on_enter(other: NodeId) {
        if in_group(other, "knight") {
            play_sound("swing");
            set_text("SpriteComponent", "region_name", "door_open");
            set_flag("ColliderComponent", "solid", false);
        }
    }

    fn on_exit(other: NodeId) {
        if in_group(other, "knight") {
            play_sound("swing");
            set_text("SpriteComponent", "region_name", "door_shut");
            set_flag("ColliderComponent", "solid", true);
        }
    }
}

play_sound

Plays the trigger of that name on the script’s own node’s Audio Source: play_sound("swing") plays the row swing, its next take by its Mode. It plays once, from where the node is, on the source’s Bus. A name with no row plays nothing.

on_enter and on_exit

A component Door : Area runs these when something comes into its Area and when it leaves, with other, the node that did. in_group asks whether it is the knight, who is in the group knight, so nothing else opens a door.

set_text and set_flag

Write a field of another component on the same node: the Sprite’s region_name, which picture it shows, and the Collider’s solid, whether it stops him.

Sprite Atlas Region

Which region of the Sprite’s sheet it draws, by name: door_shut, the cell you named, and later door_open, the starter’s, when the script swaps it.

Collider Size and Offset

The box that stops him, in world units: its width and height, and how far its middle sits from the node’s. 32 by 32, 8 up: the doorway’s two rows of cells.

The Area’s Shape Size and Offset, and its Layer and Mask

The box that notices what comes into it, measured as the Collider’s: 48 by 64, so he is noticed a step before he reaches the door, on either side. Layer and Mask say which layers it sits on and notices: left as they come, each reads 0, the first layer, the knight’s.

A bridge that creaks under him

1. Select bridge, in chasm. Press Add component and choose AreaComponent. In its Shape, set Size to 112, 32: the deck.
2. Press Add component and choose AudioSourceComponent. Leave Clip empty. Set Volume to 0.4 and, in Spatial, untick Positional.
3. Add a trigger creak: its Clip creak1.ogg; two Clips, creak2.ogg at Weight 1 and creak3.ogg at 0.5; Mode Random.
4. Make a script bridge as you made door, with the script below, and add Bridge to bridge. Its Stride reads 48. Press Ctrl+S.

/// The wooden bridge over the chasm. Its boards creak under the knight: as he
/// steps onto it, and again each time he has walked a stride along it.
/// Standing still on it, he makes no creak.
component Bridge : Area {
    /// How far he walks along the boards from one creak to the next.
    stride: f32 = 48.0,
    /// How far he has walked since the last creak.
    #[hidden]
    walked: f32 = 0.0,
    /// Where he stood on the step before.
    #[hidden]
    last: Vec2,

    fn on_enter(other: NodeId) {
        if in_group(other, "knight") {
            play_sound("creak");
            walked = 0.0;
            last = position_of(other);
        }
    }

    // Every step something stays on the boards. Written in full it is
    // while_in(other: NodeId, dt: f32). Written with no parameters, as here,
    // both are still there by those names; this uses only other, what is on
    // the boards.
    fn while_in() {
        if in_group(other, "knight") {
            let now = position_of(other);
            let moved = now - last;
            walked += sqrt(moved.x * moved.x + moved.y * moved.y);
            last = now;
            if walked >= stride {
                play_sound("creak");
                walked -= stride;
            }
        }
    }
}

while_in

Runs on every step something is in the Area, with other. Here it is how far the knight moved since the step before, from position_of, where a node stood as the step began, added up until a stride is walked.

stride

How far he walks along the boards between creaks, in world units: 48, three cells. A field of the script’s, so the Inspector shows it under Bridge and you can change it there.

#[hidden]

Keeps the field under it out of the Inspector: walked and last are the script’s own reckoning, nothing to set by hand.

sqrt

The square root of a number. sqrt(moved.x * moved.x + moved.y * moved.y) is how far he moved on that step, whichever way he went.

The lever

1. Select lever, in gate_room. Press Add component and choose AreaComponent. In its Shape, set Size to 40, 32 and Offset to 0, 12: the floor in front of it.
2. Press Add component and choose AudioSourceComponent. Leave Clip empty and set Volume to 0.25. Add a trigger pull with its Clip metalLatch.ogg, and leave its Mode as it comes.
3. Press Add component and choose SignalComponent. Click the + beside Connections, open [0], type pulled into Signal, and set To to gate: click it and choose gate, or drag gate from the Hierarchy onto it.
4. Make a script lever as you made door, with the script below, and add Lever to lever. Press Ctrl+S.

/// The old lever beside the gate, which works the gate's winch. It pulls
/// once: its latch clanks, it leans the other way, and the gate is told.
component Lever : Area {
    /// How many knights stand by it.
    #[readonly]
    near: i32 = 0,
    /// Whether it has been pulled.
    #[readonly]
    pulled: bool = false,

    fn on_enter(other: NodeId) {
        if in_group(other, "knight") {
            near += 1;
        }
    }

    fn on_exit(other: NodeId) {
        if in_group(other, "knight") {
            near -= 1;
        }
    }

    fn loop() {
        // E, which the input map calls action, pressed while he stands by it.
        if near > 0 && !pulled && pressed("action") {
            pulled = true;
            play_sound("pull");
            set_flag("SpriteComponent", "flip.x", true);
            emit("pulled");
        }
    }
}

loop and pressed

Every step, the lever asks whether action went down on that step, while a knight stands in its Area, near, and it is not yet pulled. A hold of E counts once.

emit

Tells whoever the node’s Signal wires the name to: pulled, to the gate. The gate hears it on the next step.

The Signal’s Connections, Signal and To

Its rows, one a wire: Signal, the name the node emits, and To, the node that hears it. One row here, pulled to gate.

#[readonly]

Draws the field under it greyed in the Inspector, so you can watch near and pulled change in Play but not type into them.

The gate that grinds

1. Select gate, in gate_room. Press Add component and choose AudioSourceComponent. Set Clip to gate-grind.wav, Volume to 0, and tick Looping and Autoplay.
2. Add a trigger stop with its Clip impactMetal_heavy_000.ogg.
3. Make a script gate as you made door, with the script below, and add Gate to gate. In it, set Aside to 48, 0; Grinding reads 0.3, Wound 2 and Slide 2.5. Press Ctrl+S.

/// The gate up to the alcove. Its grind has turned since the crypt opened, at
/// no Volume, unheard. When the lever is pulled the winch takes it up: the
/// grind is heard, and winds up as the bars slide aside into the wall. There
/// the grind stops, the bars come to rest with a thud, and the gate is gone
/// from the room.
component Gate {
    /// The grind's Volume while the bars move.
    grinding: f32 = 0.3,
    /// The Pitch it winds up to as they go.
    wound: f32 = 2.0,
    /// How long the bars take to slide aside, in seconds.
    slide: f32 = 2.5,
    /// How far they slide: the gate's own width, into the wall.
    aside: Vec2,

    fn on_signal() {
        if heard("pulled") {
            set_number("AudioSourceComponent", "volume", grinding);
            // Its Pitch rises with the bars, by the same curve: slow away,
            // fast across, slow into the wall.
            anneal_number("AudioSourceComponent", "pitch", wound, slide, .InOutSine);
            await anneal_by(aside, slide, .InOutSine);
            // In the wall: the winch stops, and the bars land with a thud,
            // which the same Audio Source plays, back at its own Pitch.
            stop_sound();
            set_number("AudioSourceComponent", "pitch", 1.0);
            play_sound("stop");
            // The bars are inside the wall now, and the gate leaves the room.
            // Its thud plays on where it stood.
            destroy_self();
        }
    }
}

on_signal and heard

Runs on a step a signal reaches the node; heard("pulled") is true on that step.

set_number

Writes a number field of a component on the same node, at once: here the Audio Source’s volume, from 0 to grinding, 0.3, so the grind already turning is heard from that step; and later its pitch, back to 1.

anneal_number

Moves a number field toward a value over a time, on a curve, while the script goes on. Here the grind’s pitch rises to wound, 2, over slide, 2.5 s, on .InOutSine: slow at first, fast across the middle, slow at the end. A sound’s Pitch changed while it plays is heard at once: the grind winds up an octave as it goes.

anneal_by

Moves the node itself by aside, 48, 0, over the same time and on the same curve, so the bars and the grind’s pitch move together. It is awaited: the hook waits here until the bars are in the wall.

stop_sound

Stops every sound the script’s own node is playing: here the grind’s loop.

destroy_self

Removes the node the script is on. The gate leaves the room, and the way up to the alcove is open.

Hearing them

1. Press F5. Walk down through the well room’s door, east over the bridge, and up through the cave’s door.
2. Go on to the gate room, the way chapter 1’s table runs: through the flooded passage, keeping clear of the ghost, down through the bell chamber’s door and east. Stand in front of the lever and press E.
3. Press F5 again to stop.

The doors, the bridge, the lever and the gate

Check it works