Tidy the repository now that parity is reached: launcher-first README, docs index, research leftovers removed

Removed (each unreferenced by code, workflows, tests or living docs; no harness
dependency record names any of them, and parity.py --list still finds all 281):
- 22 one-off write-ups of the Java-pack experiments in docs/: adaptive-terrain,
  client-graphics-smoke, compact-headers, core-performance, culling-empty,
  culling-rays, debounce-queue, dispatch-retry, foreground-first,
  graphics-api-comparison, heap-budget, mac-first-test, optimization-plan,
  playable-validation, quad-reuse, server-graphics-context, shader-world-smoke,
  terrain-measurements, terrain-position, terrain-read-wait, tick-membership,
  worker-pacing. Their findings are folded into one paragraph of java-packs.md.
- 24 benchmarks/ observation dumps only those write-ups linked (client graphics,
  culling, queues, heap, Mac Vulkan, shader worlds, software identity, and the
  unlinked rust-core, rust-worldgen-2026-10-05, rust-native-client and
  rust-cuboid-model-decoding runs), plus 12 unlinked files inside kept
  report folders. The scoped-parity reports the living docs cite stay.
- debug/: one server log from a chunk investigation.
- The manual macos-shader-research and macos-vulkan-research workflows.
- tools/logs/latest.log, an empty log committed by accident (now ignored).

Kept: research-lock.json (parity.py, packaging, the launcher and datafix read
it), the Java-pack how-tos (vulkan, collectors, profiling, process-memory,
tick-state) and tools/test_client_graphics.py (ci.yml runs it).

README: leads with what Horizon is and "Download the launcher" (the
launcher-v* releases; the launcher updates itself), then build from source
for developers. Direct game downloads and PLAY.txt steps for players are gone;
the launcher has its own section with two screenshots. The roadmap merges the
known differences, the final checks and the plans after parity, under the
"Roadmap" heading the launcher's What's next page reads. The parity table and
its 100%-of-what-the-harnesses-compare note are unchanged.

docs/README.md indexes what remains: build and run, parity (status and
workflow), world generation, world data and simulation, the old Java track.
Links to the removed pages and README anchors are fixed.

packaging/PLAY.txt now speaks to players who came through the launcher and
points anyone with a bare archive to it, keeping the manual steps short.

