Skip to content
factorio-rs

Benchmarking

Microbenchmark transpiled (or raw Lua) code inside Factorio using helpers.create_profiler. Mark functions with #[factorio_rs::bench] and run them with factorio-rs bench.

Command What it does
factorio-rs bench Builds (default release), launches Factorio, times benches
cargo test Does not run benches (they are not #[test])

Authoring

Section titled “Authoring”

Full suite: examples/benchmarking.

#[cfg(test)]
mod benches {
    use super::*;


    #[factorio_rs::bench(iterations = 40)]
    fn warehouse_tick() {
        run_warehouse_tick();
    }
}

See examples/benchmarking for the full nested call tree used in Speedscope demos.

Attribute Meaning
#[factorio_rs::bench] Run once per measurement
#[factorio_rs::bench(iterations = N)] Time the body N times; report min/mean/max-style sample list

Wall clock is roughly body time × iterations (plus Factorio startup). Heavy bodies need modest N or a higher --timeout (default 120s).

Benches may live in #[cfg(test)] modules or next to control-stage code. Prefer release profiles when comparing IR opts (--profile release is the default for factorio-rs bench).

lua! { ... }

Section titled “lua! { ... }”

Emits the enclosed text as raw Lua into the function body. The frontend does not parse or typecheck it.

  • Only allowed in an unsafe fn or an unsafe { ... } block
  • Use for idiom comparisons the transpile cannot express 1:1
  • Prefer lowered Rust when possible so opts and checks still apply

Running

Section titled “Running”
Terminal window
factorio-rs bench
factorio-rs bench array_indexing          # name filter (substring)
factorio-rs bench --profile release
factorio-rs bench --timeout 180
factorio-rs bench --gui

Example report (Criterion-style [min mean max] ±stddev; unit scales with the mean):

running 2 benches
bench control::benches::warehouse_tick    ... time: [28.1 ms 30.7 ms 33.5 ms] ±2.70 ms
bench control::benches::pick_orders_only  ... time: [22.0 ms 24.1 ms 26.0 ms] ±1.80 ms

How it works

Section titled “How it works”
  1. Discover #[factorio_rs::bench] functions.
  2. Emit dist/lua/factorio_rs_benches.lua and append a harness to control.lua.
  3. For each sample: helpers.create_profiler() -> run body -> stop() -> localised_print with the profiler (Factorio expands Duration: ...ms).
  4. The CLI parses those lines (Lua cannot read raw profiler numbers).

See also

Section titled “See also”