Skip to content

About

Headless, engine-agnostic Minecraft 26.2 light-engine benchmark and byte-identical correctness gate (Fabric)

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

lightbench

A headless, engine-agnostic benchmark and correctness gate for the Minecraft 26.2 light engine (Fabric). It drives only the vanilla ThreadedLevelLightEngine API, so it transparently measures whichever engine is installed — vanilla, or a Starlight-based engine like ScalableLux — with no per-engine code.

What it does

  • Benchmark (bench.sh) — times light work across three scenarios × three engine configs (vanilla / ScalableLux parallelism=1 / ScalableLux parallelism=N):
    • flat / amplified surface — block-light place/remove + full-chunk relight
    • roofed box — a max-height skylight suppressor (break/seal a hole), run at day and night
  • Correctness gate (verify.sh) — proves an engine produces byte-identical light to vanilla for every block. Hashes block-state and light value per chunk, so it distinguishes a real light difference from a diverged world.

How it runs

The mod (dev.lightbench.LightBench) auto-runs on SERVER_STARTED on a headless dedicated server, executes the configured workload on a worker thread while the server keeps ticking (which pumps the light engine), writes a CSV, and self-halts. All config is read from run/lightbench.properties (or -D system properties).

Key modes: both (relight + editstorm), skyhole (suppressor), verify (correctness hash), blockdiff (dump/diff block types), pregen (build a world to snapshot).

Why worlds are snapshotted (build-worlds.sh)

Same-seed regeneration is not reproducible — Minecraft feature placement is generation-order dependent (cascading world-gen / feature spillover), and fluids flow while ticking. So real-terrain verification generates each world type once, settles it, snapshots it, and runs every engine off a frozen copy — the only way to validly compare light on non-flat terrain.

Usage

# correctness gate: prove ScalableLux == vanilla, everywhere
./build-worlds.sh
SLUX_JAR=/path/to/ScalableLux.jar ./verify.sh

# benchmark vanilla vs ScalableLux p1 vs pN
SLUX_JAR=/path/to/ScalableLux.jar ./bench.sh

Requires JDK 25 and the Minecraft 26.2 Fabric toolchain (Loom). Drop the engine jar via SLUX_JAR (or into run/mods/).

Findings

See the generated report for the full write-up (vanilla vs ScalableLux across all scenarios, the day/night result, and the terrain-reproducibility investigation).

About

Headless, engine-agnostic Minecraft 26.2 light-engine benchmark and byte-identical correctness gate (Fabric)

Topics

Resources

Contributing

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages