Struct Storage 

pub struct Storage { /* private fields */ }

Key-value storage that survives restarts, optionally encrypted.

Implementations

impl Storage

pub fn in_memory() -> Self

Storage that lives only in memory and is never written.

pub fn open(path: impl Into<PathBuf>) -> Self

Loads storage from a plain text file at path. A missing file simply gives empty storage. An encrypted file cannot be read without its secret: it is renamed to <file>.broken and Storage::load_error explains why.

pub fn open_encrypted(path: impl Into<PathBuf>, secret: &str) -> Self

Loads storage from an encrypted file at path, using secret to make the key. A missing file gives empty storage. A plain text file is read and written encrypted on the next save. A file that cannot be decrypted (wrong secret, edited or damaged) is renamed to <file>.broken, and Storage::load_error explains why.

pub fn load_error(&self) -> Option<&str>

Why the save file could not be loaded, if it could not: wrong secret, edited or damaged file. The unreadable file was kept as <file>.broken. None when loading worked or there was no file.

if ctx.storage.load_error().is_some() {
    ctx.speak("Your save file is damaged. Starting a new game.");
}

pub fn is_encrypted(&self) -> bool

Whether the file is written encrypted.

pub fn set_encryption(&mut self, secret: Option<&str>)

Turns encryption on with a secret (Some) or off (None). The file is rewritten in the new form on the next save.

pub fn path(&self) -> Option<&Path>

The file this storage is saved to, if any.

pub fn get<T: FromStr>(&self, key: &str) -> Option<T>

Reads a value. Returns None if it is missing or cannot be parsed as T.

Examples found in repository

examples/bell_catcher.rs (line 34)

fn main() -> audio_code::Result<()> {
    Engine::new("Bell Catcher").run_with(|ctx| {
        ctx.audio.register("bell", Synth::sine(1568.0).with(Synth::sine(3136.0).volume(0.3)).length(0.35).decay(9.0).volume(0.6));
        ctx.audio.register("step", Synth::noise().length(0.05).decay(80.0).volume(0.5));
        ctx.audio.register("edge", Synth::sine(110.0).length(0.12).decay(30.0).volume(0.8));
        ctx.audio.register(
            "catch",
            Synth::sine(784.0).length(0.08).then(Synth::sine(1047.0).length(0.08)).then(Synth::sine(1568.0).length(0.2).decay(12.0)).volume(0.4),
        );
        ctx.audio.register("miss", Synth::saw(220.0).sweep_to(80.0).length(0.5).decay(5.0).volume(0.35));

        // Restore the speech settings from the last session.
        if let Some(voice) = ctx.storage.get::<String>("voice") {
            ctx.speech.set_voice(voice);
        }
        let rate: f32 = ctx.storage.get_or("rate", 50.0);
        if rate != 50.0 {
            ctx.speech.set_rate(rate / 100.0);
        }
        Title
    })
}

pub fn get_or<T: FromStr>(&self, key: &str, default: T) -> T

Reads a value, or default if it is missing or invalid.

Examples found in repository

examples/beacon.rs (line 122)

    fn finish(&mut self, ctx: &mut Context) {
        let seconds = self.clock.elapsed_secs().round() as u32;
        let best: u32 = ctx.storage.get_or("best_time", u32::MAX);
        let mut text = format!("You found every beacon in {seconds} seconds.");
        if seconds < best {
            ctx.storage.set("best_time", seconds);
            text.push_str(" That is a new record!");
        } else {
            text.push_str(&format!(" Your record is {best} seconds."));
        }
        ctx.ui.message("done", text);
    }

examples/clicker.rs (line 13)

fn main() -> audio_code::Result<()> {
    let mut score = 0;

    audio_code::run("Clicker", move |ctx| {
        if ctx.once("intro") {
            let best: u32 = ctx.storage.get_or("best", 0);
            ctx.speak(format!("Press space as often as you can in ten seconds. Your best is {best}. Go!"));
            ctx.time.after("end", 10.0);
        }

        if ctx.time.is_scheduled("end") && ctx.pressed(Key::Space) {
            score += 1;
            ctx.audio.play_tone(300.0 + score as f32 * 15.0, 0.05);
        }

        if ctx.time.fired("end") {
            let best: u32 = ctx.storage.get_or("best", 0);
            if score > best {
                ctx.storage.set("best", score);
                ctx.ui.message("result", format!("{score} presses. New record!"));
            } else {
                ctx.ui.message("result", format!("{score} presses. Your best is {best}."));
            }
        }

        if ctx.ui.closed("result") || ctx.pressed(Key::Escape) {
            ctx.quit();
        }
    })
}

