plugbench-ekaii

Multi-layer Minecraft plugin and engine performance benchmark and regression harness.

Given any plugin jar (or paper/folia/luminol server build), runs a fixed scenario in a controlled container, captures telemetry at 5 depths (server-internal → JVM → GC/heap → OS → kernel), and produces a diff vs (a) a no-plugin baseline and (b) the previous run of the same target. Every sample at every layer carries a (run_id, repeat, native_tid, ts_ns) key, so a tick-time spike can be traced down through the JVM thread → its native TID → the syscalls/IO it issued → the file descriptors and block devices it touched.

                              plugbench-ekaii
       ┌────────────────────────────────────────────────────────┐
       │  L0  spark            tick / TPS / MSPT / per-plugin   │
       │  L1  async-profiler   CPU + alloc + wall + lock        │
       │  L2  JFR              GC + locks + IO + heap-after-GC  │
       │  L3  /proc + perf     per-thread CPU, ctx-sw, faults   │
       │  L4  bpftrace         syscalls, IO lat, scheduler      │
       └────────────────────────────────────────────────────────┘
                              join key: native_tid + ts_ns

See docs/ for architecture, cross-layer tracing, scenarios, engine-bench mode, and the automatic regression-blocking gate (docs/gating.md) deployed across all jar-producing exo/* repos.

Quick start

# from any plugin repo on a `bench`-labelled forgejo runner
plugbench run \
  --jar build/libs/MyPlugin.jar \
  --flavor folia \
  --scenario chunkstorm,redstone,entity \
  --depth L4 \
  --repeats 5

Modes

• Plugin bench — --jar <plugin.jar> against a fixed engine version.
• Engine bench — --engine paper:1.21.4-build123 vs paper:1.21.4-build140 (or any flavor:version pair, including local luminol-ekaii builds). Same scenarios; diff is attributed to engine code.

License

MIT (see LICENSE).