298c125 | plum | pyrossh

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

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

298c125 — Peter John 2026-11-02T16:11:22+05:30

plum-game: command-buffer decoder, native cmd mode, PLUM_GAME_MEASURE timing

Files changed (5) hide show

plum-game/src/cmd.rs +202 -0
plum-game/src/lib.rs +1 -0
plum-game/src/main.rs +34 -3
plum-game/src/native.rs +110 -3
plum-game/tests/host_test.rs +30 -0

plum-game/src/cmd.rs ADDED Viewed

@@ -0,0 +1,202 @@
+//! Decoder for the command buffer written by `std/GameCmd` (format in
+//! docs/plans/2026-11-02-render-experiments.md): little-endian 4-byte fields,
+//! each command a u32 opcode followed by its fields.
+use crate::api::{Backend, Color};
+struct Reader<'a> {
+    buf: &'a [u8],
+    pos: usize,
+}
+impl Reader<'_> {
+    fn word(&mut self) -> Result<[u8; 4], String> {
+        let end = self.pos + 4;
+        let w = self.buf.get(self.pos..end).ok_or_else(|| format!("command buffer truncated at byte {}", self.pos))?;
+        self.pos = end;
+        Ok([w[0], w[1], w[2], w[3]])
+    }
+    fn u32(&mut self) -> Result<u32, String> {
+        self.word().map(u32::from_le_bytes)
+    }
+    fn i32(&mut self) -> Result<i32, String> {
+        self.word().map(i32::from_le_bytes)
+    }
+    fn f32(&mut self) -> Result<f32, String> {
+        self.word().map(f32::from_le_bytes)
+    }
+    fn color(&mut self) -> Result<Color, String> {
+        Ok([self.f32()?, self.f32()?, self.f32()?, self.f32()?])
+    }
+    fn f4(&mut self) -> Result<[f32; 4], String> {
+        self.color()
+    }
+}
+/// Replays `buf` into `b`, in command order. Errors (never panics) on an
+/// unknown opcode or a truncated command; commands before it were already played.
+pub fn decode(buf: &[u8], b: &mut dyn Backend) -> Result<(), String> {
+    let mut r = Reader { buf, pos: 0 };
+    while r.pos < buf.len() {
+        let at = r.pos;
+        match r.u32()? {
+            1 => {
+                let c = r.color()?;
+                b.clear(c);
+            }
+            2 => {
+                let (x, y, w, h) = (r.f32()?, r.f32()?, r.f32()?, r.f32()?);
+                let c = r.color()?;
+                b.draw_rect(x, y, w, h, c);
+            }
+            3 => {
+                let (x1, y1, x2, y2, t) = (r.f32()?, r.f32()?, r.f32()?, r.f32()?, r.f32()?);
+                let c = r.color()?;
+                b.draw_line(x1, y1, x2, y2, t, c);
+            }
+            4 => {
+                let (x, y, rad) = (r.f32()?, r.f32()?, r.f32()?);
+                let c = r.color()?;
+                b.draw_circle(x, y, rad, c);
+            }
+            5 => {
+                let (x, y, size) = (r.f32()?, r.f32()?, r.f32()?);
+                let c = r.color()?;
+                let len = usize::try_from(r.i32()?).map_err(|_| format!("negative text length in command at byte {at}"))?;
+                let padded = len.checked_add(3).ok_or("text length overflow")? / 4 * 4;
+                let end = r.pos.checked_add(padded).filter(|e| *e <= buf.len()).ok_or_else(|| format!("command buffer truncated in text at byte {at}"))?;
+                let s = String::from_utf8_lossy(&buf[r.pos..r.pos + len]).into_owned();
+                r.pos = end;
+                b.draw_text(&s, x, y, size, c);
+            }
+            6 => {
+                let t = r.i32()?;
+                let (x, y) = (r.f32()?, r.f32()?);
+                let c = r.color()?;
+                b.draw_texture(t, x, y, c);
+            }
+            7 => {
+                let t = r.i32()?;
+                let src = r.f4()?;
+                let dest = r.f4()?;
+                let rot = r.f32()?;
+                let flip = r.i32()? != 0;
+                let c = r.color()?;
+                b.draw_texture_ex(t, src, dest, rot, flip, c);
+            }
+            8 => {
+                let (x, y, s) = (r.f32()?, r.f32()?, r.f32()?);
+                b.set_camera(x, y, s);
+            }
+            9 => b.reset_camera(),
+            op => return Err(format!("unknown command opcode {op} at byte {at}")),
+        }
+    }
+    Ok(())
+}
+#[cfg(test)]
+mod tests {
+    use super::decode;
+    use crate::recorder::Recorder;
+    struct Enc(Vec<u8>);
+    impl Enc {
+        fn op(&mut self, o: u32) -> &mut Self {
+            self.0.extend(o.to_le_bytes());
+            self
+        }
+        fn f(&mut self, v: &[f32]) -> &mut Self {
+            for x in v {
+                self.0.extend(x.to_le_bytes());
+            }
+            self
+        }
+        fn i(&mut self, v: i32) -> &mut Self {
+            self.0.extend(v.to_le_bytes());
+            self
+        }
+        fn text(&mut self, s: &str) -> &mut Self {
+            self.i(s.len() as i32);
+            self.0.extend(s.as_bytes());
+            while self.0.len() % 4 != 0 {
+                self.0.push(0);
+            }
+            self
+        }
+    }
+    fn run(buf: &[u8]) -> (Result<(), String>, Vec<String>) {
+        let mut rec = Recorder::new();
+        let r = decode(buf, &mut rec);
+        (r, rec.calls)
+    }
+    #[test]
+    fn every_opcode() {
+        let mut e = Enc(vec![]);
+        e.op(1).f(&[0., 0., 0., 1.]);
+        e.op(2).f(&[1., 2., 3., 4., 1., 0., 0., 1.]);
+        e.op(3).f(&[1., 2., 3., 4., 5., 0., 1., 0., 1.]);
+        e.op(4).f(&[5., 6., 7., 0., 0., 1., 1.]);
+        e.op(5).f(&[1., 2., 16., 1., 1., 1., 1.]).text("hello");
+        e.op(6).i(2).f(&[3., 4., 1., 1., 1., 1.]);
+        e.op(7).i(2).f(&[0., 0., 8., 8., 10., 20., 16., 16., 0.5]).i(1).f(&[1., 1., 1., 1.]);
+        e.op(8).f(&[1., 2., 3.]);
+        e.op(9);
+        let (r, calls) = run(&e.0);
+        r.unwrap();
+        let mut want = Recorder::new();
+        use crate::api::Backend;
+        want.clear([0., 0., 0., 1.]);
+        want.draw_rect(1., 2., 3., 4., [1., 0., 0., 1.]);
+        want.draw_line(1., 2., 3., 4., 5., [0., 1., 0., 1.]);
+        want.draw_circle(5., 6., 7., [0., 0., 1., 1.]);
+        want.draw_text("hello", 1., 2., 16., [1., 1., 1., 1.]);
+        want.draw_texture(2, 3., 4., [1., 1., 1., 1.]);
+        want.draw_texture_ex(2, [0., 0., 8., 8.], [10., 20., 16., 16.], 0.5, true, [1., 1., 1., 1.]);
+        want.set_camera(1., 2., 3.);
+        want.reset_camera();
+        assert_eq!(calls, want.calls);
+        assert_eq!(calls.len(), 9);
+    }
+    #[test]
+    fn text_padding() {
+        for s in ["", "a", "abcd", "abcde", "héllo"] {
+            let mut e = Enc(vec![]);
+            e.op(5).f(&[0., 0., 8., 1., 1., 1., 1.]).text(s);
+            e.op(9);
+            let (r, calls) = run(&e.0);
+            r.unwrap();
+            assert_eq!(calls, [format!("drawText({s:?},0,0,8,1,1,1,1)"), "resetCamera()".to_string()], "{s}");
+        }
+    }
+    #[test]
+    fn truncated_errors_without_panic() {
+        let mut e = Enc(vec![]);
+        e.op(2).f(&[1., 2., 3., 4., 1., 0., 0., 1.]);
+        e.op(5).f(&[1., 2., 16., 1., 1., 1., 1.]).text("hello");
+        for n in 1..e.0.len() {
+            if n == 36 {
+                continue; // exactly the end of the first command
+            }
+            let (r, _) = run(&e.0[..n]);
+            assert!(r.is_err(), "len {n} should error");
+        }
+        assert!(run(&e.0).0.is_ok());
+        assert!(run(&[]).0.is_ok());
+    }
+    #[test]
+    fn bad_input_errors() {
+        assert!(run(&Enc(vec![]).op(99).0).0.is_err());
+        let mut e = Enc(vec![]);
+        e.op(5).f(&[0.; 7]).i(-1);
+        assert!(run(&e.0).0.is_err());
+        let mut e = Enc(vec![]);
+        e.op(5).f(&[0.; 7]).i(i32::MAX);
+        assert!(run(&e.0).0.is_err());
+    }
+}