examples/bell_catcher.rs (line 37)

fn main() -> audio_code::Result<()> {
    Engine::new("Bell Catcher").run_with(|ctx| {
        ctx.audio.register("bell", Synth::sine(1568.0).with(Synth::sine(3136.0).volume(0.3)).length(0.35).decay(9.0).volume(0.6));
        ctx.audio.register("step", Synth::noise().length(0.05).decay(80.0).volume(0.5));
        ctx.audio.register("edge", Synth::sine(110.0).length(0.12).decay(30.0).volume(0.8));
        ctx.audio.register(
            "catch",
            Synth::sine(784.0).length(0.08).then(Synth::sine(1047.0).length(0.08)).then(Synth::sine(1568.0).length(0.2).decay(12.0)).volume(0.4),
        );
        ctx.audio.register("miss", Synth::saw(220.0).sweep_to(80.0).length(0.5).decay(5.0).volume(0.35));

        // Restore the speech settings from the last session.
        if let Some(voice) = ctx.storage.get::<String>("voice") {
            ctx.speech.set_voice(voice);
        }
        let rate: f32 = ctx.storage.get_or("rate", 50.0);
        if rate != 50.0 {
            ctx.speech.set_rate(rate / 100.0);
        }
        Title
    })
}

// ------------------------------------------------------------------------- menu

struct Title;

fn title_menu(ctx: &Context) -> Menu {
    let voice = ctx.speech.voice().map_or("default".to_string(), |v| v.name.clone());
    let best: u32 = ctx.storage.get_or("best", 0);
    Menu::new("title", "Bell Catcher")
        .button("play", "Play")
        .button("voice", format!("Voice: {voice}"))
        .slider("rate", "Speech rate", ctx.storage.get_or("rate", 50.0), 0.0, 100.0, 5.0)
        .button("help", "How to play")
        .label(format!("Best score: {best}"))
        .button("quit", "Quit")
        .closable(false)
        .wrap(true)
}

/// One button per voice, with the current one focused. `None` if the output has no voices.
fn voice_menu(ctx: &Context) -> Option<Menu> {
    let voices = ctx.speech.voices();
    if voices.is_empty() {
        return None;
    }
    let mut menu = Menu::new("voices", "Choose a voice").button("default", "Default voice");
    for (i, voice) in voices.iter().enumerate() {
        menu = menu.button(format!("voice{i}"), voice.to_string());
    }
    if let Some(i) = ctx.speech.voice().and_then(|current| voices.iter().position(|v| v == current)) {
        menu = menu.focus(&format!("voice{i}"));
    }
    Some(menu.button("back", "Back"))
}

/// Reopens the title menu so its labels show the new values, focused on `item`.
fn refresh_title(ctx: &mut Context, item: &str) {
    ctx.ui.close_id("title");
    let menu = title_menu(ctx).focus(item);
    ctx.ui.open(menu);
}

impl Scene for Title {
    fn start(&mut self, ctx: &mut Context) {
        let menu = title_menu(ctx);
        ctx.ui.open(menu);
    }

