14c8c85 | plum | pyrossh

git clone https://git.pyrossh.dev/plum

A statically typed, imperative programming language inspired by rust, python

14c8c85 — Peter John 2026-11-02T15:01:04+05:30

Game host: sound (load/play/loop/stop/volume), example music and effects, quick start docs

Generated files not shown: plum-game/Cargo.lock

Files changed (19) hide show

README.md +22 -4
docs/game.png +0 -0
plum-examples/assets/gameover.wav +0 -0
plum-examples/assets/hit.wav +0 -0
plum-examples/assets/music.wav +0 -0
plum-examples/assets/pickup.wav +0 -0
plum-examples/game.plum +35 -4
plum-examples/tools/make_sounds.py +106 -0
plum-game/Cargo.toml +1 -1
plum-game/src/api.rs +85 -2
plum-game/src/main.rs +10 -1
plum-game/src/mq.rs +52 -1
plum-game/src/native.rs +8 -0
plum-game/src/recorder.rs +17 -0
plum-game/src/web.rs +33 -0
plum-game/tests/host_test.rs +49 -0
plum-game/web/plum_bridge.js +6 -1
plum-game/web/screenshot.mjs +0 -29
plum-std/Game.plum +17 -4

README.md CHANGED Viewed

@@ -152,6 +152,21 @@ plum editor helix|vscode      # install highlighting and the language server
 `import std/Name` resolves to `<lib-path>/plum-std/Name.plum`, and `--lib-path` defaults to the current directory, so run the commands from a checkout of this repository (or pass `--lib-path`).
+### Run the example game
+```sh
+cargo run -q -p plum-cli -- game plum-examples/game.plum      # or, after `cargo install --path plum-cli`: plum game plum-examples/game.plum
+```
+Arrow keys or WASD steer the ship, collect the orbs, dodge the mines; Enter or R restarts after the game is over. The first run builds the `plum-game` host in release mode, which takes a while. To play in a browser instead (needs `rustup target add wasm32-unknown-unknown` once):
+```sh
+plum game --web plum-examples/game.plum -o /tmp/orb-run
+python3 -m http.server -d /tmp/orb-run 8080   # then open http://localhost:8080
+```
+![the example game](docs/game.png)
 ## Layout and comments
 Blocks are indentation-sensitive (2 spaces), like Python — there's no `{ }` for grouping statements. `#` starts a line comment.
@@ -1029,9 +1044,7 @@ Every module that imports `std/Str` also exports four helpers for hosts that can
 `plum game file.plum` compiles a game and runs it in a native window (macroquad, with the module under wasmtime). `plum game --web file.plum [-o dist] [--assets DIR]` writes a static web build instead: `index.html`, `mq_js_bundle.js`, `plum_bridge.js`, `plum-game.wasm`, `plum.wasm`, `preload.txt` and an `assets/` copy of the whole asset directory (every file in it is listed in `preload.txt` and fetched before the first frame; `dist` defaults to `dist` beside the source file). Serve it from any static host; the browser needs wasm GC support. The web build needs `rustup target add wasm32-unknown-unknown`.
-`plum game plum-examples/game.plum` runs the example, a small arcade game: steer a ship with the arrow keys or WASD, collect orbs, dodge mines (Enter restarts). It draws shapes, text and an animated sprite sheet (`plum-examples/assets/sprites.png`, generated by `plum-examples/tools/make_sprites.py`, kept outside the asset dir so it is not shipped). Its rules are plain functions with `test` blocks, so `plum test plum-examples` covers them without a window.
-![the example game](docs/game.png)
+`plum game plum-examples/game.plum` runs the example, a small arcade game: steer a ship with the arrow keys or WASD, collect orbs, dodge mines (Enter restarts). It draws shapes, text and an animated sprite sheet (`plum-examples/assets/sprites.png`, generated by `plum-examples/tools/make_sprites.py`) and plays music and sound effects (`plum-examples/assets/*.wav`, generated by `plum-examples/tools/make_sounds.py`); both generators live outside the asset dir so they are not shipped. For a bigger game built on this engine see the Knights and Merchants port in the sibling repo `../kam_plum` (`./run.sh` there). Its rules are plain functions with `test` blocks, so `plum test plum-examples` covers them without a window.
 A game declares three exports. `G` is any record and holds all game state (there are no globals):
@@ -1047,7 +1060,9 @@ The host calls `init` once after the window exists, then `update` and `draw` eve
 **Asset root:** `plum-game <wasm> [--assets DIR]` reads textures and files relative to `DIR`, default `assets` beside the wasm (`$PLUM_GAME_ASSETS` overrides that default). `plum game file.plum` passes `assets` beside the source file. A path that escapes the root (`..` or absolute) fails like a missing file: `-1`, `""` or `false`.