plum-game/src/lib.rs CHANGED Viewed

@@ -1,6 +1,7 @@
 //! Native and web host for Plum game programs.
 pub mod api;
+pub mod cmd;
 pub mod mq;
 pub mod recorder;

plum-game/src/main.rs CHANGED Viewed

@@ -2,14 +2,24 @@
 //! macroquad window. The asset root defaults to `assets` beside the wasm, or
 //! `$PLUM_GAME_ASSETS`. With `PLUM_GAME_CAPTURE=<path.png>` (and optionally
 //! `PLUM_GAME_FRAMES=<n>`, default 30) it saves the screen after n frames and
+//! exits 0. With `PLUM_GAME_MEASURE=<secs>` it runs uncapped (
-//! exits 0.
+//! swap interval 0 is honored on
+//! Linux/Windows GL, but miniquad on macOS paces frames with a CVDisplayLink, so
+//! fps is capped at the display rate and present_ms then includes the wait) for that long, prints one JSON timing line
+//! (frames, avg/p50/p95/p99 ms, fps, mean update/draw/present ms) and exits 0.
 #[cfg(not(target_arch = "wasm32"))]
-use plum_game::{mq::MqBackend, native::{Capture, PlumGame}};
+use plum_game::{mq::MqBackend, native::{parse_measure, Capture, PlumGame, Timings}};
 #[cfg(not(target_arch = "wasm32"))]
 fn window_conf() -> macroquad::window::Conf {
+    // PLUM_GAME_MEASURE runs uncapped: ask the driver for swap interval 0.
+    let measuring = std::env::var("PLUM_GAME_MEASURE").is_ok_and(|v| !v.is_empty());
-    macroquad::window::Conf { window_title: "Plum Game".to_string(), window_width: 1280, window_height: 720, ..Default::default() }
+    let mut conf = macroquad::window::Conf { window_title: "Plum Game".to_string(), window_width: 1280, window_height: 720, ..Default::default() };
+    if measuring {
+        conf.platform.swap_interval = Some(0);
+    }
+    conf
 }
 #[cfg(not(target_arch = "wasm32"))]
