Merge branch 'main' into fix/home-leak-tests
This commit is contained in:
+3
-3
@@ -13,7 +13,7 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor
|
||||
- [Graphics](graphics.md): the Simple and Advanced graphics settings, the graphics benchmark and what it measured.
|
||||
- [Benchmark](benchmark.md): Horizon against vanilla 26.3 and vanilla with performance mods, on the same machine, world, path and settings: what is measured, how it is kept fair, how to reproduce it.
|
||||
- [Extras](extras.md): optional zoom, minimap, FPS and keystroke overlays and auto-reconnect, all off by default.
|
||||
- [Mods](mods.md): Horizon's own mod system (Rust, sandboxed WebAssembly), how to make and install mods, and [what carries over from Java mods](research/java-mod-compat.md).
|
||||
- [Mods](mods.md): Horizon's own mod system (Rust, sandboxed WebAssembly), how to make and install mods.
|
||||
- [Modpacks](modpacks.md): porting whole packs (ATM10 and smaller): import, inventory, carry-over, an agent per mod with a harness against the Java original, coverage, and how "10x" is measured.
|
||||
- [Launcher](../launcher/README.md): installs, updates and starts builds; its CLI and MCP server; releasing it.
|
||||
- [Versioning](versioning.md): how releases are numbered from 0.2 (`v0.2.x`, `launcher@0.2.x`), how installs from before 0.2 get there, and the steps for the day 0.2 ships.
|
||||
@@ -45,6 +45,6 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor
|
||||
- [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 comparison profiling
|
||||
|
||||
- [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). The Fabric server starter is retired: [host a server](hosting.md) with horizon-server.
|
||||
- [JFR analysis for Java comparisons](profiling.md).
|
||||
|
||||
@@ -0,0 +1,141 @@
|
||||
<!-- Generated from crates/horizon-mod-sdk/wit/horizon.wit and the manifest's capabilities by crates/horizon-mods/tests/api_reference.rs; a test fails when this file is out of date. Update it with: HORIZON_WRITE_DOCS=1 cargo test -p horizon-mods --features pack --test api_reference -->
|
||||
# Mod API reference
|
||||
|
||||
The contract between Horizon and its mods: the WIT package `horizon:mods@0.1.0`, every interface, type, function and hook in it, and the capabilities a manifest may list. The guide is [mods.md](../mods.md); stability and versions: [stability.md](stability.md). Manifest `api` lines this game serves: `0.1`, `0.2`.
|
||||
|
||||
## Capabilities
|
||||
|
||||
| In `capabilities` | Grants | The player reads "May …" |
|
||||
| --- | --- | --- |
|
||||
| `game-read` | [`game`](#game) | see your position, health and the time |
|
||||
| `chat` | [`chat`](#chat) | show you chat messages |
|
||||
| `hud` | [`hud`](#hud) | draw text on your screen |
|
||||
| `storage` | [`storage`](#storage) | save its own settings to disk |
|
||||
| `registries` | data files (`assets/`, `data/`), no interface | add blocks and items to your worlds |
|
||||
|
||||
## World `horizon-mod`
|
||||
|
||||
- Imports (what the game offers): `log`, `game`, `chat`, `hud`, `storage`
|
||||
- Exports (what the mod provides): `events`
|
||||
|
||||
## `log`
|
||||
|
||||
Access: always granted.
|
||||
|
||||
The mod's log, in the game's log under the mod's id. Always granted.
|
||||
|
||||
### enum `level`
|
||||
|
||||
| Case | |
|
||||
| --- | --- |
|
||||
| `debug` | |
|
||||
| `info` | |
|
||||
| `warn` | |
|
||||
| `error` | |
|
||||
|
||||
| Function | Signature | What it does |
|
||||
| --- | --- | --- |
|
||||
| `write` | `func(level: level, message: string)` | One line in the game's log as `[mod <id>] message`, at that level. |
|
||||
|
||||
## `game`
|
||||
|
||||
Access: capability `game-read`.
|
||||
|
||||
Capability `game-read`: the local player and the world clock.
|
||||
|
||||
### record `player`
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `x` | `f64` | Feet position, in blocks. |
|
||||
| `y` | `f64` | |
|
||||
| `z` | `f64` | |
|
||||
| `yaw` | `f32` | Degrees, as F3 shows them. |
|
||||
| `pitch` | `f32` | Degrees: -90 looks straight up, 90 straight down. |
|
||||
| `health` | `f32` | Hit points as vanilla counts them: 20 is full health without effects. |
|
||||
| `food` | `u32` | 0 to 20, as the hunger bar. |
|
||||
| `dimension` | `string` | `minecraft:overworld`, `minecraft:the_nether`, ... |
|
||||
|
||||
### record `clock`
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `game-time` | `u64` | Ticks since the world was created. |
|
||||
| `day-time` | `u64` | 24000 ticks per day; 0 is 6:00 on the first day. |
|
||||
|
||||
| Function | Signature | What it does |
|
||||
| --- | --- | --- |
|
||||
| `get-player` | `func() -> option<player>` | None on the title screen. |
|
||||
| `get-clock` | `func() -> option<clock>` | None on the title screen. |
|
||||
|
||||
## `chat`
|
||||
|
||||
Access: capability `chat`.
|
||||
|
||||
Capability `chat`: messages only the local player sees.
|
||||
|
||||
| Function | Signature | What it does |
|
||||
| --- | --- | --- |
|
||||
| `show` | `func(text: string)` | Shown in chat after the mod's name, like a system message. |
|
||||
|
||||
## `hud`
|
||||
|
||||
Access: capability `hud`.
|
||||
|
||||
Capability `hud`: one panel of text lines per mod, drawn by the game every frame until the mod changes or clears it (no call per frame).
|
||||
|
||||
### enum `corner`
|
||||
|
||||
| Case | |
|
||||
| --- | --- |
|
||||
| `top-left` | |
|
||||
| `top-right` | |
|
||||
| `bottom-left` | |
|
||||
| `bottom-right` | |
|
||||
|
||||
### record `line`
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `text` | `string` | Plain text, up to 256 characters. |
|
||||
| `color` | `u32` | 0xRRGGBB. |
|
||||
|
||||
| Function | Signature | What it does |
|
||||
| --- | --- | --- |
|
||||
| `set-panel` | `func(corner: corner, lines: list<line>)` | Replaces the mod's panel: up to 16 lines in that corner of the screen. |
|
||||
| `clear` | `func()` | Removes the mod's panel. |
|
||||
|
||||
## `storage`
|
||||
|
||||
Access: capability `storage`.
|
||||
|
||||
Capability `storage`: a per-mod folder of small key/value files, quota'd (docs/mods.md). Keys are `[a-z0-9_.-]{1,64}`, one path segment.
|
||||
|
||||
| Function | Signature | What it does |
|
||||
| --- | --- | --- |
|
||||
| `get` | `func(key: string) -> option<list<u8>>` | None if `key` has never been `set`, or the key is not well-formed. |
|
||||
| `set` | `func(key: string, value: list<u8>) -> result<_, string>` | Errs on a malformed key or over quota (bytes for the whole mod). |
|
||||
| `delete` | `func(key: string)` | No error if `key` was already absent. |
|
||||
|
||||
## `events`
|
||||
|
||||
Access: exported by the mod: the game calls it.
|
||||
|
||||
What the game calls. Only the hooks `init` asks for are ever called.
|
||||
|
||||
### record `registration`
|
||||
|
||||
| Field | Type | |
|
||||
| --- | --- | --- |
|
||||
| `commands` | `list<string>` | Chat commands, without the slash. A name vanilla already uses is refused (vanilla's command runs). |
|
||||
| `tick` | `bool` | Call `tick` every game tick (20 per second while playing). |
|
||||
| `frame` | `bool` | Call `frame` every rendered frame. Budget: 0.1 ms. |
|
||||
| `chat` | `bool` | Call `chat` for each chat line the player receives. |
|
||||
|
||||
| Function | Signature | What it does |
|
||||
| --- | --- | --- |
|
||||
| `init` | `func() -> result<registration, string>` | Once, after loading. An error keeps the mod off and is shown. |
|
||||
| `tick` | `func(tick: u64)` | Each game tick while in a world, with the game's tick counter. |
|
||||
| `frame` | `func(seconds: f32)` | Each rendered frame, with the seconds since the last one. |
|
||||
| `command` | `func(name: string, args: string) -> result<option<string>, string>` | `/name args`: ok(some(text)) is shown as feedback, err(text) in red. |
|
||||
| `chat` | `func(text: string)` | Each chat line the player receives, as plain text. |
|
||||
@@ -27,7 +27,7 @@ file selects ~103.
|
||||
| 10 | Launcher (124) | `launcher/src/` (`main.rs`, `backend.rs`, `cli.rs`, `mcp.rs`, `servers_page.rs`) | `cd launcher && cargo test`; `python3 tools/launcher_mcp_e2e.py` |
|
||||
| 11 | Mob types and species (117) | `L/mobs.rs`, `L/mobs/species.rs`, `L/mobs/data.rs`, `L/mobs/living.rs`, `L/mobs/drops.rs`, `L/mobs/gear.rs` | mob_attributes, entity_attribute, entity_death_loot, mob_ai |
|
||||
| 12 | Guests' actions on a server (98) | `G/lan_actions.rs` (`fn as_guest`, `fn tick_guests`), `G/lan_{attributes,pvp,chat,crafting,stations,trading,mount_menu,waypoints}.rs` | server_player_combat, server_player_damage, server_player_targets, lan_e2e (all) |
|
||||
| 13 | Modpack porting, mod content (97) | `crates/horizon-port-pack/`, `L/mod_content.rs`, `tools/port_*.py`, `packs/` | `cargo test -p horizon-port-pack`; `python3 tools/mod_port_harness.py` |
|
||||
| 13 | Modpack porting, mod content (97) | `crates/horizon-port-pack/`, `L/mod_content.rs`, `tools/port_*.py` | `cargo test -p horizon-port-pack`; `python3 tools/mod_port_harness.py` |
|
||||
| 14 | Mob AI (96) | `L/mobs/ai.rs`, `goals.rs`, `brain.rs`, `*_brain.rs`, `nav.rs`, `path.rs`, `control.rs` | mob_ai (probe `examples/mob_ai_probe.rs`; known failure on main: drowned_*, #290) |
|
||||
| 15 | Items and item use (96) | `L/items.rs`, `L/item_data.rs`, `G/hand.rs`, `G/consume.rs`, `G/potions.rs`, `L/effects.rs`; game.rs `fn use_hand`, `fn use_item` | use_item_on, item_use, item_use_lifecycle, consumable, consume_effect, status_effect |
|
||||
| 16 | Options and settings screens (93) | `L/options_ui.rs`, `G/options.rs`, `L/settings.rs`, `L/options_file.rs`, `L/graphics_ui.rs`, `L/graphics.rs` | options, toggle_keys |
|
||||
@@ -41,7 +41,7 @@ file selects ~103.
|
||||
| 24 | Container menus and inventory (61) | `L/menu.rs`, `L/container_screen.rs`, `L/containers.rs`, `L/creative.rs`; game.rs `fn menu_ops`, `fn click_inventory` | menu_click, container_screen, creative, lan_e2e containers clicks |
|
||||
| 25 | Workstations (60) | `L/stations.rs`, `G/stations.rs`, `L/enchant.rs`, `L/brewing.rs` | enchanting, screen_layout, lan_e2e brewing loom stonecutter grindstone anvil smithing |
|
||||
| 26 | Crafting and the recipe book (59) | `L/crafting.rs`, `L/recipe_book.rs`, `L/recipe_book_screen.rs`, `G/recipe_book.rs`, `G/machines.rs`, `G/machines/crafter.rs` | recipe, recipe_book, recipe_book_view, place_recipe, ghost_recipe, crafter |
|
||||
| 27 | Vehicles and mounts (54) | `G/boats.rs`, `G/minecarts.rs`, `G/mounts.rs`, `G/mount_menu.rs`, `G/llamas.rs`, `G/passengers.rs` | server_entities, lan_e2e boats minecarts riding mounts |
|
||||
| 27 | Vehicles and mounts (54) | `G/boats.rs`, `G/boat_passengers.rs`, `G/minecarts.rs`, `G/mounts.rs`, `G/mount_menu.rs`, `G/llamas.rs`, `G/passengers.rs` | server_entities, lan_e2e boats minecarts riding mounts |
|
||||
| 28 | Villagers, trading, raids (50) | `L/mobs/villager*.rs`, `L/merchant.rs`, `G/trading.rs`, `G/villagers.rs`, `L/raid.rs`, `G/raids.rs`, `L/gossip.rs` | trading, raid, mob_ai |
|
||||
| 29 | Title, worlds, startup (49) | `L/title.rs` + `L/title/`, `G/startup_menu.rs`, `L/title_edition.rs` | world_options; `cargo test -p horizon-client --lib title` |
|
||||
| 30 | Dedicated server, horizon-server (48) | `G/dedicated.rs`, `G/dedicated/status.rs`, `crates/horizon-server/`, `crates/horizon-server-files/` | dedicated_server, server_files, user_cache, online_mode, server_ops_feedback |
|
||||
|
||||
+1
-1
@@ -21,7 +21,7 @@ One game is started per window size (1280x720 and 1920x1080 by default) and rend
|
||||
- **Warm-up excluded.** Each scene's flight starts only after its chunks are loaded and drawn and 2 seconds have passed; the load itself is reported separately. JIT warm-up of the JVM during the first scene is part of vanilla's real behaviour and is not removed.
|
||||
- **The same statistics code.** Horizon returns its raw frame times (`horizon-ctl fly ... raw`) and the vanilla mod writes its own; `stats()` in the driver computes every figure for both.
|
||||
- **Vanilla as players run it.** Your own 26.3 client jar and libraries (as the official launcher installs them for your OS), the official launcher's default JVM arguments (`-Xmx2G` and its G1 options), Java 25. The game's assets index is not used, so neither game plays sound (Horizon runs with `HORIZON_NO_AUDIO=1`, vanilla with OpenAL's null device); textures, models and shaders come from the client jar as usual.
|
||||
- **Performance mods.** `--game vanilla-mods` adds the Fabric builds for 26.3 of Sodium, Lithium, FerriteCore and ImmediatelyFast, the versions pinned with their hashes in `packs/mods.lock.json` (downloaded from Modrinth, never committed), plus Fabric API if one of them needs it.
|
||||
- **Performance mods.** `--game vanilla-mods` adds the Fabric builds for 26.3 of Sodium, Lithium, FerriteCore and ImmediatelyFast, the versions pinned with their hashes in `tools/benchmark-deps/mods.lock.json` (downloaded from Modrinth, never committed), plus Fabric API if one of them needs it.
|
||||
|
||||
## Known caveats
|
||||
|
||||
|
||||
@@ -1,48 +0,0 @@
|
||||
# Compare Java collectors
|
||||
|
||||
Use the balanced pack first with the launcher's existing JVM policy. Java 25
|
||||
HotSpot supports explicit G1 (`-XX:+UseG1GC`) and ZGC (`-XX:+UseZGC`) selections;
|
||||
the [Java command reference](https://docs.oracle.com/en/java/javase/25/docs/specs/man/java.html)
|
||||
documents both. A collector choice can change CPU, heap headroom, collection
|
||||
behavior and frame pacing. Lower pauses alone do not establish lower RAM or
|
||||
higher FPS. The packs do not automatically select a collector.
|
||||
|
||||
For a Mac comparison, duplicate one instance. In Edit > Settings > Java, enable
|
||||
the Java Arguments override checkbox. Preserve existing non-collector arguments,
|
||||
but use exactly one collector selector in each instance. Choose G1 in one and
|
||||
ZGC in the other. Use the same native Java 25 ARM64, maximum/minimum heap, compact
|
||||
header setting, world copy, resolution, shaders, distances and warmed camera route.
|
||||
Alternate at least three 120-second runs rather than comparing unrelated captures.
|
||||
Remove the explicit selector to restore the launcher's policy, then restart.
|
||||
|
||||
The viewer shows the actual collector names captured by the game. Check them:
|
||||
setting a launcher's text field does not establish which flags reached the VM.
|
||||
Prism's per-instance Java Arguments and Memory settings have separate override
|
||||
checkboxes. A global collector selection may need removal or replacement when
|
||||
creating an explicit per-instance experiment.
|
||||
|
||||
Record FPS, slowest-1% rate, frame spikes, heap and process RSS together. RSS does
|
||||
not represent all shared GPU memory on Apple Silicon. `gc_time_ms` sums collector
|
||||
MXBean counters; concurrent cycles and overlapping phases can contribute, so it
|
||||
is not a measured pause total. Use JFR root pause events for pause analysis.
|
||||
The streaming reader is checked against the JDK's event exporter with both
|
||||
default-GC and ZGC fixtures in CI on Windows, Linux and ARM macOS.
|
||||
|
||||
The developer demo launcher accepts `--gc default`, `--gc g1` or `--gc zgc`.
|
||||
For example:
|
||||
|
||||
```sh
|
||||
python3 tools/runtime.py demo --instance .local/runtime/collector-test --heap 6G --gc zgc --compact-headers
|
||||
python3 tools/test_jfr.py --gc zgc
|
||||
```
|
||||
|
||||
Prepare demo mods/worlds before comparing.
|
||||
Options affect only the launched process; they do not change global Java settings.
|
||||
The collector and compact-header experiments can be tested independently.
|
||||
|
||||
A local 3 GiB, compact-header ZGC client completed a 120-second game recording.
|
||||
That recording also encountered a distant-terrain rejection storm. Its workload
|
||||
and cache history differed from G1 captures, so the larger memory footprint and
|
||||
different frame rate cannot be attributed to the collector alone. The dispatcher
|
||||
experiment addresses the identified retry loop separately. No M2 collector
|
||||
performance winner is established.
|
||||
@@ -0,0 +1,41 @@
|
||||
# How Horizon is built
|
||||
|
||||
Who writes Horizon, how changes are checked, and why it is safe to run. You can check every claim on this page in the repository, and anything not done yet is marked as not done.
|
||||
|
||||
This page is also on the website: [playhorizon.dev/docs/how-horizon-is-built](https://playhorizon.dev/docs/how-horizon-is-built). The longer version, with what is still missing, is [Security](security.md).
|
||||
|
||||
## Who builds it
|
||||
|
||||
Horizon is Ludovic Marie's project: he decides what it does and what ships. **Most of the code is written by AI agents**: Claude sessions that Ludovic runs, and contributors' own AI tools. Some contributors write their code by hand.
|
||||
|
||||
Agents say what they are. A pull request opened by one of Ludovic's agents starts with "Opened by Ludovic's AI agent (Claude), not by Ludovic himself.", its comments start with "🤖 Agent:", and its commits name the agent in a `Co-Authored-By` line.
|
||||
|
||||
## How changes are checked
|
||||
|
||||
Not every line is read by a person. Instead, every change is checked against the real game, automatically:
|
||||
|
||||
- **Harnesses.** A harness is a test that gives the same inputs to Horizon and to the real Minecraft 26.3, then compares the results. There are 326 of them (25 October 2026), from world generation to mobs, redstone and commands. The [status table](https://playhorizon.dev/#parity) shows what they cover. Passing them all does not prove that nothing else differs.
|
||||
- **Checks on every pull request.** `verify` runs on GitHub's machines for every pull request and every change to main: formatting, lints with warnings treated as errors, the tests, and the check that no Minecraft files are committed. Main takes no change without it. `parity` runs the harnesses a change can affect, on a machine that holds a copy of Minecraft. For a pull request from a fork, it runs once a maintainer has read the change.
|
||||
- **Outside contributions are checked again.** Before a contributor's pull request merges, Ludovic's agents compare what it claims with vanilla's own code, review it line by line, rewrite the weak parts, and test it in single player, on a LAN and on a dedicated server where those apply.
|
||||
- **Releases are tested first.** A release is published only after its smoke test passes (the game starts and draws a world) and while no issue is labelled `release-blocker`.
|
||||
|
||||
## Why it's safe to run
|
||||
|
||||
- **Open source.** All of the code is public on [GitHub](https://github.com/ludovic111/horizon), under the MIT licence.
|
||||
- **Built from the public code.** Releases are built by GitHub Actions, the build service of GitHub, from the public source. Linux and Windows are built on GitHub's machines, and macOS on Ludovic's Mac mini, which runs GitHub Actions jobs. Every build log is [public](https://github.com/ludovic111/horizon/actions/workflows/release.yml).
|
||||
- **Signed checksums.** Every release has a `SHA256SUMS` file, a fingerprint of each download, and `SHA256SUMS.sig`, a signature of that list made with Horizon's release key, which only release builds from main can use. The launcher and `horizon-server update` check both before they install anything, and refuse a file that does not match. The very first server install with `install.sh` checks the fingerprint but not the signature.
|
||||
- **Not yet signed by Apple or Microsoft.** The macOS app is not notarized by Apple, because it is not signed with a paid Apple developer account, so macOS asks you to confirm the first time ([Install](https://playhorizon.dev/docs/install#download-the-launcher) shows how). The Windows programs are not code-signed either, so Windows may warn you too.
|
||||
- **Mods run in a sandbox.** Horizon mods are WebAssembly programs with no access to your files, the network or other programs. A mod lists what it needs, you see that list before you turn it on, and it can do nothing else. See [Mods](mods.md).
|
||||
- **Nothing collected unless you say yes.** Data collection is off until you turn it on, with four separate switches. The one exception is an anonymous "I'm playing" ping for the launcher's player count, which holds nothing about you. See [Opt-in data collection](telemetry.md).
|
||||
|
||||
## What it doesn't contain
|
||||
|
||||
- **No Minecraft files.** Horizon contains no Minecraft code, assets or data, and never downloads them. The launcher builds the game files on your computer from your own copy of Minecraft: Java Edition 26.3. A check that runs on every pull request (`tools/check_public_tree.py`) keeps game files and decompiled code out of the repository and its history.
|
||||
- **No code from other mods.** Since 24 October 2026, Horizon's code may only be written from Minecraft 26.3 itself and public documentation, never from another mod, loader or renderer ([the rule](../CONTRIBUTING.md#only-original-code)). That day shader packs were removed ([#1561](https://github.com/ludovic111/horizon/pull/1561)), after a developer of Iris showed that our shader pack code had been written from Iris's source. They are being written again from a description of the pack format only.
|
||||
|
||||
## Check it yourself
|
||||
|
||||
- **Read the code and its checks.** [The source](https://github.com/ludovic111/horizon), [the checks on every pull request](https://github.com/ludovic111/horizon/actions/workflows/ci.yml) and [the release builds](https://github.com/ludovic111/horizon/actions/workflows/release.yml).
|
||||
- **Compare the fingerprints.** Put a release's files and its `SHA256SUMS` in one folder and run `sha256sum -c SHA256SUMS --ignore-missing` (on macOS `shasum -a 256 -c SHA256SUMS --ignore-missing`, on Windows `Get-FileHash <file>` in PowerShell). Each file should say `OK`.
|
||||
- **Check the signature.** Download a whole release into a folder, then from a clone of the repository run `cargo run -p horizon-release-sign -- verify --tag <tag> <folder>`. The public key is in `crates/horizon-release-sign/release-keys.txt`.
|
||||
- **Build it yourself.** The README explains how to [build from source](../README.md#build-from-source).
|
||||
+1
-1
@@ -6,7 +6,7 @@ packs, see how well each one runs before installing it, and install it with its
|
||||
|
||||
## What it offers
|
||||
|
||||
Horizon doesn't run Java code ([research/java-mod-compat.md](research/java-mod-compat.md)). It ports what a Java mod
|
||||
Horizon doesn't run Java code ([mods.md](mods.md)). It ports what a Java mod
|
||||
carries as data (blocks, items, recipes, loot tables, tags, worldgen, textures, names) with `horizon-port-pack`, and
|
||||
says before install which of the mod's features that leaves out. Horizon `.hmod` mods aren't on Modrinth or CurseForge
|
||||
yet (Modrinth has no `horizon` loader).
|
||||
|
||||
+12
-12
@@ -7,9 +7,8 @@ pipeline, not a list of hand ports. It takes a pack as players download it and p
|
||||
Horizon mods. The pipeline is AI agents in dependency order, each port checked against the
|
||||
original mod running in a dev-only Java instance.
|
||||
|
||||
This page is the design. It builds on [mods.md](mods.md) (the mod API, WASM in wasmtime) and
|
||||
[research/java-mod-compat.md](research/java-mod-compat.md) (why Java jars and Mixins cannot
|
||||
run in Horizon, so we port instead). The ATM10 inventory behind the numbers below is
|
||||
This page is the design. It builds on [mods.md](mods.md) (the mod API, WASM in wasmtime, and
|
||||
why Java jars cannot run in Horizon, so we port instead). The ATM10 inventory behind the numbers below is
|
||||
[modpacks/atm10-mods.csv](modpacks/atm10-mods.csv).
|
||||
|
||||
## In one picture
|
||||
@@ -141,12 +140,13 @@ derivative work. These rules are part of the pipeline, not advice to users:
|
||||
has given written permission, recorded in the index entry. The tooling refuses to package
|
||||
anything else. No-derivatives and non-commercial licences (14 in ATM10) are never published.
|
||||
For them, even a local port gets a warning that the licence may not allow it.
|
||||
4. **Mod code never enters this repository.** Mod jars, decompiled sources, Java oracle builds
|
||||
4. **Mod code never enters this repository, and nobody reads it.** Mod jars, Java oracle builds
|
||||
with mod code, and ports of mods we have no permission to publish all live outside the
|
||||
repo: in the user's pipeline work directory, or for our own development in
|
||||
`~/code/horizon-parity/modports/` (dev-only, never pushed). Ports are written from
|
||||
observed behaviour and the harness, with decompiled code as a local reference only. The
|
||||
repository holds the pipeline, the API, metadata (ids, names, versions, licences, counts)
|
||||
`~/code/horizon-parity/modports/` (dev-only, never pushed). A mod's code is never
|
||||
decompiled, read, quoted or paraphrased, by people or agents. Ports are written only from
|
||||
the mod's observed behaviour (the oracle and the harness), its own data files and its
|
||||
public documentation. The repository holds the pipeline, the API, metadata (ids, names, versions, licences, counts)
|
||||
and test fixtures we write ourselves.
|
||||
5. **Contacting authors or publishing any port is Ludovic's call.** Agents ask first.
|
||||
|
||||
@@ -177,7 +177,7 @@ frame, chat and command hooks. Server mods do not run yet. What a content pack n
|
||||
| Entities: types, attributes, AI goals and brains, spawning | — | deep (87) | 0.5 | `entity` interface, AI in the mod with vanilla goals reusable |
|
||||
| Custom renderers and animated models (block-entity, entity, item; GeckoLib's format) | — | deep | 0.5 | data models (Bedrock geometry + animations), plus a budgeted draw-list interface for the rest |
|
||||
| Dimensions: dimension types, levels, chunk generators | — | about 10 (Twilight Forest, Aether, Ad Astra, Undergarden, ...) | 0.5 | JSON part with worldgen; custom generators as mod code |
|
||||
| New hooks into vanilla behaviour (what Mixins do) | — | deep | as asked | each becomes a named hook, added for everyone ([java-mod-compat.md](research/java-mod-compat.md#3-a-porting-guide-outline)) |
|
||||
| New hooks into vanilla behaviour (what Mixins do) | — | deep | as asked | each becomes a named hook, added for everyone |
|
||||
| Client interfaces: `keys`, `target`, `inventory-read`, `ui`, `render`, `world-read` | planned | client tier (38) | 0.2–0.4 | as in [mods.md](mods.md#planned-interfaces) |
|
||||
|
||||
Two rules from mods.md stay: **the sandbox** (no files, sockets or processes; memory cap; fuel
|
||||
@@ -711,16 +711,16 @@ For tiers logic, machines and deep, in dependency order, as many agents at once
|
||||
budget allows:
|
||||
|
||||
- **Input:** the inventory record, the carried-over data, the oracle's exports and traces, the
|
||||
harness, the Horizon mod API docs, the ports of its dependencies, and the mod's decompiled
|
||||
code as a local reference (dev-only, in the work directory).
|
||||
harness, the Horizon mod API docs, the ports of its dependencies, and the mod's public
|
||||
documentation. Never its code: the agent doesn't decompile, read or quote it.
|
||||
- **Output:** a Rust crate in `mods/<id>/port/` built with `cargo horizon-mod build`, and its
|
||||
`.hmod`.
|
||||
- **Loop:** write → build → run the harness → read the differences → fix, until the harness
|
||||
passes or the agent reports what blocks it. Usually that is an API gap, which becomes an
|
||||
issue against the mod API ("needs a scheduled-tick hook"), the way version ports turn
|
||||
differences into work items.
|
||||
- **Rules:** the agent writes the port from observed behaviour and the harness, not by
|
||||
transliterating decompiled Java; ports follow the mod's licence ([Licences](#licences)).
|
||||
- **Rules:** the agent writes the port from observed behaviour, the harness and the mod's
|
||||
own data files only; ports follow the mod's licence ([Licences](#licences)).
|
||||
Players without an AI agent get the carry-over tiers. A port the licence lets us publish can
|
||||
be downloaded instead of regenerated.
|
||||
|
||||
|
||||
+4
-3
@@ -3,8 +3,9 @@
|
||||
Horizon gets its own mod system, written in Rust and run in a sandbox, plus
|
||||
two ways to bring over what Java players use: native Horizon ports of popular
|
||||
mods and the data-driven parts of packs and mods. Fabric and NeoForge jars do
|
||||
**not** run as they are: [research/java-mod-compat.md](research/java-mod-compat.md)
|
||||
explains why and what we do instead.
|
||||
**not** run as they are: their code calls and patches Minecraft's Java classes, and
|
||||
Horizon has none. What carries over is the data and assets inside a jar
|
||||
([modpacks.md](modpacks.md)).
|
||||
|
||||
Mods are **off and absent by default**. A fresh install has no `horizon-mods`
|
||||
folder, loads no runtime and plays exactly like vanilla 26.3.
|
||||
@@ -102,7 +103,7 @@ name (the mod reads it as `args`; API 0.1 has no way to declare argument types).
|
||||
### Planned interfaces
|
||||
|
||||
Each is a new capability, added in a 0.x minor version so older mods keep
|
||||
loading. Ordered by what the first native ports need ([research](research/java-mod-compat.md#port-first)):
|
||||
loading. Ordered by what the first native ports need:
|
||||
|
||||
| Interface | For | Notes |
|
||||
|---|---|---|
|
||||
|
||||
@@ -1,130 +0,0 @@
|
||||
# Java performance mods: which of their techniques apply to Horizon
|
||||
|
||||
A survey of the techniques used by eight Java Edition performance mods. Asked for in #991, from famescare on Discord. For each technique it gives the vanilla cost it targets, whether Horizon already avoids that cost, and whether it is worth measuring here.
|
||||
|
||||
**Rules.** Techniques only, taken from each mod's public description, documentation and changelogs (linked below). No mod code was read or copied. Several of these mods are LGPL-3.0, and Horizon's code stays its own. Anything Horizon adopts is reimplemented against vanilla 26.3's behaviour. It keeps parity, so the harnesses stay unchanged, and it needs before/after numbers like any other perf PR (`docs/benchmark.md`, `docs/profiling.md`).
|
||||
|
||||
**Why many don't apply.** A large share of these techniques work around costs of the JVM, OpenGL or GLFW rather than costs of the game's rules. Examples are object headers and duplicate objects, boxing, lambdas and Streams, garbage collection, JNI upcalls, immediate-mode GL draws and GL error checks. Horizon is Rust on wgpu and winit, so it never pays those costs. The techniques that do carry over remove work the game's rules don't need: sleeping block entities, skipped searches, and cheaper geometry tests.
|
||||
|
||||
Verdicts:
|
||||
- **has**: Horizon already avoids the cost, by its design or with a merged change.
|
||||
- **n/a**: the cost comes from the JVM, OpenGL or GLFW, and Horizon doesn't have it.
|
||||
- **later**: missing, and worth measuring. These are listed in "Worth measuring" below and in the LATER list.
|
||||
- **no**: missing, but it would change vanilla's behaviour or look, or the gain here is too small to pay for itself.
|
||||
|
||||
## Lithium (server and shared game logic)
|
||||
|
||||
Source: [Lithium's mixin configuration](https://github.com/CaffeineMC/lithium/blob/develop/lithium-fabric-mixin-config.md). Lithium keeps vanilla's behaviour, which is the same rule Horizon follows.
|
||||
|
||||
| Technique | Vanilla cost | Horizon | Verdict |
|
||||
| --- | --- | --- | --- |
|
||||
| Hopper caching, inventory change listeners and hopper sleeping | Every hopper looks up its source and target containers and tries a transfer every tick, even when nothing can move | `game/machines.rs` ticks every hopper on each tick. It checks the block's name and cooldown, then runs the transfer attempt. Nothing is cached or put to sleep | **later** |
|
||||
| Block entity sleeping (furnaces, brewing stands, campfires, crafters, shulker boxes, sculk) | Idle block entities still tick | `game/block_entity_ticks.rs` ticks every ticker each tick, as vanilla does | **later** |
|
||||
| Entity collisions: faster block access, chunk caching, the supporting block first | Collision scans read blocks through generic level lookups | Collision scans already run over Horizon's own section arrays (`horizon-world` `block_collision_scan`). A counting cursor that does fewer lookups is open as #659 | **has** (more in #659) |
|
||||
| Specialised cuboid and empty `VoxelShape`s, precomputed shape arrays | Generic voxel shape intersection and merging | `horizon-core::geometry` has its own immutable shapes and box lists (`docs/collision-geometry.md`) | **has** |
|
||||
| POI search and portal search | POI lookups go through vanilla's stream-heavy search | Section-indexed POIs (`poi_sections.rs`), searched in vanilla's order | **has** |
|
||||
| Pathfinding: cached node types per block | Node evaluation reads the same blocks over and over | Not measured. Mob pathfinding costs haven't been profiled against vanilla yet | **later** (profile first) |
|
||||
| Explosions: one access per block on a ray, skip air, skip exposure work | Each ray step reads the block and the fluid again | `game/explosion.rs` follows vanilla's loop. It hasn't been profiled, and TNT chains are the case to measure | **later** (profile first) |
|
||||
| Random ticks: roll the chance early, fast block search | Sections with nothing that ticks randomly are still walked | Sections with nothing random-tickable are skipped (`docs/random-tick-eligibility-benchmark.md`) | **has** |
|
||||
| Tick scheduler: faster collections, packed scheduled ticks | Boxed `ScheduledTick` objects in hash sets | Horizon's own tick heap and index (`horizon-core::ticks`, `docs/scheduled-ticks.md`) | **has** |
|
||||
| Collections and allocation (fastutil maps, cached `values()`, fewer `BlockPos`, no Streams) | JVM allocation, boxing, GC | Rust value types, no GC | **n/a** |
|
||||
| Math inlining, a smaller sine table | JIT inlining limits | Compiled and inlined by rustc. Horizon keeps vanilla's `Mth.sin` table where results depend on it | **n/a** |
|
||||
| Chunk access without debug locks or bounds validation | `PalettedContainer`'s thread-check lock | Horizon doesn't have that lock (`docs/performance/paletted-container-access-results.md`) | **n/a** |
|
||||
| Palette replacement and compaction | Hash palette resizing on the JVM | Horizon's own paletted containers (`horizon-core::paletted`) | **has** |
|
||||
| Game event dispatchers made only for sections with a listener | Every section holds a dispatcher | Not checked. This is small next to the items above | **no** (until a profile shows it) |
|
||||
| Item entity merging grouped by item type (experimental) | Each item entity checks every nearby item to merge with | Not present. It matters only with thousands of dropped items (see #996: fresh worlds drop about twice as many items as vanilla) | **later**, after #996 |
|
||||
| World border cache, redstone wire double reads, fluid flow reads, framed-map scans | Small repeated reads | Each is minor. Fix them where a profile points at them | **no** |
|
||||
|
||||
## FerriteCore (memory)
|
||||
|
||||
Source: [FerriteCore's summary of its changes](https://github.com/malte0811/FerriteCore/blob/main/summary.md).
|
||||
|
||||
| Technique | Vanilla cost | Horizon | Verdict |
|
||||
| --- | --- | --- | --- |
|
||||
| One `FastMap` of neighbour states per block instead of a table per state | About 600 MB of per-state neighbour tables in large packs | Block states are numeric ids with flat tables, with no object per state | **n/a** |
|
||||
| Compact property storage per state | A per-state `ImmutableMap` | Same as above | **n/a** |
|
||||
| Cached multipart predicates, shared multipart models | Hundreds of thousands of model and predicate objects | Models are baked once into a shared library (`docs/shared-model-library-benchmark.md`) | **has** |
|
||||
| Deduplicated baked-quad vertex arrays | Identical `int[]` per quad | Section meshes are built per section from the shared baked models, and no per-quad arrays are kept | **has** |
|
||||
| Deduplicated shape caches | Duplicate cached `VoxelShape`s per state | One table of distinct shapes, indexed per state (`horizon-world` `CachedCollisionRegistry`) | **has** |
|
||||
| String deduplication in model locations | Duplicate `String`s from the constructor's round-trips | No `ModelResourceLocation` objects, so the round-trip doesn't exist | **n/a** |
|
||||
| Partly loaded chunk NBT kept between loading steps | The whole tag is kept | Chunks are decoded into Horizon's own structures | **n/a** |
|
||||
|
||||
Horizon's process memory is tracked against vanilla in `docs/process-memory.md`.
|
||||
|
||||
## ImmediatelyFast (client draw submission)
|
||||
|
||||
Source: [ImmediatelyFast on Modrinth](https://modrinth.com/mod/immediatelyfast). Its gains show only when the CPU is the bottleneck.
|
||||
|
||||
| Technique | Vanilla cost | Horizon | Verdict |
|
||||
| --- | --- | --- | --- |
|
||||
| A batching buffer for immediate-mode draws (entities, block entities, particles, text, GUI) | Many small draw calls and uploads | The HUD is one atlas and one batch of quads (`hud.rs`). Entities are grouped by material (`gfx/entity_batch.rs`). Terrain uses indirect multi-draws (`gfx.rs`, `gfx/flat.rs`) | **has** |
|
||||
| HUD batching, fewer GUI draw calls | One draw per GUI element | Same batch (`hud.rs`) | **has** |
|
||||
| Fast text lookup, a bigger font atlas | Per-character lookups, atlas thrash with large fonts | Glyphs live in maps in `font.rs`, drawn into the same HUD atlas | **has** |
|
||||
| One texture for all map item textures | One texture per visible map | Not measured. It matters only with walls of maps in item frames | **later** (with a map-wall scene) |
|
||||
| Cached closed-chest geometry | Re-tessellating chests each frame | Merged in #728 (Online5277) | **has** |
|
||||
| Buffered sign text instead of redrawing it each frame | Text redrawn every frame | Sign text is recorded as text calls in the batch. Not measured with sign-heavy scenes | **later** (with a sign-heavy scene) |
|
||||
| Fewer framebuffer switches | GL state changes between render types | wgpu render passes are fixed by Horizon's pipeline | **n/a** |
|
||||
| GL error checking off | `glGetError` overhead | No GL. Release builds run without wgpu's backend validation and, outside DirectX 12, without its indirect-draw validation (`gfx.rs` `instance_descriptor`) | **n/a** |
|
||||
|
||||
## Gnetum (HUD rendering)
|
||||
|
||||
Source: [Gnetum on Modrinth](https://modrinth.com/mod/gnetum).
|
||||
|
||||
| Technique | Vanilla cost | Horizon | Verdict |
|
||||
| --- | --- | --- | --- |
|
||||
| Draw the HUD into an offscreen buffer in several passes, one pass per frame, and show the last complete buffer | The HUD is redrawn every frame | Horizon redraws its one HUD batch every frame | **no**. The HUD would then update at a lower rate than vanilla's, which changes what players see. Horizon's HUD is already one batch. |
|
||||
| Adaptive distribution and a separate HUD FPS cap | Same | Same | **no**, for the same reason |
|
||||
|
||||
## ScalableLux (lighting, from Starlight)
|
||||
|
||||
Source: [ScalableLux on Modrinth](https://modrinth.com/mod/scalablelux).
|
||||
|
||||
| Technique | Vanilla cost | Horizon | Verdict |
|
||||
| --- | --- | --- | --- |
|
||||
| Starlight's light engine: per-section light arrays and direct propagation queues | Vanilla's light engine is a bottleneck in fast chunk generation | Horizon has its own engine with vanilla's rules (`light.rs`). New chunks are lit on the streaming worker pool, and edits are relit incrementally (`relight_block`). See `docs/performance/lighting-worker-results.md` | **has** |
|
||||
| Parallel light updates | One light thread | Chunk lighting already runs on several workers during streaming | **has**. Measure the light share of fresh-chunk generation before doing more. |
|
||||
|
||||
## Structure Layout Optimizer (jigsaw structures)
|
||||
|
||||
Source: [Structure Layout Optimizer on Modrinth](https://modrinth.com/mod/structure-layout-optimizer).
|
||||
|
||||
| Technique | Vanilla cost | Horizon | Verdict |
|
||||
| --- | --- | --- | --- |
|
||||
| An octree of piece boxes instead of a `VoxelShape` for free space | Voxel shape boolean ops slow down as pieces add up | Free space is a container box minus a list of placed boxes (`worldgen/structure/jigsaw.rs` `Free`). That avoids the voxel shapes, but the scan is linear per test | **has**. An octree pays only for structures with hundreds of pieces. |
|
||||
| Skip jigsaw blocks that face the structure boundary or another piece | Every parent jigsaw is matched against every child | Not present | **later** (time trial chambers and ancient cities first) |
|
||||
| Skip pool elements already found not to fit at this spot | Weighted pools repeat an element once per weight point, and it is re-tested each time | Not present. Only the variant that keeps the result identical applies (no deduplication of the list, which changes layouts) | **later** |
|
||||
| Cull positions outside the chunk before processors run | Whole templates are processed and then mostly discarded | Not checked | **later** (same measurement) |
|
||||
| Palette-based template storage | Templates keep every block and NBT object | Templates are Horizon's own structures. Memory isn't measured | **no** (until memory shows it) |
|
||||
|
||||
## AsyncParticles (particles)
|
||||
|
||||
Source: [AsyncParticles on Modrinth](https://modrinth.com/mod/asyncparticles).
|
||||
|
||||
| Technique | Vanilla cost | Horizon | Verdict |
|
||||
| --- | --- | --- | --- |
|
||||
| Particle culling | Off-screen particles are built anyway | Vanilla already skips quad particles whose position is outside the frustum (`QuadParticleGroup.extractRenderState`, `Frustum.pointInFrustum`). Horizon builds every particle's quad (`particles.rs` `render`). This is a parity gap as well as a cost | **later** (vanilla's frustum point test) |
|
||||
| Vertex transformation on the GPU | Every particle's quad is built on the CPU and uploaded every frame | Same in Horizon (`particles.rs` `render`). Instancing would upload one record per particle | **later** (measure with 10k+ particles) |
|
||||
| Particle ticks on another thread | Particle ticks on the client thread | Horizon ticks particles on the game thread | **no**. Vanilla's particle ticks read the level, and racing them against block changes risks parity. Revisit only if a profile shows particle ticks are big. |
|
||||
| Asynchronous light cache for particles | A light lookup per particle per frame | `particles.rs` looks light up per particle | **later**, with the item above |
|
||||
| Texture animation one frame late | Animated textures tick on the client tick | Not adopted | **no**, because it changes timing |
|
||||
|
||||
## Ixeris (input and the render thread)
|
||||
|
||||
Source: [Ixeris on Modrinth](https://modrinth.com/project/p8RJPJIC).
|
||||
|
||||
| Technique | Vanilla cost | Horizon | Verdict |
|
||||
| --- | --- | --- | --- |
|
||||
| Event polling on the main thread, rendering on its own thread | GLFW event polling and JNI upcalls take time from rendering | winit, without JNI. Input and rendering share the event loop (`game.rs`, `ApplicationHandler`) | **n/a** for the JNI part |
|
||||
| Buffered raw input (`GetRawInputBuffer`) | One `GetRawInputData` call per event. An 8000 Hz mouse costs a lot on Windows | winit reads `WM_INPUT` one message at a time | **later**. Measure on Windows with a high-polling-rate mouse before changing it. |
|
||||
| Cached GLFW state | Round trips to the main thread | No GLFW | **n/a** |
|
||||
| A frame limiter that sleeps, then spins | Imprecise sleeps | Horizon has its own limiter | **no** (no reported problem) |
|
||||
|
||||
## Worth measuring
|
||||
|
||||
Each of these needs a profile or a benchmark first. They are ordered by the expected gain. They are in the LATER list in `~/code/horizon-parity/FEATURES.md`, not filed as issues:
|
||||
|
||||
1. Hopper and block-entity sleeping, with vanilla-identical results (Lithium). Benchmark: a hopper and furnace array.
|
||||
2. Particles: vanilla's frustum point test (a parity fix too), then GPU-built quads (AsyncParticles). Benchmark: 1,000+ campfires.
|
||||
3. Jigsaw placement: skip blocked connectors and already-failed elements without changing the layout (Structure Layout Optimizer). Benchmark: trial chambers and ancient cities in fresh worlds, `docs/generation-scan-benchmark.md`.
|
||||
4. Windows raw input in batches for high-polling-rate mice (Ixeris). Benchmark: an 8000 Hz mouse on Windows.
|
||||
5. Profile before choosing a technique: mob pathfinding, TNT explosions, item merging after #996, map walls and sign-heavy scenes.
|
||||
@@ -1,53 +0,0 @@
|
||||
# Measuring resident process memory
|
||||
|
||||
Horizon 0.6.0 records process RSS alongside JVM heap and nonheap pools. RSS
|
||||
counts resident pages belonging to the Minecraft process, including native
|
||||
allocations and mapped pages. It helps detect cases where reducing heap use
|
||||
merely moves memory elsewhere. It is not unique physical-memory ownership or
|
||||
a complete accounting of GPU allocations, shared pages, compressed memory,
|
||||
swap, or Apple Silicon unified memory. Do not add heap to RSS: heap pages can
|
||||
already be included in it.
|
||||
|
||||
Minecraft 26.3 already ships OSHI 6.9.0 and JNA on both client and server. The
|
||||
original mod uses those dependencies without embedding them. Native reader
|
||||
initialization and refresh happen on a low-priority daemon thread, never on
|
||||
the render or server-tick thread. One reader serves overlapping frame and
|
||||
tick recordings. Reads run about once per second only while recordings are
|
||||
active; the scheduler stops polling when the last recording finishes. Ordinary
|
||||
gameplay without a benchmark performs no resident-memory reads.
|
||||
|
||||
Reports include these optional schema-1 fields:
|
||||
|
||||
| Field | Meaning |
|
||||
| --- | --- |
|
||||
| `process_rss_peak_sampled_bytes` | Largest successful resident-memory sample during this recording |
|
||||
| `process_rss_last_sampled_bytes` | Last successful sample, which can precede recording completion |
|
||||
| `process_rss_samples` | Number of successful samples delivered to this recording |
|
||||
| `process_rss_sample_interval_ms` | Requested 1,000 ms interval; reads can take longer |
|
||||
| `process_rss_last_sample_age_ms` | Time from the last successful sample to report completion |
|
||||
|
||||
Unsupported or failed reads leave these fields absent if no sample succeeded;
|
||||
zero is not used as a substitute. Frames and ticks continue recording. A read
|
||||
that completes after a recording finishes is ignored. Sampled peaks can miss
|
||||
brief spikes, and the initial read can be delayed by native-library startup.
|
||||
|
||||
The offline viewer compares RSS separately from heap/nonheap and warns about
|
||||
stale resident samples. Keep recording duration, workload and warm-up matched
|
||||
when comparing peaks. Process CPU counters cover the whole process over the
|
||||
recording wall time, including native work and the integrated server; they do
|
||||
not identify which thread or mod caused CPU use.
|
||||
|
||||
`gc_time_ms` sums collector MXBean collection-time counters. With concurrent
|
||||
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.
|
||||
|
||||
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.
|
||||
+4
-12
@@ -1,7 +1,7 @@
|
||||
# Find the next bottleneck
|
||||
|
||||
Frame and tick recordings describe player-visible timings. A private Java Flight
|
||||
Recorder capture helps identify the code doing work or allocating objects. Use
|
||||
For Java comparison runs, a private Java Flight Recorder capture helps identify
|
||||
the code doing work or allocating objects. Use
|
||||
native Java 25, with `jcmd` and `java` from a JDK. Keep normal benchmark runs separate
|
||||
from profiling runs because sampling adds overhead.
|
||||
|
||||
@@ -53,8 +53,7 @@ allocated bytes or proving that one object type owns most of the allocation.
|
||||
GC pause totals/maximum use top-level `jdk.GCPhasePause`, excluding nested phases
|
||||
and concurrent collection-cycle duration. `gc_cycles` is a separate count.
|
||||
`heap_used_peak_at_gc_bytes` considers recorded GC heap summaries and can miss
|
||||
peaks between collections. It is separate from the game's once-per-second heap
|
||||
and process-RSS measurements.
|
||||
peaks between collections. It is separate from externally sampled process RSS.
|
||||
|
||||
The reader ignores unselected event types and never extracts properties or
|
||||
arguments. `event_span_seconds` is the span of all observed event timestamps,
|
||||
@@ -70,12 +69,5 @@ python3 tools/test_jfr.py
|
||||
This creates a real JDK recording of bounded allocations and GC, then compares
|
||||
the reader's counter differences, observation counts, GC counts and heap summaries
|
||||
against `jfr print --json`. It also verifies escaped thread names and that sampled
|
||||
weights do not appear as numeric allocation totals. CI runs it on Windows, Linux
|
||||
and Apple Silicon macOS. The reader was independently checked against the older
|
||||
weights do not appear as numeric allocation totals. The manual `jfr-analysis` CI job runs both collector fixtures on the Linux game runner. The reader was independently checked against the older
|
||||
real-game profile's JDK JSON export for 85 threads.
|
||||
|
||||
The post-queue software-rendered profile confirms remaining allocations on the
|
||||
integrated-server and chunk-meshing threads. It is not a matched comparison with
|
||||
the older capture: world/cache state, heap and object-header flags differ. It
|
||||
cannot establish M2 frame gains. Mac captures are needed before choosing a larger
|
||||
renderer or native-kernel replacement.
|
||||
|
||||
@@ -312,6 +312,15 @@ and by hand; pushes to `launcher` and `launcher-*` branches only build.
|
||||
- Published with `--latest=false`: the repository's latest release stays a game release. Notes list the pull
|
||||
requests under New and Fixed; Kira posts launcher releases without pinging.
|
||||
|
||||
Making a launcher release GitHub's latest instead would break servers: every `horizon-server` already installed,
|
||||
`install.sh` and `install.ps1` ask for `releases/latest` and expect the game's archives there, and a server that
|
||||
can't update can't fetch the fix either. So the game release stays the latest, and it sends people to the launcher
|
||||
(#1647): its notes open with a "Want to play? Download the Horizon launcher" block (`PLAYERS` in
|
||||
`tools/release_train.py`: raw HTML, which GitHub shows and launchers' notes skip; the site's Releases page leaves
|
||||
it out too), and its archives carry labels ("Game files the
|
||||
launcher installs: Linux (…)") that GitHub shows in place of the file names. Everything that downloads matches
|
||||
the asset's name, which is unchanged.
|
||||
|
||||
Starting by hand, pausing and rolling back work as for the game (`gh workflow run launcher …`,
|
||||
`RELEASES_PAUSED`, `gh release edit launcher@X.Y.Z --draft`). Launchers older than the withdrawn release then
|
||||
see the previous one as the newest; launchers that already updated keep running.
|
||||
|
||||
@@ -75,11 +75,8 @@ separate implementation. [Geometry and collision scope](collision-geometry.md).
|
||||
|
||||
```sh
|
||||
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.
|
||||
|
||||
Public branding and new mod downloads use **Horizon**. The existing Fabric mod
|
||||
ID and `dev.horizonlab` namespace remain stable for installed instances and
|
||||
measurement compatibility. The installer backs up both old `horizon-lab-*.jar`
|
||||
|
||||
@@ -1,183 +0,0 @@
|
||||
# Java mods and Horizon: what can carry over
|
||||
|
||||
Players ask "will my mods work?". Short answer: **Fabric and NeoForge jars
|
||||
will not run in Horizon as they are**, and no bridge we could build would
|
||||
change that for more than a handful of mods. What carries over is the
|
||||
*content* (data packs, resource packs, the data and assets inside mod jars)
|
||||
and the *ideas* (native Horizon ports of the mods people use most, written
|
||||
with [Horizon's own mod system](../mods.md)). This page is the reasoning.
|
||||
|
||||
## How Java mods work
|
||||
|
||||
### Fabric
|
||||
|
||||
- **Fabric Loader** finds jars in `mods/`, reads `fabric.mod.json`
|
||||
(entrypoints, dependencies, mixin configs, access wideners), and starts the
|
||||
game through a class loader that can rewrite classes as they load.
|
||||
- **Mixin** (SpongePowered) is how nearly every mod changes the game: a mixin
|
||||
class names a Minecraft class (`net.minecraft.client.gui.hud.InGameHud`) and
|
||||
injects code at points inside its methods (`@Inject(method = "render", at =
|
||||
@At("TAIL"))`, `@Redirect`, `@ModifyVariable`, `@Overwrite`...). The bytecode
|
||||
of the vanilla class is rewritten at load time. Access wideners make private
|
||||
fields and methods public for the same purpose.
|
||||
- **Fabric API** is a set of modules that give mods events and registries
|
||||
instead of raw mixins: `fabric-lifecycle-events` (`ClientTickEvents`,
|
||||
`ServerTickEvents`), `fabric-rendering` (`HudRenderCallback`,
|
||||
`WorldRenderEvents`), `fabric-command-api`, `fabric-key-binding-api`,
|
||||
`fabric-networking-api` (custom payloads), `fabric-registry-sync`,
|
||||
`fabric-resource-loader`, `fabric-screen-api`, `fabric-item-group`,
|
||||
`fabric-events-interaction` and about forty more. **Fabric API itself is
|
||||
implemented with mixins** into the same vanilla classes.
|
||||
- Mods mix the two freely: a mod using Fabric API events still calls
|
||||
`MinecraftClient.getInstance().player.getBlockPos()`,
|
||||
`world.getBlockState(pos)`, `DrawContext.drawText(...)`: direct calls into
|
||||
vanilla's classes, by their mapped names.
|
||||
|
||||
### NeoForge (and Forge)
|
||||
|
||||
- An event bus (`NeoForge.EVENT_BUS`, mod buses) with hundreds of events,
|
||||
`DeferredRegister` for registries, data attachments and capabilities,
|
||||
networking payloads, config specs. NeoForge patches vanilla's source
|
||||
directly (binary patches) to fire its events.
|
||||
- Mods also use mixins and access transformers, and call vanilla classes
|
||||
directly, as on Fabric.
|
||||
|
||||
### Data and assets in a jar
|
||||
|
||||
Besides code, a mod jar carries the same folders as packs:
|
||||
`assets/<namespace>/` (models, blockstates, textures, sounds, language files,
|
||||
shaders) and `data/<namespace>/` (recipes, loot tables, tags, advancements,
|
||||
predicates, functions, worldgen: biomes, features, structures). These are
|
||||
**vanilla formats**, read by vanilla's own code.
|
||||
|
||||
## Why a Java bridge cannot run them
|
||||
|
||||
Horizon is a reimplementation in Rust: there are no `net.minecraft` classes
|
||||
at runtime, no `InGameHud`, no `ClientPlayerEntity`, no bytecode to rewrite.
|
||||
|
||||
1. **Mixins have nothing to bind to.** A mixin is a patch against a specific
|
||||
method's bytecode. Without vanilla's classes there is no method, no
|
||||
injection point and no local variable to modify. This is not a missing
|
||||
feature we could add: it is the mechanism itself.
|
||||
2. **Fabric API is mixins too.** A shim Fabric API would have to be
|
||||
re-implemented from scratch as Java classes calling into Horizon. That part
|
||||
alone is possible for the event modules.
|
||||
3. **Mods call vanilla directly.** Even "pure Fabric API" mods use vanilla's
|
||||
classes for everything else: the player, the world, the block states, the
|
||||
renderer, the text drawing. Running them means providing Java classes with
|
||||
vanilla's names and behaviour, backed by Horizon's state: in effect a
|
||||
second Minecraft, in Java, on top of Horizon. Thousands of classes, in the
|
||||
mapped names of every mapping set (Yarn, Mojang, intermediary), version by
|
||||
version.
|
||||
4. **The JVM itself** would ship with every install (a trimmed JRE is still
|
||||
40-60 MB, the full one 150+ MB), start in a second or more, hold a few
|
||||
hundred MB of heap before any mod loads, and bring garbage-collector pauses
|
||||
back into the frame: the costs Horizon exists to remove. JNI calls cost
|
||||
tens to hundreds of nanoseconds each and every one crosses with copies.
|
||||
5. **No sandbox.** Java mods are fully trusted native-speed code with file
|
||||
and network access. Horizon's mods are sandboxed and their permissions are
|
||||
shown; a Java bridge would be the one hole in that.
|
||||
|
||||
**What a bridge could support**, if we ever built one: a stable subset of
|
||||
Fabric API events (client and server tick, HUD render callback, client
|
||||
commands, key bindings, custom payloads), with a tiny "vanilla view" API
|
||||
(player position, held item, chat), for mods written only against that
|
||||
subset. Surveying the most-downloaded Fabric mods, nearly none qualify: the
|
||||
popular ones are popular precisely because they reach into rendering, the
|
||||
world or the UI. The cost (a JVM in the game, a second API surface to keep
|
||||
stable) is far above the benefit. **We do not build it.** If that changes,
|
||||
the bridge would sit on top of the WIT API like any other mod runtime, so the
|
||||
sandbox would still hold.
|
||||
|
||||
## What we do instead
|
||||
|
||||
### 1. Data-driven content (packs and the data in mod jars)
|
||||
|
||||
Horizon already reads vanilla resource packs and data packs (functions,
|
||||
function tags, predicates today). Extending data-pack coverage to recipes,
|
||||
loot tables, tags, advancements and worldgen JSON brings most "content"
|
||||
packs over with no mod code at all, and it is vanilla behaviour, so the parity
|
||||
harnesses check it.
|
||||
|
||||
For **Fabric/NeoForge jars**, the launcher can offer "import the data": read
|
||||
`data/` and `assets/` from the jar and load them as a data pack plus a
|
||||
resource pack. What works: new recipes, loot changes, tags, advancements,
|
||||
functions, worldgen tweaks that only use vanilla blocks, retextures, language
|
||||
files. What does not: anything referring to a block, item or entity the jar
|
||||
registers in Java code (the ids do not exist); the import skips those files and
|
||||
lists them. With Horizon's planned `registries` interface, a native port can
|
||||
register those ids and reuse the jar's JSON models, textures, recipes and loot
|
||||
as they are.
|
||||
|
||||
### 2. Native Horizon ports of popular mods
|
||||
|
||||
Horizon itself covers the performance mods: Sodium, Lithium, FerriteCore,
|
||||
ModernFix, EntityCulling and ImmediatelyFast exist because vanilla Java is
|
||||
slow, and Horizon's renderer and simulation are the replacement (see
|
||||
[benchmark](../benchmark.md)). Zoom (OK Zoomer, Zoomify), FPS and keystroke
|
||||
overlays, a minimap and auto-reconnect are already built in as
|
||||
[extras](../extras.md).
|
||||
|
||||
#### Port first
|
||||
|
||||
Ranked by players reached per unit of API work. Each needs the planned
|
||||
interfaces listed in [mods.md](../mods.md#planned-interfaces).
|
||||
|
||||
| Mod (Java) | What it does | Horizon port | Needs |
|
||||
|---|---|---|---|
|
||||
| **Mod Menu** | list mods, open their settings | built in: Options > Mods (done), settings pages next | `ui` |
|
||||
| **AppleSkin** | food saturation and exhaustion on the HUD and tooltips | SDK mod | `inventory-read`, `ui` |
|
||||
| **Jade / WTHIT** | what the crosshair points at: block, entity, harvest tool, container contents | SDK mod | `target`, `ui` |
|
||||
| **JEI / EMI / REI** | browse items, recipes and uses | SDK mod (or built in: Horizon already has the recipe book's data) | `recipes`, `inventory-read`, `ui` |
|
||||
| **Xaero's Minimap / JourneyMap** | minimap, world map, waypoints | the minimap is an extra; a world map and waypoints as an SDK mod | `world-read`, `render`, `storage` |
|
||||
| **Litematica** | schematic overlay to build from | SDK mod | `world-read`, `render`, `storage`, `ui` |
|
||||
| **Mouse Tweaks / Inventory Profiles Next** | drag and sort inventory | built in or SDK mod | `inventory-read` + a sanctioned click API |
|
||||
| **Continuity / CIT** | connected and custom item textures | built into the renderer (pack formats) | none: resource-pack features |
|
||||
| **Distant Horizons** | low-detail far terrain | a Horizon renderer feature, not a mod | none |
|
||||
| **Shader packs** | shaders | removed for now; a clean-room Horizon renderer feature, later | none |
|
||||
| **Simple Voice Chat** | proximity voice | server + client mod | `server`, `net`, audio (later) |
|
||||
|
||||
### 3. A porting guide (outline)
|
||||
|
||||
To be written as `docs/porting-from-fabric.md` once API 0.2 lands:
|
||||
|
||||
1. **Separate logic from glue.** Most of a mod is plain logic (maths,
|
||||
formatting, data structures): port it to Rust once, unit-test it on the
|
||||
host.
|
||||
2. **Map events.**
|
||||
|
||||
| Fabric | Horizon |
|
||||
|---|---|
|
||||
| `ClientModInitializer.onInitializeClient` | `Mod::init`, returning a `Registration` |
|
||||
| `ClientTickEvents.END_CLIENT_TICK` | `Registration::on_tick`, `Mod::tick` |
|
||||
| `HudRenderCallback` | `hud::set_panel` when the content changes (retained), or `on_frame` |
|
||||
| `ClientCommandRegistrationCallback` | `Registration::command`, `Mod::command` |
|
||||
| `ClientReceiveMessageEvents` | `Registration::on_chat`, `Mod::chat` |
|
||||
| `KeyBindingHelper.registerKeyBinding` | `keys` (planned) |
|
||||
| `Registry.register(Registries.ITEM, ...)` | `registries` (planned) with JSON in `data/` |
|
||||
| `ServerPlayNetworking` payloads | `net` (planned) |
|
||||
| config libraries (Cloth Config, YACL) | `storage` + a `ui` settings page (planned) |
|
||||
|
||||
3. **Replace mixins with hooks.** For each mixin, write down what it observes
|
||||
or changes. If a WIT hook covers it, use the hook. If not, open an issue
|
||||
asking for the hook ("I need X before/after Y"): hooks are added to the API
|
||||
for everyone instead of each mod patching the game.
|
||||
4. **Declare capabilities** in `horizon-mod.toml`, the least the mod needs.
|
||||
5. **Reuse assets**: textures, models, language files and recipes move as
|
||||
they are into the `.hmod`'s `assets/` and `data/` (with `registries`).
|
||||
6. **Test** with `cargo horizon-mod run` and hot reload; add unit tests for the
|
||||
logic; publish with a signed `.hmod`.
|
||||
|
||||
## Sources
|
||||
|
||||
- Fabric documentation (`docs.fabricmc.net`): mod structure, Mixin
|
||||
introduction, Fabric API modules and events.
|
||||
- SpongePowered Mixin wiki: injection points and how class transformation
|
||||
works.
|
||||
- NeoForge documentation (`docs.neoforged.net`): events, registries,
|
||||
networking.
|
||||
- Modrinth's most-downloaded Fabric mods, for the porting list.
|
||||
- Horizon's own Java test mod (`mods/horizon`, built by `tools/build_mod.py`
|
||||
and the CI `portable-mod` job) is a Fabric mod used by the benchmarks and
|
||||
parity oracles: it shows the Mixin pattern (`FrameHookMixin`) this page
|
||||
describes, and stays a developer tool, not a player-facing mod.
|
||||
@@ -33,6 +33,7 @@ harness named checks that loader against vanilla).
|
||||
| Overlays per format | `pack.mcmeta` `overlays` | works | `test_resource_pack_parity` (an overlay for 26.3 applied, an older one not) |
|
||||
| Filters | `pack.mcmeta` `filter` | works | `test_resource_pack_parity` (`packs/pattern.rs` regex subset) |
|
||||
| Folder and zip packs, order, built-in packs | `resourcepacks/` | works | `test_resource_pack_parity`, `test_pack_selection_parity` |
|
||||
| Server resource packs: the prompt, the server list's Server Resource Packs setting, download (250 MiB, SHA-1, `downloads/` keeps 20), applied on top of the player's packs, removed on leaving | the server's `resource_pack_push`/`_pop` | works, no download toasts | `tools/server_pack_e2e.py` (against vanilla's server and Horizon's), unit tests in `server_packs.rs`; `test_server_resource_pack_parity` for Horizon's server |
|
||||
| Other namespaces | `assets/<namespace>/` | works | `test_resource_pack_parity` |
|
||||
| Block states: variants, multipart, weights, rotations, uvlock | `blockstates/` | works | `test_blockstate_model_parity`, `test_model_choice_parity`, `test_blockstate_transform_parity` |
|
||||
| Block models: parents, elements, rotations, faces, cullface, tint, shade, light emission, ambient occlusion | `models/block/` | works | `test_model_resolution_parity`, `test_model_baking_parity`, `test_section_mesh_parity` |
|
||||
@@ -74,7 +75,7 @@ harness named checks that loader against vanilla).
|
||||
| Core shaders | `shaders/core/`, `shaders/include/` | **no** | Horizon draws with WGSL; a pack's GLSL core shaders aren't run |
|
||||
| GPU warn list, regional compliance | `gpu_warnlist.json`, `regional_compliancies.json` | n/a | OpenGL driver warnings and play-time notices for some regions; not used |
|
||||
|
||||
Summary: 44 rows; 31 work, 3 partly, 8 don't (interpolated animation, TrueType fonts, credits and end poem,
|
||||
Summary: 45 rows; 32 work, 3 partly, 8 don't (interpolated animation, TrueType fonts, credits and end poem,
|
||||
villager hats, trims on worn armour, locator bar styles, post effects, core shaders), 2 don't apply. Except the
|
||||
shaders, the missing pieces are missing vanilla features too, and each vanilla parity fix covers the pack case as well.
|
||||
|
||||
@@ -83,6 +84,7 @@ shaders, the missing pieces are missing vanilla features too, and each vanilla p
|
||||
| Gap | Size | Where |
|
||||
| --- | --- | --- |
|
||||
| Animation `interpolate` | small | fix PR (`gfx.rs` `animate_sprites`) |
|
||||
| Server pack download toasts (`download.pack.*`) | small | `game/server_packs.rs` |
|
||||
| GUI scaling `width`/`height`, `stretch_inner`, `tile`, `stretch` | small | next fix PR (`ui.rs`) |
|
||||
| Villager hats | small | [#334](https://github.com/ludovic111/horizon/issues/334) |
|
||||
| `blur`/`clamp` from packs | small | [#335](https://github.com/ludovic111/horizon/issues/335) |
|
||||
|
||||
@@ -54,7 +54,6 @@ across 1,441,816 state pairs, including all pinned suppression-rule families.
|
||||
Animation metadata, frame sequences and tick-state selection now have native
|
||||
differential coverage, including all bundled animated texture metadata. GPU
|
||||
interpolation and game-loop synchronization remain unfinished.
|
||||
The playable Java performance packs remain available during development.
|
||||
|
||||
## Completion criteria and playable builds
|
||||
|
||||
|
||||
+2
-3
@@ -7,8 +7,7 @@ should beat vanilla, Paper and Fabric + Lithium on TPS/MSPT, RAM, CPU, chunk gen
|
||||
Gameplay stays vanilla: there are no Paper-style rule changes unless the owner turns one on.
|
||||
|
||||
This page covers what the server does today (measured), the design of `horizon-server`, and what ships for the
|
||||
first working version (2026-10-23). It replaced the Java/Fabric starter (`docs/server-quickstart.txt`,
|
||||
`tools/server.py`, retired on 2026-10-19). The owner's guide is docs/hosting.md, also at
|
||||
first working version (2026-10-23). The owner's guide is docs/hosting.md, also at
|
||||
https://playhorizon.dev/server.
|
||||
|
||||
## 1. Today
|
||||
@@ -467,7 +466,7 @@ reproducible by anyone, and show the same gameplay on both sides.
|
||||
- Horizon (`horizon-server`);
|
||||
- vanilla 26.3 (the owner's `server.jar`);
|
||||
- Paper (a jar the owner downloads; Paper's defaults are kept, and noted as non-vanilla);
|
||||
- optionally Fabric + Lithium (the old starter's setup, via the pinned `packs/mods.lock.json`).
|
||||
- optionally Fabric + Lithium (via the pinned `tools/benchmark-deps/mods.lock.json`).
|
||||
|
||||
Java servers run on Java 25 with `-Xms` = `-Xmx` (the same heap for all, 4 GB by default), and the heap is
|
||||
reported.
|
||||
|
||||
@@ -1,26 +0,0 @@
|
||||
# Interpreting measured server ticks
|
||||
|
||||
Tick execution time omits scheduler sleep. `stats.meanRate` is the inverse average duration, not actual TPS. `observed_ticks_per_second` already counts accepted plus dropped measured invocations divided by wall-clock recording duration. Frozen tick invocations count; paused wall time stays in the denominator. Neither number measures completed simulation work.
|
||||
|
||||
Version 0.20 observes the server tick manager after each measured invocation on the server thread. Reports record the first and last sampled configured rate, frozen/stepping/sprinting flags and `runs_game_elements`, plus counters for samples with each nonstandard state. This is read-only instrumentation: it does not set a tick rate, freeze worlds or change game rules. Frame reports do not claim to sample server state; use their accompanying integrated-server tick reports.
|
||||
|
||||
The recorder retains which state fields changed between samples. A 20 → 40 → 20 rate change or freeze → unfreeze sequence stays visible even when first and last states match. Both comparison tools mark such recordings as changed workloads, mark differing sampled boundary states, and warn about frozen, stepping, sprinting, suppressed-game-element and nonstandard-rate samples. A consistently configured custom rate can match another report at the same rate, with an explicit warning about that workload. Older, absent or invalid state metadata remains unknown, rather than normal by assumption.
|
||||
|
||||
State and tick duration are accepted under the same recording lock, including buffer overflow. The observation path retains scalar values and allocates no maps or lists per invocation; report serialization creates them once. Non-finite or sub-minimum rates are counted as invalid observations without aborting duration capture. The state object is only allocated for tick recordings.
|
||||
|
||||
Sampling has limits. These are first/last sampled server states, not exact recording boundary states. Changes entirely between samples can be missed. An integrated server paused by the game menu does not call the measured superclass method, so state counters do not enumerate paused time. The manager flag also does not establish that every entity/chunk was simulated, or detect all other reasons a server skips work. A final stepping tick may already have decremented the remaining-step counter to zero while `runs_game_elements` is still true. Compare world copies, entity populations, completed work and real player workloads separately.
|
||||
|
||||
## Validation
|
||||
|
||||
Pure recording checks exercise restored intermediate changes, distinct frozen/suppressed states, late observations, absent/invalid manager state and wall-clock TPS calculation under G1, compact headers and ZGC. Offline comparison checks cover map ordering, changed/custom states and legacy/malformed input. The desktop and 390-pixel viewer checks also load the actual discarded paused capture (12 ticks over approximately 120 seconds), display its roughly 0.1 observed TPS and distinguish it from execution capacity. That capture remains excluded from performance evidence.
|
||||
|
||||
The private `TickStateIntegration` fixture runs only on a disposable demo-world copy. It starts a short recording, samples normal ticking, changes to 40 configured ticks/second and freezes, steps ten ticks, restores 20/unfrozen state, and requests a five-tick sprint. It checks that sampled boundary states match, all five intermediate state changes/counters survive, and accepted state/duration counts agree. The fixture is compiled in platform CI and excluded from the production JAR and downloadable packs. The [final local applied-hook observation](../benchmarks/tick-state-2026-10-04/live-observations.json) records 285 invocations, with 161 frozen, 9 stepping, 5 sprinting, 151 suppressed-game-element and 161 nonstandard-rate samples. All five change fields survive restored boundary states; CSV count/mean and zero invalid/drop observations are verified, and the client exits with code zero. This is functional evidence rather than a performance comparison. Compilation is not a live Mac result.
|
||||
|
||||
Compile the private fixture after building the original mod:
|
||||
|
||||
```sh
|
||||
python3 tools/build_mod.py
|
||||
python3 -c "from tools.build_mod import build_integration_fixture; build_integration_fixture('tick-state', 'dev.horizonlab.metrics.TickStateIntegration')"
|
||||
```
|
||||
|
||||
Install `.local/mod-build/tick-state-fixture.jar` only into a disposable locally prepared balanced demo instance. Open its copied demo world and dismiss the demo screen. The fixture validates the report and closes the client after its sequence. Never add it to a normal play instance or starter package.
|
||||
@@ -1,32 +0,0 @@
|
||||
# Compare the Vulkan renderer on your Mac
|
||||
|
||||
The `vulkan` profile asks Minecraft 26.3 to use its existing Vulkan backend, with
|
||||
its original OpenGL fallback. It uses balanced mods/distances.
|
||||
The game renderer handles the backend; this project has not written a separate
|
||||
Metal renderer. The benchmark records the actual backend and driver.
|
||||
|
||||
The checksum-verified 26.3 manifest includes LWJGL Vulkan 3.4.3 Mac ARM64 natives.
|
||||
Inspecting that official native JAR confirmed `libMoltenVK.dylib`; its paired
|
||||
LWJGL loader first tries MoltenVK on macOS. [MoltenVK](https://github.com/KhronosGroup/MoltenVK)
|
||||
implements Vulkan functionality over Apple's Metal framework. This verifies a
|
||||
bundled route to Metal, rather than proving that a particular Mac backend starts
|
||||
or performs better. No separately installed Vulkan SDK is required for the bundled
|
||||
library; driver/backend compatibility still needs a real Mac test.
|
||||
|
||||
Import `m2-balanced` and `vulkan` as separate Prism instances. Keep Java 25 ARM64,
|
||||
heap, header/collector flags, world copies, resolution, view/simulation distance
|
||||
and camera route equal. Warm terrain and shader/pipeline caches before comparing.
|
||||
Run at least three alternating 120-second F8 recordings. Inspect nearby blocks,
|
||||
distant terrain, transparency, water, lighting and reloads as well as timings.
|
||||
Use the viewer's actual backend field: OpenGL fallback is an OpenGL result.
|
||||
|
||||
After the isolated test works, `foreground-first` and `foreground-vulkan` compare
|
||||
the two backends with the same combined terrain controls. Their 120 FPS adaptive
|
||||
goal controls background duty cycle; rendering remains uncapped in pack options.
|
||||
Do not add shaders to one side of an isolated backend comparison.
|
||||
|
||||
Linux software rendering checks reached the actual Vulkan backend, rendered the
|
||||
demo world and recorded matching CSV/JSON frame/tick samples. An unavailable
|
||||
Vulkan-driver test reached the menu using OpenGL fallback. These tests do not
|
||||
validate MoltenVK, real GPU speeds, all visual details or macOS 27. The user's
|
||||
M2 Pro remains the priority device for those checks.
|
||||
Reference in New Issue
Block a user