    fn on_ui(&mut self, event: &UiEvent, ctx: &mut Context) {
        match event {
            UiEvent::Activated { menu, item } if menu == "title" => match item.as_str() {
                "play" => {
                    ctx.ui.close_all();
                    ctx.switch_scene(Game::default());
                }
                "voice" => match voice_menu(ctx) {
                    Some(menu) => ctx.ui.open(menu),
                    None => ctx.ui.message(
                        "no voices",
                        "Your screen reader speaks with its own voice. Change it in the screen reader's settings.",
                    ),
                },
                "help" => ctx.ui.message(
                    "help",
                    "Bells fall in one of seven lanes in front of you. Listen where a bell rings, \
                     step under it with left and right, and catch it before it lands. \
                     The bell rings faster and higher the closer it gets. You have three lives. \
                     Press S for your score, Escape for the menu.",
                ),
                "quit" => ctx.quit(),
                _ => {}
            },
            UiEvent::Activated { menu, item } if menu == "voices" => {
                if item == "back" {
                    ctx.ui.close();
                    return;
                }
                if item == "default" {
                    ctx.speech.reset_voice();
                    ctx.storage.remove("voice");
                } else if let Some(voice) =
                    item.strip_prefix("voice").and_then(|i| i.parse::<usize>().ok()).and_then(|i| ctx.speech.voices().get(i).cloned())
                    && ctx.speech.set_voice(&voice.id)
                {
                    ctx.storage.set("voice", &voice.id);
                }
                ctx.ui.close();
                refresh_title(ctx, "voice");
                let name = ctx.speech.voice().map_or("Default voice".to_string(), |v| v.name.clone());
                ctx.speech.speak_queued(format!("{name}. This is how I sound now."));
            }
            UiEvent::Changed { menu, item, value } if menu == "title" && item == "rate" => {
                ctx.speech.set_rate(value.as_f32() / 100.0);
                ctx.storage.set("rate", value.as_f32());
            }
            _ => {}
        }
    }

    fn update(&mut self, _ctx: &mut Context) {}
}

// ------------------------------------------------------------------------- game

struct Game {
    lane: i32,
    bell_lane: i32,
    /// Seconds a bell needs to land; shrinks with every catch.
    fall: f32,
    /// Seconds until the current bell lands. Negative while waiting for the next bell.
    left: f32,
    next_ring: f32,
    score: u32,
    lives: u32,
    over: bool,
}

impl Default for Game {
    fn default() -> Self {
        Self { lane: 0, bell_lane: 0, fall: FIRST_FALL, left: 0.0, next_ring: 0.0, score: 0, lives: LIVES, over: false }
    }
}

impl Game {
    fn drop_bell(&mut self) {
        self.bell_lane = random::int(-LANES as i64, LANES as i64) as i32;
        self.left = self.fall;
        self.next_ring = 0.0;
    }

    /// Where the bell is, seen from the player: lanes to the side, a little in front.
    fn bell_position(&self) -> Vec3 {
        vec3((self.bell_lane - self.lane) as f32 * LANE_WIDTH, 2.0, 0.0)
    }

    fn ring(&mut self, ctx: &mut Context) {
        // 0.0 when the bell starts falling, 1.0 when it lands.
        let progress = 1.0 - self.left / self.fall;
        let position = self.bell_position();
        ctx.audio.sound("bell").at(position).pitch(1.0 + progress * 0.6).play();
        self.next_ring = 0.12 + 0.45 * (1.0 - progress);
    }

    fn land(&mut self, ctx: &mut Context) {
        if self.lane == self.bell_lane {
            self.score += 1;
            self.fall = (self.fall * 0.93).max(FASTEST_FALL);
            ctx.play("catch");
            if self.score.is_multiple_of(5) {
                ctx.speak(format!("{} bells!", self.score));
            }
        } else {
            self.lives -= 1;
            ctx.play("miss");
            match self.lives {
                0 => return self.game_over(ctx),
                1 => ctx.speak("Missed! Last life."),
                n => ctx.speak(format!("Missed! {n} lives left.")),
            }
        }
        // A short break before the next bell.
        self.left = -0.8;
    }

    fn game_over(&mut self, ctx: &mut Context) {
        self.over = true;
        let best: u32 = ctx.storage.get_or("best", 0);
        let text = if self.score > best {
            ctx.storage.set("best", self.score);
            format!("Game over. {} bells, a new best score!", self.score)
        } else {
            format!("Game over. {} bells. Your best is {best}.", self.score)
        };
        ctx.ui.message("over", text);
    }

pub fn set(&mut self, key: &str, value: impl ToString)

Stores a value. It is written to disk when the game quits or Storage::save is called.

Panics

If key contains = or a line break.

Examples found in repository

examples/beacon.rs (line 125)