@@ -47,21 +57,42 @@ async fn run(wasm: std::path::PathBuf, assets: std::path::PathBuf) -> Result<(),
     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 measure = parse_measure(std::env::var("PLUM_GAME_MEASURE").ok())?;
+    let mut timings = Timings::default();
+    let started = std::time::Instant::now();
     let mut frame = 0u32;
     loop {
+        let t0 = std::time::Instant::now();
         let dt = macroquad::time::get_frame_time();
         game.update(dt).map_err(|e| format!("update: {e:#}"))?;
+        let t1 = std::time::Instant::now();
         game.draw().map_err(|e| format!("draw: {e:#}"))?;
+        let t2 = std::time::Instant::now();
+        let ms = |a: std::time::Instant, b: std::time::Instant| (b - a).as_secs_f64() * 1000.0;
+        timings.update += ms(t0, t1);
+        timings.draw += ms(t1, t2);
         frame += 1;
         if let Some(c) = &capture {
             if frame >= c.frames {
                 // `export_png` flips the bottom-up readback so the PNG is upright.
                 let path = c.path.to_str().ok_or("PLUM_GAME_CAPTURE is not valid UTF-8")?;
                 macroquad::texture::get_screen_data().export_png(path);
+                if measure.is_some() {
+                    println!("{}", timings.json());
+                }
                 return Ok(());
             }
         }
         macroquad::window::next_frame().await;
+        let t3 = std::time::Instant::now();
+        timings.present += (t3 - t2).as_secs_f64() * 1000.0;
+        timings.frame.push((t3 - t0).as_secs_f64() * 1000.0);
+        if let Some(secs) = measure {
+            if started.elapsed().as_secs_f64() >= secs {
+                println!("{}", timings.json());
+                return Ok(());
+            }
+        }
     }
 }

