Tutorials · Interfaces · Chapter 6

Settings

A settings screen

1. Copy the seven files below into your project, each to where the list says: the pictures into art, and the music into audio. Then press Refresh in the Assets panel.

1. Open scenes/title.ron and choose File → Save as…. Save it as scenes/settings.ron. The editor now holds the copy.
2. In the Hierarchy, rename Title to Settings, title_canvas to settings_canvas and title_name to settings_name. Select title_fade and press Delete: the menu stays on the title.
3. Select settings_name. In its Rect, set Anchor Min and Anchor Max both to 0.5, 0.5, Offset Min to -360, -256, Offset Max to 360, -176 and Pivot to 0.5, 1.
4. In its Text, set Text to Settings, Scale to 1.5, Outline Width to 2 and Shadow Offset to 3, 3. Its Align stays Center, its outline and shadow colours as they are, and its role Accent.
5. Select settings_canvas, click + Add node and choose Panel. Rename it settings_frame.
6. In its Rect, set Anchor Min and Anchor Max both to 0.5, 0.5, Offset Min to -270, -160 and Offset Max to 270, 240. Pivot stays 0.5, 0.5. In its Panel, set Texture to panel_brown.png and Border to 8.
7. Select settings_frame, click + Add node and choose Stack. Rename it settings_rows.
8. In its Rect, set Anchor Max to 1, 0, Offset Min to 24, 24, Offset Max to -24, 312 and Pivot to 0.5, 0. Anchor Min stays 0, 0. In its Stack, set Fit to Fixed and Spacing to 12. Item stays 48, which makes five rows of 48 and four gaps of 12: 288, the Stack’s height.
9. Select settings_rows, click + Add node and choose Node. Rename it music_row. Add four more Nodes under settings_rows, in this order: effects_row, hints_row, names_row and size_row. Each is a row 492 wide and 48 high, and each holds one control.

1. Open scenes/title.ron. Select settings and untick Disabled in its Button.
2. Select Title, click Add component and choose AudioSourceComponent. Set Clip to abandoned_castle_music_-_starninjas_6.ogg and Bus to Music. Tick Looping and Autoplay, and untick Positional.

Two sliders

1. Open scenes/settings.ron. Select music_row, click + Add node and choose Slider. Rename it music.
2. In its Rect, set Anchor Min and Anchor Max both to 0, 0.5, Offset Min to 244, -8, Offset Max to 484, 8 and Pivot to 0, 0.5. That is a bar 240 wide and 16 high, 244 in from the row’s left edge and centred up and down.
3. In its Slider, set Action to music, Value to 0.8 and Step to 0.1. Min stays 0, Max 1 and Interactive ticked. Under Textures, set Fill Texture to slide_horizontal_color.png, Track Texture to slide_horizontal_grey.png and Border to 8. Fill and Track come from Apply theme.
4. Click Add component and choose FocusComponent. Its links come with the ring, below.
5. Select music, click + Add node and choose Label. Rename it music_label.
6. In its Rect, set Anchor Min and Anchor Max both to 0, 0.5, Offset Min to -244, -24, Offset Max to -24, 24 and Pivot to 0, 0.5. It is a child of the slider and hangs to its left, the row’s label, 220 wide. In its Text, set Text to Music and Scale to 0.75.
7. Select music and press Ctrl+C. Right-click effects_row and choose Paste as child. Rename the copy effects, and its child effects_label. Set effects’s Action to effects and effects_label’s Text to Effects.

Action

A Slider’s Action: the action it fires as it moves. A script hears it with pressed("music"), and reads where the slider stands with amount("music"), in the slider’s own range, 0 to 1 here.

Step

The smallest amount a Slider’s value can change by, and how far one arrow press moves it. 0.1 makes ten notches from one end to the other, and Left and Right move one. 0 allows any value, and the arrows then move it a twentieth of its range. A new Slider’s is 0.

1. In Assets, click Assets in the path bar over the tree, so the script is written at the project’s top, then press Create, choose New script, type music_volume, and press Enter.
2. In the Code tab, replace everything in music_volume.rgs with the script below, and press Ctrl+S.