    fn finish(&mut self, ctx: &mut Context) {
        let seconds = self.clock.elapsed_secs().round() as u32;
        let best: u32 = ctx.storage.get_or("best_time", u32::MAX);
        let mut text = format!("You found every beacon in {seconds} seconds.");
        if seconds < best {
            ctx.storage.set("best_time", seconds);
            text.push_str(" That is a new record!");
        } else {
            text.push_str(&format!(" Your record is {best} seconds."));
        }
        ctx.ui.message("done", text);
    }

examples/clicker.rs (line 26)

fn main() -> audio_code::Result<()> {
    let mut score = 0;

    audio_code::run("Clicker", move |ctx| {
        if ctx.once("intro") {
            let best: u32 = ctx.storage.get_or("best", 0);
            ctx.speak(format!("Press space as often as you can in ten seconds. Your best is {best}. Go!"));
            ctx.time.after("end", 10.0);
        }

        if ctx.time.is_scheduled("end") && ctx.pressed(Key::Space) {
            score += 1;
            ctx.audio.play_tone(300.0 + score as f32 * 15.0, 0.05);
        }

        if ctx.time.fired("end") {
            let best: u32 = ctx.storage.get_or("best", 0);
            if score > best {
                ctx.storage.set("best", score);
                ctx.ui.message("result", format!("{score} presses. New record!"));
            } else {
                ctx.ui.message("result", format!("{score} presses. Your best is {best}."));
            }
        }

        if ctx.ui.closed("result") || ctx.pressed(Key::Escape) {
            ctx.quit();
        }
    })
}

examples/bell_catcher.rs (line 128)

    fn on_ui(&mut self, event: &UiEvent, ctx: &mut Context) {
        match event {
            UiEvent::Activated { menu, item } if menu == "title" => match item.as_str() {
                "play" => {
                    ctx.ui.close_all();
                    ctx.switch_scene(Game::default());
                }
                "voice" => match voice_menu(ctx) {
                    Some(menu) => ctx.ui.open(menu),
                    None => ctx.ui.message(
                        "no voices",
                        "Your screen reader speaks with its own voice. Change it in the screen reader's settings.",
                    ),
                },
                "help" => ctx.ui.message(
                    "help",
                    "Bells fall in one of seven lanes in front of you. Listen where a bell rings, \
                     step under it with left and right, and catch it before it lands. \
                     The bell rings faster and higher the closer it gets. You have three lives. \
                     Press S for your score, Escape for the menu.",
                ),
                "quit" => ctx.quit(),
                _ => {}
            },
            UiEvent::Activated { menu, item } if menu == "voices" => {
                if item == "back" {
                    ctx.ui.close();
                    return;
                }
                if item == "default" {
                    ctx.speech.reset_voice();
                    ctx.storage.remove("voice");
                } else if let Some(voice) =
                    item.strip_prefix("voice").and_then(|i| i.parse::<usize>().ok()).and_then(|i| ctx.speech.voices().get(i).cloned())
                    && ctx.speech.set_voice(&voice.id)
                {
                    ctx.storage.set("voice", &voice.id);
                }
                ctx.ui.close();
                refresh_title(ctx, "voice");
                let name = ctx.speech.voice().map_or("Default voice".to_string(), |v| v.name.clone());
                ctx.speech.speak_queued(format!("{name}. This is how I sound now."));
            }
            UiEvent::Changed { menu, item, value } if menu == "title" && item == "rate" => {
                ctx.speech.set_rate(value.as_f32() / 100.0);
                ctx.storage.set("rate", value.as_f32());
            }
            _ => {}
        }
    }

    fn update(&mut self, _ctx: &mut Context) {}
}

// ------------------------------------------------------------------------- game

struct Game {
    lane: i32,
    bell_lane: i32,
    /// Seconds a bell needs to land; shrinks with every catch.
    fall: f32,
    /// Seconds until the current bell lands. Negative while waiting for the next bell.
    left: f32,
    next_ring: f32,
    score: u32,
    lives: u32,
    over: bool,
}

impl Default for Game {
    fn default() -> Self {
        Self { lane: 0, bell_lane: 0, fall: FIRST_FALL, left: 0.0, next_ring: 0.0, score: 0, lives: LIVES, over: false }
    }
}

impl Game {
    fn drop_bell(&mut self) {
        self.bell_lane = random::int(-LANES as i64, LANES as i64) as i32;
        self.left = self.fall;
        self.next_ring = 0.0;
    }

    /// Where the bell is, seen from the player: lanes to the side, a little in front.
    fn bell_position(&self) -> Vec3 {
        vec3((self.bell_lane - self.lane) as f32 * LANE_WIDTH, 2.0, 0.0)
    }