-**Host API** (`std/Game`; texture handles are `-1` on failure; coordinates are world units once a camera is set):
+**Sounds:** macroquad decodes sounds asynchronously (always on the web), so the host decodes every `.wav` and `.ogg` file in the asset root before it calls `init` (natively it walks the asset directory, in the browser it uses the preloaded files); `soundLoad` then looks the decoded sound up by path with the same path-escape rules as `textureLoad`. Browsers only start audio after a user gesture (a key press or click); sounds played before that are silent, and macroquad's audio plugin resumes playback on the first gesture, so the example's music begins once you press a key.
+**Host API** (`std/Game`; texture and sound handles are `-1` on failure; coordinates are world units once a camera is set):
 | function | meaning |
 |---|---|
@@ -1060,6 +1075,9 @@ The host calls `init` once after the window exists, then `update` and `draw` eve
 | `textureSetSmooth(t, smooth)` | linear (`true`) or nearest (`false`, the default) filtering |
 | `drawTexture(t, x, y, tint)` | the texture at its natural size, top-left at `(x, y)` |
 | `drawTextureEx(t, sx, sy, sw, sh, x, y, w, h, rotation, flipX, tint)` | source rect `(sx, sy, sw, sh)` in texture pixels drawn into dest rect `(x, y, w, h)`, rotated `rotation` radians clockwise about the dest centre |
+| `soundLoad(path)` | a handle for a WAV or OGG file relative to the asset root (`-1` on failure) |
+| `soundPlay(s, volume)`, `soundLoop(s, volume)` | one-shot play (plays may overlap) and start looping; `volume` is 0..1 |
+| `soundStop(s)`, `soundSetVolume(s, volume)` | stop every play of the sound; change its volume. A bad handle is a no-op |
 | `fileExists(path)`, `fileLoad(path)` | whole file as a `Str` (`""` if missing), relative to the asset root |
 | `isKeyDown(k)`, `isKeyPressed(k)`, `isMouseDown(b)`, `isMousePressed(b)` | input; `k` is a `Key` constant, `b` a `Mouse` constant |
 | `mousePos()`, `mouseWheel()` | pointer in screen pixels; wheel direction this frame (+ is up) |

docs/game.png CHANGED Viewed

Binary file

plum-examples/assets/gameover.wav ADDED Viewed

Binary file

plum-examples/assets/hit.wav ADDED Viewed

Binary file

plum-examples/assets/music.wav ADDED Viewed

Binary file

plum-examples/assets/pickup.wav ADDED Viewed

Binary file

plum-examples/game.plum CHANGED Viewed

@@ -1,6 +1,7 @@
 # Orb Run: a small arcade game for the game host (`plum game plum-examples/game.plum`).
 # Steer the ship with the arrow keys or WASD, collect the drifting orbs and avoid
-# the mines. Three lives; Enter or R restarts after the game is over.
+# the mines. Three lives; Enter or R restarts after the game is over. The music
+# loops from `init`; orbs, mines and the end of a run each play a sound.
 #
 # All rules are plain functions over `World` that never call the host, so the
 # `test` blocks below run under `plum test`; only `init`, `update` and `draw`
@@ -45,7 +46,11 @@ record World(
   hurt: Float,
   clock: Float,
   over: Bool,
-  sheet: Int)
+  sheet: Int,
+  pickupSound: Int,
+  hitSound: Int,
+  overSound: Int,
+  musicSound: Int)
 fun distance(a: Body, b: Body) -> Float =
   Math.hypot(a.x - b.x, a.y - b.y)
@@ -83,7 +88,8 @@ fun newWorld(seed: Int, sheet: Int) -> World =
   ship := Body(x: Rules.ArenaW / 2.0, y: Rules.ArenaH / 2.0, vx: 0.0, vy: 0.0, angle: 0.0)
   w := World(
     ship: ship, orbs: List[Body](), mines: List[Body](), rng: rng, score: 0, best: 0,
-    lives: Rules.StartLives, hurt: 0.0, clock: 0.0, over: false, sheet: sheet)
+    lives: Rules.StartLives, hurt: 0.0, clock: 0.0, over: false, sheet: sheet,
+    pickupSound: -1, hitSound: -1, overSound: -1, musicSound: -1)
   for i := range Rules.OrbCount
     w.orbs.push(spawn(rng, ship, 120.0, 40.0))
   for i := range mineCount(0)
@@ -184,8 +190,22 @@ fun step(w: World, ax: Float, ay: Float, dt: Float) =
 # --- host glue: input, drawing ---
+fun musicVolume() -> Float =
+  0.3
+# Restarts the music loop from the top.
+fun startMusic(w: World) =
+  soundStop(w.musicSound)
+  soundLoop(w.musicSound, musicVolume())
 export fun init() -> World =
