cb19660fbe
Add version-bound core, world data, geometry, generation and feature implementations with native client/server comparison tools and scoped evidence reports. Apply Horizon project branding. Workspace tests, Clippy and 147 Python tests passed. Full 51-family survival and expanded provider comparisons are still running; complete gameplay parity and a playable Rust client remain unfinished. Private game artifacts and the isolated simple-block placement work are excluded.
196 lines
13 KiB
Plaintext
196 lines
13 KiB
Plaintext
HORIZON @PACK_VERSION@ — playable optimization experiments
|
||
|
||
YOUR MAC
|
||
1. Extract this ZIP. Double-click Mac-Start.command. If macOS asks, use Open
|
||
from the file's context menu. It installs the official Prism Launcher in
|
||
~/Applications if needed and opens the M2 balanced pack import.
|
||
Alternatively install Prism yourself: https://prismlauncher.org/download/macOS/
|
||
then Add Instance > Import > horizon-m2-balanced-@PACK_VERSION@.mrpack.
|
||
2. Sign into your Microsoft account in Prism yourself. No credentials are
|
||
shared with this project. You need an owned Minecraft Java license.
|
||
3. Enable Prism automatic Java downloads, using Java 25 ARM64 on Apple Silicon.
|
||
Instance > Edit > Settings > Java: check the Memory override box, then set
|
||
maximum memory 6144 MiB and minimum 512 MiB.
|
||
If auto Java fails, install a native ARM64 Java 25 JDK and select it there.
|
||
4. Launch. Start with a new test world or a COPY of a world from Minecraft 26.3.
|
||
This release is 26.3; do not load an older-version world for a fair comparison.
|
||
Choose 1280x800 or 1920x1200 before testing; the Retina screen's full native
|
||
resolution is a substantially larger GPU workload.
|
||
|
||
WINDOWS / LINUX
|
||
Install Prism from https://prismlauncher.org/download/ and import the same packs.
|
||
Use Java 25 matching your CPU architecture. No Rust compilation is required.
|
||
|
||
PROFILES
|
||
- m2-balanced: 12 chunks of full-detail terrain plus 128 chunks of distant LOD.
|
||
Sodium, Lithium, FerriteCore, ImmediatelyFast, EntityCulling, Distant Horizons.
|
||
Recommended first test for your 16 GB M2 Pro. OpenGL, shaders not installed.
|
||
- core-performance: 12 full-detail chunks, no distant LOD or shaders, with Sodium,
|
||
Lithium, FerriteCore, ImmediatelyFast and EntityCulling. After a first balanced smoke test,
|
||
compare this against baseline to test the core mods at the same view and
|
||
simulation distances.
|
||
Use the same heap, resolution, world copy, camera route and Java flags in both.
|
||
All original experimental controllers are disabled. This is a full-detail
|
||
comparison profile; it does not add balanced's 128-chunk distant horizon.
|
||
- baseline: original game renderer and simulation with Fabric API and the same
|
||
Horizon timing instrument. 12 full-detail chunks, no performance mods or LOD.
|
||
Use the SAME 6144 MiB maximum heap as m2-balanced for a fair comparison.
|
||
- adaptive: same render distances, worker count and mods as m2-balanced, with
|
||
experimental foreground-first terrain work scheduling. /horizon adaptive off
|
||
disables it; /horizon adaptive on enables it. /horizon status shows its budget.
|
||
It reduces DH background duty cycle when frames fall below a 60 FPS target or
|
||
heap usage exceeds 85%, then recovers gradually. Distant terrain can take longer
|
||
to appear. It does not reduce your view distance or change normal simulation.
|
||
This is a heuristic, not proof that background work caused a slow frame.
|
||
- worker-pacing: same balanced configuration, with an experimental precise worker
|
||
timer for pinned DH 3.3.4. It accumulates tiny sleep durations instead of rounding
|
||
each one down to milliseconds, and avoids per-task timestamp boxing. This can
|
||
substantially change background CPU and distant-generation completion times.
|
||
- adaptive-pacing: combines the adaptive controller with that precise worker timer.
|
||
Compare against balanced on your Mac; no actual M2 graphics result is established.
|
||
Disable the timer in config/horizon-worker-pacing.properties (enabled=false),
|
||
then restart. /horizon adaptive off changes only the adaptive controller.
|
||
- queue-wait: same balanced settings, with a short wait instead of continuous
|
||
retries while a DH update is still inside its existing 250 ms debounce period.
|
||
Incoming work wakes the queue worker. OS timers can overshoot the requested
|
||
1 ms maximum wait; evaluate terrain update latency as well as CPU/FPS.
|
||
Version 0.9 also lets incoming work wake an empty queue's former 50 ms sleep.
|
||
Cache maintenance keeps its 50 ms cadence; the original debounce stays intact.
|
||
- adaptive-queue: combines queue-wait with adaptive terrain and precise pacing.
|
||
For an isolated comparison use queue-wait versus m2-balanced. For the combined
|
||
controls use adaptive-queue versus adaptive-pacing. Disable the queue hook in
|
||
config/horizon-queue-wait.properties (enabled=false), then restart.
|
||
- dispatch-retry: same balanced settings, with bounded retries when DH rejects
|
||
a task submission. The original task is requeued; other executors can progress.
|
||
This is a separate experiment: adaptive, worker-pacing and queue-wait are off.
|
||
Set enabled=false in config/horizon-dispatch-retry.properties and restart
|
||
to disable it. A synthetic applied-hook test checks exact task completion.
|
||
- tick-dedup: same balanced settings, with compact reusable storage for private
|
||
terrain tick membership checks. Action order and visual settings stay the same.
|
||
Set enabled=false in config/horizon-tick-dedup.properties and restart to disable.
|
||
Compare against m2-balanced for an isolated test; no Mac FPS gain is measured yet.
|
||
- culling-empty: same balanced settings, with a shared empty iterator for empty
|
||
dynamic entity/block-entity whitelists. Registered callbacks stay upstream.
|
||
Disable in config/horizon-culling-empty.properties (enabled=false), then restart.
|
||
Compare against m2-balanced; no whole-game or Mac FPS gain is measured yet.
|
||
- quad-reuse: same balanced settings, with reuse of one discarded terrain quad
|
||
when DH's existing pool would otherwise allocate a fresh object. Generated
|
||
opaque/translucent geometry and concurrent builders match upstream. Caller-loop
|
||
allocations fall in the merging-heavy fixture; CPU results vary with warm-up.
|
||
It is off in combined profiles. Disable enabled in
|
||
config/horizon-quad-reuse.properties and restart for a comparison.
|
||
- terrain-position: same balanced settings, with equivalent position arithmetic
|
||
in the full-data lookup. Original rounding and fallback errors are retained.
|
||
Disable in config/horizon-terrain-position.properties (enabled=false), then
|
||
restart. Compare against m2-balanced; no game or Mac FPS gain is established.
|
||
- culling-rays: same balanced settings, with two per-instance scratch vectors for
|
||
temporary visibility-ray calculations. Upstream arithmetic and decisions stay
|
||
in place. Disable in config/horizon-culling-rays.properties (enabled=false),
|
||
then restart. Compare against m2-balanced; game/Mac gains remain unmeasured.
|
||
- foreground-first: combines adaptive terrain, precise pacing, wakeable queue
|
||
waits, bounded rejected dispatch retries and (since 0.13) tick membership reuse.
|
||
Uses OpenGL and a 120 FPS
|
||
adaptive goal. This is not an FPS cap; terrain may take longer to appear.
|
||
- foreground-vulkan: the same combined controls with Vulkan preference and
|
||
OpenGL fallback. On Apple Silicon the game bundles a MoltenVK library.
|
||
Test the isolated vulkan pack first, then compare both combined profiles
|
||
using equal worlds, heap, resolution and camera routes. Check the actual
|
||
backend in the benchmark viewer; a fallback is not a Vulkan result.
|
||
- low-memory: 8 full-detail chunks, no LOD. Set maximum memory 3072 MiB.
|
||
For a matched comparison set both instances to the same render distance.
|
||
- far-distance: 12 full-detail plus 256 LOD chunks. Start with 8192 MiB ONLY on
|
||
machines with enough physical RAM; this is not the recommended 16 GB Mac pack.
|
||
- cinematic: M2 pack plus Iris and Complementary Reimagined. Shaders start OFF.
|
||
Video Settings > Shader Packs lets you enable them. They cost GPU time; Mac
|
||
driver limitations may cause visual issues. Try after the balanced pack works.
|
||
- vulkan: experimental Vulkan preference with the game's OpenGL fallback,
|
||
no Iris. Test independently against OpenGL; faster is hardware-dependent.
|
||
|
||
All profiles retain simulation distance 12 and normal 20 TPS. These are initial
|
||
budgets, not promises of identical speed on every CPU/GPU. More distant LOD uses
|
||
simplified geometry; blocks nearby retain full detail. Building a fresh LOD cache
|
||
costs CPU/disk/memory. Wait for it to settle before judging steady-state FPS.
|
||
Background distant generation does not replace your normal gameplay simulation.
|
||
|
||
MEASURE ON YOUR M2 PRO
|
||
1. Import baseline too. Close every other Minecraft instance. Plug in the Mac,
|
||
disable Low Power Mode, and use the same window size, FPS cap, VSync setting,
|
||
render distance, simulation distance, world COPY, and camera route in each.
|
||
2. Warm each world for 2–3 minutes; allow distant generation to settle. Test new
|
||
chunk exploration separately from already-generated terrain. Do not compare
|
||
baseline's warmed world against an optimized world's first-time generation.
|
||
3. Press F8 in gameplay to start a 120-second recording; press again to stop.
|
||
On Mac you may need Fn+F8 if media keys take priority. You can rebind it in
|
||
Controls. Alternatively run /horizon bench baseline 120, close chat and play
|
||
your route. In balanced use /horizon bench m2 120. /horizon stop ends early.
|
||
/horizon status shows the profile. F8 also works when chat is restricted.
|
||
4. Open Prism's instance Minecraft folder > horizon-benchmarks. Each run writes
|
||
frames JSON/CSV and integrated-server ticks JSON/CSV. They include average FPS,
|
||
slowest-1%-average FPS, p95/p99 frame durations, stalls, sampled peak JVM heap,
|
||
process CPU time, process resident memory (RSS) when available, and GC data.
|
||
RSS reads run once per second on a shared background thread during recordings.
|
||
They include resident native pages; this is not a complete GPU/unified-memory
|
||
measurement. Last RSS is the last sample, not necessarily the finish time.
|
||
Heap is sampled once per second during gameplay;
|
||
shorter peaks can be missed. CPU measurement spans the whole recording.
|
||
Menus, pauses and unfocused frames are excluded. Tick execution time is not
|
||
the observed TPS. JVM heap is not whole-process memory or unified GPU memory.
|
||
5. Repeat at least three times, alternating baseline/optimized. For daily play
|
||
turn VSync back on or cap FPS to your display; uncapped FPS spends more power.
|
||
|
||
COMPARE WITHOUT PYTHON
|
||
Open Compare-Benchmarks.html from this ZIP in Safari, Chrome, Firefox or Edge.
|
||
Choose one baseline JSON and one candidate JSON from horizon-benchmarks. You can
|
||
select each JSON together with its matching CSV to see duration charts. Frame and
|
||
tick reports are compared separately. Files stay on your device; the viewer needs
|
||
no server, account, installation or network access. Check its settings/route/warm-up
|
||
warnings before drawing conclusions. Save comparison exports a summary JSON.
|
||
The viewer also shows Java implementation and loaded mod versions. Expand the
|
||
mod list to inspect it. Upgrades, additions and removals are flagged as experiment
|
||
variables; older reports with missing software identity show an unknown warning.
|
||
Tick reports also show sampled configured rate, freeze, step and sprint state.
|
||
Restored changes remain flagged; old or invalid state is unknown. Observed TPS
|
||
counts measured invocations, including frozen ticks, over recording wall time.
|
||
State is sampled after server invocations; it is not a completed-work or pause
|
||
trace. Compare the accompanying tick reports when judging integrated-server load.
|
||
|
||
DH changes clouds, chunk fade and transparency to blend its distant renderer;
|
||
assess visual differences as well as speed. For collector experiments test
|
||
Java 25's -XX:+UseZGC against its default G1 in both profiles; ZGC trades some
|
||
CPU/memory for shorter pauses and is not an automatic win on a 16 GB machine.
|
||
|
||
OPTIONAL JAVA MEMORY EXPERIMENT
|
||
With Java 25 HotSpot, add -XX:+UseCompactObjectHeaders to the instance's Java JVM
|
||
arguments and restart. Retain your other arguments. Packs do not enable this flag
|
||
automatically. For a separate off/on test use duplicate balanced instances with
|
||
-XX:-UseCompactObjectHeaders and -XX:+UseCompactObjectHeaders respectively.
|
||
Use one flag at a time and keep the collector, heap and workload identical.
|
||
Reports and the offline viewer show the actual compact-header setting and GC.
|
||
Some object layouts shrink; others do not. Whole-game RAM/FPS gains need testing.
|
||
|
||
Version 0.8 explicitly selects the custom graphics preset so Minecraft's startup
|
||
preset does not override the pack's render distance. Check the recorded settings.
|
||
|
||
This build is a playable Java optimization stack with original measurement code.
|
||
It is NOT a completed Rust rewrite, a new custom renderer, or a measured M2 speedup.
|
||
It has no gameplay feature additions and is intended to preserve vanilla rules;
|
||
exhaustive vanilla equivalence has not been proven. Start on world copies.
|
||
Only original project binaries are embedded. Mods, the game and assets download
|
||
from their publishers with pinned hashes. No decompiled Minecraft is distributed.
|
||
|
||
Source, build commands and measured validation:
|
||
https://github.com/ludovic111/Horizon
|
||
|
||
TERRAIN / SHADER COMPARISONS
|
||
Version 0.12 records actual DH radius/quality, worker count/duty cycle, Iris state
|
||
and field of view at capture boundaries. If visual settings changed, the viewer
|
||
flags the run. Older reports without these fields cannot establish quality
|
||
equivalence. Snapshots cannot detect a change that was restored before the end,
|
||
and do not prove that all requested distant terrain finished rendering.
|
||
|
||
Since 0.14, profiles with Distant Horizons request an interruptible blending-read
|
||
wait for its generation workers during shutdown. Ordinary Minecraft callers and
|
||
chunk saves keep their original behavior. To disable, set enabled=false in
|
||
config/horizon-terrain-read-wait.properties and restart. This is a scoped shutdown
|
||
correctness fix, not a claim of greater FPS or faster terrain generation.
|