/// The music slider, on the settings screen: it opens where the saved music
/// volume is, and each move the player makes sets the music's volume and
/// saves it.
component MusicVolume {
    fn on_create() {
        // Writing a slider moves it and presses nothing, so the screen opens
        // on the saved volume and saves nothing. 0.8 until the player has
        // chosen one.
        set_number("SliderComponent", "value", saved_number("music_volume", 0.8));
    }

    fn loop() {
        // A drag, a click on the bar, or Left and Right while it holds the
        // focus moves it, and presses music on that step; amount() answers
        // where it now is.
        if pressed("music") {
            let level = amount("music");
            set_music_volume(level);
            save_number("music_volume", level);
        }
    }
}

1. Select music, click Add component and choose MusicVolume.

set_number and saved_number

set_number("SliderComponent", "value", …) writes a number onto another component of this node, here the slider’s value. saved_number("music_volume", 0.8) reads a number saved on disk, or the second number if none was ever saved.

amount, set_music_volume and save_number

amount("music") is the slider’s value. set_music_volume(level) sets the music bus, 0 to 1. save_number("music_volume", level) writes the number to disk, where it lasts from one launch to the next.

1. In Assets, press Create, choose New script, type effects_volume, and press Enter.
2. In the Code tab, replace everything in effects_volume.rgs with the script below, and press Ctrl+S.

/// The effects slider, on the settings screen: it opens where the saved
/// effects volume is, and each move the player makes sets the effects' volume,
/// saves it, and plays a click at it, so the player hears how loud the game
/// will be. While it is dragged, the click plays no more than once every
/// sample_gap.
component EffectsVolume {
    /// The shortest time between two clicks while the slider moves.
    #[suffix("s")]
    sample_gap: f32 = 0.15,
    /// Seconds until the click may sound again.
    #[hidden]
    quiet: f32 = 0.0,

    fn on_create() {
        // Writing a slider moves it and presses nothing, so the screen opens
        // on the saved volume without a sound. 0.8 until the player has
        // chosen one.
        set_number("SliderComponent", "value", saved_number("effects_volume", 0.8));
    }

    fn loop(dt: f32) {
        // Counted here rather than waited out: a hook that waits hears
        // nothing, and the moves made meanwhile would go unset and unsaved.
        if quiet > 0.0 {
            quiet -= dt;
        }
        // A drag, a click on the bar, or Left and Right while it holds the
        // focus moves it, and presses effects on that step.
        if pressed("effects") {
            let level = amount("effects");
            set_sfx_volume(level);
            save_number("effects_volume", level);
            if quiet <= 0.0 {
                play_sound("click");
                quiet = sample_gap;
            }
        }
    }
}

1. Select effects, click Add component and choose EffectsVolume. Its Sample Gap starts at the script’s own 0.15, and its Quiet is hidden at 0: leave both.
2. Click Add component again and choose AudioSourceComponent. Untick Positional. In its Triggers, press the + beside it once, and set the entry’s Name to click and its Clip to click_001.ogg.

Tick boxes

1. Select hints_row, click + Add node and choose Toggle. Rename it show_hints.
2. Remove its Text: press the bin at the right of its TextComponent header. The box has no word of its own; its name sits beside it.
3. In its Rect, set Anchor Min and Anchor Max both to 0, 0.5, Offset Min to 244, -16, Offset Max to 276, 16 and Pivot to 0, 0.5. That is a box 32 wide and 32 high.
4. In its Panel, set Texture to check_square_grey.png. Border stays 0.
5. In its Toggle, set Action to show_hints, tick On, and set On Texture to check_square_grey_checkmark.png. The colours come from Apply theme.
6. Click Add component and choose FocusComponent.
7. Select show_hints, click + Add node and choose Label. Rename it show_hints_label. Give its Rect and its Text the values of music_label, with Text Show hints.
8. Select show_hints and press Ctrl+C. Right-click names_row and choose Paste as child. Rename the copy item_names and its child item_names_label. Set item_names’s Action to item_names and untick its On, and set item_names_label’s Text to Item names.

Action

A Toggle’s Action: the action it presses on the step it flips, here show_hints. A script reads amount("show_hints"), which is 1 while it is ticked and 0 while it is not, from then on.

On

Whether the box is ticked. It is saved with the scene, unlike a Button’s pressed look. show_hints opens ticked, and item_names not, as a player who has chosen nothing finds them.

Normal, Hovered, Pressed