-  newWorld(2024, textureLoad("sprites.png"))
+  w := newWorld(2024, textureLoad("sprites.png"))
+  w.pickupSound = soundLoad("pickup.wav")
+  w.hitSound = soundLoad("hit.wav")
+  w.overSound = soundLoad("gameover.wav")
+  w.musicSound = soundLoad("music.wav")
+  startMusic(w)
+  w
 fun axis(negative: Bool, positive: Bool) -> Float =
   if negative && !positive
@@ -198,11 +218,22 @@ fun axis(negative: Bool, positive: Bool) -> Float =
 export fun update(w: World, dt: Float) =
   if w.over && {isKeyPressed(Key.Enter) || isKeyPressed(Key.KeyR)}
     restart(w)
+    startMusic(w)
   left := isKeyDown(Key.Left) || isKeyDown(Key.KeyA)
   right := isKeyDown(Key.Right) || isKeyDown(Key.KeyD)
   up := isKeyDown(Key.Up) || isKeyDown(Key.KeyW)
   down := isKeyDown(Key.Down) || isKeyDown(Key.KeyS)
+  score := w.score
+  lives := w.lives
   step(w, axis(left, right), axis(up, down), dt)
+  if w.score > score
+    soundPlay(w.pickupSound, 0.8)
+  if w.lives < lives
+    if w.over
+      soundStop(w.musicSound)
+      soundPlay(w.overSound, 1.0)
+    else
+      soundPlay(w.hitSound, 1.0)
 # Draws frame `frame` of sheet row `row`, centred on (x, y), at `Rules.Zoom` times its size.
 fun sprite(w: World, row: Int, frame: Int, x: Float, y: Float, angle: Float, tint: Color) =

