Merge main and preserve tick chunk membership invalidation
This commit is contained in:
@@ -7,8 +7,11 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor
|
||||
- [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.
|
||||
- [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.
|
||||
- [Launcher](../launcher/README.md): installs, updates and starts builds; its CLI and MCP server; releasing it.
|
||||
- [Opt-in data collection](telemetry.md): the consent, exactly what is sent, how it is stored and sent.
|
||||
- [Benchmark report format](benchmark-report.md): the versioned JSON every benchmark writes (game, launcher, `tools/perf_bench.py`), the local log and, with consent, the upload.
|
||||
- Menus: the title, world list, create world, multiplayer, options and pause screens share the launcher's design tokens and fonts (`crates/horizon-theme`), drawn by `ui_theme` over a live frozen backdrop (`game/backdrop.rs`, blurred and graded by `post.rs`). Options → Interface → Menu style switches to vanilla's screens (Classic, kept in `horizon.txt`; `HORIZON_MENU_STYLE=horizon|classic` overrides it, and scripted runs default to Classic). [Title](media/menu-title.png) ([webm](media/menu-title.webm)), [worlds](media/menu-worlds.png), [options](media/menu-options.png), [pause](media/menu-pause.png).
|
||||
|
||||
## Parity
|
||||
|
||||
@@ -0,0 +1,124 @@
|
||||
# Benchmark report format (version 1)
|
||||
|
||||
Every benchmark Horizon writes uses this one JSON format: `horizon-client --benchmark`, the launcher's own
|
||||
measurements, and `tools/perf_bench.py` (which also writes it for vanilla and vanilla with mods). The same
|
||||
file is the local log a player can attach to an issue and, only with the player's consent, what the
|
||||
telemetry upload sends (minus the local-only fields below). The types, the statistics and the hardware
|
||||
detection are in `crates/horizon-bench`; nothing else builds a report by hand.
|
||||
|
||||
A report holds summaries and histogram counts, never raw frame streams: a 10-minute run is a few
|
||||
kilobytes whatever the frame rate. Measured numbers are rounded to 3 decimals.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
{
|
||||
"format": "horizon-benchmark-report",
|
||||
"version": 1,
|
||||
"kind": "game",
|
||||
"created": "2026-10-15T14:03:27Z",
|
||||
"app": { "name": "horizon-client", "version": "0.21.0", "commit": "e96e1571" },
|
||||
"hardware": {
|
||||
"os": "macos", "os_version": "27.0", "arch": "aarch64",
|
||||
"cpu": "Apple M4 Pro", "cpu_threads": 14, "ram_mb": 65536,
|
||||
"gpu": { "name": "Apple M4 Pro", "vendor": "apple", "driver": "", "backend": "metal", "kind": "integrated" },
|
||||
"display": { "width": 2560, "height": 1440, "scale": 2.0, "refresh_hz": 60 }
|
||||
},
|
||||
"conditions": {
|
||||
"scenario": "flight", "seed": "1234", "render_distance": 16, "simulation_distance": 12,
|
||||
"window": [1280, 720], "vsync": false, "repeats": 3, "warmup_s": 2.0, "power": "ac", "load_avg_1m": 1.2
|
||||
},
|
||||
"metrics": {
|
||||
"startup.title_ms": { "n": 3, "mean": 812.0, "stdev": 21.5, "min": 790.0, "max": 833.0, "ci95": 53.4 },
|
||||
"memory.rss_peak_mb": { "n": 3, "mean": 1210.0, "stdev": 4.0, "min": 1206.0, "max": 1214.0, "ci95": 9.9 }
|
||||
},
|
||||
"frames": [
|
||||
{
|
||||
"phase": "village", "repeat": 0, "frames": 4920, "seconds": 12.0,
|
||||
"avg_fps": 410.0, "low_1pct_fps": 120.3, "low_01pct_fps": 61.0,
|
||||
"p50_ms": 2.31, "p95_ms": 3.8, "p99_ms": 6.9, "p999_ms": 14.2, "max_ms": 21.0,
|
||||
"cpu_p50_ms": 1.4, "gpu_p50_ms": 1.9,
|
||||
"histogram": [0, 0, 3011, 1520, 301, 62, 15, 7, 3, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Fields
|
||||
|
||||
**`format`, `version`.** Always `"horizon-benchmark-report"` and `1`. A reader rejects other formats and
|
||||
newer versions. Adding an optional field keeps the version; renaming, removing or changing the meaning of
|
||||
one (histogram edges included) makes it 2.
|
||||
|
||||
**`kind`.** `"game"` (a game run: Horizon, or vanilla from `tools/perf_bench.py`) or `"launcher"`.
|
||||
|
||||
**`created`.** When the run ended, UTC, `YYYY-MM-DDTHH:MM:SSZ`.
|
||||
|
||||
**`app`.** What was measured: `name` (`horizon-client`, `horizon-launcher`, `minecraft`), `version`,
|
||||
optionally `commit` (Horizon builds) and `mods` (`[{ "name", "version" }]`, vanilla with mods).
|
||||
|
||||
**`hardware`.** `os` (`macos`, `linux`, `windows`), `os_version`, `arch`, `cpu` (brand string),
|
||||
`cpu_threads`, `ram_mb`; `gpu` (`name`, `vendor`, `driver`, `backend`: `metal`, `vulkan`, `dx12`, `gl`;
|
||||
`kind`: `integrated`, `discrete`, `virtual`, `cpu`, `other`) and `display` (the screen the window was on:
|
||||
`width`, `height` in physical pixels, `scale`, `refresh_hz`) when known. Any field can be missing.
|
||||
|
||||
**`conditions`.** What has to match for two reports to be compared, all optional: `scenario`, `seed`,
|
||||
`render_distance`, `simulation_distance`, `window` (`[width, height]` actually rendered), `vsync`,
|
||||
`fps_cap` (absent: unlimited), `offscreen` (rendered without presenting: not a player number), `repeats`,
|
||||
`warmup_s`, `power` (`ac`, `battery`), `load_avg_1m` (before the run; above about 1 the machine was busy),
|
||||
`backend` (when forced). Readers compare reports only with equal `scenario`, distances, `window`, `vsync`,
|
||||
`fps_cap` and `offscreen`.
|
||||
|
||||
**`metrics`.** Scalar measurements, by name; each is a summary over the run's repeats: `n`, `mean`,
|
||||
`stdev` (sample standard deviation, null when `n` is 1), `min`, `max`, `ci95` (half-width of the 95%
|
||||
confidence interval of the mean, Student's t, null when `n` is 1). The unit is the name's suffix: `_ms`,
|
||||
`_s`, `_mb`, `_bytes`, `_fps`, `_pct`, `_mspt`, `_w`, `_c` (degrees Celsius), `_count`. Names in use:
|
||||
|
||||
| Name | What |
|
||||
| --- | --- |
|
||||
| `startup.title_ms` | process start to the first frame of the title screen |
|
||||
| `startup.world_ms` | process start to in-world, every chunk around the spawn loaded and drawn |
|
||||
| `chunks.<phase>.load_ms` | teleport to every chunk in view distance loaded and drawn |
|
||||
| `chunks.<phase>.generated_count`, `chunks.<phase>.meshed_count`, `chunks.<phase>.generated_per_s` | chunks generated and section meshes built while loading, and the rate |
|
||||
| `fps.<phase>.avg_fps`, `fps.<phase>.low_1pct_fps`, `fps.<phase>.low_01pct_fps` | per-phase figures across repeats |
|
||||
| `tick.mspt`, `tick.tps` | integrated server tick time and rate (planned) |
|
||||
| `memory.rss_peak_mb`, `memory.rss_steady_mb` | resident memory: peak over the run, median while flying |
|
||||
| `memory.gpu_mb`, `memory.<phase>.gpu_mb` | video memory the game allocated (or NVIDIA attributes to it), where readable |
|
||||
| `power.package_w`, `power.battery_drain_pct` | power draw, battery used per hour (laptops; planned) |
|
||||
| `thermal.cpu_c`, `thermal.throttled_pct` | temperature, share of the run spent throttled (planned) |
|
||||
| `launcher.start_ms` | launcher process start to its first frame (a session) |
|
||||
| `launcher.cold_start_ms`, `launcher.warm_start_ms` | the same in `horizon-launcher benchmark`: its first start, then the others |
|
||||
| `launcher.rss_mb`, `launcher.cpu_idle_pct` | launcher resident memory (sampled; `max` is the peak), CPU used while idle |
|
||||
| `launcher.release_list_ms` | fetching the release list |
|
||||
| `launcher.install_ms`, `launcher.update_ms` | downloading and unpacking a version: a new one, an update |
|
||||
| `launcher.prepare_ms` | preparing a version's resources |
|
||||
| `launcher.play_to_game_frame_ms` | Play pressed to the game's first frame |
|
||||
| `launcher.binary_bytes`, `game.binary_bytes` | size of the executables |
|
||||
|
||||
New names can be added without a new version; the table lists the ones the tools write.
|
||||
|
||||
**`frames`.** One entry per measured phase and repeat (a scene's flight, the launcher's page switching):
|
||||
`phase`, `repeat`, `frames`, `seconds`, `avg_fps`, `low_1pct_fps` and `low_01pct_fps` (the average frame
|
||||
time of the slowest 1% or 0.1% of frames, as FPS), `p50_ms`, `p95_ms`, `p99_ms`, `p999_ms`, `max_ms`,
|
||||
`cpu_p50_ms` and `gpu_p50_ms` when measured, and `histogram`: frame counts per bucket. The bucket edges
|
||||
are fixed by the version, so histograms from any number of reports add up:
|
||||
|
||||
0, 1, 2, 3, 4.17, 5, 6, 7, 8.33, 10, 12, 14, 16.67, 20, 25, 33.33, 40, 50, 66.67, 100, 150, 250, 500, 1000 ms
|
||||
|
||||
Bucket *i* counts frames from edge *i* (included) to edge *i* + 1; the last bucket is 1000 ms and over
|
||||
(24 buckets). 4.17, 8.33, 16.67 and 33.33 ms are 240, 120, 60 and 30 FPS.
|
||||
|
||||
## Local only
|
||||
|
||||
`label` (a name the person running it chose) and `local` (paths of the logs the run wrote next to the
|
||||
report) stay on the machine: the upload removes them and dates the report to the day only, as every
|
||||
telemetry item is (`Report::for_upload`). The upload is `horizon-telemetry`'s `benchmark` item: this
|
||||
report, as it is, only with the player's consent to benchmark uploads (docs/telemetry.md). Nothing in a report
|
||||
identifies the player, the machine's name or the world: no host name, user name, path or address.
|
||||
|
||||
## Where reports go
|
||||
|
||||
- The game: `benchmarks/<kind>-<created>-<scenario>.json` in the game folder.
|
||||
- The launcher: `benchmarks/` in the launcher's data folder.
|
||||
- `tools/perf_bench.py`: one report per game and render distance, `benchmarks/perf/<label>-rd<N>.json` in the
|
||||
repository checkout.
|
||||
@@ -0,0 +1,62 @@
|
||||
# Benchmark: Horizon vs vanilla 26.3
|
||||
|
||||
`tools/perf_bench.py` measures Horizon, the vanilla 26.3 client and vanilla with performance mods on the same machine, the same world and the same camera path, and computes every number with the same code. This page says what it measures, how it keeps the comparison fair, what it can't control, and how to reproduce it. The results are in [Results](#results).
|
||||
|
||||
## What is measured
|
||||
|
||||
One game is started per render distance (8, 16 and 32 chunks by default), each from a fresh world, so nothing generated by an earlier run is reused. In each game:
|
||||
|
||||
1. **Start to the title screen.** Wall-clock time from starting the process to the first frame of the title screen with no loading overlay.
|
||||
2. **Create the world.** A creative world named `PerfBench`, seed 1234, default world type and difficulty, created the way the game's own Create World does. **Start to in-world** is the time from starting the process until the player has spawned and every chunk around the spawn is loaded and drawn.
|
||||
3. **Four scenes**, the paths of `tools/graphics_bench.py`: straight 192-block flights over a village, a forest, the ocean and a mountain. For each scene the player is teleported to the start (time set to noon), held there flying, and the **chunk load time** is the time from the teleport until every chunk in view distance is loaded and drawn. After 2 seconds of settling, the player flies the path at constant speed in 12 seconds (16 blocks per second, faster than sprint-flying), facing along it at the scene's pitch, placed on the line every frame. Chunks are generated and drawn as they come into range during the flight, as in play.
|
||||
4. **Frame times.** Every frame of every flight is recorded (time between the starts of consecutive frames). From them: average FPS, **1% and 0.1% lows** (the average frame time of the slowest 1% or 0.1% of frames, as FPS: a single long freeze shows), the median, p95, p99 and p99.9 frame times, the slowest frame, and the share of frames in buckets (under 4.17 ms = 240 FPS, 8.33, 16.67, 33.33, 50, 100 ms, and over).
|
||||
5. **Memory.** The process's resident set size (RSS), sampled 4 times a second with `ps` from outside the process: **peak** over the whole run (startup included) and **steady**, the median during the flights. For vanilla this counts the whole JVM (heap, JIT, native buffers, the integrated server), for Horizon the whole process. GPU memory where it can be read: Horizon's own Vulkan allocator total, and what `nvidia-smi` attributes to the process on NVIDIA. On Apple Silicon the GPU shares RAM and no per-process figure is available.
|
||||
|
||||
## How it is kept fair
|
||||
|
||||
- **Same machine, same run conditions.** Games run one at a time; the load average before and after each run and the machine (CPU, RAM, OS) are stored with the results. Runs on a machine doing other work are marked as such and not published.
|
||||
- **Same settings, one file.** Every game gets the same `options.txt`, written by the driver: render distance, simulation distance 12, unlimited frame rate (`maxFps:260`), VSync off, FOV 70, automatic GUI scale, windowed, no pause on lost focus, and `inactivityFpsLimit:minimized` (both games otherwise drop to 30 FPS after a minute without input). Everything else stays at vanilla's defaults: Horizon reads vanilla's `options.txt` keys and its defaults match vanilla's (the options harness checks it), and Horizon's own settings (`horizon-graphics.txt`) are left at their defaults, which render as vanilla does.
|
||||
- **Same resolution.** Both windows are 1280x720 (Horizon's default window; vanilla gets `--width 1280 --height 720`). The size each game actually renders at is stored with the results.
|
||||
- **Same world and path.** Same seed and world type; same paths, yaw and pitch, same flight speed; the same steps in the same order. Vanilla is driven by a small dev-only Fabric mod (`mods/horizon/src/bench`), which only calls the game's own code: it creates the world with `WorldOpenFlows.createFreshLevel` as the Create World screen does, teleports with `/tp`, sets the time with `/time set`, and places the player on the path each frame as Horizon's `horizon-ctl fly` does.
|
||||
- **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.
|
||||
|
||||
## Known caveats
|
||||
|
||||
- **Fabric Loader is present in the vanilla runs**, to load the driver mod. The only patch it applies is the driver's frame hook, so its cost after startup is negligible, but its mod discovery and class transformation add to vanilla's startup time (the modded runs use the same loader).
|
||||
- **Readiness is detected differently.** For Horizon the driver waits until nothing is queued, the chunk counts are unchanged for a second and meshing has gone quiet (fewer than 100 section meshes a second: blocks that change keep being remeshed), and takes the time of the last of these; sections wait for their neighbours' light before they are meshed, so the chunk counts alone stop the clock before the last sections are drawn. For vanilla it waits until the loaded chunk count is unchanged for a second with nothing left to compile, and takes the time of the last change. Both stop the clock within a frame or two of the last section drawn.
|
||||
- **Locked or headless screens.** A window nobody can see is not composited. On a Mac whose session is locked, Horizon draws only with `--offscreen` (it renders into a texture and does not wait for the window), and vanilla keeps rendering into its window without it being shown. Such runs measure rendering without presentation and are marked `offscreen`; numbers for players come from runs with the window on a real screen.
|
||||
- **Different graphics APIs.** Horizon renders with wgpu (Vulkan on Linux and Windows, Metal on macOS); vanilla 26.3 uses OpenGL (or its Vulkan backend when chosen). The backend each game used is stored with the results. This is part of what is being compared.
|
||||
- **World generation is the same algorithm but not the same threads.** Both generate the same terrain (the parity harnesses check it), with their own threading; the work per chunk differs, which is also part of what is being compared.
|
||||
- **Variance.** Flights are short (12 seconds), so each configuration runs `--repeats` times (3 by default), each from a fresh world, and every figure is reported as the mean over the repeats with its standard deviation and 95% confidence interval (Student's t). Differences inside the intervals are noise. Lows are the noisiest figures.
|
||||
|
||||
## Benchmark your own machine
|
||||
|
||||
The game runs the Horizon half of this benchmark by itself, with nothing else installed:
|
||||
|
||||
```sh
|
||||
horizon-client --benchmark standard --render-distance 16
|
||||
```
|
||||
|
||||
It starts at the title screen, creates the world `horizon-benchmark` (seed 1234, creative; the next run replaces it, and it never touches a world it didn't create), flies the four scenes as above, writes a report to `benchmarks/` in the game folder and quits. `--benchmark village` (or `forest`, `ocean`, `mountain`) flies one scene. For the run only, VSync is off, the frame rate unlimited and the game doesn't pause or slow down without focus; your options are not changed. Your other settings (render distance unless given, graphics, window size) are used as they are, and stored in the report, so compare reports with the same conditions.
|
||||
|
||||
The report is the [benchmark report format](benchmark-report.md): startup to the title screen and to in-world, each scene's chunk load time, chunks generated and section meshes built, every flight's frame figures and histogram, resident and GPU memory, the binary's size, and the machine (OS, CPU, RAM, GPU, driver, backend, display), the load average before the run and whether it ran on battery. If you allowed benchmark uploads (the launcher's data collection choices, [docs/telemetry.md](telemetry.md)), the same report, dated to the day and without local fields, is kept for the launcher to send; otherwise it stays on your machine.
|
||||
|
||||
## Reproduce it
|
||||
|
||||
You need Horizon built (`cargo build --release -p horizon-client --bins`) and its resources prepared from your own copy of 26.3 (which also provides `.local/minecraft/26.3`, the vanilla client the driver starts), Java 25 with `javac`, and Python 3.10 or newer.
|
||||
|
||||
```sh
|
||||
python3 tools/perf_bench.py --game horizon --label horizon-mine
|
||||
python3 tools/perf_bench.py --game vanilla --label vanilla-mine
|
||||
python3 tools/perf_bench.py --game vanilla-mods --label mods-mine
|
||||
python3 tools/perf_bench.py --table horizon-mine vanilla-mine mods-mine
|
||||
```
|
||||
|
||||
Options: `--distances 8,16`, `--scenes village,ocean`, `--seconds 20`, `--repeats 5`, `--heap 4G` (vanilla), `--offscreen` (Horizon, for locked or headless sessions). Results go to `benchmarks/perf/<label>-rd<N>.json`, one [benchmark report](benchmark-report.md) per render distance (the same format the game's `--benchmark` and the launcher write), with the load average before each game; each game's log, and the vanilla driver's event log, stay in `.local/perf-bench/`. Keep the machine otherwise idle, plugged in, and the window on a screen.
|
||||
|
||||
## Results
|
||||
|
||||
Saved runs go to `benchmarks/perf/`; `--table` prints them as Markdown.
|
||||
+131
-24
@@ -70,25 +70,128 @@ hold-to-sneak.
|
||||
|
||||
## Menus and inventories
|
||||
|
||||
Vanilla's screens are all mouse-driven, and Horizon draws them 1:1, so a pad
|
||||
drives them through a **virtual cursor** (as Bedrock's classic inventory UI
|
||||
and Java's controller mods do), not focus navigation:
|
||||
Vanilla's screens are all mouse-driven, and Horizon draws them 1:1. A pad
|
||||
drives them in one of two ways, picked in the controller options ("Menu
|
||||
Navigation: Focus / Pointer", `menuNavigation:focus|pointer`):
|
||||
|
||||
- **Focus** (the default): a console-style highlight that the D-pad and the
|
||||
left stick move between buttons, sliders, switches, text fields, list
|
||||
rows, tabs and inventory slots.
|
||||
- **Pointer**: a virtual cursor the left stick moves, as Bedrock's classic
|
||||
inventory UI and Java's controller mods do.
|
||||
|
||||
Focus is the default because it is what a pad player expects from a console
|
||||
game, it needs no aiming (every widget is one D-pad press away, which also
|
||||
suits the Steam Deck's small screen), and it works from the couch. The
|
||||
pointer stays one option away, and a **right stick click swaps the two for
|
||||
the open screen**, for the few places a pointer is better (dragging the
|
||||
advancements map, painting a crafting grid with a held stack).
|
||||
|
||||
Both modes feed the screens the same pointer events a mouse sends: in focus
|
||||
mode the (hidden) pointer sits on the focused widget. So every screen keeps
|
||||
its mouse behaviour (drags, sliders, scrollbars, hover highlights) with no
|
||||
controller code of its own, and both modes reach every screen. Moving the
|
||||
real mouse hands control back at once.
|
||||
|
||||
### Focus navigation
|
||||
|
||||
Every interactive rectangle a screen draws registers itself as a focus
|
||||
target with its kind (`widgets::target_as`): classic buttons, sliders, edit
|
||||
boxes and list rows (worlds, servers, languages), every Horizon-style widget
|
||||
(`ui_theme::Ui::interact`: sidebar items, switches, segments, sliders,
|
||||
fields, buttons), inventory and container slots, creative and recipe-book
|
||||
tabs, and the stations' own buttons (trades, loom patterns, beacon effects,
|
||||
enchantments, stonecutter recipes, the recipe book's recipes, pages and
|
||||
filter). A screen that registers nothing falls back to the pointer.
|
||||
|
||||
The step itself is **vanilla's arrow-key navigation**
|
||||
(`ContainerEventHandler.nextFocusPathInDirection`, 26.3), applied to every
|
||||
target of the screen at once: from a strip one pixel past the focused edge,
|
||||
the nearest target that overlaps it on the other axis wins (ties go to the
|
||||
leftmost or topmost); without one, the target whose facing edge's centre is
|
||||
nearest the focused edge's centre (`nextFocusPathVaguelyInDirection`). That
|
||||
gives vanilla-like jumps in containers too: hotbar to inventory, the grid to
|
||||
the crafting result, armour to the player's grid.
|
||||
|
||||
| Input | Focus mode |
|
||||
|---|---|
|
||||
| D-pad, left stick | move focus (held: repeats after 0.35 s, every 0.09 s) |
|
||||
| A | press the focused widget (held: drag); on a text field, type with the on-screen keyboard |
|
||||
| B, Menu | back (Escape) |
|
||||
| X | right click (inventories: take half, place one) |
|
||||
| Y | quick move (shift-click) in inventories |
|
||||
| View | throw one item from the focused slot (Q) |
|
||||
| Left stick click | throw the focused stack (Ctrl+Q) |
|
||||
| LB / RB | previous / next tab (creative, recipe book, the Horizon options' sections) |
|
||||
| Right stick | scroll |
|
||||
| Right stick click | swap focus and pointer for this screen |
|
||||
|
||||
- **Sliders**: left and right move the value (one pixel per press like
|
||||
vanilla's arrow keys, faster while held); A does nothing on a slider, as a
|
||||
click would jump the handle.
|
||||
- **Lists** follow focus: a step past the last visible row scrolls the list
|
||||
and lands on the next row once it is drawn.
|
||||
- **Inventories**: the carried stack is drawn on the focused slot (vanilla
|
||||
draws it under the pointer). A takes or places, X splits or places one, Y
|
||||
quick-moves, View and the left stick click throw.
|
||||
- **Where focus lands** when a screen opens: the held hotbar slot in an
|
||||
inventory, else the first button.
|
||||
|
||||
How it looks follows the menu style:
|
||||
|
||||
- **Classic screens** look as vanilla's own keyboard focus does: buttons,
|
||||
sliders and slots show their highlighted sprite (`isHoveredOrFocused`,
|
||||
drawn because the hidden pointer is over them), and list rows and text
|
||||
fields get vanilla's white one-pixel outline (`AbstractSelectionList`'s
|
||||
focused selection, `EditBox`'s highlighted border).
|
||||
- **Horizon-style screens** get the design system's focus colour: a two-dp
|
||||
ring in the accent colour around the focused widget, pill-shaped on
|
||||
buttons, tabs and sliders.
|
||||
|
||||
### Pointer
|
||||
|
||||
- Left stick moves the cursor with acceleration; in container screens the
|
||||
cursor is gently pulled toward the nearest slot centre.
|
||||
- D-pad steps one slot (18 GUI pixels in containers) or one widget row in
|
||||
menus and snaps to it.
|
||||
- A = left click (take / place stack, press a button), X = right click
|
||||
(half stack / place one), Y = quick move (shift-click), B = back / close.
|
||||
- LB / RB switch creative tabs and recipe book pages; right stick scrolls
|
||||
(creative grid, lists, chat).
|
||||
- D-pad steps to the nearest target that way (a slot, a button) and snaps to
|
||||
it.
|
||||
- A = left click, X = right click, Y = quick move, B = back; View and the left
|
||||
stick click throw, as in focus mode.
|
||||
- LB / RB switch tabs; right stick scrolls.
|
||||
- Sliders: hold A on the slider and move the stick, or nudge with the D-pad.
|
||||
- Text fields: the Steam Deck's keyboard (Steam + X) types into them like a
|
||||
real keyboard. Other platforms have no on-screen keyboard yet; text input
|
||||
needs a keyboard.
|
||||
|
||||
The cursor is drawn only while the pad is the last-used input; moving the
|
||||
mouse hands control back immediately.
|
||||
The cursor is drawn only while the pad is the last-used input.
|
||||
|
||||
### Text fields
|
||||
|
||||
A on a focused text field (A in pointer mode clicks into it) opens the
|
||||
**on-screen keyboard**: a QWERTY grid and a symbols grid in Horizon's design
|
||||
language, at the bottom of the screen (at the top when the field is in the
|
||||
lower half, as chat is). D-pad or stick to move, A types, X deletes, Y is a
|
||||
space, LT is Shift (twice: caps lock), RB switches to symbols and accents,
|
||||
Menu is Enter, B closes it. It opens by itself when the pad opens chat or a
|
||||
sign. It types into every field the keyboard reaches: chat (local and
|
||||
server), signs, books, the title screens' fields, the options' searches, the
|
||||
creative and recipe-book searches, the anvil, the LAN port.
|
||||
|
||||
On a Steam Deck under Steam (`SteamDeck=1`), A asks Steam for its own
|
||||
keyboard instead (`steam://open/keyboard`), which types like a real keyboard;
|
||||
Steam + X opens it at any time. "On-Screen Keyboard: Auto / Horizon / Steam"
|
||||
(`keyboard:`) picks one.
|
||||
|
||||
### Screens covered
|
||||
|
||||
Both modes reach every screen through the pointer events. Focus mode
|
||||
registers targets on: the title menus (main, world list and its search, create
|
||||
and edit world, delete, multiplayer list and its edit screens), every options
|
||||
page (classic pages and the Horizon-style sections, key and controller binds,
|
||||
language list), pause, death, chat, signs and books (their buttons), the
|
||||
survival and creative inventories, every container and station (chests,
|
||||
furnaces, brewing, crafter, crafting table with its recipe book, anvil,
|
||||
grindstone, smithing, stonecutter, loom, cartography, enchanting, beacon,
|
||||
villager and wandering-trader trades, mount inventories), and the LAN /
|
||||
world options. Where a screen draws something clickable no target names
|
||||
(the advancements map, the statistics lists, the pack screen's rows, the
|
||||
book's page text), the right stick click gives the pointer for that screen.
|
||||
|
||||
## Glyphs
|
||||
|
||||
@@ -161,14 +264,18 @@ no force feedback, so it is silently skipped there.
|
||||
|
||||
## PR plan
|
||||
|
||||
1. **Input layer and gameplay** (this note, gilrs, defaults, movement,
|
||||
camera, actions, hotbar, B/Start to leave screens, `horizon-ctl pad`,
|
||||
`horizon-controller.txt` with the look/deadzone settings).
|
||||
2. **Menus and inventories**: virtual cursor, slot snapping, clicks, quick
|
||||
move, tabs, scrolling, sliders.
|
||||
3. **Glyphs and the Controller options page**: glyph drawing per pad type,
|
||||
the options page, remapping UI.
|
||||
4. **Rumble**.
|
||||
The first round (input layer, menus, glyphs and options, rumble) shipped in
|
||||
PRs #120, #129, #145 and #149. The second round, each shippable alone:
|
||||
|
||||
Each is shippable alone. Testing is with unit tests, the injected pad and
|
||||
vscreen screenshots; each PR says what still needs a real controller.
|
||||
1. **Focus navigation** (this section above): the menu navigation option,
|
||||
focus targets and vanilla's arrow-key step, the focus highlight in both
|
||||
menu styles, the on-screen keyboard.
|
||||
2. **Button prompts**: contextual hints with the pad's glyphs in menus and
|
||||
optionally in game, and rebinding from them.
|
||||
3. **DualSense output**: adaptive triggers, lightbar, player LEDs and richer
|
||||
rumble over HID, off-safe.
|
||||
4. **Launcher**: the same focus navigation in the gpui launcher.
|
||||
|
||||
Each is tested with unit tests (focus steps, prompt contexts, report bytes),
|
||||
the injected pad and vscreen screenshots; each PR says what still needs a
|
||||
real controller.
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
# Generation scan gate benchmark
|
||||
|
||||
`Streaming::update` now reuses an exhausted generation scan until its range,
|
||||
loaded membership, or generation state changes. Pending candidates keep the
|
||||
original per-frame bounded scheduling. Worker generation results and proto
|
||||
pruning invalidate the gate; light/mesh results do not. Public extra/forced
|
||||
ranges are compared exactly. `ChunkMap` tracks structural membership and map
|
||||
replacement, while value edits and existing-key replacement keep its token.
|
||||
The empty-extra/forced stationary gate is constant time; comparisons scale with
|
||||
those auxiliary ranges when present.
|
||||
|
||||
Reproduce from the repository root:
|
||||
|
||||
```sh
|
||||
CARGO_INCREMENTAL=0 CARGO_TARGET_DIR=/home/bob/Documents/horizon/target \
|
||||
cargo test -p horizon-client --lib --profile fast generation_scan_benchmark \
|
||||
-- --ignored --nocapture
|
||||
```
|
||||
|
||||
The ignored test exercises the production candidate helper called by
|
||||
`Streaming::update`, compared against an independent copy of the original
|
||||
scan. It validates scheduled coordinates, job counts, and final membership
|
||||
and in-flight state. It uses a radius-32 decorated world: 5,041 scanned square
|
||||
positions, 3,409 finished resident keys and 552 outer-margin proto keys, capacity 12. Each sample runs 2,000
|
||||
frames, with one warmup sample and eight measured samples; values below are
|
||||
median nanoseconds per frame. The dynamic case removes the centre column every
|
||||
32 frames, schedules regeneration, and accepts a saved-load completion on the
|
||||
following frame.
|
||||
|
||||
Measured on Linux x86-64, AMD Ryzen 5 5600X, Rust 1.99.0
|
||||
(`b940084d7`, 2026-09-28), optimized `fast` profile, 2026-10-14:
|
||||
|
||||
| Scenario | Original | Gated | Speedup | Scans per 2,000 frames | Jobs original/gated |
|
||||
| --- | ---: | ---: | ---: | ---: | ---: |
|
||||
| Stationary fully resident | 15,441.3 ns | 10.1 ns | 1,528.99x | 2,000 / 0 | 0 / 0 |
|
||||
| Dynamic remove/load cycle | 14,794.3 ns | 1,004.8 ns | 14.72x | 2,000 / 126 | 63 / 63 |
|
||||
|
||||
This is a generation scheduling microbenchmark, not a full-update, FPS, worker
|
||||
throughput, or startup benchmark. No prepared assets are needed: the fixture
|
||||
shares an empty real `Chunk` under different resident keys and uses unit
|
||||
protos because this path only reads membership. It excludes decoration execution, terrain generation, lighting,
|
||||
meshing, uploads, and other per-frame scans. The stationary speedup reflects
|
||||
replacing a completed scan with a small gate and should not be extrapolated to
|
||||
overall game performance. Timing and assertion overhead are included in both
|
||||
implementations. Memory cost is a u64 token per resident map plus a small gate
|
||||
snapshot and copies of extra/forced range metadata; no resident-key cache.
|
||||
|
||||
Focused differential tests also cover movement, radius changes, extra and
|
||||
forced areas, removal/replacement at unchanged count, entire world reset,
|
||||
capacity pressure, staged generation membership, proto discard/retry, and
|
||||
light/content edits that should leave the gate reusable. `ChunkMap` tests cover
|
||||
structural tokens and value/light mutation separately.
|
||||
+3
-1
@@ -22,11 +22,13 @@ Every row has a one-line description and its cost in frame time (none, low, medi
|
||||
| | sky, fog, weather, animated textures | `horizon-graphics.txt` |
|
||||
| Display | FOV, max framerate, VSync, fullscreen, GUI scale | `options.txt` |
|
||||
| | resolution scale, anti-aliasing (FXAA), present mode, frame pacing | `horizon-graphics.txt` |
|
||||
| Performance | worker threads, upload budget per frame | `horizon-graphics.txt` |
|
||||
| Performance | battery mode, worker threads, upload budget per frame | `horizon-graphics.txt` |
|
||||
| Overlay | performance overlay: FPS, frame/CPU/GPU times, frame-time graph | `horizon-graphics.txt` |
|
||||
|
||||
`options.txt` keeps exactly vanilla's keys and values, so the options harness still compares it with vanilla; Horizon's settings live in `horizon-graphics.txt` beside it. Their defaults render as vanilla does: cave culling on, no upload budgets, sky, fog and weather on, 100% resolution, no FXAA, the present mode following VSync. Frame pacing defaults to Efficient: the limiter sleeps through the last half millisecond where vanilla spins, which changes timing, not pixels.
|
||||
|
||||
**Battery mode** (Performance, off by default) is for laptops and handhelds: at most 60 frames per second in a world, 30 in menus without a world or while another window has focus, and half the automatic worker threads (chunks load slower). It changes only when frames are drawn: what they show and the game's 20 ticks per second stay as they are.
|
||||
|
||||
Which settings each level shows, their descriptions and costs are in `crates/horizon-client/src/graphics_ui.rs` (`rows`); the Horizon shell draws them in `options_horizon.rs` with `ui_theme::described_row`, and the Classic screens use `graphics_style.rs`.
|
||||
|
||||
Not implemented: distant-terrain LOD, anisotropic filtering (wgpu needs linear magnification for it, which blurs close blocks), MSAA (FXAA instead) and exclusive fullscreen (fullscreen is borderless).
|
||||
|
||||
@@ -0,0 +1,56 @@
|
||||
# Lighting worker result packaging
|
||||
|
||||
`light_chunk` now returns only `Vec<Light>`. `apply_lighting` moves each light
|
||||
into the current section through `Arc::make_mut`, preserving current block and
|
||||
biome edits and snapshots held by other workers. Streaming still rejects stale
|
||||
sequences before applying results and replays edits after applying valid light.
|
||||
All direct examples use the same application function.
|
||||
|
||||
## Reproduce
|
||||
|
||||
```sh
|
||||
CARGO_INCREMENTAL=0 CARGO_TARGET_DIR=/home/bob/Documents/horizon/target cargo test -p horizon-client --lib --profile fast benchmark_worker_light_results -- --ignored --nocapture
|
||||
```
|
||||
|
||||
The ignored test invokes the production `pack_lighting` and `apply_lighting`
|
||||
functions and compares them to original main's packaging/application loops.
|
||||
It checks every resulting block, biome, and light value before timing. Each
|
||||
measurement uses 500 columns per batch, one discarded warm-up batch, and ten
|
||||
measured batches with alternating baseline/optimized order and `black_box`.
|
||||
The reported median is the upper middle of the ten samples. Both implementations
|
||||
receive identical precomputed propagation arrays. The fixture contains 24
|
||||
sections with 16-state block palettes, four-biome palettes, and existing full
|
||||
light arrays. A second case retains a fresh snapshot each iteration to force
|
||||
copy-on-write during application. Fixtures are synthetic, not loaded saves.
|
||||
|
||||
AMD Ryzen 5 5600X, Linux x86_64, rustc 1.99.0, optimized `fast` profile,
|
||||
nonincremental, no LTO:
|
||||
|
||||
| Packaging + application | Original main | New | Speedup |
|
||||
| --- | ---: | ---: | ---: |
|
||||
| Sections uniquely owned | 63.948 us/column | 44.397 us/column | 1.44x |
|
||||
| Snapshot retained | 65.332 us/column | 53.025 us/column | 1.23x |
|
||||
|
||||
These measurements exclude propagation, region snapshot creation, outer chunk
|
||||
copy-on-write, channels, replay, and remeshing. They establish savings in the
|
||||
actual worker output/application paths, not a whole lighting runtime or FPS gain.
|
||||
|
||||
## Copy and allocation scope
|
||||
|
||||
`Section::heap_bytes` reports 149,760 bytes of fixture payload per column.
|
||||
Original packaging clones that payload and allocates 24 section Arcs. Original
|
||||
application clones the current section payload, allocates another 24 section
|
||||
Arcs, and clones 98,304 bytes of returned light. New packaging clones no section
|
||||
payload and allocates no section Arcs. New application moves the returned light;
|
||||
with unique sections it clones no payload and allocates no section Arcs. With a
|
||||
retained snapshot it still copies the current section payload and allocates 24
|
||||
Arcs, as required to preserve the snapshot. New light arrays and the result Vec
|
||||
still allocate. These are structural copy/allocation observations, not global
|
||||
allocator instrumentation; byte figures exclude Arc headers, Vec headers, and
|
||||
allocator overhead.
|
||||
|
||||
Focused tests cover moved light buffer identity, current block/biome edits,
|
||||
retained snapshots, forced replay versus fresh full relighting, empty chunks,
|
||||
missing neighbours, no-sky dimensions, light attenuation, occlusion, and
|
||||
incremental/full equivalence. The stale-sequence guard and missing-current-chunk
|
||||
handling in streaming are unchanged.
|
||||
@@ -0,0 +1,221 @@
|
||||
# Play with friends
|
||||
|
||||
A player opens their single-player world to friends with one click and gets an **invite code**.
|
||||
Friends paste the code (on the multiplayer screen in game, or on the launcher's Play page) and join.
|
||||
There is no Horizon server in the middle and no account: the code itself says where the host is and
|
||||
holds the key that encrypts the game between them.
|
||||
|
||||
It is built on Open to LAN: the integrated server (`crates/horizon-client/src/lan`) listens on a local
|
||||
TCP port and speaks the vanilla protocol. Play with friends puts an encrypted tunnel in front of that
|
||||
port. Neither the integrated server nor the guest's client changes: the tunnel carries exactly the
|
||||
bytes vanilla's protocol would send, between a loopback port on each side.
|
||||
|
||||
```
|
||||
guest's game host's game
|
||||
┌──────────────┐ 127.0.0.1:A ┌────────────┐ TCP, end-to-end encrypted ┌────────────┐ 127.0.0.1:LAN ┌──────────────┐
|
||||
│ client │────────────▶│ guest │══════════════════════════════▶│ host │──────────────▶│ integrated │
|
||||
│ (unchanged) │ │ tunnel │ to an address from the code │ tunnel │ │ server (LAN) │
|
||||
└──────────────┘ └────────────┘ └────────────┘ └──────────────┘
|
||||
╲ optional: a relay anyone can run ╱
|
||||
╲──────────▶ horizon-relay (short codes, fallback) ◀╱
|
||||
```
|
||||
|
||||
## How it works
|
||||
|
||||
**Hosting.** "Invite friends" (in Horizon's pause menu) opens the world to LAN if it isn't (Open to
|
||||
LAN's defaults), then the host's game, on its own:
|
||||
|
||||
1. listens on its **direct port**, TCP 25580 by default (the same port every time, so a port forwarded
|
||||
by hand keeps working; another one if it is taken; `HORIZON_FRIENDS_PORT` picks it);
|
||||
2. collects this computer's addresses: the LAN address, VPN addresses (Tailscale's `100.x`, ZeroTier
|
||||
and others), IPv6. Container and VM bridges are left out;
|
||||
3. asks the home router to open the direct port for an hour, renewed every half hour and deleted when
|
||||
sharing stops: **PCP** (RFC 6887), then **NAT-PMP** (RFC 6886) on the default gateway, then **UPnP
|
||||
IGD** (SSDP discovery, SOAP `AddPortMapping`). A router that only takes permanent UPnP mappings gets
|
||||
one, deleted on stop the same way (if the game crashes instead, a timed mapping expires within the
|
||||
hour; a permanent one stays until it is removed in the router's settings);
|
||||
4. asks public **STUN** servers for its public IPv4 address (only the address: STUN sees UDP, the game
|
||||
is TCP). Defaults: `stun.cloudflare.com:3478` and `stun.l.google.com:19302`, two independent
|
||||
operators of free STUN at a global scale, so one outage doesn't break discovery. `HORIZON_STUN_SERVERS`
|
||||
(a comma list, or `none`) changes them;
|
||||
5. builds the **invite code**: the endpoints (the router mapping, the public address on the direct
|
||||
port, the interface addresses) and a fresh 80-bit secret, in base32 with a checksum.
|
||||
|
||||
**Joining.** The guest's game dials every endpoint in the code at once. The first that answers as a
|
||||
Horizon host gets the handshake, the others are dropped. On the same LAN, over a VPN, with IPv6, with a
|
||||
router that opened the port, or with a forwarded port, that's it: no server took part.
|
||||
|
||||
**Codes.** Crockford base32 (`0-9 A-Z` without `I L O U`; input ignores case, spaces and dashes and reads
|
||||
`O` as `0`, `I`/`L` as `1`) in groups of five, with a 16-bit checksum so a typo is caught before
|
||||
anything is dialled:
|
||||
|
||||
- a home with a router mapping, a LAN address and a tailnet address: 52 symbols
|
||||
(`2A7KQ-M3XPD-…`, 11 groups); with IPv6 too, 79;
|
||||
- byte layout: version, secret (10 bytes), direct port, endpoints (tag, address, own port when it
|
||||
differs), an optional relay entry, the first two bytes of SHA-256 of all that.
|
||||
|
||||
A code lives as long as the host shares: stopping, closing the world or quitting ends it (the direct
|
||||
port closes, the router mapping is deleted). Sharing again makes a new secret.
|
||||
|
||||
## When friends can't reach the host
|
||||
|
||||
The host's panel says what to expect, from what the game found:
|
||||
|
||||
| What the game found | What the host reads |
|
||||
| --- | --- |
|
||||
| The router opened the port | "Friends anywhere can join: your router opened the port with UPnP (203.0.113.5:25580)." |
|
||||
| This computer has a public address | "Friends anywhere can join … (TCP port 25580 must not be blocked by a firewall)." |
|
||||
| No router answered | "Friends on your network or VPN can join. For friends on the internet: turn on UPnP on your router, or forward TCP port 25580 to 192.168.1.20, or use a relay, or a VPN such as Tailscale or ZeroTier (the code already holds your VPN address)." |
|
||||
| The router is behind another NAT (the router's public side is a private or `100.64/10` address, or STUN sees another address) | "… your router is itself behind another NAT (your provider's carrier-grade NAT, CGNAT, or a second router), so opening its port isn't enough. Use a relay or a VPN such as Tailscale or ZeroTier." |
|
||||
|
||||
The code always holds the public address on the direct port when STUN found it, so **forwarding the
|
||||
port by hand** works without a new code. A guest that can't reach any endpoint is told: "Couldn't reach
|
||||
your friend's game. Ask them to read the note under their code: they may need UPnP on their router, a
|
||||
forwarded port, a relay or a VPN."
|
||||
|
||||
## Encryption
|
||||
|
||||
The code's secret never leaves the code. Every session runs a password-authenticated key exchange
|
||||
(SPAKE2 over Ed25519, RustCrypto's `spake2`) keyed by it and bound to a session number, then derives
|
||||
per-direction ChaCha20-Poly1305 keys with HKDF-SHA256 from the exchange and two fresh randoms, with a
|
||||
key confirmation first. A wrong code, a changed byte, a replayed or reordered frame ends the stream.
|
||||
The same exchange runs over relayed sessions, where it matters most: the relay gets nothing to test
|
||||
guesses against offline. Online guesses on the direct port face the 80-bit secret; at most 8 openings
|
||||
run at once there, and each must finish within 10 seconds however slowly its bytes come.
|
||||
|
||||
## Privacy: who sees what
|
||||
|
||||
- **Friends with the code** see the host's addresses in it (LAN, VPN, public), as with any server
|
||||
address. A guest's address is seen by the host, as on any server.
|
||||
- **STUN servers** see the host's public IP address and a 20-byte request, like any website it visits.
|
||||
Turn them off with `HORIZON_STUN_SERVERS=none` (the code then lacks the public address unless the
|
||||
router reported it).
|
||||
- **The router** gets a port mapping named "Horizon (play with friends)".
|
||||
- **A relay** (only if one is configured) sees the IP addresses of the host and the guests, the short
|
||||
code's first half, when sessions start and end and the size of encrypted frames. It can't see the
|
||||
secret, the key or the game (names, chat, the world). It logs counts every five minutes, nothing else.
|
||||
- **Horizon** sees nothing: there is no Horizon service.
|
||||
|
||||
## Identity
|
||||
|
||||
Like LAN: offline mode. A guest joins with the name their game uses; the host's own profile is reserved.
|
||||
Online-mode checks against Mojang's session servers can come later on top of the same tunnel. Every
|
||||
tunnelled guest reaches the integrated server from `127.0.0.1`.
|
||||
|
||||
## Relays (optional)
|
||||
|
||||
For networks nothing can reach (CGNAT on both sides, no VPN), a **relay** carries the session: one small
|
||||
binary, `horizon-relay`, that anyone can run on their own PC, a VPS, a Raspberry Pi or a free tier.
|
||||
There is no default relay. With one configured:
|
||||
|
||||
- the host also registers there and gets a **short code** (`K7QM-3XPD`: a 4-symbol nameplate the relay
|
||||
allocates, a 4-symbol secret it never sees), and the full code names the relay and carries the short
|
||||
code, so guests with the full code fall back to the relay without any setting;
|
||||
- guests with only the short code need the relay's address (on the Join a friend page);
|
||||
- a relayed session first races direct connections both ways (candidates exchanged encrypted, TCP
|
||||
simultaneous open from the direct port), and stays on the relay only if none connects.
|
||||
|
||||
Configuring it: the **Relay** field on the Join a friend page (saved to `horizon.txt` as
|
||||
`friendsRelay:host:port`, used for hosting too), or `HORIZON_RELAY_URL`.
|
||||
|
||||
### Running your own relay
|
||||
|
||||
The relay needs one TCP port reachable by your friends and almost nothing else (a few MB of memory, no
|
||||
disk). Relayed players cost what the game sends: a join is a few MB, play is about 10–50 KB/s, flying
|
||||
over new terrain up to a few hundred KB/s (capped per session).
|
||||
|
||||
**From a release or source** (any OS with Rust):
|
||||
|
||||
```
|
||||
cargo build --release -p horizon-relay
|
||||
PORT=7000 ./target/release/horizon-relay
|
||||
```
|
||||
|
||||
**With Docker** (build context: the repository root):
|
||||
|
||||
```
|
||||
docker build -f crates/horizon-relay/Dockerfile -t horizon-relay .
|
||||
docker run -d --restart unless-stopped -p 7000:7000 horizon-relay
|
||||
```
|
||||
|
||||
**As a service** (Linux, including a Raspberry Pi): copy the binary to `/usr/local/bin/horizon-relay`,
|
||||
`crates/horizon-relay/horizon-relay.service` to `/etc/systemd/system/`, then
|
||||
`systemctl enable --now horizon-relay`.
|
||||
|
||||
Then forward TCP port 7000 on your router to that machine (or run it on a VPS with a public address),
|
||||
check `curl http://<address>:7000/health` from outside, and give friends `<address>:7000`. `GET /whoami`
|
||||
shows the address the relay sees for you: behind a proxy that hides client addresses (some hosting
|
||||
platforms' TCP proxies), set `RELAY_PER_ADDRESS_LIMITS=0`. Run **one** instance per address: codes live
|
||||
in its memory.
|
||||
|
||||
Settings, all optional:
|
||||
|
||||
| Variable | Default | |
|
||||
| --- | --- | --- |
|
||||
| `PORT` | 7000 | the TCP port (also answers `GET /health` and `GET /whoami`) |
|
||||
| `RELAY_BIND` | all addresses | listen on one address only (e.g. a tailnet address) |
|
||||
| `RELAY_MAX_HOSTS` | 1000 | short codes at once |
|
||||
| `RELAY_MAX_BRIDGES` | 200 | relayed streams at once |
|
||||
| `RELAY_MAX_PENDING_PER_HOST` | 8 | guests joining one host at the same time |
|
||||
| `RELAY_MAX_CONNECTIONS` | 4096 | connections open at once, of every kind (more are closed unanswered) |
|
||||
| `RELAY_SESSION_KBPS` | 1024 | KiB/s each way per relayed stream |
|
||||
| `RELAY_TOTAL_MBPS` | 100 | Mbit/s for everything relayed |
|
||||
| `RELAY_GLOBAL_UNKNOWN_PER_MIN` | 120 | unknown short codes a minute, all clients together |
|
||||
| `RELAY_PER_ADDRESS_LIMITS` | 1 | per-address rate limits (see below) |
|
||||
| `RELAY_PROXY_PROTOCOL` | 0 | read the client address from a PROXY protocol v1 line |
|
||||
|
||||
Fixed limits: per client address (IPv6 by /64), 6 host registrations a minute (burst 3), 12 joins a
|
||||
minute (burst 6), 5 unknown short codes in 10 minutes block joins for 10 minutes; a relayed stream idle
|
||||
for 120 s is closed (the game's keep-alive sends every 15 s); the first line must be complete within 10 s;
|
||||
hosts answer pings within 60 s; five wrong secrets on a short code and the host retires it for a new one.
|
||||
|
||||
### The relay protocol
|
||||
|
||||
One TCP port. The first line of each connection is a JSON object (at most 4 KiB, within 10 seconds); a
|
||||
connection starting with `GET ` gets an HTTP answer instead.
|
||||
|
||||
| From | Line | Meaning |
|
||||
| --- | --- | --- |
|
||||
| host | `{"op":"host","v":1,"protocol":P,"game":"26.3"}` | register; answer `{"op":"registered","nameplate":"K7QM","token":T,"observed":"ip:port"}` |
|
||||
| guest | `{"op":"join","v":1,"nameplate":"K7QM","protocol":P,"game":"26.3"}` | resolve; the relay announces the session to the host and waits for its attach, then answers `{"op":"bridged","session":S,"observed":…}` or `{"op":"error","code":…}` |
|
||||
| relay → host | `{"op":"join","session":S}` | open a new connection and attach |
|
||||
| host | `{"op":"attach","v":1,"session":S,"token":T}` | paired with the guest; both get `bridged`, then raw bytes |
|
||||
| relay ↔ host | `{"op":"ping"}` / `{"op":"pong"}` | every 20 s |
|
||||
|
||||
Errors: `unknown_code`, `ended` (kept 15 minutes after a host leaves), `version_mismatch` (with the
|
||||
host's version), `host_unreachable`, `full`, `rate_limited`, `bad_request`.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
- **"Friends on your network or VPN can join"**: turn on UPnP (sometimes "UPnP IGD" or "NAT-PMP") in
|
||||
the router's settings and share again; or forward TCP port 25580 (the panel shows the port and your
|
||||
LAN address) to this computer; or install Tailscale or ZeroTier on both computers (the code already
|
||||
holds the VPN address); or run a relay.
|
||||
- **CGNAT / a second router**: port forwarding on your own router can't help. Use a VPN or a relay (on a
|
||||
machine with a public address, e.g. a VPS).
|
||||
- **"Couldn't reach your friend's game"** (guest): the host's note under the code says why. A firewall
|
||||
on the host computer can also block the direct port: allow `horizon-client` on private and public
|
||||
networks (Windows asks the first time; on macOS answer "Allow" when asked whether Horizon may accept
|
||||
incoming network connections).
|
||||
- **"The code has a typo"**: copy it again; codes are only letters and digits in groups of five.
|
||||
- **"This short code works through your friend's relay"**: enter the relay's address under Join a
|
||||
friend, or ask for the full code.
|
||||
- **"Your friend plays Minecraft X; you have Y"**: both need the same game version.
|
||||
|
||||
## Testing
|
||||
|
||||
- Unit tests (`horizon-friends`): code format (round trips, every single-symbol typo caught, versions),
|
||||
STUN against a mock server, PCP / NAT-PMP against a mock router (map, renew, delete; NAT-PMP when PCP
|
||||
is unsupported), UPnP against a mock IGD (description, chunked replies, `AddPortMapping`, permanent-only
|
||||
leases (725), taken ports (718), `DeletePortMapping`), the verdicts and endpoint order, gateway
|
||||
parsing for Linux, macOS and Windows, the key exchange and frames (wrong secret, tampering), the direct
|
||||
race.
|
||||
- `crates/horizon-relay/tests/tunnel.rs`: the code alone with no server (1 MiB, two guests at once); a
|
||||
self-hosted relay with the short code (relayed, then its direct race); dead endpoints falling back to
|
||||
the relay named in the code; wrong secrets (full and short codes, the short code retired after five);
|
||||
unknown and ended codes, version mismatch, rate limits, bandwidth caps, `/health`.
|
||||
- `tools/test_friends.py`: real games: a host Horizon sharing a world and a guest Horizon joining over
|
||||
plain LAN (`--baseline`), with the **code alone** (no relay running), and through a **locally run
|
||||
relay** with the short code; chat, movement and blocks both ways, then the ended invite.
|
||||
- Two machines over a tailnet with the code alone (`--role host` on one, `--role guest --code …` on the
|
||||
other).
|
||||
@@ -0,0 +1,46 @@
|
||||
# Reusing resource-pack overlays
|
||||
|
||||
`packs::build_overlay` reuses a completed overlay through a versioned sibling JSON marker and persistent OS lock. Pack sources/order, overlay roots, filters, source topology and materialized vanilla inputs determine validity. The marker is removed before rebuilding and published only after a successful build and stable input checks.
|
||||
|
||||
On Unix, ZIPs and materialized inputs use length, modification time, device/inode and change-time stamps. Cache hits do not read archive bytes or traverse generated output. Directory packs still validate their topology; ordinary linked files and untouched vanilla subtrees remain live. Materialized vanilla directory stamps detect membership changes without listing them again. Only marker identity resolves paths; the builder retains the caller's original symlink targets and root aliases.
|
||||
|
||||
On non-Unix platforms, materialized files retain content hashing because portable metadata lacks a change timestamp. That path was not runtime-tested. External folder overlays and symlink cycles retain uncached behavior. Missing/corrupt markers and a missing output root rebuild. Generated output is owned cache data: external edits to individual output files are deliberately not detected; delete the sibling marker or overlay directory to rebuild it.
|
||||
|
||||
## Real pack measurements
|
||||
|
||||
The ignored test measures the actual production `resource_root` entry point against its original selection/key/build sequence. Two warmups and 11 alternating samples use identical prepared Minecraft 26.3 resources (manifest schema 7). Complete materialized output bytes and symlink identities are compared outside timing. Cold means an absent marker with warm filesystem caches, rather than cold storage.
|
||||
|
||||
Linux x86_64/ext4/NVMe, Ryzen 5 5600X, Rust 1.99.0, Cargo `fast`, measured 2026-10-15:
|
||||
|
||||
| ZIP pack | Original rebuild | Cached cold | Unchanged hit | Saved per hit |
|
||||
| --- | ---: | ---: | ---: | ---: |
|
||||
| Faithful 32x, 26.3 September 2026 | 159.827 ms | 162.711 ms | 0.707 ms | 159.120 ms |
|
||||
| Default HD 128x demo, 1.8.2.7 | 111.501 ms | 114.386 ms | 0.310 ms | 111.191 ms |
|
||||
| FPBR, 1.21.9 R1.3 | 347.639 ms | 348.012 ms | 0.448 ms | 347.191 ms |
|
||||
|
||||
Unchanged speedups are approximately 226x, 359x and 775x. Cold overhead on these ZIPs is 0.1–2.6%, replacing the original cache implementation's 73–79% synthetic overhead. This measures overlay assembly and cache validation, excluding scan, texture decoding, total startup and FPS.
|
||||
|
||||
Mac mini (M4 Pro, APFS, Rust stable, Cargo `fast`), same harness and packs, measured 2026-10-15 during review while the machine ran other builds:
|
||||
|
||||
| ZIP pack | Original rebuild | Cached cold | Unchanged hit | Saved per hit |
|
||||
| --- | ---: | ---: | ---: | ---: |
|
||||
| Faithful 32x, 26.3 September 2026 | 1,184.400 ms | 1,295.069 ms | 0.571 ms | 1,183.829 ms |
|
||||
| FPBR, 1.21.9 R1.3 | 5,292.149 ms | 5,503.965 ms | 0.391 ms | 5,291.758 ms |
|
||||
|
||||
Creating thousands of files and links costs far more on macOS than on Linux, so the saving there is seconds per startup with a pack enabled.
|
||||
|
||||
Pack downloads were verified against publisher SHA-512 metadata. Exact versions, URLs, sizes, asset counts, hashes and prepared-manifest identity are recorded in `benchmarks/overlay-real-packs-2026-10-15.json`. Sources: [Faithful](https://modrinth.com/resourcepack/faithful-32x/version/lDYpMiqk), [Default HD](https://modrinth.com/resourcepack/default-hd-128x/version/rErHu3BE), [FPBR](https://modrinth.com/resourcepack/fpbr/version/dynf82xk). FPBR targets older 1.21.9 snapshots; it is measured as a large real 128x archive over prepared 26.3 resources, without claiming visual/version compatibility. Default HD is the publisher's free demo. Downloaded pack contents are not committed.
|
||||
|
||||
## Reproduce and validate
|
||||
|
||||
```sh
|
||||
export CARGO_INCREMENTAL=0
|
||||
export HORIZON_OVERLAY_BENCH_VANILLA=/path/to/prepared/26.3
|
||||
export HORIZON_OVERLAY_BENCH_PACKS='["/path/to/Faithful.zip","/path/to/DefaultHD.zip","/path/to/FPBR.zip"]'
|
||||
cargo test -p horizon-client --lib --profile fast packs::cache::tests::benchmark_real_resource_root -- --ignored --nocapture --test-threads=1
|
||||
cargo test -p horizon-client --lib --profile fast packs:: -- --nocapture
|
||||
cargo clippy -p horizon-client --lib --tests --profile fast -- -D warnings
|
||||
cargo fmt --all -- --check
|
||||
```
|
||||
|
||||
Thirteen focused tests pass, covering source edits/replacements, Unix preserved-mtime edits, pack order/removal, overlays/filters, vanilla membership, marker/output-root recovery, failed ZIP rebuilds, symlink aliases/cycles, contention and unchanged relative link targets. The opt-in real-pack benchmark passes; strict Clippy, formatting and whitespace checks pass. Each overlay retains a small marker and empty lock file; cache hits retain no archive byte buffer.
|
||||
@@ -0,0 +1,55 @@
|
||||
# Opt-in data collection
|
||||
|
||||
Horizon collects nothing unless the player says yes. The launcher asks once, with four separate switches that are all off until the player turns one on, and the same switches stay in Settings. The game and the launcher obey the same answer. The code is in `crates/horizon-telemetry`.
|
||||
|
||||
## Consent
|
||||
|
||||
`telemetry/consent.json` in the game folder (`HORIZON_HOME`, else `horizon` in the platform data folder):
|
||||
|
||||
```json
|
||||
{ "version": 1, "answered": 1792060800, "choices": { "performance": true, "crashes": true, "bugs": false, "benchmarks": false }, "install_id": "3f2c…" }
|
||||
```
|
||||
|
||||
- `version` is the consent version the player answered (`CONSENT_VERSION`). It goes up when what is collected changes. The launcher then asks again, and until the player answers nothing new is kept or sent.
|
||||
- `answered` is when they answered, in seconds since 1970 (UTC).
|
||||
- `install_id` is 128 random bits, made the first time the player says yes to anything. It ties their items together so they can be deleted, and nothing else. "Delete my data" asks the server to delete everything under it, then replaces it.
|
||||
|
||||
Nothing leaves the machine without consent:
|
||||
|
||||
- `outbox::push` keeps an item only if its kind is allowed.
|
||||
- `upload::flush` reads the consent again before sending and deletes any waiting item whose kind the player has turned off since, so with everything off it never opens a connection.
|
||||
|
||||
`tests/consent_gating.rs` checks this against a local mock server that counts connections.
|
||||
|
||||
## What is sent
|
||||
|
||||
Every item has `day` (days since 1970, UTC: no finer time), `source` (`launcher` or `game`), `version` (the release), `kind` and `data`.
|
||||
|
||||
| Kind | Switch | `data` | Largest | A day |
|
||||
|---|---|---|---|---|
|
||||
| `perf` | performance | `system`, `settings` (render and simulation distance, max FPS, vsync, fullscreen, graphics mode), `seconds` played, `frames` and `ticks` summaries, `peak_ram_mb`, `to_title_ms`, `to_world_ms` | 4 KiB | 12 |
|
||||
| `crash` | crash reports | `system`, `error`, `stack` (one frame a line), `thread`, the graphics and settings details, all scrubbed. No log, no world, no server | 32 KiB | 5 |
|
||||
| `bug` | bug reports | `system`, the player's `text` (up to 4000 characters), and the `log` only if they add it after reading it | 80 KiB | 5 |
|
||||
| `benchmark` | benchmark uploads | the benchmark report as `docs/benchmark-report.md` defines it, as it is, with its own schema field | 128 KiB | 10 |
|
||||
|
||||
`system` is the OS and its version, the architecture, the CPU model and thread count, installed memory rounded to the GiB, and the GPU, driver and graphics backend.
|
||||
|
||||
A summary (`frames`, `ticks`) is the count, the 50th, 95th and 99th percentile and the maximum in milliseconds (to the tenth), and 14 bucket counts: under 4 ms, 4–6, 6–8, 8–10, 10–12, 12–14, 14–16.7, 16.7–20, 20–25, 25–33.3, 33.3–50, 50–100, 100–250, and 250 ms and more. Raw frame times never leave: `Timings` records them in tenths of a millisecond (20 KB however long the session) and only its summary is kept. A perf item is under 1 KiB.
|
||||
|
||||
Never sent: account names or UUIDs, world names, server or LAN addresses, chat, file paths with the user's name, IP addresses. `scrub::Scrubber` replaces the user folder in paths (`/Users/<user>/…`, `C:\Users\<user>\…`), the user name, e-mail and IP addresses and UUIDs. It also replaces the terms the caller passes (the world's name, the server's address, account names). The server does not store the sender's IP address.
|
||||
|
||||
## Storage and sending
|
||||
|
||||
- `telemetry/outbox/` holds one JSON file per item, `<day>-<kind>-<random>.json`. It never holds more than 200 items or 2 MiB, and the oldest go first. `kept.json` counts today's items per kind against the caps above.
|
||||
- The launcher sends the outbox when it starts and when it closes. Items go as one JSON batch (`{"schema":1,"install_id":…,"items":[…]}`, up to 64 items and 1 MiB), compressed with zstd: `POST /v1/batch` with `Content-Encoding: zstd`. A day's perf summaries are under 2 KB on the wire.
|
||||
- After a failure the launcher waits a minute, doubling up to a day, and sends at most 8 batches a day. A batch the server refuses with a 4xx (not 429) is dropped.
|
||||
- `HORIZON_TELEMETRY_URL` sets the server. There is none by default: until there is, nothing is sent and the outbox stays within its caps.
|
||||
- `SCHEMA` versions the format. New optional fields keep it. A field that changes meaning or goes bumps it, and the server keeps reading the older ones.
|
||||
|
||||
## Server
|
||||
|
||||
- `POST /v1/batch`
|
||||
- `DELETE /v1/installs/<install_id>`: deletes everything sent under that ID.
|
||||
- `GET /v1/aggregate`: the anonymous totals the website's results page reads.
|
||||
|
||||
`crates/horizon-telemetry-server` is the server. Its [README](../crates/horizon-telemetry-server/README.md) covers storage (about 190 bytes per play session), retention (180 days of raw rows, anonymous daily totals kept), rate limits and hosting.
|
||||
Reference in New Issue
Block a user