The launcher's README link points at main instead of the launcher branch.
.gitignore: tools/logs/ and .DS_Store. No code behaviour changes; the compiler
and clippy flag no unused code and the tree has no stale TODOs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-13 14:16:55 +02:00
parent 2e4c4d1861
commit 8cdec2c8d9
90 changed files with 111 additions and 16131 deletions
+35
View File
@@ -0,0 +1,35 @@
# Horizon documentation
To play, use [the launcher](../launcher/README.md). These pages are for developers.
## Build and run
- [Build from source](../README.md#build-from-source): your own copy of the game, resource preparation, `cargo run`.
- [Native client](native-client.md): options, controls, the dedicated server, `horizon-ctl` scripting, packaging, architecture.
- [Launcher](../launcher/README.md): installs, updates and starts builds; its CLI and MCP server; releasing it.
## Parity
- [Rust rewrite status](rust-parity.md): completion criteria, how to reproduce the validation, and per-area scope.
- [Parity workflow](parity-workflow.md): `tools/parity.py`, the gate, other machines, merging.
- Area notes: [block behaviours and ticking](parity/blocks.md), [section meshing](parity/meshing.md).
- [Decompilation and research lab](research-lab.md) and [decompilation status](decompilation-status.md): the local game inspection workspace the harnesses build on.
## Architecture: world generation
- [World generation](world-generation.md): the pipeline from noise to features.
- [Noise generation](noise-generation.md), [compiled density functions](density-functions.md), [structure density](structure-density.md), [terrain filling](terrain-filling.md).
- Biomes: [lookup](biome-lookup.md), [temperatures](biome-temperatures.md).
- Surfaces: [material surfaces](material-surfaces.md), [material conditions](material-conditions.md), [rule libraries](material-rule-libraries.md), [vertical anchors](vertical-anchors.md), [value providers](value-providers.md).
- [Carving](carving.md), [heightmaps](heightmaps.md), [feature placement](feature-placement.md).
## Architecture: world data and simulation
- [World data](world-data.md): chunk storage, palettes, region files.
- [Block-state codecs](block-state-codecs.md), [scheduled ticks](scheduled-ticks.md).
- [Collision geometry](collision-geometry.md): shapes, collision, movement and fluids.
- [Face visibility](face-visibility.md): which model faces the mesher emits.
## The earlier Java track (no longer developed)
- [Java performance packs](java-packs.md), with [Vulkan on your Mac](vulkan.md), [collector comparisons](collectors.md), [profiling](profiling.md), [process memory](process-memory.md) and [tick state](tick-state.md); [server quickstart](server-quickstart.txt).
-54
View File
@@ -1,54 +0,0 @@
# Adaptive distant-terrain budget
The optional `adaptive` profile keeps the balanced profile's full-detail distance,
distant radius, worker count and simulation settings. Its original controller changes
only Distant Horizons' background worker duty cycle. Existing stable downloads remain
available while this experiment is validated.
Import adaptive into a separate Prism instance with the same Java, heap, world copy
and graphics settings as balanced. `/horizon adaptive on` and `/horizon adaptive off`
change the policy for the current session. Changes are refused during recording;
`/horizon status` shows the current budget.
The opt-in configuration is `config/horizon-adaptive.properties`:
```properties
enabled=true
targetFps=60
```
The target is clamped to 10–240 FPS and respects a lower configured frame cap.
Every two seconds of focused gameplay, the policy considers mean frame duration,
the fraction of frames exceeding twice the target duration, and current used heap.
Slow frames or heap usage above 85% cut the duty cycle to 65% of its previous
value, with a 0.05 floor or the user's lower ceiling. Three consecutive healthy
windows permit a 0.025 increase. The user-configured DH ratio remains the ceiling.
Menus, pauses and loss of focus release the temporary override and discard the partial
window. Another mod's existing or changed override makes the controller yield.
The controller does not write DH settings to disk.
Frame intervals include presentation and frame pacing. A GPU bottleneck can also
trigger this heuristic even when background CPU work was not responsible. Terrain
generation may take longer. Reducing duty cycle does not free cached terrain or
guarantee lower peak memory. No resolution, visual-quality, worker-count,
simulation-distance or tick-rate change is made.
The pinned DH public `threadRuntimeRatio()` API wraps its live configuration entry.
Inspection confirmed that its executor reads the effective entry after each task
and sleeps according to that ratio. Changes affect subsequent pacing without
restarting the pool; individual long-running tasks cannot be preempted. API code
stays in the upstream dependency. Only original `dev.horizonlab` classes are packaged.
Compare **balanced against adaptive**, first with matched cold terrain exploration
and then matched warm terrain. Record three alternating runs per condition. Check
average FPS, slowest-1% FPS, p99 frame duration, integrated-server tick times,
sampled peak heap and process mean CPU cores. Also judge terrain completion time:
improved pacing at the expense of excessive generation delay is a tradeoff to measure.
The local software renderer validates integration only; the M2 Pro must provide
the actual performance result.
JVM heap/nonheap samples are taken once per second during recorded gameplay, plus
start/end samples. Short spikes can be missed. Process CPU time covers the whole
recording, including menus, all Java threads and the integrated server; one mean CPU
core means one CPU-second per elapsed second. JVM memory excludes some native
allocations and GPU memory and is not process RSS.
-124
View File
@@ -1,124 +0,0 @@
# Client startup and world-rendering probes
Compilation does not show whether a client creates its graphics device, reaches
the menu, enters a world or reads back a rendered frame. The private graphics
probe runs the actual pinned game and performance mods to check those steps.
It is a separate test mod, excluded from production JARs and playable packs.
The required macOS CI cases use the recommended OpenGL `core-performance` and
`m2-balanced` profiles. Each profile starts at the title screen and then, in a
separate instance, creates or opens an ordinary limited-demo world. World mode
dismisses the demo-help popup, waits for focused, unpaused gameplay, reads back
the main render target, and stops the client so its integrated server saves.
The readiness counter resets while a loading overlay is present: a title screen
object can already exist underneath asynchronous loading. Private screenshots
must have a nonuniform sample grid and a verified file hash;
world mode also checks for saved world data after a clean process exit.
The startup wrapper observes backend library/device creation and preserves the
original calls and thrown exceptions. Selected diagnostics contain initialization
stages, bounded exception type names, Vulkan error-code identifiers and device
labels. Failed probes also select up to eight graphics stack method names, without
module prefixes, filenames, line numbers or messages. Those observed locations
do not by themselves identify a root cause. Expected demo authentication errors
are reported separately. Full log
messages, raw screenshots, assets and world files stay under gitignored `.local/`.
Nonuniform pixels are not proof of correct visuals, full LOD completion or
exhaustive gameplay equivalence.
The [selected live observations](../benchmarks/client-graphics-2026-10-04/live-observations.json)
record passing title and demo-world readbacks for both profiles on the hosted
macOS ARM64 runner. Both world cases are focused, produce saved data and exit
cleanly. All four CI jobs pass for that source head. Its independently built
macOS production JAR matches published 0.20.0 byte-for-byte and contains neither
probe class. The observed macOS OpenGL device is **Apple Software Renderer**;
these are platform runtime checks, not physical Apple GPU performance results.
## Run locally
Build the original mod first, then use the platform's display:
```sh
python3 tools/build_mod.py
python3 tools/test_client_graphics.py --native-display
python3 tools/test_client_graphics.py --native-display --world
```
These default to core and balanced, with a 3 GiB heap. That budget can trigger
DH's low-memory warning; the 16 GB Mac starter suggests 6 GiB. A short startup
check is not a recommendation for sustained memory or distant-generation load.
On headless Linux, omit `--native-display` to use Xvfb, or run through `vscreen`
with its display available. World mode creates private, disposable demo worlds
in its isolated runtime folders. No Microsoft credentials are needed for the
game's limited demo. It does not accept the dedicated-server EULA.
The selected output is `dist/client-graphics-smoke.json`. Each case records the
observed backend rather than inferring it from the preference. Normal CI retains
separate title/world JSONs. Neither the fixture nor screenshots enter releases.
## Vulkan investigation
The manual **macOS Vulkan research** workflow separately probes vanilla, core and
the distant-terrain Vulkan profile. It runs every case, retains selected successful
and failed outcomes, and exits unsuccessfully when a case fails. Its exploratory
results do not count as passing the required OpenGL checks.
Its optional `world` input selects disposable demo-world probes for every case;
the default still probes titles.
Local Linux software OpenGL/Vulkan title readbacks passed. Early macOS OpenGL
title checks for core and balanced also passed with **Apple Software Renderer**.
The macOS runner's **Apple Paravirtual device**, using MoltenVK 1.4.2, created
Vulkan devices but all three Vulkan cases failed with `VK_ERROR_FEATURE_NOT_PRESENT`.
The failure also occurs with vanilla; these observations do not isolate an
optimization-mod fault or prove behavior on a physical M2 GPU.
The separate [readback-stage observations](../benchmarks/mac-vulkan-2026-10-04/live-observations.json)
from manual run 37193558884 show that all three cases reached the client test
initializer and requested readback before failing. They produced no completed
readback report. This narrows the observed sequence; it does not establish whether
the screenshot operation itself or subsequent rendering failed. Graphics stack
locations from the next run, 37193954843, place each observed failure in the
screenshot callback after Vulkan submission. Later probes also record callback
entry, a whitelist of numeric readback dimensions/sample counts, and fixed failure
categories from our own assertions. Separately logged Vulkan codes are not
treated as the cause of a probe assertion.
Run 37194354615 identifies the actual probe assertion: each callback received a
1280×646 image, but its 4,160 sampled pixels had only one distinct RGB colour.
The strict nonuniform-readback assertion rejected all three cases. Overlay state
was not recorded in those failures; later probes wait for its removal before
counting readiness. This tests an initialization hypothesis while preserving the
same nonuniform-image requirement. It is not evidence that the game's displayed
Vulkan window was uniform or that a physical M2 GPU has the same problem.
After the overlay guard, run 37194690645 has mixed results: core and distant-terrain
title probes pass on the Apple Paravirtual Vulkan device, with no overlay and
nonuniform readback, then exit cleanly. Vanilla still fails the uniform-readback
assertion. The overall research run therefore remains failed. These outcomes
justify retaining the readiness guard; they do not establish the cause of the
remaining failure, full visual correctness, world rendering or physical M2 speed.
The subsequent world-mode run 37195149166 passes all three cases on the hosted
Apple Paravirtual Vulkan device. Each reaches focused gameplay without an overlay,
returns a nonuniform framebuffer, produces saved demo-world data and exits with
code zero. This verifies short Vulkan world startup on that runner, while the
failed title observations remain retained. A local Linux core Vulkan world probe
also passes, and its private screenshot was visually inspected. These checks do
not prove exhaustive graphics/gameplay equivalence, completed distant terrain,
physical M2 GPU compatibility or an FPS improvement.
For an isolated private preference override:
```sh
python3 tools/test_client_graphics.py --native-display --profile baseline --backend vulkan
python3 tools/test_client_graphics.py --native-display --profile core-performance --backend vulkan
```
Overrides use separate runtime folders. The shipped profiles retain their
configured preferences. These probes make no FPS, CPU/RAM reduction, hardware-GPU
compatibility or M2 Pro performance claim. Actual-world performance comparisons
still use the [Mac first-test procedure](mac-first-test.md).
For a shader-enabled world rather than a disabled shader configuration, use the
separate [cinematic shader probe](shader-world-smoke.md). It requires actual Iris
runtime activation and the pinned pack identity.
-73
View File
@@ -1,73 +0,0 @@
# Compact object headers experiment
Java 25 HotSpot offers `-XX:+UseCompactObjectHeaders`. This changes object-header
representation without replacing game logic. Oracle documents the header format
and enable flag in its [Java 25 GC guide](https://docs.oracle.com/en/java/javase/25/gctuning/other-considerations.html).
Object alignment and fields determine whether a particular allocation gets smaller.
Native renderer buffers and GPU allocations are outside this optimization.
## Try on your Mac
Import the balanced pack normally. In Prism, edit the instance's Java settings
check the Java Arguments override box, and add `-XX:+UseCompactObjectHeaders` to its JVM arguments, retaining any existing
arguments. Use Java 25 HotSpot matching your CPU architecture. Restart the game.
Remove the argument to return to the launcher's default, or use
`-XX:-UseCompactObjectHeaders` to explicitly test the disabled mode. Do not supply
both flags. Packs do not automatically enable this option.
For an isolated comparison, duplicate the same balanced instance and use explicit
off/on flags. Keep collector, heap, world copy, camera route and all video settings
matched. Alternate at least three warmed 120-second recordings. The 0.8 recorder
captures the actual `compact_object_headers` setting and `garbage_collectors` names;
check these in the offline viewer. Older reports show "not captured", rather than
an assumed default. Launcher and JVM defaults can differ.
Local demo and server tools accept `--compact-headers`. This enables the option
only in that process. The server still requires local EULA acceptance before it runs.
## Isolated allocation measurement
```sh
python3 tools/build_mod.py --benchmark-headers
```
The original benchmark uses the verified game/Distant Horizons publisher types
on its classpath, without redistributing them. It forks separate JVMs with explicit
off/on flags three times. Each type gets three discarded warm-up batches followed
by three measured batches of 100,000 objects. `ThreadMXBean` counts allocated bytes;
reference-array storage is allocated before measurement. Objects escape through a
volatile array, and their values are checked after measurement. The benchmark
asserts that the running VM reports the requested flag. Output includes Java/OS/CPU
architecture and goes to gitignored `dist/object-header-benchmark.txt`.
Local Linux x64 and hosted Linux x64, Windows x64 and Apple Silicon macOS 26
measurements yielded the same medians:
| Type | Headers off, bytes/object | Headers on, bytes/object |
| --- | ---: | ---: |
| Minecraft `AABB` | 64 | 56 |
| Minecraft `Vec3` | 40 | 32 |
| Distant Horizons `DhChunkPos` | 24 | 24 |
| Boxed `Long`, outside cache | 24 | 16 |
| Plain `Object` | 16 | 8 |
[Raw platform results](../benchmarks/object-headers-2026-10-03) come from
[CI run 37153955462](https://github.com/ludovic111/Horizon/actions/runs/37153955462).
Each platform has nine measured batches per type/mode across three JVM forks.
The hosted ARM Mac has three logical CPUs and is not the user's M2 Pro.
These are allocations for specific object layouts, not a measured reduction in
whole-game retained heap, process RSS, FPS or server TPS. Changing headers can
also change runtime tradeoffs. Real workloads and the user's M2 Pro remain the
decision point. CI runs the probe on Windows, Linux and Apple Silicon macOS and
runs the metric tests with compact headers enabled as well as the default.
## Fresh video settings correction in 0.8
Minecraft 26.3 applies its selected graphics preset at startup. A fresh minimal
0.7 options file had the correct data-version marker but omitted an explicit
custom preset, allowing the default Fancy preset to override full-detail distance
to 16 chunks. Version 0.8 explicitly selects the custom preset so the pack's
12-chunk budget (8 in low-memory) is retained. This fixes configuration, without
reducing simulation distance or changing gameplay. Runtime reports capture the
effective settings; always compare those, not just pack labels.
-118
View File
@@ -1,118 +0,0 @@
# Core performance comparison
`core-performance` adds the pinned core performance mods while retaining the
baseline's 12 full-detail chunks, 12 simulation chunks, suggested heap, custom
graphics preset and OpenGL backend. Neither profile installs distant terrain or
Iris shaders; every original experimental controller is disabled. Use this pair
for the first comparison at the same view distance, then test balanced separately
for its additional 128-chunk distant horizon.
The loaded-mod report also exposes dependencies bundled inside those downloads,
such as Transition and Trender in this observed core run. The comparator treats
these software changes as explicit experiment variables. Matching configuration
is not proof of pixel-identical rendering or exhaustive gameplay equivalence.
## Three repeated pairs on 0.20.0
The later series uses the exact published 0.20.0 mod with fresh JVMs and identical
initial private world copies. Each run warms for 180 seconds in focused gameplay,
then records frames and integrated-server ticks for 120 seconds. A separate test
fixture in both profiles holds the same stationary camera. It is absent from
playable packs. The workload remains 12 full-detail / 12 simulation chunks,
1280×800, FOV 70, no LOD/shaders, G1, compact headers and a 3 GiB maximum heap.
Private copies use Peaceful difficulty and a fixed noon clock/weather; distributed
packs retain normal rules. All original experimental controllers are disabled.
| Pair | Baseline FPS | Core FPS | Baseline peak RSS | Core peak RSS | Baseline CPU | Core CPU |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| 1 | 5.39 | 6.53 | 2,310.68 MiB | 2,043.46 MiB | 2.931 cores | 2.898 cores |
| 2 | 5.55 | 6.32 | 2,572.06 MiB | 2,031.07 MiB | 2.928 cores | 2.981 cores |
| 3 | 5.39 | 6.52 | 2,172.38 MiB | 2,121.73 MiB | 2.942 cores | 2.950 cores |
Paired average-FPS changes are **+21.28%, +14.00%, +20.96%**. Their arithmetic
mean is +18.75%; this is a descriptive average of three changes, not a pooled
frame estimate or a statistical significance claim. The slowest-1%-average rate
is higher in all pairs, while p95 frame intervals are 8.43–21.25% lower. Peak
sampled RSS changes are **−11.56%, −21.03%, −2.33%**. Memory varies substantially
across fresh processes, so the earlier single pair's 22% reduction is not a
stable memory-saving estimate.
Average process CPU changes are −1.11%, +1.81%, +0.30%: there is no consistent
absolute CPU reduction while rendering more frames. Peak sampled JVM heap is
slightly higher in the third core run. GC accounting time is 113→92 ms, 57→154 ms
and 157→96 ms across the three pairs, so it is mixed too. These are collector
MXBean totals, not JFR stop-the-world pause measurements; no JFR profiling runs
alongside these captures.
Every accepted run has nonempty frame/tick CSVs with verified counts and mean
durations, zero excluded frames or dropped samples, matching captured settings
and no visual-setting changes. Sampled tick-manager state remains normal at
20 configured TPS with no observed freeze, step, sprint or rate changes. Observed
invocation throughput ranges from 19.997 to 20.006 TPS; mean tick execution time
is 26.43–32.91% lower with core. This stationary integrated-server workload does
not establish capacity for a populated dedicated server. Saved cameras, positions,
clock/rules and clean process exits are checked for every run. All three real
JSON/CSV pairs pass desktop/mobile comparison and chart checks.
The original third-pair candidate lost focus when the headless input tool's
single long sleep overflowed and its keyboard disappeared. Its 448 eligible
frames, 211 excluded frame starts and 1,391 measured ticks over about 120 seconds
are excluded. The preceding valid baseline is retained separately as unpaired
data. The complete third pair was repeated from fresh copies after replacing
the long sleep with several shorter sleeps in one persistent process and adding
an input-process liveness check. Neither excluded attempt enters the summary.
The [selected repeated observations](../benchmarks/core-client-repeats-2026-10-04/live-observations.json)
include all six accepted runs, the excluded attempts, each pair's comparison,
loaded mod identities and private capture/fixture hashes. This is still one
stationary view on an i7-7500U Linux **llvmpipe software renderer**. Baseline is
always first within each pair. OS cache, JIT, entity activity and thermal effects
remain uncontrolled variables. Three pairs do not prove a universal improvement;
Apple Silicon/native GPU performance, movement and terrain generation remain to
be measured. See the [Mac first-test guide](mac-first-test.md) for a matched-view
comparison on the user's hardware.
## Earlier single pair on 0.19.0
The selected 4 October 2026 live observations use separate private world copies,
a stationary camera, native Linux x64 Java 25, G1, compact headers and the same
3 GiB maximum heap. The test copies use Peaceful difficulty and a noon clock with
weather/time advancement disabled to reduce lighting variation. Distributed packs
do not change world rules. First saved cameras and saved clock/rules are checked.
JFR begins roughly 121 seconds after demo dismissal; a separate 120-second frame
capture begins roughly 307 seconds after dismissal.
| Observation | Vanilla baseline | Core mods |
| --- | ---: | ---: |
| Eligible frames | 651 | 785 |
| Average frame rate | 5.44 FPS | 6.56 FPS |
| 95th-percentile frame interval | 194.89 ms | 163.18 ms |
| Sampled peak process RSS | 2,710.76 MiB | 2,108.96 MiB |
| Average process CPU | 2.81 cores | 2.88 cores |
| Tick execution mean | 8.98 ms | 6.37 ms |
| Recorded tick samples | 2,401 | 2,402 |
In this single fixed-order, software-rendered pair, average FPS is about 20.7%
higher and sampled peak RSS about 22.2% lower with the core stack. Process CPU is
slightly higher while more frames are rendered. Tick execution durations are
lower; their inverse is execution capacity, not observed TPS. Both captures span
about 120 seconds and record approximately 20 tick samples per elapsed second.
These are descriptive observations, not a statistical or universal speedup claim.
They do not isolate which mod caused a difference. Entity activity, completion
of rendering work, cache/JIT and thermal state remain possible variables. RSS
excludes a complete GPU/unified-memory measurement; Apple Silicon performance
remains unmeasured. Hardware graphics measurements remain needed; the separate repeated series above
uses a different warm-up protocol and must not be pooled with this pair.
Preceding JFR counter rates for the server and render thread are lower with the
core stack, but total and longest measured GC pauses are higher in that profile.
Those recordings precede the frame captures, so rates/pauses must not be treated
as if they covered the later frame interval. Selected observations retain both
findings instead of presenting only favorable measurements.
The [selected raw observations](../benchmarks/core-client-2026-10-04/live-observations.json)
retain software identity, protocol and both positive and negative measurements.
Both clients save and exit with code zero; the core world reloads and saves again.
Actual JSON/CSV viewer and mobile checks pass. Windows, macOS ARM and Linux builds
pass, with byte-identical local and independent Linux production JARs. These are
platform build checks, not game graphics tests on each platform.
-58
View File
@@ -1,58 +0,0 @@
# Avoid allocating iterators for empty culling whitelists
A local game JFR found `HashMap.KeySet` iterator allocation in Entity Culling's
dynamic entity/block-entity whitelist checks on `CullThread`. The pinned 1.11.2
methods create a set iterator before discovering that there are no handlers.
The optional hook returns the JDK's shared empty iterator while the live set is
empty. It checks that set every call; it does not cache a whitelist, remember an
empty state, skip a registered handler, or alter culling decisions. Nonempty
sets use their original iterator, callback order, type guard and short circuit.
No per-call callback object is introduced by the hook.
Use the `culling-empty` profile for an isolated comparison with `m2-balanced`.
Both keep the same graphics, LOD radius, worker budget and other controller
settings. The hook is opt-in, restricted to Entity Culling 1.11.2, and can be
disabled with `enabled=false` in `config/horizon-culling-empty.properties` and a
restart. Frame reports record `empty_culling_whitelist`; the CLI and offline
viewer disclose a difference as an experiment variable.
`python tools/test_culling_empty.py` runs the actual publisher methods inside
Fabric. It checks empty iterator dispatch, registration after initialization,
duplicate registration, real block-entity callback order/short circuit, null and
wrong-type inputs, and returning to an empty state. The menu-only fixture does
not exercise callbacks using a valid world entity; nonempty entity iteration
uses the original implementation. Private instrumentation and fixture JARs
never enter release packs. Full game logs remain private.
A local warmed loop of four million empty checks allocated 128,001,248 bytes
upstream versus 1,248 with the hook. CPU was 41 ms versus 33 ms in that single
observation. These counts isolate this allocation path; JIT escape analysis can
produce different results in other calling contexts. They are not game FPS,
whole-game RAM, statistical speed estimates or Mac GPU results. Repeated matching workloads and real hardware tests remain needed. A fixed-order
Linux software-rendered pair observed about 97,445 versus 35,128 allocated bytes
per second on `CullThread`, over separate 64-second counter spans. The captured
graphics matched and both recordings excluded zero frames, but this one pair is
not a repeatable FPS or retained-RAM result. The candidate also encountered an
intermittent shutdown wait after its world had saved; the control exited normally.
See the [terrain read shutdown check](terrain-read-wait.md).
For local world smoke checks, the baseline and candidate use separate copies of
the same peaceful demo-world snapshot. An earlier capture was interrupted by a
zombie killing the player and is excluded from performance comparisons. Release
packs do not change world difficulty. Frame reports now capture actual world
difficulty at their start/end boundaries so comparison tools can flag a mismatch.
The [sanitized Linux CI result](../benchmarks/culling-empty-2026-10-04/linux-applied-hooks.json)
includes its source/workflow provenance and independently checks live registration
and the applied shortcut. CPU timings can include JIT folding of this empty loop;
they are not per-check costs or estimates of game speed.
The final candidate JAR (`c506982631880604513de8ef85e3b4461fbb898702e60b4a6f74ca3b3d4a687f`)
then recorded 579 frame intervals and 2,408 integrated-server tick durations over
120 seconds, with zero excluded frames and matching CSV counts/means. Its actual
frame report retained custom graphics, render/simulation distances 12/12, DH radius
128 at MEDIUM/MEDIUM quality, two workers at runtime ratio 0.5, compact headers,
and both the culling shortcut and scoped terrain-read fix enabled. No captured
visual setting changed. This verifies integration; it is not a repeated hardware
performance comparison.
-67
View File
@@ -1,67 +0,0 @@
# Reuse numeric scratch vectors in visibility tests
A game allocation profile found temporary vectors in the pinned Entity Culling
1.11.2 visibility library. Its visibility check creates a direction vector, then
normalizes it; its ray intersection creates a second vector for reciprocals.
These vectors remain within the calculation and carry only numeric values.
The opt-in hook redirects those two constructors to separate vectors owned by
that culling instance. All three components are reset each time. Upstream
normalization, division, intersection, traversal, caches and decisions stay in
place. No approximation, ray limit, global pool or shared scratch object is added.
The instance already keeps mutable camera, target, hit-block and cache state;
the hook retains that single-caller contract. It does not make an instance safe
for concurrent or reentrant calls. Two retained numeric objects per instance
replace temporary objects on this path.
Use `culling-rays` for an isolated comparison with `m2-balanced`. Graphics, LOD
radius, worker budget and other controller settings match. All other profiles,
including the combined foreground experiments, explicitly keep this hook off.
It only applies to Entity Culling 1.11.2. To disable, set `enabled=false` in
`config/horizon-culling-rays.properties` and restart. Frame reports record the
actual `culling_ray_scratch` state; the CLI and offline viewer disclose changes
in that state.
`python tools/test_culling_rays.py` runs the publisher's actual geometry with the
hook disabled and enabled. It compares boolean and provider-query digests for
12,800 bounding-box checks across eight occluder patterns and two interleaved
instances. Each mode performed the same 105,239 block reads. It also checks
2,197 direct ray cases covering signed zero, tiny and large values, infinities
and NaN, unchanged input vectors, separate instance scratch objects and retained
arithmetic values. The test uses private fixture invokers; its JAR and accessors
never enter a release pack. These cases support this workload's equivalence,
rather than proving every world's rendered pixels or every mod callback.
A local warmed loop of two million visibility checks allocated 24,318,096 bytes
with the original constructors versus 920 with scratch reuse. Single caller CPU
observations were about 167 versus 149 ms. Another unchanged run allocated only
6,259,360 bytes, illustrating how JIT compilation and escape analysis vary during
these loops. No fixed per-check allocation or statistical speedup is inferred.
The independent Linux CI run allocated only 1,040 bytes upstream versus 920
with scratch reuse, and its caller CPU observation was about 102 versus 119 ms.
That run provides no useful allocation reduction and is slower in this loop.
The hook therefore stays isolated and disabled in every recommended profile.
Raw [local](../benchmarks/culling-rays-2026-10-04/local-applied-hooks.json) and
[CI](../benchmarks/culling-rays-2026-10-04/linux-applied-hooks.json) observations
include source and workflow provenance. This is not a whole-game FPS/RAM or Mac
GPU benchmark; repeated real hardware comparisons and live allocation profiles
are required.
A fixed-order live Linux software-rendering pair observed about 28.18 KB/s
allocated by `CullThread` with the hook off and 27.96 KB/s with it on, over
roughly 64-second counter spans. This does not establish a useful reduction.
Allocation samples were dominated by whitelist iteration; the recorded stacks
did not include either ray constructor. The separate `culling-empty` experiment
addresses that observed path. The clean 120-second frame captures produced
599 control and 584 candidate frames, with zero exclusions and matching CSV
counts; captured graphics and worker settings matched except the ray flag.
Both worlds saved and exited without crash reports or remaining game processes.
The outer control launcher returned 143 without exposing the game exit status;
that return is not counted as a verified normal game exit. Selected
[live observations](../benchmarks/culling-rays-2026-10-04/live-observations.json)
retain the recording limits. These are per-thread diagnostic observations, not
retained memory, a statistical comparison, or a Mac result.
The factory hook follows the upstream [Mixin constructor redirect contract](https://github.com/SpongePowered/Mixin/blob/master/src/main/java/org/spongepowered/asm/mixin/injection/Redirect.java).
Compilation uses a checksum-verified publisher JAR; the release mod contains only
original Horizon classes. Profiles without Entity Culling must still load.
-143
View File
@@ -1,143 +0,0 @@
# Debounce queue experiment
The local profile showed substantial allocation on the distant-terrain chunk
update queue thread. Direct per-thread allocation counters confirmed activity
there; sampled stacks repeatedly entered player-position reads and queue
reinsertion. Inspection of the pinned DH 3.3.4 bytecode explains a mechanism:
an update younger than its existing 250 ms debounce deadline is removed and
reinserted, while the outer queue loop sleeps only when both queues are empty.
A nonempty pending queue can therefore retry continuously before it can do work.
The optional `queue-wait` profile keeps balanced graphics, distances, simulation
settings, mods and worker budgets. Its original hook performs the existing
debounce reinsertion, then requests a wait of up to 1 ms, bounded by the remaining
deadline, if no preprocessing work is pending. It only waits on the queue worker,
never a caller such as the render thread. Incoming queued work unparks a debounce
wait. Starting with 0.9, incoming work can also wake an empty queue's idle wait,
which previously slept for 50 ms. The idle park ends by the next 50 ms cache
maintenance deadline; early wakeups do not trigger maintenance more often than
that cadence. OS scheduling determines when the worker resumes.
The same update object, priority queue, debounce timestamp, overload policy,
executor dispatch and normal simulation remain in use. Executor-unavailable and
rejected-dispatch retries are outside this hook.
`adaptive-queue` combines this hook with the existing adaptive terrain budget
and precise worker pacing. Use `queue-wait` versus `m2-balanced` to isolate the
queue change, and `adaptive-queue` versus `adaptive-pacing` to evaluate the
combination. Each profile explicitly enables only its requested experiments.
Set `enabled=false` in `config/horizon-queue-wait.properties` and restart to
disable the queue hook. It is disabled by default and requires exact DH 3.3.4.
Requested waits are not hard latency bounds: operating-system timers can
overshoot, and arrival/worker scheduling affect responsiveness. Debounce parking
leaves the interruption flag intact, so the existing shutdown loop handles it.
The wakeable idle wait throws with a cleared interrupt flag, as `Thread.sleep`
did; the original catch restores the flag and exits on the next loop check.
New arrival wakeups reduce the chance of delaying useful preprocessing, but
real terrain completion, block-change visibility and platform behavior need
evaluation alongside CPU, allocations and frame pacing.
## Idle wakeup experiment in 0.9
After building, run
`python -c "from tools.build_mod import benchmark_idle; benchmark_idle()"`.
An actual publisher queue starts empty; synthetic incoming work is published
about 5 ms into an idle interval. Separate upstream-sleep and wakeable-park workers
check the same update identity and empty queue after removal. Four warm-up pairs
precede 20 alternating measured pairs. Output reports actual arrival time and
publication-start-to-pop latency. Local Linux medians were 45.181 ms upstream and
0.199 ms wakeable.
Hosted medians and nearest-rank p95 over 20 measured trials:
| Platform | Upstream median | Wakeable median | Wakeable p95 | Wakeable maximum |
| --- | ---: | ---: | ---: | ---: |
| macOS ARM64 | 84.273 ms | 0.068 ms | 0.103 ms | 16.096 ms |
| Linux x64 | 45.065 ms | 0.053 ms | 0.073 ms | 0.073 ms |
| Windows x64 | 45.159 ms | 0.074 ms | 0.127 ms | 0.182 ms |
The upstream Mac maximum was 108.892 ms; its requested 50 ms sleep overshot.
The wakeable Mac maximum also shows scheduler variability. The hosted ARM Mac
has three logical CPUs and is not the user's M2 Pro. [Raw trials](../benchmarks/idle-queue-2026-10-03)
are from [CI run 37155695460](https://github.com/ludovic111/Horizon/actions/runs/37155695460).
This isolates idle wakeup, including enqueue/pop overhead. It does not simulate
the existing 250 ms debounce, preprocessing, chunk generation, meshing, network
delivery or a visible block update. Those delays remain separate. OS scheduling
can change latency; this is not an FPS measurement or a hard responsiveness bound.
Concurrency tests cover arrival before park, arrival while parked, pending
interrupts and interruption while parked. The runtime hook still requires exact
DH 3.3.4 and is enabled only with the existing queue experiment.
## Isolated measurement
Run `python -c "from tools.build_mod import benchmark_debounce; benchmark_debounce()"`
after building the mod. It uses the actual publisher's `ChunkPosQueue`, with
synthetic entries and a 250 ms pending-debounce interval. The upstream mode
repeatedly pops and reinserts the nearest update; the waiting mode inserts the
same bounded-wait policy between retries. Warm-ups precede three alternating
trials at one and 64 queued entries. Each trial checks update identity, nearest
priority and queue count, then reports wall time, worker CPU and worker allocation.
This benchmark isolates redundant polling; it does not simulate game chunk
lighting, rendering, network traffic or terrain completion. Thread CPU counters
can be coarse, particularly on Windows, so a zero reading is below measurement
resolution, not proof of zero CPU cost. Allocation counts are cumulative bytes
allocated during the interval, not retained heap or process memory. Hardware,
timer behavior and workload can change results. The CI publishes raw output
for Linux, Windows and Apple Silicon macOS. No game-FPS claim follows from this
microbenchmark alone.
## Hosted results, 3 October 2026
Raw output is checked in under
[`benchmarks/debounce-queue-2026-10-03`](../benchmarks/debounce-queue-2026-10-03/).
The tables show medians of three trials. Allocations and CPU refer only to this
synthetic queue polling interval, not the entire game. The macOS runner is hosted
Apple Silicon with three logical CPUs; it is not the user's M2 Pro.
| Platform / queued entries | Upstream allocation | Waiting allocation | Upstream worker CPU | Waiting worker CPU |
| --- | ---: | ---: | ---: | ---: |
| macOS ARM64 / 1 | 80,066,144 B | 768 B | 247.157 ms | 0.873 ms |
| macOS ARM64 / 64 | 34,344,320 B | 2,112 B | 248.550 ms | 1.154 ms |
| Linux x64 / 1 | 99,456,064 B | 7,520 B | 248.446 ms | 2.960 ms |
| Linux x64 / 64 | 31,971,072 B | 7,488 B | 249.987 ms | 2.890 ms |
| Windows x64 / 1 | 95,728,256 B | 5,536 B | 250.000 ms | Below counter resolution |
| Windows x64 / 64 | 32,051,200 B | 5,376 B | 250.000 ms | Below counter resolution |
Each upstream interval lasted about 250 ms. Waiting medians were 250.068 ms on
Linux, 250.593–250.856 ms on Windows, and 251.431–252.426 ms on macOS. One macOS
trial lasted 258.012 ms, demonstrating timer overshoot. These are interval-ending
times; they are not measurements of a real block change reaching the screen.
The real 0.7.0 adaptive-queue demo world renders and records with the hook enabled.
Thread inspection reached the injected debounce parking path. A 120-second run
wrote 643 frame intervals and 2,408 server ticks with matching CSV counts/means,
and 119–120 RSS samples. Distant-terrain data continued updating; game worlds and
DH databases closed cleanly. A separate 60-second profile confirmed allocation
counter activity on the queue thread. Its workload/cache state differs from the
earlier profile, so those profiles are not a numerical before/after comparison.
## Stationary live allocation observation, 4 October 2026
A [selected real-game pair](../benchmarks/debounce-queue-2026-10-04/live-observations.json)
uses separate copies of the same private world, matching graphics/JVM settings
and first saved cameras, with the released 0.18 production JAR. Both captures
have zero exclusions/drops and both worlds save and exit with code zero. JFR
starts roughly 121 seconds after demo dismissal; the later 120-second frame
capture starts roughly 307 seconds after dismissal.
Overworld queue allocation counters record about 15.3 MB/s upstream versus
11.5 KB/s with waiting across their roughly 64-second spans. This supports a
large targeted allocation difference in this observation. Work/geometry volumes
are not quantitatively controlled, and daylight, entities and cache/JIT state
can differ. The later control capture has 230 frames versus 225 with waiting;
sampled peak RSS is lower in control and whole-process CPU differs little.
No useful game FPS, retained-memory or whole-process CPU gain is established.
This is Linux software rendering, not an Apple Silicon test. The hook remains
optional, and actual terrain update latency still needs hardware measurement.
Both JSON/CSV viewer charts and the 390-pixel layout pass. An earlier failed
capture had zero eligible frames and 209 exclusions after the virtual keyboard
ended and the game paused. The viewer rejects that real report, clears prior
comparison results and asks for focused gameplay; it is excluded from the pair.
-70
View File
@@ -1,70 +0,0 @@
# Rejected dispatch retry experiment
A local game recording showed allocation samples repeatedly entering DH's
`ThreadPoolExecutor.AbortPolicy`, exception construction and diagnostic strings.
The direct allocation counters showed substantial allocation on render-loader
workers. This was a scheduler retry path, rather than evidence of useful terrain
generation. Inspecting the pinned DH 3.3.4 dispatcher confirmed that rejection
requeues the same tracked task and immediately tries it again while retaining
the dispatcher lock. A busy or unavailable physical pool can make that loop
allocate and prevent other executors from progressing.
The optional `dispatch-retry` profile uses balanced graphics, mods, distances,
worker count and heap guidance. It enables only the new dispatcher hook; adaptive
budgeting, precise worker pacing and queue waiting stay disabled. Other profiles
explicitly disable the new hook, so existing isolated comparisons remain useful.
It requires exact DH 3.3.4. Set `enabled=false` in
`config/horizon-dispatch-retry.properties` and restart to disable it.
After one rejection for an executor in a dispatch pass, the hook ends that
executor's inner submission loop. Other executors can consume available logical
slots in the same pass. The original catch still requeues the original task or
clears it during shutdown. The original lock, priority ordering, occupied-slot
increments/decrements, exception handling and scheduled-future cancellation
remain in use. A rejected pass requests a later retry after 1 ms; a pass with
only paused executors retains DH's original 1000 ms interval. Shutdown prevents
new retry scheduling. OS timers and lock contention can delay the requested retry.
This bounds repeated rejection within each pass. It still constructs an exception
for a rejected submission, and frequent callers can cause additional passes.
It is not a complete replacement scheduler or proof of faster terrain completion.
No simulation rule, server tick rate, render distance or voxel content is changed.
## Applied-hook integration test
Build with `python tools/build_mod.py`, then run `python tools/test_dispatch.py`.
On Linux the latter uses Xvfb; `--native-display` uses an existing display.
The tool builds a private fixture mod under `.local/mod-build`, runs two isolated
Fabric clients with the dispatcher hook disabled and enabled, and exits before
opening a world. It uses the local demo launcher and requires no account.
Official game libraries/assets and publisher mods remain private downloads.
The fixture never enters a release pack or production JAR.
The fixture creates an actual publisher dispatcher with two executors. It replaces
one executor's physical pool with a one-worker, one-slot pool and deliberately
fills it with blocking work outside the dispatcher. This reproduces rejection
while logical slots remain free. Upstream retains the caller in the retry loop
during a 200 ms observation window and stalls independent queued work. With the
hook, the caller returns and the other executor progresses before releasing the
blocked physical worker. Both runs then require each tracked task to run exactly
once, empty logical queues, zero occupied slots and physical-worker shutdown.
The sanitized output reports the submission caller's wall time, CPU time and
allocated bytes, plus total observed physical-pool rejections. Retry-scheduler
CPU/allocation is excluded from the caller counters. The observation window and
earlier patched return produce different caller durations; these measurements
describe the rejected-submission path, not normal task throughput. Linux CI runs
the applied hooks; Windows and ARM Mac CI compile the fixture and production mod.
In [Linux CI run 37158922187](https://github.com/ludovic111/Horizon/actions/runs/37158922187),
[the raw fixture result](../benchmarks/dispatch-retry-2026-10-04/linux-applied-hooks.json)
reported 216,987,192 caller allocation bytes and 63,790 rejections upstream,
versus 103,384 caller bytes and 6 rejections with the hook. Caller wall times were
401.549 ms and 0.959 ms respectively. These are single, unwarmed failure-path
observations, including initialization/JIT effects, rather than normal throughput
or a fixed-duration whole-process comparison. Both modes completed two tasks.
An initial patched Linux game also loaded, recorded 120 seconds and shut down
normally. Its subsequent JFR capture avoided the earlier allocation storm.
The captures had different cache histories; they do not establish an FPS or
whole-game memory improvement, and this is not an M2 graphics benchmark.
-32
View File
@@ -1,32 +0,0 @@
# Combined foreground-first experiments
`foreground-first` combines the adaptive background-terrain budget, precise
worker pacing, bounded/wakeable queue waits and rejected-dispatch retries.
From version 0.13 it also includes compact per-tick membership storage; the
original action collections and their iteration order remain unchanged.
`foreground-vulkan` uses the same combination with Vulkan preference and the
game's OpenGL fallback. Both retain balanced mods, 12 full-detail chunks,
128-chunk LOD radius, two DH workers and simulation distance 12.
The adaptive target is 120 FPS to suit the first M2 Pro/ProMotion testing target.
It is a heuristic frame-time goal, not an FPS cap or a guaranteed rate. The
controller reduces background duty cycle when frames fall behind that target
or heap pressure rises. This can delay distant-terrain completion. It cannot
identify whether GPU, CPU, disk, generation or other work caused a slow frame.
Uncapped game options do not override VSync, driver or display behavior.
Start with balanced, then compare the combined OpenGL profile at equal graphics,
heap and world settings. The individual profiles remain available for isolating
each hook. Compare `foreground-first` against `foreground-vulkan` only after the
isolated Vulkan pack works on the device. Each combined profile explicitly
enables these controls; changing `/horizon adaptive off` disables only the
adaptive controller. Other hooks require their configuration flag and restart.
Change `targetFps` in `config/horizon-adaptive.properties` to evaluate a different
goal, then restart. The recorder captures the goal, actual applied hook flags,
backend and effective video settings. Java compact headers and collector changes
remain separate optional experiments. Normal simulation/tick rules are retained.
These profiles combine measured scheduler mechanisms, not independently measured
Minecraft FPS gains that can be added together. Their interaction, visible
terrain latency, memory and frame pacing need whole-game testing on real GPUs.
-72
View File
@@ -1,72 +0,0 @@
# Matched graphics API comparison
Three core-profile pairs compare OpenGL with Vulkan at the same stationary view.
On this Linux software renderer, Vulkan produces only 1.22–1.74% more average FPS
while using 11.23–12.95% more process CPU. Frame-time tails and sampled RSS are
mixed, and integrated-server tick execution is slower. Playable backend defaults
remain unchanged. These results do not predict physical M2 GPU performance.
## Protocol
Each fresh process uses the exact published 0.20.0 mod, identical core mods,
private camera fixture, initial world copy and 3 GiB maximum / 512 MiB initial
heap. Both APIs use 12 full-detail / 12 simulation chunks, 1280×800, FOV 70,
uncapped FPS, no LOD/shaders, G1 and compact headers. Every original experimental
controller is disabled. The private camera is fixed and world copies use Peaceful
difficulty with noon/weather advancement rules fixed. Playable packs retain
normal rules.
Runs warm for 180 seconds, then record frames and ticks for 120 seconds. Each
pair runs OpenGL first and Vulkan second. Actual devices report llvmpipe LLVM
21.1.8, with Mesa 26.0.8 OpenGL 4.5 or Vulkan 1.4.335. The Vulkan preference is
verified against the observed backend; a fallback would invalidate this series.
The host is an i7-7500U with 2 physical cores / 4 logical processors and about
30.2 GiB system RAM. Native GPU access is unavailable to this user.
## Results
| Pair | OpenGL FPS | Vulkan FPS | OpenGL CPU | Vulkan CPU | OpenGL peak RSS | Vulkan peak RSS | Tick mean, OpenGL → Vulkan |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| 1 | 6.5786 | 6.6765 | 2.895 cores | 3.248 cores | 2,362.36 MiB | 2,337.00 MiB | 6.455 → 7.460 ms |
| 2 | 6.5869 | 6.6671 | 2.918 cores | 3.246 cores | 2,471.90 MiB | 2,526.52 MiB | 6.845 → 7.602 ms |
| 3 | 6.5632 | 6.6775 | 2.879 cores | 3.252 cores | 2,424.70 MiB | 2,459.63 MiB | 6.499 → 7.593 ms |
Paired FPS changes are +1.49%, +1.22%, +1.74%, with a descriptive arithmetic
mean of +1.48%. CPU changes are +12.18%, +11.23%, +12.95% (mean +12.12%).
These three fixed-order pairs do not establish statistical significance.
p95 frame intervals change −2.08%, +0.94%, −1.43%; slowest-1%-average FPS
changes −2.19%, −7.63%, +5.49%. Peak sampled RSS changes −1.07%, +2.21%,
+1.44%. GC accounting is mixed and is not a measured stop-the-world pause total.
Tick execution means increase 11.06–16.84%, while observed invocation throughput
remains near 20 TPS with normal sampled tick-manager state in all runs.
Process CPU includes native rendering and the integrated server. Higher tick
durations in a shared rendering process do not isolate a server algorithm change
or establish dedicated-server capacity. Tick reports do not capture the client
graphics API; their captured-settings match must be interpreted alongside each
paired frame report's explicit backend/driver differences.
## Validation and limits
All six clients save and exit cleanly. Raw frame/tick CSV counts and mean durations
match the JSONs, with zero exclusions/drops. Runtime and fixture hashes, mod
identities, other captured settings, saved camera/position and clock/weather rules
match. Frame comparisons retain only the deliberate backend/driver mismatches.
Both first-pair warmed views were visually inspected before recording and showed
the same forest/terrain. This is not an exhaustive pixel-equivalence test.
All three actual frame/tick JSON+CSV pairs pass desktop/mobile viewer and chart
checks; representative screenshots were inspected. The
[selected observations](../benchmarks/graphics-api-2026-10-04/live-observations.json)
retain all six runs, every paired metric, configuration, device identities and
private capture/fixture hashes. Raw logs, CSVs, images and worlds remain private.
One stationary view, a software renderer, fixed order and three pairs cannot
establish movement/generation behavior, native GPU or Mac speedups, full visual
equivalence or populated-server capacity. OS cache, JIT, entities and thermal
effects can still vary. Sampled RSS covers the settled recording, can miss spikes
and is not complete GPU/unified-memory accounting. Do not pool these API pairs
with heap or vanilla/core experiments. See the [Mac procedure](mac-first-test.md)
for physical-device comparisons and the [graphics probes](client-graphics-smoke.md)
for separate hosted-Mac startup results.
-70
View File
@@ -1,70 +0,0 @@
# Heap budget experiment
Halving the maximum Java heap from 3 GiB to 1.5 GiB does not halve total process
RAM in this workload. Three repeated core-profile pairs show nearly unchanged
average FPS and variable sampled RSS reductions, with more GC accounting time
in every smaller-heap run. Playable memory recommendations remain unchanged.
## Matched experiment
These runs use the exact published 0.20.0 mod and the same private camera fixture
as the [repeated core comparison](core-performance.md). Both sides use the core
stack, 12 full-detail / 12 simulation chunks, 1280×800, FOV 70, uncapped FPS,
OpenGL, no LOD/shaders, G1 and compact headers. Only maximum heap differs. The
initial heap is 512 MiB in both sides. Every run uses a fresh process and the same
initial world copy, warms for 180 seconds and records for 120 seconds. Each pair
runs 3 GiB first, followed by 1.5 GiB.
The host is an i7-7500U with 2 physical cores / 4 logical processors and about
30.2 GiB total RAM, using Linux llvmpipe software rendering. This is not a test
under low system-memory pressure. Private copies use Peaceful difficulty and
fixed noon/weather advancement rules. The camera is stationary and every
original experimental controller is disabled. Those fixture rules are absent
from playable packs.
## Results
| Pair | 3 GiB FPS | 1.5 GiB FPS | 3 GiB peak RSS | 1.5 GiB peak RSS | 3 GiB p95 frame | 1.5 GiB p95 frame | GC accounting |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| 1 | 6.4549 | 6.5133 | 2,080.07 MiB | 2,041.48 MiB | 166.26 ms | 173.65 ms | 95 → 162 ms |
| 2 | 6.5528 | 6.5115 | 2,482.75 MiB | 1,997.45 MiB | 166.18 ms | 174.22 ms | 72 → 93 ms |
| 3 | 6.5624 | 6.5556 | 2,242.84 MiB | 1,989.43 MiB | 166.55 ms | 165.82 ms | 71 → 105 ms |
Paired average-FPS changes are +0.90%, −0.63%, −0.10%. Their descriptive
arithmetic mean is +0.06%; this does not establish an FPS improvement. Peak
sampled RSS is 1.86%, 19.55% and 11.30% lower, illustrating substantial process
variation. A smaller configured heap limit is not a total resident-memory cap.
The smaller-heap captures still use roughly 1.94–1.99 GiB of sampled process RSS.
p95 frame intervals are 4.44% and 4.84% worse in the first two pairs and 0.44%
better in the third. Slowest-1%-average FPS changes are −0.06%, −5.08%, +10.03%.
CPU changes are −5.10%, +0.24%, −0.17%, without a consistent absolute reduction.
GC accounting time increases 29–71%; these MXBean totals are not measured
stop-the-world pause durations. Tick execution means change −7.25%, +9.22%,
+1.15%, while observed invocation throughput stays near 20 TPS in every run.
## Validation and limits
All six clients save and exit with code zero. Frame/tick CSV counts and mean
durations match their JSONs, with zero exclusions or dropped samples. Captured
settings, Java/collector/header configuration and loaded mod identities match
apart from the intentional heap maximum. Sampled tick-manager state remains
normal at 20 configured TPS, without freeze, step, sprint or rate changes. Saved
camera, position, clock and weather rules match across runs.
All three actual frame/tick JSON+CSV pairs pass desktop/mobile viewer checks,
including duration traces and the visible intentional heap mismatch. The
[selected observations](../benchmarks/heap-budget-2026-10-04/live-observations.json)
retain all six runs, paired metrics, configuration, software identity and private
capture/fixture hashes. Raw worlds, CSVs and complete logs remain private.
These are sampled peaks during settled recordings, not whole-session startup
peaks or complete GPU/unified-memory accounting. Three fixed-order pairs in one
world cannot establish capacity for exploration, generation, long sessions,
shaders, distant terrain, all hardware or 50 dedicated-server players. JIT, OS
cache, entities and thermal effects can still vary. Do not pool this experiment
with vanilla/core comparisons or infer physical M2 results from it.
The 16 GB Mac starter retains its 6 GiB recommendation for balanced distant
terrain. See the [Mac test procedure](mac-first-test.md) and
[memory measurement limits](process-memory.md) when measuring another budget.
+17 -84
View File
@@ -8,11 +8,9 @@ Build **horizon-mac-starter-0.21.0.zip** with `python3 tools/build_release.py` (
Use native **Java 25 ARM64**, maximum heap **6144 MiB**, minimum **512 MiB** on a 16 GB M2 Pro Mac. Prism can download Java automatically. Start at 1280×800 or 1920×1200; full Retina resolution is a larger GPU workload. [START-HERE.txt](../packs/START-HERE.txt) has details. The same `.mrpack` files import into Prism on Windows and Linux.
If Prism is already installed, follow the [Mac import and first comparison guide](mac-first-test.md).
Core and balanced also pass [macOS title/demo-world rendering probes](client-graphics-smoke.md)
on the hosted ARM64 software renderer, including readback, saves and clean exits.
Physical M2 GPU performance and macOS 27 remain to be tested.
Core and balanced passed macOS title and demo-world rendering probes on the hosted
ARM64 software renderer, including readback, saves and clean exits. Physical M2
GPU performance and macOS 27 were never tested.
| Profile | Full-detail chunks | Distant LOD radius | Suggested maximum heap |
| --- | ---: | ---: | ---: |
@@ -46,76 +44,24 @@ For the first comparison at the same view distance, use `baseline` versus
The latter adds only the pinned core performance mods and leaves every original
controller disabled. Then test balanced separately for its additional distant
terrain. Matching captured settings does not prove pixel-identical rendering.
[Core comparison protocol and selected observations](core-performance.md)
include three repeated matched-view software-rendered pairs with 14–21% higher
FPS in this workload; M2 performance remains unmeasured.
[Heap budget experiment](heap-budget.md): three pairs with 3 GiB versus
1.5 GiB maximum heap show variable RAM savings and GC/frame-time tradeoffs;
playable defaults remain unchanged.
The profiles marked *experiment* each isolate one change to Distant Horizons,
EntityCulling or the JVM (adaptive terrain throttling, precise worker pacing,
debounce-queue waits, rejected-dispatch retries, empty culling whitelists,
culling ray scratch vectors, terrain quad reuse, terrain position arithmetic,
tick membership storage, a smaller heap, compact object headers). Each kept the
upstream behaviour it replaced and was measured only on Linux software rendering,
where none showed a gain large enough to enable by default; balanced keeps them
all off. Their write-ups were removed once the Rust rewrite replaced this track;
they remain in Git history. Matched software-rendered pairs showed `core-performance`
14–21% faster than `baseline`, and Vulkan about 1.5% more FPS for about 12% more
CPU; neither is evidence for a Mac GPU.
[Matched graphics API comparison](graphics-api-comparison.md): Vulkan adds
about 1.5% average FPS but about 12% CPU in three Linux software-rendered pairs;
backend defaults remain unchanged and physical Mac performance is unmeasured.
The optional `queue-wait` pack yields during pending distant-terrain debounce retries; `adaptive-queue` combines it with the existing controllers. [Queue experiment and measurement limits](debounce-queue.md).
Version 0.16 adds a separate [terrain position arithmetic experiment](terrain-position.md)
for the sampled full-data lookup. It retains the pinned library’s unusual
negative-coordinate rounding and invalid-level errors. Balanced keeps it off;
whole-game and Mac performance still require measurement.
Version 0.15 adds an isolated [culling ray scratch experiment](culling-rays.md)
that reuses two numeric vectors within each culling instance while retaining
upstream arithmetic and decisions. Balanced keeps it off; hardware gains remain
unmeasured.
Version 0.14 adds an isolated [empty culling whitelist experiment](culling-empty.md)
that avoids allocating iterators while there are no dynamic handlers. Live
registration and nonempty callbacks retain upstream behavior. Balanced keeps it
off; whole-game gains still need hardware comparisons. DH profiles also request
a scoped [interruptible blending-read wait](terrain-read-wait.md) to let
background workers leave a pending metadata read during shutdown.
Version 0.13 adds an isolated [tick membership experiment](tick-membership.md)
that reuses compact storage for DH's private per-tick membership checks. The
combined foreground profiles include it too; balanced keeps it off. The applied
holder test verifies action semantics and removes repeated entry allocations;
whole-game FPS and RAM gains still need hardware measurements.
Version 0.12 captures effective distant-terrain quality, radius, worker budgets,
Iris state and field of view. Start/end snapshots flag changed visual settings;
[measurement details](terrain-measurements.md) explain their limits.
Version 0.11 adds combined foreground-first OpenGL/Vulkan profiles with a 120 FPS
adaptive goal, plus explicit collector experiments and GC measurement guidance.
See [combined controls](foreground-first.md), [Vulkan on your Mac](vulkan.md)
and [collector comparisons](collectors.md). The frame goal is not a rendering cap.
Version 0.10 adds an isolated [rejected-dispatch retry experiment](dispatch-retry.md).
It bounds retry passes when a DH worker rejects queued work, preserving original
requeue handling and allowing other executors to progress. Balanced keeps it off.
Version 0.9 also makes the queue's idle wait wakeable for incoming work, preserving
its debounce rules and bounded cache-maintenance cadence. It remains part of the
optional queue profiles, with separate wake-latency measurements.
Version 0.8 fixes a fresh-instance graphics preset that could override the selected
render distance. It also records actual GC/header settings and supports an optional
[compact object headers experiment](compact-headers.md) for Java 25; packs
do not enable that JVM flag automatically.
To try the game's own Vulkan backend on a Mac, see [Vulkan on your Mac](vulkan.md);
to compare garbage collectors, see [collector comparisons](collectors.md).
## Measure on your hardware
The optional [adaptive terrain experiment](adaptive-terrain.md) 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.
The additional [precise worker pacing experiment](worker-pacing.md) makes short
terrain tasks respect their duty-cycle budget and avoids boxed worker timestamps.
It changes generation speed and CPU use, so it stays separate from balanced.
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.
@@ -128,22 +74,9 @@ python3 tools/compare_benchmarks.py baseline-frames.json optimized-frames.json -
Open `Compare-Benchmarks.html` from the starter ZIP or [the source file](../tools/Compare-Benchmarks.html) in your browser to compare without Python. Select each JSON and optionally its matching CSV. It exports summary JSON, flags settings and duration differences, and charts frames by recorded active time or ticks by sample number. It is self-contained and makes no network requests.
Version 0.18 adds an isolated [terrain quad reuse experiment](quad-reuse.md).
It reuses a temporary quad discarded by successful premerge when the existing
pool would otherwise allocate. Generated geometry and thread ownership checks
pass; allocation results are not whole-game RAM or FPS evidence. It remains off
in combined profiles.
Version 0.17 also records loaded mod versions and the Java vendor, VM and runtime
build in client and server reports. Both comparison tools flag software changes
as explicit experiment variables; older reports remain usable with an unknown
software warning. The viewer can expand the complete loaded mod list.
[Live software identity check](../benchmarks/software-identity-2026-10-04/live-observations.json)
records the metadata and file-count validation; its short capture is not a
performance comparison.
The comparison flags captured setting differences, but cannot verify route, world, shader state or cache warm-up. See [validation evidence](playable-validation.md). Software-renderer test FPS is not evidence of a Mac/GPU speedup.
The comparison flags captured setting differences, but cannot verify route, world, shader state or cache warm-up. Software-renderer test FPS is not evidence of a Mac/GPU speedup.
For CPU/allocation investigation, [capture and stream a private JFR summary](profiling.md).
It distinguishes directly observed allocation counters from sampled hot methods;
-89
View File
@@ -1,89 +0,0 @@
# First test on the M2 Pro Mac
For the 16 GB M2 Pro, start with the 0.21.0 packs. No release downloads are published; build them with `python3 tools/build_release.py`. Core and balanced
pass title/demo-world rendering and save/exit probes on the hosted macOS ARM64
software renderer. Gameplay and FPS on this physical Mac remain unmeasured.
The Linux software-rendering observations do not predict an M2 speedup.
## Import after installing Prism
1. Build `horizon-mac-starter-0.21.0.zip` with `python3 tools/build_release.py`, copy it
from `dist/` to the Mac and extract it in Finder.
2. In Prism, choose **Add Instance > Import**, then select
`horizon-m2-balanced-0.21.0.mrpack` from the extracted folder. The individual
`.mrpack` is the import file; the starter ZIP contains several different packs.
[Prism's import guide](https://prismlauncher.org/wiki/help-pages/zip-import/)
describes the supported archive formats.
3. Sign into your Microsoft account inside Prism, using your own Java Edition
license. This project needs no account credentials.
4. Open Prism's global **Settings > Java** and enable **Autodetect Java version**
and **Auto-download Mojang Java**. This pack requires Java 25. On Apple Silicon,
use ARM64/aarch64 Java. If you select Java manually, use the instance's
**Edit > Settings > Java > Java installation > Auto-Detect** and select native
Java 25. [Prism's Java guide](https://prismlauncher.org/wiki/getting-started/installing-java/)
explains automatic downloads and manual selection.
5. In the instance's **Edit > Settings > Java**, enable the Memory override and
set maximum memory to **6144 MiB**, minimum to **512 MiB**. This is a starting
heap budget, not a measurement of total process or unified GPU memory.
6. Launch and create a new test world, or use a copy of a Minecraft 26.3 world.
Save, quit, reopen and check normal movement, breaking/placing blocks and
inventory interaction before benchmarking. Start at a modest window size,
such as 1280×800; the recorder reports the actual framebuffer dimensions,
which may differ from the logical window size on a Retina display.
Balanced uses 12 full-detail chunks and a 128-chunk distant terrain radius.
Allow the distant cache to settle. Distant terrain uses simplified geometry and
does not extend normal simulation. The cinematic and Vulkan packs are separate
experiments to try after this first launch succeeds.
## Measure performance at the same view distance
Import `horizon-baseline-0.21.0.mrpack` and
`horizon-core-performance-0.21.0.mrpack` from the same starter folder. Both use
12 full-detail chunks, 12 simulation chunks and no distant LOD or shaders. Core
adds the pinned performance mods; all original experimental controllers are off.
Comparing these two isolates the core stack more closely than comparing baseline
with balanced's additional distant terrain.
Use identical separate world copies, the same Java/heap/JVM flags, actual
framebuffer size, FOV, graphics quality, VSync, FPS limit and camera route. Close
other game instances, plug in the Mac and keep its power mode consistent. Use
uncapped FPS with VSync off for both measurements if you want to measure available
throughput; return to a display-appropriate cap or VSync for everyday play.
Warm each run for at least three minutes after entering the world and dismissing
menus. Longer generation workloads may need more time. Press **F8** (possibly
**Fn+F8**) in focused gameplay for a 120-second recording. Keep the view or route
consistent and avoid menus during recording. After it finishes, save and quit.
Repeat three pairs in this order:
| Pair | First run | Second run |
| --- | --- | --- |
| 1 | baseline | core-performance |
| 2 | baseline | core-performance |
| 3 | baseline | core-performance |
This alternates profiles but always puts baseline first within a pair. It reduces
dependence on one run; it does not remove order, cache or thermal effects. Keep
fresh terrain exploration separate from already-generated terrain. Also test
normal gameplay after the stationary view; matching settings is not exhaustive
gameplay or visual equivalence.
## Read the results
Open each instance's Minecraft folder in Prism and find `horizon-benchmarks/`.
Keep each run's frame JSON/CSV and tick JSON/CSV together. Open
`Compare-Benchmarks.html` from the starter folder and select one baseline frame
JSON plus its CSV and the paired core frame JSON plus its CSV. Then compare the
paired tick files separately. The viewer works locally without uploading files.
Check settings mismatches, exclusions, dropped samples and tick-state warnings
before comparing FPS, p95/p99 frame intervals, peak sampled RSS and average process
CPU. Compare all three pairs rather than selecting the best result. Normal tick
invocation throughput should remain near 20 TPS; inverse tick execution duration
is not TPS. RSS is sampled once per second and does not cover all unified GPU
memory. See [tick-state limits](tick-state.md) and [memory limits](process-memory.md).
Finally test balanced for the longer horizon using the same route and resolution,
with a settled distant cache. Treat its extra view distance as a changed visual
workload, then decide whether the appearance and performance meet your goal.
+2 -2
View File
@@ -8,7 +8,7 @@ hardness/tool rules, collect drops from the block loot tables, place blocks,
craft in the 2x2 inventory grid or on a crafting table, and save and reload worlds
in vanilla's Anvil format.
**Status:** playable, in development. The [Java parity table](../README.md#project-status)
**Status:** playable; players get it through [the launcher](../launcher/README.md). The [Java parity table](../README.md#project-status)
in the README scores each subsystem against vanilla and lists what is still
missing; [Rust rewrite status](rust-parity.md) has the details.
@@ -17,7 +17,7 @@ missing; [Rust rewrite status](rust-parity.md) has the details.
Use current stable Rust (1.90+), Python 3.10+ and JDK 25. Horizon never
downloads the game: resource preparation imports **your own copy** (the 26.3
client from your official launcher install, and the 26.3 server jar you
downloaded yourself; see [Bring your own copy](../README.md#bring-your-own-copy)),
downloaded yourself; see [Build from source](../README.md#build-from-source)),
verifies it against the pinned checksums, runs vanilla's data generator and small
exporters against those jars, and extracts the jar's assets and data into ignored
`.local/horizon-client/26.3/`. Sounds (about 380 MB) are copied from your
-76
View File
@@ -1,76 +0,0 @@
# Optimization research plan
## Starting point
The first playable Java foundation is described in [Java performance packs](java-packs.md). Client optimization has priority. Vanilla gameplay, world formats and multiplayer behavior must be preserved; existing modpack compatibility is not required. Any language, renderer or architecture is in scope when measured gains justify it. Windows/Linux and Apple Silicon/Intel macOS are targets, with the M2 Pro/16 GB Mac prioritized.
Inspect both pinned game JARs locally, retain bytecode as the reference, and measure actual Minecraft workloads before selecting a subsystem to replace. The Rust face-count experiment establishes a small correctness/benchmark workflow; it does not identify a Minecraft bottleneck.
Whole-game translation is a long-term research objective. Decompiled Java is an inspection artifact, not the original source tree: build configuration, comments, tooling history, and some source-level constructs cannot be recovered faithfully. A mechanically translated Rust game would also have to preserve behavior, data formats, networking and rendering. An isolated hot-path replacement is a useful first experiment.
The Rust rewrite now has an original `horizon-core` foundation and a bytecode
differential runner for selected position, random-stream and packed-storage
operations. [Rust parity status](rust-parity.md) distinguishes that tested slice
from the unimplemented gameplay and renderer. This establishes compatibility
testing infrastructure; it does not select an FPS bottleneck or supply a playable
Rust client.
## Local code map
These entry points were verified present in the decompiled 26.3 client. Paths below are relative to `.local/minecraft/26.3/sources/client/net/minecraft/`; shared/server logic can also be inspected in the dedicated-server tree.
| Area | Local entry points | Questions to measure |
| --- | --- | --- |
| Client loop | `client/Minecraft.java` | CPU frame-time distribution, allocation/GC, render-thread stalls |
| Server loop | `server/MinecraftServer.java`, `server/level/ServerLevel.java` | Tick time, entity/block tick work, waiting on chunk jobs |
| Section compilation | `client/renderer/chunk/SectionCompiler.java`, `SectionRenderDispatcher.java` in that directory | Work per rebuild, queue latency, allocations, upload overhead |
| World generation | `world/level/levelgen/NoiseChunk.java`, `NoiseBasedChunkGenerator.java` in that directory | Time per newly generated chunk, cache reuse, generation scheduling |
| Lighting | `world/level/lighting/LevelLightEngine.java` | Update propagation work and queue contention |
| Block storage | `world/level/chunk/PalettedContainer.java` | Palette access costs, locality, mutation behavior |
| Region I/O | `world/level/chunk/storage/RegionFile.java` | Serialization/compression cost versus disk waits |
The local inventory contains every class, bytecode size, method count, and source-file relationship. Large classes are navigation hints; bytecode size does not establish execution cost. Generated registries can be large while irrelevant to steady-state frame time.
## Capture a real baseline
Use a licensed launcher installation and a copy of a test world. Keep raw captures and world data in `.local/`. Record game version/hash, mod versions, Java version/flags, CPU/GPU, OS, resolution, render/simulation distance, world seed, route, and warm-up duration.
Use at least these separate scenarios:
1. A fixed stationary view after chunks settle.
2. A reproducible movement route through already generated chunks.
3. The same route through newly generated terrain.
4. A controlled entity/redstone workload on the dedicated server.
5. World loading/saving as a separate latency test.
For a running local Java process, JDK tooling can capture a bounded recording:
```sh
jcmd -l
# Replace 12345 with the Minecraft JVM PID, and use an absolute capture path.
jcmd 12345 JFR.start name=mc-baseline settings=profile duration=120s filename=/absolute/path/to/repo/.local/baseline.jfr
jfr summary .local/baseline.jfr
jfr print --events jdk.ExecutionSample,jdk.GarbageCollection .local/baseline.jfr > .local/baseline-events.txt
```
Collect CPU profiles, allocation/GC information, frame-time percentiles, server tick-time percentiles, and relevant GPU timings. JFR samples alone do not measure FPS or GPU cost. JVM compilation/warm-up, profiling overhead, world generation, and background activity must be controlled when comparing runs. The [core comparison](core-performance.md) now contains stationary Linux software-rendering observations; Mac GPU, movement/generation and populated dedicated-server measurements remain open.
## First native integration experiment
Choose a kernel only after a profile shows enough inclusive cost to justify it. A candidate should have a clear input/output boundary and deterministic reference tests. Candidate areas include occupancy preprocessing, palette scans, or batched generation calculations; these are hypotheses to investigate.
Measure an improved Java implementation first. Then compare an original Rust implementation with equivalent work and account for Java/native transition cost, data marshaling, allocation, and scheduling. Use coarse batches rather than a call per block. Preserve Minecraft behavior for boundaries, partial/transparent blocks, lighting, saved data, and deterministic world generation wherever the selected kernel touches them.
Ship any integration as an original mod/native library loaded into the user's local game. Do not bundle a modified Minecraft client/server. Add a fallback to the reference implementation and differential tests using locally generated fixtures.
## Gates before expanding scope
| Gate | Evidence required |
| --- | --- |
| Bottleneck selected | Reproducible real-game profile and workload definition |
| Kernel equivalent | Boundary cases and randomized differential tests, including real input shapes |
| Native call worthwhile | End-to-end measurements including copying and transitions |
| Game improves | Repeated real-game frame/tick distributions, allocations, memory, and CPU/GPU cost |
| More Rust justified | Improvement persists across workloads without changing gameplay |
If a subsystem occupies fraction `p` of total measured time, even eliminating its cost gives a theoretical maximum overall speedup of `1 / (1 - p)`. For example, a subsystem consuming 10% of frame time cannot alone yield a 2× whole-game speedup. Apply this before undertaking a large rewrite.
-170
View File
@@ -1,170 +0,0 @@
# First playable release validation
Version 0.2.0 targets Minecraft 26.3 / Fabric 0.19.5 / Java 25. This is an initial playable Java optimization stack, not a completed renderer rewrite. Measurements here establish what was actually checked.
## Local checks
- Official client runs through a Wayland virtual screen in built-in limited demo mode, without Microsoft credentials. Normal Mac play uses licensed Prism sign-in.
- Balanced stack (Sodium, Lithium, FerriteCore, ImmediatelyFast, EntityCulling, Distant Horizons, Fabric API, Horizon) reaches the menu, loads the demo world, logs in locally, renders terrain, and saves/quits.
- DH generates and accepts the current configuration schema: 128-chunk LOD radius, two background threads at 0.5 run-time ratio, priority 3. No old-version guessed config keys.
- A missing desktop AWT component in the local headless JRE initially caused a DH cloud-texture error. Installing the complete Java 25 runtime resolved it; this was an environment issue, not a packaged mod change.
- Native libraries are chosen by OS and architecture, including ARM64 selection when the official manifest has OS-only rules. Builds use portable `/` ZIP paths on Windows too.
- The official Prism 11.1.1 macOS ZIP was downloaded, SHA-256 verified, and its actual app layout checked. Its launcher executable is a universal Mach-O containing x86_64 and arm64. The starter does not redistribute it or disable macOS security checks.
- Dedicated-server optimized dependencies and original mod initialize with the real server game JAR; EULA-false startup exits as expected. No license acceptance is made on the user's behalf. Integrated-server gameplay is a separate client check.
- The original recorder loads with the vanilla renderer and F8 starts/stops it during actual demo gameplay. A persistent virtual keyboard is needed on this headless compositor: removing the last temporary keyboard otherwise removes window focus and auto-pauses the game. This is a test harness detail, not a change to pause behavior or focus exclusions.
- That runtime check wrote both raw CSV/JSON pairs, containing 69 actual frame intervals and 744 actual integrated-server tick durations. GPU/backend/driver and render settings were captured. The comparison tool successfully reads these real report files. This short, cold, software-rendered run validates capture/output only; it is not a performance baseline to compare with a real Mac.
- Build/metrics/pack tests pass on actual hosted Apple Silicon macOS 26, Windows x64 and Linux x64 runners. The Windows run exposed an existing decompilation-coverage path separator mismatch; paths are now normalized to match JAR SourceFile metadata.
- 17 offline Python tests cover corrupt/cached artifacts, server extraction/traversal rejection, decompilation inventory, publication exclusions, dependency closure, safe download paths, pack format, OS/ARM native selection, and comparison mismatches.
- Original Java metrics tests cover percentiles, the average of the slowest 1% (not the reciprocal of p99), stall boundaries, bounded samples/overflow, filename sanitization, exclusions and player counts.
- Existing three Rust differential tests, formatting and Clippy checks pass. Rust kernels remain unintegrated.
- The exact published balanced pack was then re-run through real demo world rendering, with its published original mod binary checked byte-for-byte against the runtime. F8 produced nonempty frame/tick JSON and matching raw CSV; each reported sample count and mean duration were checked against the CSV.
## Interpretation limits
The exact 0.11.0 JAR (SHA-256
`c2f59ca0b2f1e356f51b41cd0d9f1d98d6b86e240f5b5a1424f27de57f0e9c4a`)
ran `foreground-first` with an explicit G1 collector, compact headers and 3 GiB
heap. Its 120-second OpenGL world capture produced 640 frame intervals and
2,401 server ticks with matching CSV counts/means and 120 RSS samples each.
All four controls and the wakeable idle path were reported enabled, with adaptive
goal 120 FPS, uncapped rendering and actual distances 12/12. World saves, all
three DH database closures, worker shutdown and client quit completed. The offline
viewer displayed the actual combined state, goal/cap distinction and collector
accounting guidance. These software-rendered checks validate integration rather
than establishing M2 FPS, RAM, LOD-completion or real-GPU visual improvements.
The same exact JAR then ran `foreground-vulkan` with all controls enabled,
adaptive goal 120, uncapped rendering and distances 12/12. The actual Vulkan
backend and driver were captured. Its 120-second recording produced 618 frame
intervals and 2,413 server ticks with matching CSV counts/means and 120 RSS
samples each. This verifies the combination on Linux software Vulkan; it does
not validate MoltenVK, all distant-geometry visuals or GPU performance on the Mac.
The exact 0.10.0 JAR (SHA-256
`101790057c969333e2d9753640d4996649e8ced27e465897d8b6beab2474ed4c`)
ran the standalone dispatch-retry profile with 3 GiB heap and compact headers.
Its 120-second recording produced 568 frame intervals and 2,407 server ticks,
with matching CSV counts/means and 120/119 RSS samples. The actual frame report
retained custom graphics preset and 12/12 render/simulation distances, enabled
the dispatcher hook, and disabled adaptive/pacing/debounce/idle hooks. The world
saved, all three DH databases closed, worker threads stopped and the client quit.
The offline viewer read actual dispatch metadata, JVM settings, RSS and CSV.
Applied-hook fixtures verify exact task completion, independent-executor progress,
recovered slots and shutdown against the actual upstream rejection path in Linux
CI; Windows and ARM macOS compile the fixture. [Results and limits](dispatch-retry.md)
describe synthetic, caller-only failure-path measurements. An unchanged client
from the same saved world did not reproduce the earlier game allocation storm;
these variable captures do not prove a repeatable game-FPS or RAM improvement.
The exact 0.9.0 JAR (SHA-256
`2c5a731d4c93df427cc6054f120a52bf9456b3343b94ad9b79de1584b14d783f`)
ran the combined queue/adaptive/pacing profile with a 3 GiB heap and compact
headers enabled. Thread inspection reached the new wakeable idle park in all
three dimension queues. The 120-second capture produced 806 frame intervals and
2,411 server ticks, with matching CSV counts/means and 120 RSS samples each.
The frame report captures the idle hook as true and actual render/simulation
distances 12/12. The offline viewer reads the new flag, JVM settings and raw CSV;
general viewer checks also pass. World/database/worker shutdown completed cleanly.
Concurrency tests and the actual publisher-queue wake-latency probe pass on
Linux, Windows and hosted Apple Silicon macOS; [raw results and limits](debounce-queue.md)
keep idle wakeup separate from terrain completion and FPS. A 3 GiB heap passing
this short world test is not a recommendation for heavy or long-running worlds.
The exact 0.8.0 JAR (SHA-256
`b674be112cd148406b6b79c14f54b91a4da1ac0e03fe744aaee857c5a51eae8a`)
loaded the complete adaptive-queue stack with compact headers enabled. A fresh
options file retained custom graphics preset, render distance 12 and simulation
distance 12 in the actual frame report. The 120-second run produced 793 frame
intervals and 2,409 server-tick samples; CSV counts and mean durations match JSON.
Both reports captured compact headers as true, G1 collector names and 120 RSS
samples. The offline viewer displayed these actual settings, RSS and CSV charts;
general frame/tick, invalid-input, escaping and mobile checks also passed.
World/database shutdown completed cleanly. This software-rendered integration
test is not a matched RAM/FPS comparison. Cross-platform builds, native-reader
tests, metrics under compact headers, isolated allocation probes and 20 Python
tests passed on Linux, Windows and hosted Apple Silicon macOS 26. See
[object layouts and measurement limits](compact-headers.md).
Generated pack options now carry data version 5023, verified against `version.json`
inside the checksum-verified Minecraft 26.3 JAR. Without this marker, the game's
legacy-options migration reset the intended backend to Default. The fixed Vulkan
preference starts the actual Vulkan backend with the pinned Sodium/DH/ImmediatelyFast
stack, renders the demo world, and records 256 frame intervals / 2,372 server ticks
over 120 seconds with matching CSV/JSON and 119–121 RSS samples. The frame report
identifies Vulkan and its driver. DH data continues updating and saves/databases
close cleanly. With an unavailable Vulkan driver path confined to a separate test
process, the game reports backend creation failure and reaches the menu using its
OpenGL fallback. These checks do not establish Vulkan speed, distant-LOD visual
correctness, shader compatibility, or behavior on the user's Mac. Balanced remains
the OpenGL first test; Vulkan remains an optional independent comparison.
The 0.7.0 optional debounce queue hook initializes and renders with the combined
adaptive/pacing controls. The exact candidate JAR wrote 643 frame intervals and
2,408 server-tick samples over 120 seconds; CSV counts and means match the reports,
which capture all three controls as enabled and include resident-memory samples.
Thread inspection reached the injected debounce parking path, DH terrain data
continued updating, and worlds/databases/workers closed cleanly. The actual
publisher queue microbenchmark passes identity/priority/count checks on Linux,
Windows and Apple Silicon macOS; its raw results and timing overshoot are documented
in [the queue experiment](debounce-queue.md). These are separate from game-FPS,
block-update-latency or RAM-reduction claims. All fourteen pack overrides retain
simulation distance 12 and explicitly set the intended experimental flags.
The 0.6.0 resident-memory sampler ran in the actual adaptive-pacing demo world.
A 120-second recording produced 370 frame intervals and 2,407 server-tick samples;
both CSV counts and mean durations match their JSON summaries. Each report has
120 successful RSS samples, a peak of about 2,643 MiB, and a last-sample age under
800 ms. The runtime JAR matches the release candidate byte-for-byte. After capture,
the sampler thread waits without further scheduled reads. Native-read tests also
pass on hosted Windows x64, Linux x64 and Apple Silicon macOS 26; unsupported
reader behavior preserves timing samples and omits unavailable RSS fields.
These numbers validate reporting in this particular software-rendered workload,
not a RAM reduction or a prediction of the user's Mac memory use.
The 0.5.0 offline viewer passed Chromium checks using real frame/tick JSON and CSV
files, charts, exports, malformed inputs, kind mismatches, escaped profile labels,
and mobile layout. It is self-contained and has no network dependencies. Its game
runtime classes are identical to 0.4.0, apart from mod version metadata.
The 0.4.0 worker-pacing hook also renders the demo world with the complete mod stack.
Both pacing and adaptive controls are captured as enabled in the final build's
120-second frame report. It produced 359 frame intervals and 2,401 integrated-server
tick samples, verified against raw CSV counts and heap/resource fields. The DH database
received terrain-data updates during this run. The earlier hook build saved/quitted
and closed its databases/workers cleanly. Hosted executor benchmarks pass on Linux,
Windows and Apple Silicon macOS; [their results](worker-pacing.md) remain separate
from game-performance claims. The revised policy tests include 1 ms and 15 ms timer
overshoot and bounded credit after long stalls.
The 0.3.0 adaptive profile rendered the actual demo world and applied live DH duty-cycle
changes from 0.5 down to 0.05 under software-renderer frame pressure. Opening the pause
menu released the override and reported an effective ratio of 0.5 again. A separate
baseline instance starts without DH. API adapter tests cover suspension/resumption,
changed user ceilings, and yielding to an existing or changed override from another mod.
The real recorder wrote 193 frame intervals and 1,651 integrated-server tick samples,
with matching CSV counts, sampled heap peaks and process CPU data. Dedicated-server
0.3.0 dependencies initialize and exit with EULA false. No populated server result
is inferred. The updated offline suite has 19 Python tests, including upgrade backups
and refusing to replace an unrelated JAR with a matching filename.
A 60-second JFR recording identified foreground, server and DH worker activity. It
also demonstrated why allocation sampling must be corroborated: large sample weights
at timestamp boxing did not correspond to the largest per-thread allocation counter
deltas. Profiles stay private under `.local/`; neither sample weights nor this
software-renderer workload establish a real-hardware optimization result.
The local Linux host uses **Mesa llvmpipe software rendering**. It is useful for mod/mixin/startup/report validation, not for predicting M2 Pro, Windows GPU or Linux discrete-GPU performance. Warm-up/world loading on this host is slow. Demo credentials produce expected unavailable account-properties/Realms logs, and chat availability can be restricted; the independent F8 measurement shortcut avoids relying on chat.
CI compiles/builds on Linux and Apple Silicon macOS (Windows was dropped from scope on 2026-10-08; earlier Windows results below are historical). Successful compilation is not graphics, authentication, UI or Mac-driver runtime validation. macOS 27 and the user's actual M2 Pro have not been tested here. Optional cinematic shaders and Vulkan are experiments; the OpenGL balanced pack is the first manual test.
The [core comparison](core-performance.md) records numerical observations for
matched software-rendered workloads. They do not establish a Mac or hardware-GPU
speedup, least-memory result, exhaustive vanilla equivalence, universal GPU
support, or a 50-active-player result. Worlds need copies, repeated matched routes
and real hardware measurements before decisions about deeper replacements. New
terrain generation and steady-state rendering are separate workloads.
## Release content
Packs embed only the original MIT Horizon JAR and config. Mod/game/library downloads retain upstream licenses and are checked against pinned hashes. No game JAR, class, decompiled source, asset, world or credential is committed or uploaded in a starter. The narrow publication allowance is for original Java under `dev/horizonlab`, and the built JAR checks its emitted class namespace.
+4 -5
View File
@@ -42,13 +42,12 @@ collectors these can include cycle duration and overlapping phases; it is not a
direct stop-the-world pause measurement. The viewer calls it collection time.
Use [JFR pause events](profiling.md) when investigating GC-induced stalls.
The [three-pair heap experiment](heap-budget.md) compares 3 GiB and 1.5 GiB
maximum heaps with the same core stack. It records variable RSS savings, nearly
unchanged average FPS and increased GC accounting; playable defaults remain
A three-pair heap experiment compared 3 GiB and 1.5 GiB
maximum heaps with the same core stack. It recorded variable RSS savings, nearly
unchanged average FPS and increased GC accounting; playable defaults stayed
unchanged.
The native-read test exercises the real library, overlapping recordings,
background execution, idle cancellation and unavailable-reader behavior on
the build platform. This validates measurement availability, not an FPS or
RAM optimization result. Real game integration and platform results are
recorded in the release validation document after they finish.
RAM optimization result.
-106
View File
@@ -1,106 +0,0 @@
# Reusing discarded terrain quads
A private live allocation recording sampled Distant Horizons 3.3.4's
`LodQuadBuilder.getOrCreateBufferQuad` on terrain render-loader threads. The
builder obtains a temporary quad before trying to merge it with the last face.
After a successful adjacent-face premerge, the incoming temporary quad is
unused. The original method returns without retaining it in its existing pool.
The isolated `quad-reuse` profile keeps at most one such discarded quad per
builder. It supplies that object only at the two fresh-constructor sites in
`getOrCreateBufferQuad`; selection from the publisher's existing pool stays
upstream. A successful merge requires a false error flag on both quads, matching
the constructor's initial error state. The existing setter replaces every other
stored field before use. This preserves the existing pool's ordering and error
flags instead of adding a discarded object to that pool. No geometry list,
merge predicate, sorting, lighting, texture/material identifier, upload budget,
world data or simulation rule is replaced.
The hook requires exactly DH 3.3.4 and validates both constructor and both
premerge call sites. It is off in every other profile, including combined
profiles. Disable `enabled` in `config/horizon-quad-reuse.properties` and restart
to compare with the same profile. Reports capture the actual applied flag.
The applied Fabric fixture generates 55,296 input faces spanning all directions,
opaque/translucent colors, light levels and material/tile identifiers. It checks
all stored quad fields before and after upstream merging, including sort keys
and error flags. A deliberately poisoned existing-pool object checks that its
state stays upstream. Identity checks reject aliases in live geometry lists.
Four concurrent builder workers compare geometry and reject shared live quads.
These are generated geometry checks, not rendered-pixel comparison on each GPU.
Private exploratory loops measured about 145 MB caller allocation upstream and
2 MB with reuse over 3,072,000 faces. The same reduction appeared in the initial
production-hook fixture. CPU observations varied: one private pair favored the
hook, another favored upstream, and the first production pair favored the hook.
Fixed-order sequential observations do not establish a statistical speedup.
The fixture favors merging and does not represent every terrain workload.
The hook adds a reference and can retain one discarded object per builder.
Lower allocation is not a measurement of lower retained heap, process RSS,
unified memory, game FPS or Apple Silicon performance. Live startup, capture,
save/reload and independent platform checks are required before recommending it.
Raw [production-hook results](../benchmarks/quad-reuse-2026-10-04/local-applied-hooks.json)
and [private exploratory observations](../benchmarks/quad-reuse-2026-10-04/exploratory-observations.json)
retain protocol and provenance limits. The current fixture fingerprints include
opaque/translucent list boundaries, face indices and list sizes. A baseline
without DH reaches the menu and exits with code zero.
The independent [Linux CI fixture](../benchmarks/quad-reuse-2026-10-04/linux-applied-hooks.json)
matched the geometry and four-worker fingerprints. Its allocation totals matched
the local reduction, but caller CPU was about 40.4 ms upstream versus 44.1 ms
with reuse, so this check does not support a universal CPU improvement. Windows,
macOS ARM and Linux checks pass, and the Linux production JAR matches the local
binary byte-for-byte.
The [live software-rendered observations](../benchmarks/quad-reuse-2026-10-04/live-observations.json)
record 220 control versus 224 candidate frames over roughly 120 seconds, with
zero exclusions and matching captured settings and first saved cameras. Peak
sampled RSS differed by less than one percent. Preceding render-loader allocation
counter rates were higher with reuse in this pair. Task completion/geometry
volumes and cache/JIT effects are not quantitatively controlled, so neither the
small frame/RSS differences nor these counters establish a useful game
performance or memory improvement. The candidate saved, reloaded, saved again
and exited with code zero; the control saved, closed its terrain databases and
exited with code zero.
Actual JSON/CSV comparison and mobile layout checks pass. The hook remains an
optional experiment, disabled in combined profiles.
The [initial shallow-size observations](../benchmarks/quad-reuse-2026-10-04/shallow-size-observations.json)
measure the actual hooked classes with `Instrumentation.getObjectSize` inside
four separate Fabric demo clients on local Linux x64 Java 25. They use four
adjacent north-facing quads, which premerge to one geometry quad in every mode.
| Compact headers | Hook | Builder bytes | Quad bytes | Pending scratch bytes |
| --- | --- | ---: | ---: | ---: |
| Off | Off | 48 | 56 | 0 |
| Off | On | 48 | 56 | 56 |
| On | Off | 40 | 48 | 0 |
| On | On | 48 | 48 | 48 |
Without compact headers, the extra reference fits the measured builder's existing
alignment padding. With compact headers, the builder itself grows by eight bytes.
In this workload both modes add 56 shallow bytes per builder including the pending
scratch. This excludes existing pools, referenced lists and every other game
object. JVM alignment and compressed-reference settings or other architectures
can change layouts. It is not a deep heap, residency, RSS, unified RAM or Mac
measurement, and does not demonstrate a net game memory benefit.
The reusable probe keeps both test binaries outside playable packs and records
JVM runtime, alignment and compressed-reference settings. With Java 25 and the
usual build prerequisites, reproduce it using:
```sh
python3 tools/build_mod.py
python3 tools/test_quad_sizes.py
```
Linux uses Xvfb by default; `--native-display` uses an existing screen. The output
is gitignored `dist/quad-size-integration.json`; game logs and the test agent/fixture
remain in `.local/`. No account or world is needed for this demo-mode probe.
The [reusable local applied probe](../benchmarks/quad-reuse-2026-10-04/local-shallow-size-applied.json)
reproduces the initial sizes and records eight-byte object alignment and compressed
references. All four processes exit successfully. A separate Java source-launcher
check verifies agent loading from a quoted path containing spaces.
+2 -2
View File
@@ -4,7 +4,7 @@ Horizon started as a decompilation and optimization lab. This page describes the
## 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 rebuild the inspection workspace from your own copy of the game (see [Bring your own copy](../README.md#bring-your-own-copy)); nothing of the game is downloaded.
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 rebuild the inspection workspace from your own copy of the game (see [Build from source](../README.md#build-from-source)); nothing of the game is downloaded.
```sh
git clone https://github.com/ludovic111/horizon.git
@@ -78,7 +78,7 @@ 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](optimization-plan.md) describes profiling, improved Java baselines, native integration and behavior checks before expanding scope.
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.
Public branding and new mod downloads use **Horizon**. The existing Fabric mod
ID and `dev.horizonlab` namespace remain stable for installed instances and
-34
View File
@@ -1,34 +0,0 @@
# Integrated-server graphics context
Client rendering competes with the integrated server for CPU time. Version 0.21
copies GPU, backend and driver into the tick report when F8 or `/horizon bench`
starts a single-player recording. The values come from the client/render thread
and are copied into immutable metadata; server ticks never access GPU APIs.
Reports identify `server_runtime_kind` as integrated, dedicated or unknown.
`client_graphics_capture_status` is `captured_at_recording_start` only when all
three graphics fields are supplied for an integrated server. The server-only
command does not inspect client graphics. Old callers retain their compatible
four-argument recording entrypoint and report unknown runtime context.
The offline viewer and CLI flag differing runtime kinds, graphics backends and
drivers. Legacy reports remain readable, with unknown-context warnings. A
matched start snapshot does not establish unchanged graphics throughout the
recording, equivalent client quality, world work or scheduling. Rendering changes
still require paired frame reports and an explicitly controlled experiment.
This metadata change makes no FPS, TPS or RAM improvement claim.
```sh
python3 tools/build_mod.py
python3 tools/test_server_graphics.py --native-display --backend opengl
# Separate fresh private instance; Linux software renderer research only:
python3 tools/test_server_graphics.py --native-display --backend vulkan
```
The private fixture starts a normal 10-second frame/tick recording through the
client recorder, checks both reports against the actual device, saves the demo
world and exits. It does not change simulation rate or gameplay rules. Windows
compiles the fixture; Linux and hosted macOS check the actual game-selected backend. An explicit
`--backend` experiment still rejects fallback; the default metadata check does
not require a particular renderer. Full logs,
worlds and fixture JARs remain private and outside playable downloads.
-67
View File
@@ -1,67 +0,0 @@
# Optional shader world probe
The cinematic pack starts with shaders disabled. A world rendering successfully
with that profile does not establish that its optional shader pack works.
The separate manual **macOS shader research** workflow explicitly enables the
pinned Complementary Reimagined pack in private cinematic instances and probes
OpenGL and Vulkan independently.
The probe uses Iris's runtime API through the recorder's existing read-only
inspection. Success requires available shader status, an active shader pack,
the exact pinned pack identity, focused world gameplay without an overlay,
nonuniform framebuffer readback, saved world data and a clean exit. A disabled,
unavailable or different pack fails even if ordinary world pixels look valid.
Arbitrary runtime pack names and paths are not exported.
```sh
python3 tools/build_mod.py
python3 tools/test_client_graphics.py --native-display --profile cinematic --backend opengl --world --shaders
python3 tools/test_client_graphics.py --native-display --profile cinematic --backend vulkan --world --shaders
```
Shader instances use separate runtime folders and a 6 GiB maximum heap. Other
graphics probes keep their 3 GiB budget. The fixture reports the actual maximum
heap and observed shader status. Playable packs and their shader defaults are
unchanged. Full logs, PNGs, world files, assets and shader ZIPs stay private.
The research workflow runs both cases and retains selected failed outcomes.
It fails if either case fails and remains separate from required OpenGL CI.
This is a short initialization/readback/save check, not a shader FPS, physical
M2 GPU, exhaustive visual quality or distant-terrain completion benchmark.
## Observed results
The [selected shader observations](../benchmarks/shader-worlds-2026-10-04/live-observations.json)
retain successful and failed cases. On Linux llvmpipe, the OpenGL cinematic
world probe passes with the pinned shader pack actually active, matching identity,
nonuniform readback and clean save/exit. Its private image was visually inspected.
This is a software-renderer startup result, not a shader FPS or physical Mac claim.
The Linux Vulkan cinematic case fails before readback, with a Distant Horizons
lightmap handler in selected stack locations. A fresh private isolation instance
with the DH JAR removed reaches ordinary Vulkan world readback but Iris reports
shaders inactive. The strict activation assertion rejects it; ordinary world
pixels alone would have produced a misleading shader success.
Hosted Mac run 37198566508 times out in both OpenGL and Vulkan cinematic cases,
with no completed probe report. The previous timeout wrapper retained only
`completed: false`; initialization/readback/waiting state is unknown. This does
not establish shader support or incompatibility on physical Apple GPUs.
Later timeout diagnostics preserve selected initialization/readback stages,
actual child exit status after bounded cleanup, and the last private waiting-state
snapshot. Waiting state contains only six booleans and a tick count; arbitrary
screen names, messages and paths are excluded. An unsuccessful research run
remains unsuccessful. Playable shader/backend defaults remain unchanged.
Diagnostic repeat [37199837867](https://github.com/ludovic111/Horizon/actions/runs/37199837867)
uses the richer diagnostics. Both cases again hit the 240-second timeout and
require bounded termination. OpenGL initializes its device and loads a world
with a player, no overlay, an active window and no pause; a screen remains
present and the fixture never reaches readback readiness. Selected stack
locations include Iris terrain rendering, but do not identify the screen or
establish a root cause. Vulkan initializes its device and client entrypoint,
but provides no waiting-state snapshot or readback request before timeout.
Neither case yields an actual shader-activation assertion or saved/clean-exit
success. The research workflow correctly fails; required non-shader OpenGL
checks pass independently on Windows, Linux and macOS.
-37
View File
@@ -1,37 +0,0 @@
# Capture terrain quality as well as speed
Version 0.12 adds effective DH configuration to frame reports: LOD radius,
horizontal/vertical quality, maximum horizontal resolution, renderer mode,
rendering enable setting, transparency, shading, ambient occlusion, LOD-only
mode, camera quality falloff, worker count and runtime ratio. It reads the
actual public API values, including active overrides. Pack names and TOML files
alone do not establish which settings reached the running game.
Reports also capture configured field of view and optional Iris enabled state.
An enabled Iris pack's name is included when available. Iris is queried through
its public API; missing or incompatible APIs are marked unavailable, rather than
assumed disabled. Other shader frameworks are not observed by this adapter.
Visual settings are read at recording start and finish. The final snapshot is
stored in `visual_settings_end`; `visual_settings_changed` lists detected changes.
The viewer and strict CLI flag these runs as mismatched. An adaptive runtime-ratio
change is expected and is displayed separately; it is not treated as a visual
quality change. Snapshots cannot detect a change that was restored before the
end. Keep settings fixed and avoid menus during the actual comparison.
The comparison tools check captured DH/Iris quality fields, and report different
worker budgets or controller settings as experiment variables. Older reports
without these fields show unknown quality/shader equivalence. A vanilla baseline
without DH versus a distant-terrain profile intentionally has different visual
work: inspect that difference rather than presenting it as equal draw settings.
These are configuration observations, not counts of visible geometry, completed
terrain or GPU timings. A 128-chunk configured radius does not prove every chunk
has generated or drawn. Warm-up, world/route equivalence, occlusion, terrain cache,
weather, actual visual detail and external shader frameworks still need testing.
Base FOV does not capture every transient sprint/zoom camera effect.
The adapter reads at capture boundaries on the owning client thread. It performs
no per-frame polling and changes no settings. Tests exercise the pinned upstream
API contracts, effective overrides, absent/unavailable APIs and comparison
mismatches. Game smoke checks validate the actual captured values separately.
-80
View File
@@ -1,80 +0,0 @@
# Equivalent position arithmetic in the LOD data lookup
A live allocation/CPU investigation sampled Distant Horizons 3.3.4's relative
position conversion on render-loader threads. This is a numeric step within
`FullDataSourceV2.getDataPointAtBlockPos`; the first candidate is a Java hook at
that call, with no native transition, cache, new worker or retained per-source
field. The original library handles containment, column selection and datapoint
search. No writes, world generation, block mechanics or rendering budgets change.
Select `terrain-position` for an isolated comparison with `m2-balanced`.
Graphics, worker and other controller settings match. This hook is off in all
other profiles, including combined profiles, and requires exactly DH 3.3.4.
Disable `enabled` in `config/horizon-terrain-position.properties` and restart.
Reports and both comparison tools capture its actual applied flag.
The conversion retains the original numeric output, including its unusual
negative-coordinate bias. A plain coordinate shift failed a differential test
and was discarded; correcting that apparent rounding is outside this hook's
scope. The replacement computes truncation toward zero for a positive power-of-two
divisor using shifts and sign masks. For a negative coordinate, the publisher's
bias is applied before truncation, and the final relative coordinate retains its
original remainder result. The zero-shift bias is retained too.
The decoded coordinate is a signed 28-bit value. For shift values 0 through 30,
all adjusted negative values and their truncation correction fit a signed 32-bit
integer. Positive coordinates use the same zero correction. Java's masked shift
count is retained for larger valid level differences. A sign-bit divisor (masked
shift 31) and invalid output levels delegate to the original method, preserving
its result or exception class/message. The hook is numeric and has no mutable
shared state.
The actual publisher differential suite checks 1,525,313 cases, including
1,124,986 invalid-level exceptions. Cases include powers-of-two boundaries,
positive/negative coordinates, integer extrema passed through the original
encoding, all output bytes across selected input levels, reserved position bits
and a million randomized position/level combinations. The observed negative
counterexample is retained explicitly.
Private probes rejected a numeric cache, which provided no useful benefit and
was slower with varying inputs. A version with coordinate-sign branches also
became slower with a broad input set and was discarded. A subsequent version
using sign masks matched the randomized results and reduced caller CPU time in
the local synthetic loop across its tested input-set sizes. These are mechanism
observations, not whole-game FPS, retained RAM, GPU cost or Mac performance.
The applied Fabric fixture matched 491,520 public lookups across 30 generated
data owners and six detail levels, with 327,049 populated-column results. Output
and source-data fingerprints matched, and both modes verified whether the
redirect was actually installed.
Timing remains sensitive to warm-up. The first two-million-lookup observation
was about 120 ms caller CPU upstream versus 225 ms with the hook. Subsequent
warmed six-million-lookup sets observed 250/261 ms and, after longer warm-up
and compilation waits, 331/260 ms. The later set favors the hook, but these
are fixed-order single forks with three sequential observations, not independent
repetitions or a statistical speed estimate. Compiler-diagnostic observations
are kept separate. Live captures and independent platform checks are required
before recommending it.
Raw [current applied-hook results](../benchmarks/terrain-position-2026-10-04/local-applied-hooks.json)
and [earlier exploratory observations](../benchmarks/terrain-position-2026-10-04/exploratory-observations.json)
retain warm-up, diagnostics and source-provenance limits.
The independent [Linux CI lookup fixture](../benchmarks/terrain-position-2026-10-04/linux-applied-hooks.json)
matched the same output/data fingerprints. Its three caller CPU observations
were about 59.7/52.7/52.5 ms upstream and 56.1/47.9/47.7 ms with the hook,
for two million checks each. These sequential observations favor the hook in
that workload, but do not establish whole-game or cross-hardware performance.
Windows, macOS ARM and Linux compilation and publisher differential checks pass.
The independent Linux production JAR matches the local binary byte-for-byte.
The [live software-rendered observations](../benchmarks/terrain-position-2026-10-04/live-observations.json)
record 221 control frames versus 219 candidate frames in roughly 120 seconds,
with zero excluded frames and matching captured visual settings. Separate copies
of the same private world used matched stationary cameras and approximately
five-minute warm-up. No FPS gain is established. The candidate saved, reloaded,
saved again and quit; the control saved and quit. Both foreground launchers
returned zero and left no crash report or game process. The actual JSON/CSV pair
also passed offline viewer checks, including flag differences and mobile layout.
The hook remains optional and disabled in combined profiles. These checks do
not measure Apple Silicon graphics, unified memory or performance.
-50
View File
@@ -1,50 +0,0 @@
# Release a blocked terrain read during shutdown
A local world test saved its chunks and closed the DH databases, then hit the
client shutdown watchdog. Its remaining non-daemon DH world-generation worker
was waiting in `IOWorker.isOldChunkAround` on a cached blending-metadata future.
The unchanged control exited normally, so the failure is intermittent; this
observation does not attribute it to the culling optimization.
The scoped redirect uses an interruptible wait only for pending blending reads
on threads named `DH-World Gen Thread[...]`. The pinned DH 3.3.4 pool uses this
name and interrupts remaining workers during shutdown. Ordinary Minecraft
callers keep `CompletableFuture.join` behavior. Completed results use the original
join path. Failed reads retain join's exception identity and wrapping behavior.
An interrupted DH waiter restores its interrupt flag and throws a completion
exception whose interrupted cause is recognized by DH's existing shutdown
handling. It never cancels or completes the cached future, which belongs to other
callers too. Chunk stores, saves, storage closure and world difficulty are untouched.
This changes cancellation of an interrupted background task, rather than terrain
results from an uninterrupted task.
Profiles with distant terrain request the fix; baseline and low-memory profiles
without DH do not. It is restricted to Minecraft 26.3 and DH 3.3.4. To opt out,
set `enabled=false` in `config/horizon-terrain-read-wait.properties` and restart.
Frame reports record `interruptible_terrain_read`, and comparison tools disclose
changes in that state.
`python tools/test_terrain_read.py` checks the actual transformed game IOWorker
inside Fabric, with controlled cached metadata futures. It forces an interrupted
pending DH read, verifies the shared future remains available to a later caller,
and checks that ordinary callers remain blocked until completion. It also
checks an interrupt already set before a pending read, successful completed
reads with an interrupt already set, cancelled
futures, exceptional completion identity, and recognition by DH's shutdown
exception utility. The private fixture does not enter release packs. This is a
correctness check, not an FPS, throughput or Mac shutdown benchmark.
The [sanitized Linux CI result](../benchmarks/terrain-read-2026-10-04/linux-applied-hooks.json)
includes source/workflow provenance and the original mod checksum. The CI JAR
matches the local candidate byte-for-byte. Windows and hosted Apple Silicon
macOS 26 compile the fixture and pass the portable build/metrics checks; applied
read interruption is exercised on Linux, not a live macOS game.
The exact candidate also completed a 120-second local world recording, saved,
and reloaded that world in the same client. After the first save, thread inspection
found no remaining DH generation workers and no background workers blocked on a
future. After reload, two generation workers existed and neither was waiting in
blending metadata; no background metadata-scan wait was present at that snapshot.
This is one software-rendered lifecycle observation, not proof that every
shutdown race, world or platform is covered.
-44
View File
@@ -1,44 +0,0 @@
# Reuse distant-terrain tick membership storage
DH 3.3.4's tick holder clears and repopulates a private `HashSet` of nodes every
tick. Clearing retains the table but discards its entry objects, so handling the
same terrain again creates new entries. A local allocation profile identified
these entries in the `DH-ClientTickTimer` tree traversal.
The optional hook uses the game's existing fastutil `ObjectOpenHashSet` for only
this private membership test. Its reusable array stores the references directly.
The original branches, published action sets/lists, action iteration order,
tree traversal, node identity, detail levels and render settings stay upstream.
The replacement clears at the original tick boundary, releasing member references
while retaining table capacity. It adds no node cache, global pool or renderer.
Use `tick-dedup` for an isolated comparison with `m2-balanced`; their visual,
simulation, worker and other controller settings match. From version 0.13 the
combined `foreground-first` and `foreground-vulkan` experiments include this
hook too. Other profiles explicitly disable it. Set `enabled=false` in
`config/horizon-tick-dedup.properties` and restart to disable it. The hook only
applies to pinned DH 3.3.4. Reports record actual `tick_membership_dedup` state;
the comparison tools disclose differing state as an experiment variable.
`python tools/test_tick_dedup.py` runs the publisher's actual holder inside two
isolated Fabric clients. Both check 6,000 deterministic randomized transitions,
including duplicate/null membership, first-action precedence, forced disable,
clear boundaries and published collection order. A warmed allocation loop uses
512 preallocated nodes, duplicate visits and the reused delete-children action
list for 20,000 ticks. It measures only the calling thread's allocated bytes,
CPU and elapsed time, keeping membership allocation separate from node creation.
The fixture JAR and full game logs remain private; the sanitized JSON result
contains no game code, credentials or launch arguments.
The local Linux check allocated 245,760,208 bytes upstream versus 208 with the
hook. Its single CPU observation was 565 ms versus 381 ms. This establishes the
entry-allocation mechanism in that isolated loop; it does not establish a
statistical speedup, game FPS gain, whole-game RAM reduction, completed terrain
or performance on an M2 GPU. Actual game profiles and repeated Mac comparisons
are required for those conclusions. Table capacity remains proportional to the
largest tick membership, as the upstream hash table already did.
The [sanitized Linux CI result](../benchmarks/tick-membership-2026-10-04/linux-applied-hooks.json)
includes its source commit and workflow provenance. It independently reproduced
the same allocation counts and transition checks. Its CPU timings are another
single warmed observation, not a statistical estimate or Mac result.
-93
View File
@@ -1,93 +0,0 @@
# Precise distant-terrain worker pacing
The optional `worker-pacing` and `adaptive-pacing` profiles change the timer used by
Distant Horizons background workers. Both keep balanced's 12 full-detail chunks,
128-chunk distant radius, two workers, normal simulation and graphics configuration.
Balanced's timer remains unchanged. `adaptive-pacing` also enables the frame/heap
pressure controller; `worker-pacing` uses the fixed user-configured duty cycle.
The pinned DH 3.3.4 executor measures task duration, calculates a proportional wait,
then converts nanoseconds to whole milliseconds before sleeping. A task that requests
less than a millisecond of waiting reaches `sleep(0)`. Its effect depends on JVM,
operating system and scheduling contention. The configured duty cycle therefore may
not describe what short tasks actually receive. The timestamp is also boxed into a
`Long` per task. Profiling established the boxing site, but did not establish it as
the game's primary allocation cost.
The original Horizon hook accumulates fractional waits until at least 250 microseconds
are due, then sleeps with nanosecond precision. Measured timer overshoot earns credit
against later waits, capped at 50 milliseconds to bound recovery after a long stall.
Primitive state is allocated once per worker rather than boxing
each timestamp. Changes to the duty-cycle setting discard stale debt; an idle worker
also discards it. Interruption during sleep releases debt with the upstream hook's
interruption behavior. The runnable, queues, result, exception and execution order
are unchanged. The inspected direct superclass hooks are no-ops.
This changes background completion time: a worker that previously exceeded a 5%
budget can now take longer to finish the same jobs while leaving more CPU time for
the foreground. On some systems the old zero-duration sleep instead overthrottles
work. Neither less background CPU nor a correct timer guarantees higher game FPS.
OS timer precision and scheduler overhead can still shift actual CPU duty cycle.
The hook is disabled by default and applies only to the exact inspected DH 3.3.4
version. Enable with `config/horizon-worker-pacing.properties`:
```properties
enabled=true
```
Restart the game after changing this property. `/horizon adaptive off` changes the
adaptive controller, not this timer. Frame reports capture `precise_worker_pacing`.
Reproduce the isolated executor benchmark:
```sh
python3 tools/build_mod.py --benchmark-workers
```
`dist/worker-pacing-benchmark.txt` records three runs per mode and requested budget,
using 50,000 jobs with a nominal ten-microsecond workload after warm-up. It compares
the actual upstream executor with a subclass using the original pacing routine.
Worker CPU time and allocation counters exclude allocations on the producer thread.
This is a timer/allocation microbenchmark, not Minecraft FPS, player TPS or a full
terrain generation benchmark. Hosted Linux, macOS and Windows runs produce their
own artifacts; contention and warm-up can change the results.
The first 2,000-job Windows runs exposed CPU-counter quantization: a single worker
could appear above one core or at zero CPU during a very short interval. Those
figures are not reliable CPU-duty results. The longer workload provides a larger
measurement window; counters and scheduling still have finite precision.
Deterministic tests simulate multiple job sizes, timer overshoot, configuration
changes, idle time and invalid ratios. Native game validation must also check terrain
progress, frame/tick capture and clean shutdown. On the M2 Pro, compare balanced,
worker-pacing and adaptive-pacing with identical cold and warm worlds. Record distant
terrain completion times alongside foreground performance and CPU use.
## Hosted executor measurements
[Raw platform results](../benchmarks/worker-pacing-2026-10-03/) came from
[CI run 37147381649](https://github.com/ludovic111/Horizon/actions/runs/37147381649),
using the 50,000-job workload and the revised overshoot credit. Median worker CPU
seconds per elapsed second across three runs were:
| Platform | Requested budget | Upstream | Precise |
| --- | ---: | ---: | ---: |
| macOS ARM64 | 0.50 | 0.620 | 0.514 |
| macOS ARM64 | 0.05 | 0.466 | 0.063 |
| Linux x64 | 0.50 | 1.000 | 0.524 |
| Linux x64 | 0.05 | 0.976 | 0.076 |
| Windows x64 | 0.50 | 0.996 | 0.556 |
| Windows x64 | 0.05 | 0.867 | 0.078 |
These are isolated worker ratios, not game CPU reductions or FPS gains. The macOS
runner exposes three logical CPUs and is not the user's M2 Pro. At the 0.05 setting,
processing the fixed workload takes roughly 10–11 seconds with the precise timer;
many upstream runs finish in under two seconds because the requested delay is not
being applied consistently. Lower background activity costs completion time.
Actual CPU ratios exceed the nominal task-time ratio because executor/sleep overhead
also consumes CPU. OS preemption and counter precision affect each run.
Median worker allocation per job at the 0.50 setting fell from approximately 28–30
bytes to 0.3–1.3 bytes on these runners. This supports removal of the per-job boxed
timestamp; it does not establish a significant whole-game heap reduction.