A Toggle’s tints for its box, as a Button’s are: at rest, under the pointer or with the focus, and while held down. Apply theme writes them from the palette’s button colours: 255, 255, 255 at rest and lit, and 211, 211, 211 held.

Check

The colour of the mark drawn inside the box when it is on. Apply theme writes the palette’s Button Text, the plum 63, 38, 49. A Toggle that has an On Texture draws that and no mark, so here Check is set and not seen.

On Texture

The picture drawn instead of the Panel’s, and instead of the mark, while the box is on: the same box with a tick in it, check_square_grey_checkmark.png. Empty, the box draws the mark in Check, inset by Check Inset, which stays 6.

1. In Assets, press Create, choose New script, type tick_box, and press Enter.
2. In the Code tab, replace everything in tick_box.rgs with the script below, and press Ctrl+S.

/// A tick box on the settings screen that keeps a setting: it opens on the
/// saved setting, and saves it, 1 ticked and 0 not, each time the player ticks
/// or unticks it.
component TickBox {
    /// The setting it keeps: the name it is saved under, which is also the
    /// action its Toggle presses.
    setting: String = "show_hints",
    /// The setting before the player has ever chosen: 1 ticked, 0 not.
    unsaved: f32 = 1.0,

    fn on_create() {
        // Writing a tick box ticks or unticks it and presses nothing, so the
        // screen opens on the saved setting and saves nothing.
        set_flag("ToggleComponent", "on", saved_number(setting, unsaved) == 1.0);
    }

    fn loop() {
        // A click, or Space or Enter while it holds the focus, flips it and
        // presses its action on that step; amount() answers 1 ticked, 0 not.
        if pressed(setting) {
            save_number(setting, amount(setting));
        }
    }
}

1. Select show_hints, click Add component and choose TickBox. Its Setting is show_hints and its Unsaved 1, as the script starts: leave both.
2. Select item_names, click Add component and choose TickBox. Set its Setting to item_names and its Unsaved to 0.

set_flag

Writes a true or false onto another component of this node: here the Toggle’s On, ticked if the saved number is 1. Unsaved is the number a player who has never chosen is given.

1. In Assets, press Create, choose New script, type shown_by_setting, and press Enter.
2. In the Code tab, replace everything in shown_by_setting.rgs with the script below, and press Ctrl+S.

/// Shows this node only while a setting the player chose in Settings is on:
/// the key hints in the HUD, a pickup's name in the room.
component ShownBySetting {
    /// The setting that shows it: show_hints or item_names.
    setting: String = "show_hints",
    /// The setting before the player has ever chosen: 1 on, 0 off.
    unsaved: f32 = 1.0,

    fn on_create() {
        // Settings are saved as 1 for on and 0 for off.
        if saved_number(setting, unsaved) == 1.0 {
            show();
        } else {
            hide();
        }
    }
}

1. Open scenes/delve.ron. Select hud, click + Add node and choose Label. Rename it key_hints.
2. In its Rect, set Anchor Min and Anchor Max both to 0.5, 1, Offset Min to -320, -44, Offset Max to 320, -12 and Pivot to 0.5, 1. That is a line 640 wide at the foot of the screen.
3. In its Text, set Text to WASD or arrows walk, Scale to 0.625 and Align to Center. Set Outline to 63, 38, 49, alpha 255 and Outline Width to 2.
4. Click Add component and choose ShownBySetting. Its Setting is show_hints and its Unsaved 1, as the script starts: leave both.

1. Select potion_1, click + Add node and choose Node. Rename it potion_1_name, and untick its Visible: the name starts hidden.
2. Click Add component and choose WorldTextComponent. Set Text to Potion, Scale to 0.1, Color to 236, 227, 206, alpha 255, Offset to 0, -10 and Sort Layer to 4. Set Outline to 63, 38, 49, alpha 255 and Outline Width to 0.5.
3. Click Add component and choose ShownBySetting. Set its Setting to item_names and its Unsaved to 0.
4. Press Ctrl+C. For each of the other eleven pickups, right-click it and choose Paste as child: potion_2, elixir, key, gem_green, gem_red, gem_blue and coin_1 to coin_5.
5. Rename each copy after its pickup, potion_2_name, elixir_name, key_name, gem_green_name, gem_red_name, gem_blue_name and coin_1_name to coin_5_name, and set its Text: Elixir for the elixir, Key for the key, Gem for each of the three gems, and Coin for each of the five coins.

