Minecraft Optimization Lab / Horizon Lab

Client-first performance research for Minecraft Java 26.3, preserving vanilla gameplay rules. Any language or renderer may be used when measured gains justify it. Not affiliated with Mojang or Microsoft.

First playable release: pinned Java performance packs, distant terrain, an original frame/tick recorder, and Mac/client/server starter downloads. The M2 Pro/16 GB Mac is the first testing target. A Rust rewrite or custom renderer has not been completed; no M2 FPS improvement has been measured yet.

Play on your Mac

Download horizon-mac-starter-0.2.0.zip from Releases, extract it and open Mac-Start.command. It verifies and installs official universal Prism Launcher in ~/Applications if needed, then opens the balanced pack import. Sign into Microsoft inside Prism yourself. This project needs no credentials.

Use native Java 25 ARM64, maximum heap 6144 MiB, minimum 512 MiB on your 16 GB M2 Pro. Prism can download Java automatically. Start at 1280×800 or 1920×1200; full Retina resolution is a larger GPU workload. START-HERE.txt has details. The same .mrpack files import into Prism on Windows and Linux.

Profile	Full-detail chunks	Distant LOD radius	Suggested maximum heap
baseline	12	none	6144 MiB
m2-balanced	12	128	6144 MiB
adaptive (experiment)	12	128	6144 MiB
low-memory	8	none	3072 MiB
far-distance	12	256	8192 MiB, with sufficient physical RAM
cinematic	12	128	6144 MiB
vulkan	12	128	6144 MiB

Balanced combines Sodium, Lithium, FerriteCore, ImmediatelyFast, EntityCulling, and Distant Horizons. Cinematic adds Iris and Complementary Reimagined, initially disabled. Vulkan independently experiments with the game's own backend and fallback, without Iris.

Distant LOD is simplified terrain. Nearby blocks retain full detail. Initial generation costs CPU/disk/memory and needs warm-up. DH adjusts clouds, chunk fade and transparency to blend its renderer; assess appearance as well as speed. Shaders cost GPU time and have Mac-specific limits. Universal CPU/GPU support and exact vanilla equivalence remain validation goals. Simulation distance stays 12 in every profile; normal 20 TPS rules are retained.

Measure on your hardware

The optional adaptive terrain experiment throttles distant terrain background work when frames slow down or heap pressure rises, keeping the balanced profile's view distances and simulation settings. It remains opt-in until real hardware demonstrates a benefit.

Press F8 during gameplay to start a 120-second recording, or again to stop early. Rebind in Controls if needed. This also works with restricted chat accounts. Alternatively: /horizon bench <label> 120, /horizon stop, /horizon status.

Use separate identical world copies and the same camera route, resolution, render/simulation distance, heap, VSync and FPS limit. Warm up, then alternate at least three baseline/optimized runs. Test fresh chunk exploration separately. For everyday play cap FPS or enable VSync to reduce power usage.

The instance's horizon-benchmarks/ folder receives JSON/CSV frame and integrated-server tick timings: average FPS, slowest-1%-average FPS, p95/p99 durations, stalls, JVM heap/GC, GPU/backend/driver and render settings. Frames include presentation/limiting waits and exclude menus/pauses/unfocused time. Tick meanRate is execution capacity, not TPS; observed tick counts are separate. Heap is not process RSS or unified GPU memory.

python3 tools/compare_benchmarks.py baseline-frames.json optimized-frames.json --strict

The comparison flags captured setting differences, but cannot verify route, world, shader state or cache warm-up. See validation evidence. Software-renderer test FPS is not evidence of a Mac/GPU speedup.

Build and run

Requires Python 3.10+ and JDK 25. No Gradle, Rust or native compilation is required for playable packs.

python3 tools/build_mod.py
python3 tools/build_release.py

Gitignored dist/ contains seven packs, our original instrumentation JAR, client/server starter ZIPs and SHA256SUMS. mods.lock.json pins mod versions, exact dependency closure, SHA-1/SHA-512 and source/license; fabric.lock.json pins loader/library SHA-256. Packs use the Modrinth format. They embed only original project code; third-party mods, game and assets download from their publishers.

The server starter uses Lithium/FerriteCore and /horizonserver bench <label> <seconds>. Server instructions cover setup and a baseline. Files are prepared before you accept Minecraft's EULA locally. A 50-active-player workload remains to be measured.

Local smoke testing uses the game's built-in limited demo; normal play uses Prism's licensed account authentication:

python3 tools/build_pack.py --profile m2-balanced --instance .local/runtime/m2-balanced
vscreen run python3 tools/runtime.py demo --instance .local/runtime/m2-balanced

Local game inspection

Game JARs, decompiled Java, libraries, inventories, worlds and logs live inside this checkout under gitignored .local/. No game code is in Git history or release downloads. Fresh clones regenerate the inspection workspace from official downloads; Microsoft credentials are not needed for this step.

git clone https://github.com/ludovic111/minecraft-optimization-lab.git
cd minecraft-optimization-lab
git config core.hooksPath .githooks
python3 tools/lab.py prepare
python3 tools/lab.py decompile
python3 tools/lab.py status

research-lock.json pins the official manifest and Vineflower. The inner server JAR is extracted and checked; client/server libraries provide decompiler context. Output: .local/minecraft/26.3/sources/{client,server}/ and coverage/inventory reports. Current inventories cover 11,383 client classes and 7,762 server classes, producing 7,301/5,037 Java files. See decompilation status.

Class-file SourceFile metadata covers inner classes, which often share a source file. Coverage does not prove semantic equivalence or recompilability; original bytecode remains the reference. Completed source directories are not overwritten automatically. Older obfuscated releases require a separate remapping stage.

Original Rust research

cargo test --workspace
cargo run --release --bin voxel-bench -- 100 > .local/voxel-benchmark.csv

The dependency-free occupancy experiment compares scalar and bitset exposed-face counting for synthetic 16³ sections. It has no real mesh, material/AO/light work, neighboring-section context, JNI bridge or game integration. Speedups are kernel-only, not Minecraft FPS. Research plan describes profiling, improved Java baselines, native integration and behavior checks before expanding scope.

Validation and ownership

python3 -m unittest discover -s tests -v
python3 tools/build_mod.py --test-only
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
python3 tools/check_public_tree.py
python3 tools/check_public_tree.py --history

CI checks offline tools/Rust and compiles the original mod/builds packs on Linux, Windows and Apple Silicon macOS. Game dependencies download to ephemeral .local/; CI uploads only our original JAR and packs. Compilation is not Mac GPU gameplay testing. Publication checks allow Java only under our original dev/horizonlab namespace; review diffs as well.

MIT covers only our original tracked work. Dependencies retain their licenses. Mojang removed obfuscation without changing Minecraft's EULA. Decompiled game source remains local; published code implements independent tooling and instrumentation.