plum-game/src/native.rs CHANGED Viewed

@@ -15,6 +15,16 @@ pub struct PlumGame<B: Backend> {
     instance: Instance,
     /// The `init` result, rooted across frames.
     state: Option<OwnedRooted<AnyRef>>,
+    /// `Some` when the module exports `cmdReset`/`cmdPtr`/`cmdLen`/`memory`:
+    /// draw calls arrive as one command buffer read after `draw`.
+    cmd: Option<CmdExports>,
+}
+struct CmdExports {
+    reset: Func,
+    ptr: Func,
+    len: Func,
+    memory: wasmtime::Memory,
 }
 fn f(p: &[Val], i: usize) -> f32 {
@@ -178,7 +188,30 @@ impl<B: Backend> PlumGame<B> {
             linker.define(&store, imp.module(), imp.name(), func)?;
         }
         let instance = linker.instantiate(&mut store, &module)?;
+        let cmd = Self::cmd_exports(&mut store, &instance)?;
-        Ok(PlumGame { store, instance, state: None })
+        Ok(PlumGame { store, instance, state: None, cmd })
+    }
+    fn cmd_exports(store: &mut Store<HostState<B>>, instance: &Instance) -> Result<Option<CmdExports>> {
+        let (Some(reset), Some(ptr), Some(len), Some(memory)) = (
+            instance.get_func(&mut *store, "cmdReset"),
+            instance.get_func(&mut *store, "cmdPtr"),
+            instance.get_func(&mut *store, "cmdLen"),
+            instance.get_memory(&mut *store, "memory"),
+        ) else {
+            return Ok(None);
+        };
+        Ok(Some(CmdExports {
+            reset,
+            ptr,
+            len,
+            memory,
+        }))
+    }
+    /// Whether draw calls are read from a command buffer.
+    pub fn uses_command_buffer(&self) -> bool {
+        self.cmd.is_some()
     }
     pub fn backend(&self) -> &B {
@@ -221,7 +254,30 @@ impl<B: Backend> PlumGame<B> {
     }
     pub fn draw(&mut self) -> Result<()> {
+        let Some(cmd) = &self.cmd else {
+            return self.call_with_state("draw", &[]);
+        };
+        let (reset, ptr, len, memory) = (cmd.reset.clone(), cmd.ptr.clone(), cmd.len.clone(), cmd.memory);
+        reset.call(&mut self.store, &[], &mut [])?;
-        self.call_with_state("draw", &[])
+        self.call_with_state("draw", &[])?;
+        // `Int` is i64 in Plum; accept i32 too.
+        let mut int_result = |f: &Func| -> Result<i64> {
+            let mut out = [Val::I64(0)];
+            f.call(&mut self.store, &[], &mut out)?;
+            match out[0] {
+                Val::I64(v) => Ok(v),
+                Val::I32(v) => Ok(v as i64),
+                _ => Err(wasmtime::Error::msg("cmdPtr/cmdLen must return Int")),
+            }
+        };
+        let (ptr, len) = (int_result(&ptr)?, int_result(&len)?);
+        let (data, host) = memory.data_and_store_mut(&mut self.store);
+        let range = usize::try_from(ptr)
+            .ok()
+            .zip(usize::try_from(len).ok())
+            .and_then(|(p, l)| data.get(p..p.checked_add(l)?))
+            .ok_or_else(|| wasmtime::Error::msg(format!("command buffer [{ptr}, +{len}) is outside memory")))?;
+        crate::cmd::decode(range, &mut host.backend).map_err(wasmtime::Error::msg)
     }
 }
@@ -252,9 +308,60 @@ impl Capture {
     }
 }
+/// Per-frame timings (milliseconds) for `PLUM_GAME_MEASURE`.
+#[derive(Default)]
+pub struct Timings {
+    pub frame: Vec<f64>,
+    pub update: f64,
+    pub draw: f64,
+    pub present: f64,
+}
+/// Seconds from `PLUM_GAME_MEASURE`; `None` when unset, an error when not a positive number.
+pub fn parse_measure(v: Option<String>) -> std::result::Result<Option<f64>, String> {
+    let Some(v) = v.filter(|v| !v.is_empty()) else { return Ok(None) };
+    v.trim().parse::<f64>().ok().filter(|s| s.is_finite() && *s > 0.0).map(Some).ok_or_else(|| format!("PLUM_GAME_MEASURE must be a positive number of seconds, got `{v}`"))
+}
+impl Timings {
+    /// One JSON line: frame stats over all frames, split means per frame.
+    pub fn json(&mut self) -> String {
+        let n = self.frame.len().max(1) as f64;
+        let total: f64 = self.frame.iter().sum();
+        self.frame.sort_by(|a, b| a.total_cmp(b));
+        let pct = |p: f64| self.frame.get(((self.frame.len() as f64 * p) as usize).min(self.frame.len().saturating_sub(1))).copied().unwrap_or(0.0);
+        let avg = total / n;
+        format!(
+            "{{\"frames\":{},\"avg_ms\":{:.3},\"p50_ms\":{:.3},\"p95_ms\":{:.3},\"p99_ms\":{:.3},\"fps\":{:.1},\"update_ms\":{:.3},\"draw_ms\":{:.3},\"present_ms\":{:.3}}}",
+            self.frame.len(),
+            avg,
+            pct(0.5),
+            pct(0.95),
+            pct(0.99),
+            if avg > 0.0 { 1000.0 / avg } else { 0.0 },
+            self.update / n,
+            self.draw / n,
+            self.present / n
+        )
+    }
+}
 #[cfg(test)]
 mod tests {
-    use super::Capture;
+    use super::{parse_measure, Capture, Timings};
+    #[test]
+    fn measure_parsing_and_json() {
+        assert_eq!(parse_measure(None), Ok(None));
+        assert_eq!(parse_measure(Some("2.5".into())), Ok(Some(2.5)));
+        assert!(parse_measure(Some("0".into())).is_err());
+        assert!(parse_measure(Some("x".into())).is_err());
+        let mut t = Timings { frame: vec![1.0, 2.0, 3.0, 4.0], update: 4.0, draw: 8.0, present: 0.0 };
+        assert_eq!(
+            t.json(),
+            r#"{"frames":4,"avg_ms":2.500,"p50_ms":3.000,"p95_ms":4.000,"p99_ms":4.000,"fps":400.0,"update_ms":1.000,"draw_ms":2.000,"present_ms":0.000}"#
+        );
+    }
     #[test]
     fn capture_env_parsing() {

plum-game/tests/host_test.rs CHANGED Viewed

@@ -250,3 +250,33 @@ fn soundPathEscapeRejected() {
     assert_eq!(escaped, [-1, -1, -1]);
     assert_eq!(ok, 0);
 }
+/// Draw calls of one frame of `src`, with texture/size queries left in.
+fn one_frame(src: &Path, assets: &Path) -> (Vec<String>, bool) {
+    let mut g = PlumGame::load(&compile(src), Recorder::with_assets(assets.to_path_buf())).expect("load");
+    g.init().expect("init");
+    g.update(1.0 / 60.0).unwrap();
+    g.backend_mut().calls.clear();
+    g.draw().unwrap();
+    (g.backend().calls.clone(), g.uses_command_buffer())
+}
+/// The command-buffer variant of the stress scene must replay the same call
+/// sequence as the per-call variant. Skipped while std/GameCmd or the fixture
+/// is not in the tree.
+#[test]
+fn commandBufferMatchesPerCall() {
+    let fixtures = Path::new(env!("CARGO_MANIFEST_DIR")).join("web-test/fixtures");
+    let (per_call, cmd) = (fixtures.join("stress.plum"), fixtures.join("stress_cmd.plum"));
+    if !root().join("plum-std/GameCmd.plum").exists() || !cmd.exists() || !per_call.exists() {
+        eprintln!("SKIP commandBufferMatchesPerCall: std/GameCmd.plum or stress_cmd.plum is missing");
+        return;
+    }
+    let assets = fixtures.join("assets");
+    let (a, a_cmd) = one_frame(&per_call, &assets);
+    let (b, b_cmd) = one_frame(&cmd, &assets);
+    assert!(!a_cmd && b_cmd, "stress_cmd must use the command buffer, stress must not");
+    assert!(!a.is_empty());
+    assert_eq!(a.len(), b.len());
+    assert_eq!(a, b);
+}