A list

1. Open scenes/settings.ron. Select size_row, click + Add node and choose Dropdown. Rename it text_size.
2. In its Rect, set Anchor Min and Anchor Max both to 0, 0.5, Offset Min to 244, -20, Offset Max to 484, 20 and Pivot to 0, 0.5. That is a face 240 wide and 40 high.
3. In its Panel, set Texture to input_rectangle.png and Border to 8. In its Text, set Text to Text size, Scale to 0.75 and Align to Center.
4. In its Dropdown, set Action to text_size. Under Options, press the + until there are three, and set them to Small, Normal and Large. Set Selected to 1 and Item Height to 40.
5. Click Add component and choose FocusComponent.
6. Select text_size, click + Add node and choose Panel. Rename it text_size_arrow. In its Rect, set Anchor Min and Anchor Max both to 1, 0.5, Offset Min to -46, -11, Offset Max to -12, 11 and Pivot to 1, 0.5. In its Panel, set Texture to icon_arrow_down_dark.png.
7. Select text_size, click + Add node and choose Label. Rename it text_size_label. Give its Rect the values of music_label, and set its Text to Text size and its Scale to 0.75.

Action

A Dropdown’s Action: the action it fires when the chosen row really changes. Choosing the row that is already chosen presses nothing. A script reads amount("text_size"), the chosen row’s number counted from 0.

Options

The rows of the open list, in order: Small, Normal, Large.

Selected

Which row is chosen, counted from 0, so 1 is Normal. A number past the last row reads as nothing chosen. The closed face shows the chosen option’s words, over its own Text.

Item Height

The height of one row of the open list, in UI units: 40, so the three rows are 120 high.

Normal, Hovered, Pressed

A Dropdown’s tints for its closed face, as a Button’s are: at rest, under the pointer or with the focus, and held down or while the list is open. Apply theme writes them: 255, 255, 255 at rest, the palette’s accent yellow 254, 231, 97 when lit, which is also the colour of the row the keys or the pointer are on, and 211, 211, 211 held.

Popup

The background of the open list, white here, 255, 255, 255. It is drawn opaque, since the list opens over the rows below it.

1. In Assets, press Create, choose New script, type text_size_list, and press Enter.
2. In the Code tab, replace everything in text_size_list.rgs with the script below, and press Ctrl+S.

/// The Text size list on the settings screen: it opens on the saved size, and
/// saves the size each time the player picks one. 0 is Small, 1 Normal and 2
/// Large, the order of the list's options.
component TextSizeList {
    fn on_create() {
        // Writing the list's choice changes what it shows and presses
        // nothing. Normal until the player has chosen.
        set_number("DropdownComponent", "selected", saved_number("text_size", 1.0));
    }

    fn loop() {
        // A click on a row, or Enter on the row the arrows lit, chooses it and
        // presses text_size on that step; amount() answers the row, from 0.
        if pressed("text_size") {
            save_number("text_size", amount("text_size"));
        }
    }
}

1. Select text_size, click Add component and choose TextSizeList.

1. In Assets, press Create, choose New script, type text_size, and press Enter.
2. In the Code tab, replace everything in text_size.rgs with the script below, and press Ctrl+S.

/// Sizes everything on this canvas by the text size the player chose in
/// Settings. A canvas fits its reference into the window, so the smaller the
/// reference, the bigger everything on it is drawn.
component TextSize {
    /// The reference at Small.
    small: Vec2 = vec2(1536.0, 864.0),
    /// The reference at Normal: the window's own size, the art at 1x.
    normal: Vec2 = vec2(1280.0, 720.0),
    /// The reference at Large.
    large: Vec2 = vec2(1066.0, 600.0),

    fn loop() {
        // Read on every step, so the settings screen changes size as soon as
        // its list saves a new choice. Normal, 1, until the player has chosen.
        let size = saved_number("text_size", 1.0);
        if size == 0.0 {
            set_point("CanvasComponent", "reference_size", small);
        } else if size == 2.0 {
            set_point("CanvasComponent", "reference_size", large);
        } else {
            set_point("CanvasComponent", "reference_size", normal);
        }
    }
}

1. Select settings_canvas, click Add component and choose TextSize. Its Small, Normal and Large start at the script’s own 1536 by 864, 1280 by 720 and 1066 by 600: leave them.
2. Do the same for title_canvas in scenes/title.ron, and for hud in scenes/delve.ron.