plum-examples/tools/make_sounds.py ADDED Viewed

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Generates the Orb Run sound effects and music loop into ../assets.
+Standard library only: python3 plum-examples/tools/make_sounds.py
+Everything is synthesized here, so the WAVs are original and reproducible.
+All files are mono, 16-bit, 22050 Hz.
+"""
+import math
+import os
+import random
+import struct
+import wave
+RATE = 22050
+OUT = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "assets")
+def write(name, samples, fade=True):
+    if fade:
+        # A short fade-out so a clip never ends on a click.
+        n = int(0.01 * RATE)
+        samples = samples[:-n] + [x * (1 - i / n) for i, x in enumerate(samples[-n:])]
+    peak = max(1e-9, max(abs(s) for s in samples))
+    gain = min(1.0, 0.9 / peak)
+    path = os.path.join(OUT, name)
+    with wave.open(path, "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(RATE)
+        w.writeframes(b"".join(struct.pack("<h", int(s * gain * 32767)) for s in samples))
+    print(f"{name}: {len(samples)} samples, {os.path.getsize(path)} bytes")
+def tone(freq, seconds, decay=6.0, harmonic=0.0):
+    n = int(seconds * RATE)
+    out = []
+    for i in range(n):
+        t = i / RATE
+        env = math.exp(-decay * t) * min(1.0, i / 80)
+        v = math.sin(2 * math.pi * freq * t) + harmonic * math.sin(4 * math.pi * freq * t)
+        out.append(v * env)
+    return out
+def pickup():
+    # Two quick rising notes, a fifth apart.
+    a = tone(784.0, 0.07, 14.0, 0.3)
+    b = tone(1175.0, 0.12, 12.0, 0.3)
+    return [0.6 * s for s in a + b]
+def hit():
+    # A low thump with a burst of noise.
+    rng = random.Random(3)
+    n = int(0.25 * RATE)
+    out = []
+    phase = 0.0
+    for i in range(n):
+        t = i / RATE
+        freq = 140.0 * math.exp(-9.0 * t) + 45.0
+        phase += 2 * math.pi * freq / RATE
+        env = math.exp(-11.0 * t)
+        noise = (rng.random() * 2 - 1) * math.exp(-30.0 * t)
+        out.append(0.8 * math.sin(phase) * env + 0.4 * noise)
+    return out
+def gameover():
+    # Three falling notes with a slight wobble.
+    out = []
+    for f in (440.0, 349.0, 262.0):
+        n = int(0.133 * RATE)
+        for i in range(n):
+            t = i / RATE
+            wob = 1 + 0.01 * math.sin(2 * math.pi * 7 * t)
+            env = math.exp(-4.0 * t) * min(1.0, i / 80) * min(1.0, (n - i) / 200)
+            out.append(0.55 * (math.sin(2 * math.pi * f * wob * t) + 0.4 * math.sin(2 * math.pi * f * 0.5 * t)) * env)
+    return out
+def music():
+    # Two beats of arpeggio over Am then F, 96 bpm, eight eighth notes. Notes
+    # ring past their slot and wrap around the end, so the loop has no seam.
+    bpm = 96
+    step = 60.0 / bpm / 2
+    n = int(8 * step * RATE)
+    buf = [0.0] * n
+    am = [220.0, 261.63, 329.63, 261.63]
+    fm = [174.61, 261.63, 349.23, 261.63]
+    for k, f in enumerate(am + fm):
+        start = int(k * step * RATE)
+        for i, s in enumerate(tone(f, 0.9, 4.5, 0.25)):
+            buf[(start + i) % n] += 0.28 * s
+    for start_beat, f in ((0, 110.0), (2, 87.31)):
+        start = int(start_beat * 2 * step * RATE)
+        for i, s in enumerate(tone(f, 1.2, 2.2, 0.15)):
+            buf[(start + i) % n] += 0.32 * s
+    return buf
+if __name__ == "__main__":
+    os.makedirs(OUT, exist_ok=True)
+    write("pickup.wav", pickup())
+    write("hit.wav", hit())
+    write("gameover.wav", gameover())
+    write("music.wav", music(), fade=False)

plum-game/Cargo.toml CHANGED Viewed

@@ -5,7 +5,7 @@ edition = "2021"
 description = "Native and web host for Plum game programs"
 [dependencies]
-macroquad = { version = "0.4", default-features = false }
+macroquad = { version = "0.4", default-features = false, features = ["audio"] }
 [target.'cfg(not(target_arch = "wasm32"))'.dependencies]
 wasmtime = "47"

plum-game/src/api.rs CHANGED Viewed

@@ -46,6 +46,17 @@ pub trait Backend: 'static {
     /// The whole file, empty when it is missing.
     fn file_load(&mut self, path: &str) -> Vec<u8>;
+    /// A handle for the WAV or OGG file at `path`, `-1` when it is missing,
+    /// escapes the asset root or was not decoded.
+    fn sound_load(&mut self, path: &str) -> i32;
+    /// A one-shot play; plays of the same sound may overlap.
+    fn sound_play(&mut self, s: i32, volume: f32);
+    /// Starts the sound looping.
+    fn sound_loop(&mut self, s: i32, volume: f32);
+    /// Stops every play and loop of the sound.
+    fn sound_stop(&mut self, s: i32);
+    fn sound_set_volume(&mut self, s: i32, volume: f32);
     fn is_key_down(&mut self, k: i32) -> bool;
     fn is_key_pressed(&mut self, k: i32) -> bool;
     fn mouse_pos(&mut self) -> (f32, f32);
@@ -86,16 +97,39 @@ struct Tex {
 pub struct AssetStore {
     source: Source,
     textures: Vec<Tex>,
+    /// Asset-root-relative paths of the sounds handed out by `sound_load`.
+    sounds: Vec<String>,
+}
+/// Whether `path` names a sound file the host decodes.
+pub fn is_sound_path(path: &str) -> bool {
+    let lower = path.to_ascii_lowercase();
+    lower.ends_with(".wav") || lower.ends_with(".ogg")
+}
+/// Appends the relative paths of the regular files under `dir` to `out`.
+/// Symlinked directories are not followed.
+fn walk(dir: &Path, rel: &str, out: &mut Vec<String>) {
+    let Ok(entries) = std::fs::read_dir(dir) else { return };
+    for e in entries.flatten() {
+        let Some(name) = e.file_name().to_str().map(str::to_string) else { continue };
+        let path = if rel.is_empty() { name } else { format!("{rel}/{name}") };
+        match e.file_type() {
+            Ok(t) if t.is_dir() => walk(&e.path(), &path, out),
+            Ok(_) => out.push(path),
+            Err(_) => {}
+        }
+    }
 }
 impl AssetStore {
     pub fn new(root: PathBuf) -> Self {
-        AssetStore { source: Source::Dir(root), textures: Vec::new() }
+        AssetStore { source: Source::Dir(root), textures: Vec::new(), sounds: Vec::new() }
     }
     /// A store that serves only files added with [`AssetStore::insert`].
     pub fn preloaded() -> Self {
-        AssetStore { source: Source::Files(HashMap::new()), textures: Vec::new() }
+        AssetStore { source: Source::Files(HashMap::new()), textures: Vec::new(), sounds: Vec::new() }
     }
     /// Registers a file under its asset-root-relative path. No effect on a
@@ -141,6 +175,37 @@ impl AssetStore {
         }
     }
+    /// Every readable `.wav` or `.ogg` file in the asset root, sorted.
+    pub fn sound_paths(&self) -> Vec<String> {
+        let mut all = Vec::new();
+        match &self.source {
+            Source::Dir(root) => walk(root, "", &mut all),
+            Source::Files(files) => all.extend(files.keys().cloned()),
+        }
+        all.retain(|p| is_sound_path(p) && self.file_exists(p));
+        all.sort();
+        all
+    }
+    /// The handle for the sound file at `path` (the same one on every call),
+    /// `-1` when it is not a readable `.wav` or `.ogg` inside the root.
+    pub fn sound_load(&mut self, path: &str) -> i32 {
+        if !is_sound_path(path) || !self.file_exists(path) {
+            return -1;
+        }
+        let path = path.trim_start_matches("./");
+        let i = self.sounds.iter().position(|p| p == path).unwrap_or_else(|| {
+            self.sounds.push(path.to_string());
+            self.sounds.len() - 1
+        });
+        i as i32
+    }
+    /// The path a sound handle was loaded from.
+    pub fn sound_path(&self, s: i32) -> Option<&str> {
+        self.sounds.get(usize::try_from(s).ok()?).map(String::as_str)
+    }
     fn tex(&self, t: i32) -> Option<&Tex> {
         self.textures.get(usize::try_from(t).ok()?)
     }
@@ -206,6 +271,24 @@ mod tests {
         let _ = std::fs::remove_dir_all(&base);
     }
+    #[test]
+    fn sound_handles_need_a_sound_file_in_the_root() {
+        let mut s = AssetStore::preloaded();
+        s.insert("a.wav", vec![1]);
+        s.insert("sub/b.OGG", vec![1]);
+        s.insert("c.png", vec![1]);
+        assert_eq!(s.sound_paths(), ["a.wav", "sub/b.OGG"]);
+        assert_eq!(s.sound_load("sub/b.OGG"), 0);
+        assert_eq!(s.sound_load("./a.wav"), 1);
+        assert_eq!(s.sound_load("a.wav"), 1);
+        assert_eq!(s.sound_load("c.png"), -1);
+        assert_eq!(s.sound_load("missing.wav"), -1);
+        assert_eq!(s.sound_load("../a.wav"), -1);
+        assert_eq!(s.sound_path(1), Some("a.wav"));
+        assert_eq!(s.sound_path(-1), None);
+        assert_eq!(s.sound_path(2), None);
+    }
     #[test]
     fn paths_escaping_the_root_are_rejected() {
         for bad in ["../x", "a/../../x", "/etc/passwd", "a\\b", ""] {

plum-game/src/main.rs CHANGED Viewed

@@ -36,7 +36,15 @@ fn parse_args() -> Result<(std::path::PathBuf, std::path::PathBuf), String> {
 #[cfg(not(target_arch = "wasm32"))]
 async fn run(wasm: std::path::PathBuf, assets: std::path::PathBuf) -> Result<(), String> {
     let bytes = std::fs::read(&wasm).map_err(|e| format!("{}: {e}", wasm.display()))?;
+    let mut backend = MqBackend::new(assets);
+    // Sounds are decoded before `init`, so `soundLoad` can hand out handles.
+    for (path, data) in backend.sound_files() {
+        match plum_game::mq::decode_sound(&data).await {
+            Some(sound) => backend.add_sound(&path, sound),
+            None => eprintln!("{path}: could not decode sound"),
+        }
+    }
-    let mut game = PlumGame::load(&bytes, MqBackend::new(assets)).map_err(|e| format!("{e:#}"))?;
+    let mut game = PlumGame::load(&bytes, backend).map_err(|e| format!("{e:#}"))?;
     game.init().map_err(|e| format!("init: {e:#}"))?;
     let capture = Capture::from_env()?;
     let mut frame = 0u32;
@@ -92,6 +100,7 @@ async fn run_web() -> Result<(), String> {
     while !plum_game::web::bridge_ready() {
         next_frame().await;
     }
+    plum_game::web::decode_sounds().await;
     plum_game::web::bridge_init();
     loop {
         plum_game::web::bridge_update(macroquad::time::get_frame_time());

plum-game/src/mq.rs CHANGED Viewed

@@ -3,7 +3,9 @@
 //! and `resetCamera` returns to screen pixels.
 use crate::api::{AssetStore, Backend, Color};
+use macroquad::audio;
 use macroquad::prelude as mq;
+use std::collections::HashMap;
 use std::path::PathBuf;
 /// Maps the Design's GLFW key numbers to macroquad key codes.
@@ -50,6 +52,14 @@ pub struct MqBackend {
     /// Textures uploaded on first use, with the filter currently applied.
     uploaded: Vec<Option<(mq::Texture2D, bool)>>,
     cam: (f32, f32, f32),
+    /// Sounds decoded before `init`, by asset-root-relative path.
+    sounds: HashMap<String, audio::Sound>,
+}
+/// Decodes WAV or OGG bytes. macroquad decodes in the background on the web,
+/// so this resolves a few frames later there.
+pub async fn decode_sound(bytes: &[u8]) -> Option<audio::Sound> {
+    audio::load_sound_from_bytes(bytes).await.ok()
 }
 impl MqBackend {
@@ -58,13 +68,28 @@ impl MqBackend {
     }
     pub fn with_assets(assets: AssetStore) -> Self {
-        MqBackend { assets, uploaded: Vec::new(), cam: (0.0, 0.0, 1.0) }
+        MqBackend { assets, uploaded: Vec::new(), cam: (0.0, 0.0, 1.0), sounds: HashMap::new() }
     }
     pub fn assets_mut(&mut self) -> &mut AssetStore {
         &mut self.assets
     }
+    /// The `(path, bytes)` of every sound file in the asset root, for the host
+    /// to decode (with [`decode_sound`]) and hand back through
+    /// [`MqBackend::add_sound`] before the game's `init`.
+    pub fn sound_files(&self) -> Vec<(String, Vec<u8>)> {
+        self.assets.sound_paths().into_iter().filter_map(|p| Some((p.clone(), self.assets.read(&p)?))).collect()
+    }
+    pub fn add_sound(&mut self, path: &str, sound: audio::Sound) {
+        self.sounds.insert(path.to_string(), sound);
+    }
+    fn sound(&self, s: i32) -> Option<&audio::Sound> {
+        self.sounds.get(self.assets.sound_path(s)?)
+    }
     fn to_screen(&self, x: f32, y: f32) -> (f32, f32) {
         ((x - self.cam.0) * self.cam.2, (y - self.cam.1) * self.cam.2)
     }
@@ -175,6 +200,32 @@ impl Backend for MqBackend {
     fn file_load(&mut self, path: &str) -> Vec<u8> {
         self.assets.file_load(path)
     }
+    fn sound_load(&mut self, path: &str) -> i32 {
+        if !self.sounds.contains_key(path.trim_start_matches("./")) {
+            return -1;
+        }
+        self.assets.sound_load(path)
+    }
+    fn sound_play(&mut self, s: i32, volume: f32) {
+        if let Some(snd) = self.sound(s) {
+            audio::play_sound(snd, audio::PlaySoundParams { looped: false, volume });
+        }
+    }
+    fn sound_loop(&mut self, s: i32, volume: f32) {
+        if let Some(snd) = self.sound(s) {
+            audio::play_sound(snd, audio::PlaySoundParams { looped: true, volume });
+        }
+    }
+    fn sound_stop(&mut self, s: i32) {
+        if let Some(snd) = self.sound(s) {
+            audio::stop_sound(snd);
+        }
+    }
+    fn sound_set_volume(&mut self, s: i32, volume: f32) {
+        if let Some(snd) = self.sound(s) {
+            audio::set_sound_volume(snd, volume);
+        }
+    }
     fn is_key_down(&mut self, k: i32) -> bool {
         key_code(k).is_some_and(mq::is_key_down)
     }

plum-game/src/native.rs CHANGED Viewed

@@ -130,6 +130,14 @@ fn dispatch<B: Backend>(name: &str, caller: &mut Caller<'_, HostState<B>>, p: &[
             let bytes = b!().file_load(&s);
             r[0] = new_str(caller, &bytes)?;
         }
+        "soundLoad" => {
+            let s = str_arg(caller, p, 0)?;
+            r[0] = Val::I32(b!().sound_load(&s));
+        }
+        "soundPlay" => b!().sound_play(int(p, 0), f(p, 1)),
+        "soundLoop" => b!().sound_loop(int(p, 0), f(p, 1)),
+        "soundStop" => b!().sound_stop(int(p, 0)),
+        "soundSetVolume" => b!().sound_set_volume(int(p, 0), f(p, 1)),
         "isKeyDown" => r[0] = Val::I32(b!().is_key_down(int(p, 0)) as i32),
         "isKeyPressed" => r[0] = Val::I32(b!().is_key_pressed(int(p, 0)) as i32),
         "mousePos" => {

plum-game/src/recorder.rs CHANGED Viewed

@@ -123,6 +123,23 @@ impl Backend for Recorder {
         self.rec(format!("fileLoad({path:?}) -> {} bytes", bytes.len()));
         bytes
     }
+    fn sound_load(&mut self, path: &str) -> i32 {
+        let s = self.assets.sound_load(path);
+        self.rec(format!("soundLoad({path:?}) -> {s}"));
+        s
+    }
+    fn sound_play(&mut self, s: i32, volume: f32) {
+        self.rec(format!("soundPlay({s},{volume})"));
+    }
+    fn sound_loop(&mut self, s: i32, volume: f32) {
+        self.rec(format!("soundLoop({s},{volume})"));
+    }
+    fn sound_stop(&mut self, s: i32) {
+        self.rec(format!("soundStop({s})"));
+    }
+    fn sound_set_volume(&mut self, s: i32, volume: f32) {
+        self.rec(format!("soundSetVolume({s},{volume})"));
+    }
     fn is_key_down(&mut self, k: i32) -> bool {
         self.rec(format!("isKeyDown({k})"));
         self.keys_down.contains(&k)

plum-game/src/web.rs CHANGED Viewed

@@ -52,6 +52,18 @@ fn with<R>(f: impl FnOnce(&mut MqBackend) -> R) -> R {
     BACKEND.with(|b| f(&mut b.borrow_mut()))
 }
+/// Decodes every preloaded `.wav` and `.ogg` file. Run it once, after all
+/// `preload` calls and before the game's `init`.
+pub async fn decode_sounds() {
+    let files = with(|b| b.sound_files());
+    for (path, bytes) in files {
+        // No borrow is held across the await: decoding takes frames on the web.
+        if let Some(sound) = crate::mq::decode_sound(&bytes).await {
+            with(|b| b.add_sound(&path, sound));
+        }
+    }
+}
 /// Registers a fetched file under its asset-root-relative path.
 pub fn preload(path: &str, bytes: Vec<u8>) {
     with(|b| b.assets_mut().insert(path, bytes));
@@ -197,6 +209,27 @@ pub extern "C" fn pg_file_read(dst: *mut u8) {
     })
 }
 #[no_mangle]
+pub extern "C" fn pg_sound_load(p: *const u8, n: usize) -> i32 {
+    let s = text(p, n);
+    with(|b| b.sound_load(&s))
+}
+#[no_mangle]
+pub extern "C" fn pg_sound_play(s: i32, volume: f32) {
+    with(|b| b.sound_play(s, volume))
+}
+#[no_mangle]
+pub extern "C" fn pg_sound_loop(s: i32, volume: f32) {
+    with(|b| b.sound_loop(s, volume))
+}
+#[no_mangle]
+pub extern "C" fn pg_sound_stop(s: i32) {
+    with(|b| b.sound_stop(s))
+}
+#[no_mangle]
+pub extern "C" fn pg_sound_set_volume(s: i32, volume: f32) {
+    with(|b| b.sound_set_volume(s, volume))
+}
+#[no_mangle]
 pub extern "C" fn pg_is_key_down(k: i32) -> i32 {
     with(|b| b.is_key_down(k)) as i32
 }

plum-game/tests/host_test.rs CHANGED Viewed

@@ -200,4 +200,53 @@ fn exampleGameRunsFrames() {
     assert!(calls.iter().any(|c| c.starts_with("drawTextureEx(0,")), "no drawTextureEx recorded");
     assert!(calls.iter().any(|c| c.starts_with("drawCircle(")));
     assert!(calls.iter().any(|c| c.starts_with("drawText(\"Score ")));
+    for sound in ["pickup", "hit", "gameover", "music"] {
+        assert!(calls.iter().any(|c| c.starts_with(&format!("soundLoad(\"{sound}.wav\") -> "))), "{sound}: {calls:?}");
+    }
+    assert!(calls.contains(&"soundLoad(\"music.wav\") -> 3".to_string()), "{calls:?}");
+    assert!(calls.contains(&"soundLoop(3,0.3)".to_string()), "music loop not started: {calls:?}");
+}
+#[test]
+fn soundLoadAndPlayRecorded() {
+    use plum_game::api::Backend;
+    let mut rec = Recorder::with_assets(examples_assets());
+    let s = rec.sound_load("pickup.wav");
+    assert_eq!(s, 0);
+    assert_eq!(rec.sound_load("./pickup.wav"), 0);
+    assert_eq!(rec.sound_load("sprites.png"), -1);
+    assert_eq!(rec.sound_load("missing.wav"), -1);
+    rec.sound_play(s, 0.5);
+    rec.sound_loop(s, 0.25);
+    rec.sound_set_volume(s, 0.75);
+    rec.sound_stop(s);
+    assert_eq!(
+        rec.calls,
+        [
+            "soundLoad(\"pickup.wav\") -> 0",
+            "soundLoad(\"./pickup.wav\") -> 0",
+            "soundLoad(\"sprites.png\") -> -1",
+            "soundLoad(\"missing.wav\") -> -1",
+            "soundPlay(0,0.5)",
+            "soundLoop(0,0.25)",
+            "soundSetVolume(0,0.75)",
+            "soundStop(0)",
+        ]
+    );
+}
+#[test]
+fn soundPathEscapeRejected() {
+    use plum_game::api::Backend;
+    let dir = scratch("sound_escape");
+    let root = dir.join("assets");
+    std::fs::create_dir_all(&root).unwrap();
+    std::fs::copy(examples_assets().join("pickup.wav"), dir.join("pickup.wav")).unwrap();
+    std::fs::copy(examples_assets().join("pickup.wav"), root.join("ok.wav")).unwrap();
+    let mut rec = Recorder::with_assets(root);
+    let escaped = [rec.sound_load("../pickup.wav"), rec.sound_load("sub/../../pickup.wav"), rec.sound_load("/etc/pickup.wav")];
+    let ok = rec.sound_load("ok.wav");
+    let _ = std::fs::remove_dir_all(&dir);
+    assert_eq!(escaped, [-1, -1, -1]);
+    assert_eq!(ok, 0);
 }

plum-game/web/plum_bridge.js CHANGED Viewed

@@ -29,6 +29,11 @@
     drawTexture: "pg_draw_texture",
     drawTextureEx: "pg_draw_texture_ex",
     fileExists: "pg_file_exists",
+    soundLoad: "pg_sound_load",
+    soundPlay: "pg_sound_play",
+    soundLoop: "pg_sound_loop",
+    soundStop: "pg_sound_stop",
+    soundSetVolume: "pg_sound_set_volume",
     isKeyDown: "pg_is_key_down",
     isKeyPressed: "pg_is_key_pressed",
     isMouseDown: "pg_is_mouse_down",
@@ -36,7 +41,7 @@
     mouseWheel: "pg_mouse_wheel",
   };
   // Externs whose first parameter is a Str.
-  const STR_FIRST = new Set(["drawText", "textureLoad", "fileExists"]);
+  const STR_FIRST = new Set(["drawText", "textureLoad", "soundLoad", "fileExists"]);
   // Externs with a multi-value result, built from several pg_* calls.
   const MULTI = {
     mousePos: (host) => [host.pg_mouse_x(), host.pg_mouse_y()],

plum-game/web/screenshot.mjs DELETED Viewed

@@ -1,29 +0,0 @@
-import { spawn } from "node:child_process";
-import fs from "node:fs";
-// Headless Chrome screenshot after a real-time wait (Chrome's --screenshot fires before the frame loop has drawn).
-// usage: node screenshot.mjs <url> <out.png> <seconds> <chrome-profile-dir>
-const [url, out, secs = "12", prof] = process.argv.slice(2);
-const chrome = spawn("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", [
-  "--headless=new", "--use-angle=swiftshader", "--enable-unsafe-swiftshader", "--window-size=1024,768",
-  "--remote-debugging-port=9333", `--user-data-dir=${prof}`, "about:blank"], { stdio: "ignore" });
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-let tabs;
-for (let i = 0; i < 50; i++) { try { tabs = await (await fetch("http://127.0.0.1:9333/json")).json(); if (tabs.length) break; } catch {} await sleep(200); }
-const ws = new WebSocket(tabs.find((t) => t.type === "page").webSocketDebuggerUrl);
-await new Promise((r) => (ws.onopen = r));
-let id = 0; const pend = new Map();
-const send = (method, params = {}) => new Promise((r) => { pend.set(++id, r); ws.send(JSON.stringify({ id, method, params })); });
-ws.onmessage = (m) => {
-  const d = JSON.parse(m.data);
-  if (d.id && pend.has(d.id)) return pend.get(d.id)(d.result);
-  if (d.method === "Runtime.consoleAPICalled") console.log("CONSOLE", d.params.type, d.params.args.map((a) => a.value ?? a.description).join(" ").slice(0, 200));
-  if (d.method === "Runtime.exceptionThrown") console.log("EXC", JSON.stringify(d.params.exceptionDetails.exception?.description ?? d.params.exceptionDetails.text).slice(0, 300));
-};
-await send("Runtime.enable");
-await send("Page.enable");
-await send("Page.navigate", { url });
-await sleep(Number(secs) * 1000);
-const shot = await send("Page.captureScreenshot", { format: "png" });
-fs.writeFileSync(out, Buffer.from(shot.data, "base64"));
-chrome.kill();
-process.exit(0);

plum-std/Game.plum CHANGED Viewed

@@ -5,10 +5,11 @@ import std/Str
 import std/Vec2
 import std/Color
-# The host API of a game: drawing, textures, files and input, all provided by
+# The host API of a game: drawing, textures, sounds, files and input, all
-# the game host (`plum game`). Texture handles are -1 on failure. File and
+# provided by the game host (`plum game`). Texture and sound handles are -1 on
-# texture paths are relative to the asset root; a path that escapes it fails
+# failure. File, texture and sound paths are relative to the asset root; a path
-# like a missing file. Coordinates are world units once `setCamera` is set.
+# that escapes it fails like a missing file. Coordinates are world units once
+# `setCamera` is set.
 extern fun screenWidth() -> Float
 extern fun screenHeight() -> Float
@@ -40,6 +41,18 @@ extern fun fileExists(path: Str) -> Bool
 # The whole file; "" if it is missing.
 extern fun fileLoad(path: Str) -> Str
+# Loads a WAV or OGG file relative to the asset root; -1 on failure. The host
+# decodes every sound file in the asset root before `init` runs.
+extern fun soundLoad(path: Str) -> Int
+# A one-shot play; plays of the same sound may overlap. Volume is 0..1.
+extern fun soundPlay(s: Int, volume: Float)
+# Starts the sound looping. Call `soundStop` first to restart it cleanly.
+extern fun soundLoop(s: Int, volume: Float)
+# Stops every play and loop of the sound.
+extern fun soundStop(s: Int)
+# Changes the volume of a sound that is playing or looping.
+extern fun soundSetVolume(s: Int, volume: Float)
 extern fun isKeyDown(k: Int) -> Bool
 extern fun isKeyPressed(k: Int) -> Bool
 extern fun mousePos() -> Vec2