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:
@@ -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).
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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
@@ -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;
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user