A ring for the keys

1. Select settings_canvas, click Add component and choose FocusRingComponent.
2. Open scenes/title.ron, select title_canvas, and add a FocusRingComponent the same way. The title’s menu then shows it too.

Color

A Focus Ring’s Color: the colour of the ring. Apply theme sets it to the palette’s accent words, 254, 174, 52, a gold that reads over pictures and plates alike. A new ring’s is white.

1. Open scenes/title.ron, select quit and press Ctrl+C. Open scenes/settings.ron, right-click settings_frame and choose Paste as child. The copy brings the button’s pictures, its Shortcut and its Focus. Rename it back.
2. In its Rect, set Anchor Min and Anchor Max both to 0.5, 1, Offset Min to -110, -73, Offset Max to 110, -24 and Pivot to 0.5, 1. In its Text, set Text to Back. In its Button, set Action to back. Its Shortcut’s Action stays ui_cancel.
3. In each control’s Focus, set the four links from the table below.

1. In Assets, press Create, choose New script, type settings_menu, and press Enter.
2. In the Code tab, replace everything in settings_menu.rgs with the script below, and press Ctrl+S.

/// The settings screen's way back: Back goes to the title. Each control keeps
/// its own setting.
component SettingsMenu {
    fn loop() {
        // A click on Back, Enter while it holds the focus, or Escape through
        // its Shortcut presses back on the game's next step. Escape closes an
        // open list first, and goes back on the next press.
        if pressed("back") {
            // A sound asked for on the step that changes scene plays on after
            // it.
            play_sound("back");
            change_scene("title");
        }
    }
}

1. Select settings_frame, click Add component and choose SettingsMenu.
2. Click Add component again and choose AudioSourceComponent. Untick Positional. In its Triggers, press the + beside it once, and set the entry’s Name to back and its Clip to back_001.ogg.
3. Select settings_canvas and press Apply theme. It writes the colours of everything on the screen from the palette: the labels’ cream, the sliders’ and the list’s tints, the boxes’ marks, and the ring’s colour, the accent’s words, 254, 174, 52, alpha 255.
4. Do the same on title_canvas in scenes/title.ron, where it gives the ring its colour, and on hud in scenes/delve.ron, where it gives the key line its cream.

Saved and applied

1. In the Code tab’s Scripts list, click title.rgs, replace everything in it with the script below, and press Ctrl+S.

/// The title, as it opens: the volumes the player chose in Settings, set before
/// the game's first sound, and the menu faded in. The Canvas Group on this
/// node starts at alpha 0, where the menu is not drawn and takes no key; this
/// brings it to 1 over half a second.
component Title {
    fn on_create() {
        // 0.8 until the player has chosen a volume.
        set_music_volume(saved_number("music_volume", 0.8));
        set_sfx_volume(saved_number("effects_volume", 0.8));
        anneal_number("CanvasGroupComponent", "alpha", 1.0, 0.5, .OutQuad);
    }
}

1. Click title_menu.rgs in the list, replace everything in it with the script below, and press Ctrl+S.

/// The title's menu: New game starts a fresh run in the delve, Settings opens
/// the settings screen, and Quit closes the game.
component TitleMenu {
    /// The health a new game starts with.
    start_health: f32 = 10.0,

    fn loop() {
        // A button pressed by a click, by Enter while it holds the focus, or
        // by its Shortcut presses its action on the game's next step.
        if pressed("new_game") {
            // What a run keeps outlasts a change of scene, so a new game puts
            // it back as a run starts: full health, and nothing picked up.
            keep_number("health", start_health);
            keep_number("potions", 0.0);
            keep_number("elixirs", 0.0);
            keep_number("keys", 0.0);
            keep_number("gems", 0.0);
            keep_number("coins", 0.0);
            // A sound asked for on the step that changes scene plays on after
            // it.
            play_sound("click");
            change_scene("delve");
        }
        if pressed("settings") {
            play_sound("click");
            change_scene("settings");
        }
        if pressed("quit") {
            play_sound("back");
            // The game closes at the end of the step that asks, which would
            // cut the sound off, so it waits a tenth of a second first.
            await wait(0.1);
            quit();
        }
    }
}

The settings screen, its controls and the changes to the title and the delve

Check it works