    fn ring(&mut self, ctx: &mut Context) {
        // 0.0 when the bell starts falling, 1.0 when it lands.
        let progress = 1.0 - self.left / self.fall;
        let position = self.bell_position();
        ctx.audio.sound("bell").at(position).pitch(1.0 + progress * 0.6).play();
        self.next_ring = 0.12 + 0.45 * (1.0 - progress);
    }

    fn land(&mut self, ctx: &mut Context) {
        if self.lane == self.bell_lane {
            self.score += 1;
            self.fall = (self.fall * 0.93).max(FASTEST_FALL);
            ctx.play("catch");
            if self.score.is_multiple_of(5) {
                ctx.speak(format!("{} bells!", self.score));
            }
        } else {
            self.lives -= 1;
            ctx.play("miss");
            match self.lives {
                0 => return self.game_over(ctx),
                1 => ctx.speak("Missed! Last life."),
                n => ctx.speak(format!("Missed! {n} lives left.")),
            }
        }
        // A short break before the next bell.
        self.left = -0.8;
    }

    fn game_over(&mut self, ctx: &mut Context) {
        self.over = true;
        let best: u32 = ctx.storage.get_or("best", 0);
        let text = if self.score > best {
            ctx.storage.set("best", self.score);
            format!("Game over. {} bells, a new best score!", self.score)
        } else {
            format!("Game over. {} bells. Your best is {best}.", self.score)
        };
        ctx.ui.message("over", text);
    }

pub fn add(&mut self, key: &str, amount: i64) -> i64

Adds amount to a number (missing counts as 0) and returns the new value. Handy for statistics: ctx.storage.add("games_played", 1).

pub fn remove(&mut self, key: &str)

Removes a value.

Examples found in repository

examples/bell_catcher.rs (line 123)

    fn on_ui(&mut self, event: &UiEvent, ctx: &mut Context) {
        match event {
            UiEvent::Activated { menu, item } if menu == "title" => match item.as_str() {
                "play" => {
                    ctx.ui.close_all();
                    ctx.switch_scene(Game::default());
                }
                "voice" => match voice_menu(ctx) {
                    Some(menu) => ctx.ui.open(menu),
                    None => ctx.ui.message(
                        "no voices",
                        "Your screen reader speaks with its own voice. Change it in the screen reader's settings.",
                    ),
                },
                "help" => ctx.ui.message(
                    "help",
                    "Bells fall in one of seven lanes in front of you. Listen where a bell rings, \
                     step under it with left and right, and catch it before it lands. \
                     The bell rings faster and higher the closer it gets. You have three lives. \
                     Press S for your score, Escape for the menu.",
                ),
                "quit" => ctx.quit(),
                _ => {}
            },
            UiEvent::Activated { menu, item } if menu == "voices" => {
                if item == "back" {
                    ctx.ui.close();
                    return;
                }
                if item == "default" {
                    ctx.speech.reset_voice();
                    ctx.storage.remove("voice");
                } else if let Some(voice) =
                    item.strip_prefix("voice").and_then(|i| i.parse::<usize>().ok()).and_then(|i| ctx.speech.voices().get(i).cloned())
                    && ctx.speech.set_voice(&voice.id)
                {
                    ctx.storage.set("voice", &voice.id);
                }
                ctx.ui.close();
                refresh_title(ctx, "voice");
                let name = ctx.speech.voice().map_or("Default voice".to_string(), |v| v.name.clone());
                ctx.speech.speak_queued(format!("{name}. This is how I sound now."));
            }
            UiEvent::Changed { menu, item, value } if menu == "title" && item == "rate" => {
                ctx.speech.set_rate(value.as_f32() / 100.0);
                ctx.storage.set("rate", value.as_f32());
            }
            _ => {}
        }
    }

pub fn contains(&self, key: &str) -> bool

Whether a value exists.

pub fn keys(&self) -> impl Iterator<Item = &str>

All keys in alphabetical order.

pub fn clear(&mut self)

Removes everything.

pub fn save(&mut self) -> Result<()>

Writes changes to disk now. Does nothing for in-memory storage or without changes.

Trait Implementations

impl Debug for Storage

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Storage

fn default() -> Self

Returns the “default value” for a type.