Merge remote-tracking branch 'origin/main' into feat/server-bench-paper-fabric

# Conflicts:
#	docs/server.md
This commit is contained in:
Ludovic Marie
2026-10-19 08:33:52 +02:00
23 changed files with 1469 additions and 184 deletions
+1 -1
View File
@@ -46,4 +46,4 @@ To play, use [the launcher](../launcher/README.md); the project site is [playhor
## The earlier Java track (no longer developed)
- [Java performance packs](java-packs.md), with [Vulkan on your Mac](vulkan.md), [collector comparisons](collectors.md), [profiling](profiling.md), [process memory](process-memory.md) and [tick state](tick-state.md); [server quickstart](server-quickstart.txt).
- [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.
+2 -3
View File
@@ -28,16 +28,15 @@ 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.
Developer demo and server launchers accept `--gc default`, `--gc g1` or `--gc zgc`.
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/server.py run --heap 4G --gc zgc
python3 tools/test_jfr.py --gc zgc
```
Prepare demo mods/worlds before comparing. The server retains its EULA requirement.
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.
+22 -3
View File
@@ -204,6 +204,8 @@ horizon-server restore BACKUP [--yes]
horizon-server service install|uninstall|print [--system]
horizon-server panel a one-time login link for the web panel
horizon-server import FILE server.toml from a vanilla server.properties
horizon-server update [--check] install the newest release and restart on it (below)
horizon-server rollback back to the release before
```
While the server runs, `op`, `whitelist` and `cmd` go to the game's console, so they act exactly as vanilla's
@@ -213,14 +215,31 @@ console commands do. While it's stopped, they edit vanilla's files directly. Any
The server restarts the game by itself if it crashes: after 5 s, then waiting longer each time, up to 5
minutes. It keeps the crash report and gives up after 5 crashes in 10 minutes, and `status` says why.
Coming: `update` and `rollback`, `console` (attach to a server running in the background), `ban` and
`pardon` as their own commands, and `mcp` (an MCP server so an AI assistant can run the server).
**Updates** (a server installed with the install script). The server checks for a newer release a minute
after it starts and every 6 hours after, and says so in its log, in `status` and in the panel; it never
updates by itself. `horizon-server update --check` asks once. `horizon-server update`:
1. downloads the newest release and checks it against the SHA-256 GitHub publishes for it;
2. stops the game, backs up the world (`backups/<time>-before-<release>.zip`) and switches to the new
release;
3. starts the game on it and waits up to 5 minutes (`--timeout SECONDS`) for it to come up.
If the new game crashes or doesn't come up in time, the server goes back to the release it was on by itself
and puts the world back as it was just before the switch (the world the new game left is kept in
`backups/`). `horizon-server rollback` goes back to the release before by hand, keeping the world as it is
(it backs it up first). `--version vX.Y.Z` installs a given release, and `--archive FILE --version NAME` an
archive you have, such as your own build. A stopped server is switched and starts on the new release next
time. Set `HORIZON_NO_UPDATE_CHECK=1` in the server's environment to turn the check off.
Coming: `console` (attach to a server running in the background), `ban` and `pardon` as their own
commands, and `mcp` (an MCP server so an AI assistant can run the server).
## 6. Web panel
The panel runs inside `horizon-server` while the server runs. It shows live TPS, MSPT, RAM and CPU graphs for
the last 10 minutes, the players with their ping (and a kick button), the console with a command line, and the
backups (back up now, restore with a confirmation), with Restart and Stop.
backups (back up now, restore with a confirmation), with Restart and Stop. When a newer release is out it says
so, with an Update button that runs `horizon-server update` (section 5), and shows how it went.
```sh
horizon-server panel
+3 -3
View File
@@ -1,6 +1,6 @@
# Java performance packs (no longer developed)
Before the Rust rewrite, Horizon was a lab for Minecraft Java client performance: pinned Fabric performance packs, distant terrain, an original frame and tick recorder, and client and server starter downloads. This track is **no longer developed**. No release downloads are published; build the packs and starters locally with `python3 tools/build_release.py` (see [Build and run](#build-and-run)). This page keeps its documentation.
Before the Rust rewrite, Horizon was a lab for Minecraft Java client performance: pinned Fabric performance packs, distant terrain, an original frame and tick recorder, and client and server starter downloads (the server starter is gone: [horizon-server](hosting.md) replaces it). This track is **no longer developed**. No release downloads are published; build the packs and starters locally with `python3 tools/build_release.py` (see [Build and run](#build-and-run)). This page keeps its documentation.
## Java packs: Mac starter (out of scope)
@@ -91,9 +91,9 @@ python3 tools/build_mod.py
python3 tools/build_release.py
```
Gitignored `dist/` contains twenty packs, our original instrumentation JAR, client/server starter ZIPs and SHA256SUMS. [mods.lock.json](../packs/mods.lock.json) pins mod versions, exact dependency closure, SHA-1/SHA-512 and source/license; [fabric.lock.json](../packs/fabric.lock.json) pins loader/library SHA-256. Packs use the [Modrinth format](https://support.modrinth.com/en/articles/8802351-modrinth-modpack-format-mrpack). They embed only original project code; third-party mods, game and assets download from their publishers.
Gitignored `dist/` contains twenty packs, our original instrumentation JAR, the client starter ZIP and SHA256SUMS. [mods.lock.json](../packs/mods.lock.json) pins mod versions, exact dependency closure, SHA-1/SHA-512 and source/license; [fabric.lock.json](../packs/fabric.lock.json) pins loader/library SHA-256. Packs use the [Modrinth format](https://support.modrinth.com/en/articles/8802351-modrinth-modpack-format-mrpack). They embed only original project code; third-party mods, game and assets download from their publishers.
The server starter uses Lithium/FerriteCore and `/horizonserver bench <label> <seconds>`. [Server instructions](server-quickstart.txt) cover setup and a baseline. Files are prepared before you accept Minecraft's EULA locally. A 50-active-player workload remains to be measured.
The Fabric server starter (Lithium/FerriteCore, `tools/server.py`) was retired on 2026-10-19. To host a server, use [horizon-server](hosting.md) ([playhorizon.dev/server](https://playhorizon.dev/server)); its benchmarks are in [server.md](server.md), section 9.
Local smoke testing uses the game's built-in limited demo; normal play uses Prism's licensed account authentication:
-54
View File
@@ -1,54 +0,0 @@
Horizon server @PACK_VERSION@ — Minecraft 26.3, Fabric 0.19.5, Java 25
Install Python 3.10+ and native Java 25. Extract this ZIP and open a terminal here.
This starter never downloads the game: download the Minecraft 26.3 server jar
yourself (https://www.minecraft.net/download/server while 26.3 is current), then:
python3 tools/server.py prepare --server-jar PATH/TO/server.jar
Read Minecraft's EULA at https://www.minecraft.net/eula. Create/edit
.local/server/optimized/eula.txt to contain eula=true if you agree, then:
python3 tools/server.py run --heap 4G
Windows: use python in place of python3 if needed. Your server jar, mods and
assets stay in .local. No game code, third-party mod JARs or credentials are bundled.
Lithium and FerriteCore optimize the original simulation/storage; tick rate and
vanilla gameplay rules are retained. No Paper-style gameplay configuration.
From the server console:
horizonserver bench populated-50 120
horizonserver stop
From an operator's in-game chat, prefix each command with /. JSON/CSV reports
appear in the instance's horizon-benchmarks directory. They record actual peak
players, tick execution durations, observed tick count per elapsed second,
JVM heap/GC and platform metadata. meanRate is tick execution capacity, NOT TPS.
An idle server does not establish performance for 50 active players.
Baseline:
python3 tools/server.py prepare --baseline
python3 tools/server.py run --baseline --heap 4G
Use separate world copies with the same seed, settings, Java and maximum heap.
Only run one at a time unless you give them distinct ports/resources. When
benchmarking 50 players include normal exploration, entity farms, redstone and
chunk loading; repeat with 1, 10 and 100. Do not change simulation/view distance
between matched runs or turn off game logic to manufacture a speedup.
This first release has not been validated under a 50-player real workload.
Optional Java 25 HotSpot experiment: add --compact-headers to the run command.
Reports capture the actual compact object header flag and collector names.
Compare against the same workload with the flag omitted; object allocation
changes do not establish a whole-server RAM/TPS gain.
Optional collector comparison: select --gc g1 or --gc zgc on the run command.
Match world, player activity, heap, Java and header mode; use one collector at a
time. gc_time_ms includes collector cycle accounting, not a measured pause total.
Use JFR pause events for pause analysis and compare RSS/CPU/TPS together.
Compare generated reports:
python3 tools/compare_benchmarks.py baseline-ticks.json optimized-ticks.json --strict
Baseline must be a separate instance: --baseline adds no optimizers but doesn't
delete mods from an existing optimized instance. Use clean directories.
+35 -18
View File
@@ -7,8 +7,9 @@ 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 replaces the Java/Fabric starter (`docs/server-quickstart.txt`,
`tools/server.py`), which goes once the benchmark below exists.
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
https://playhorizon.dev/server.
## 1. Today
@@ -325,11 +326,12 @@ horizon-server backup [NAME] backups restore <backup> [-
horizon-server import <server.properties>
horizon-server service install|uninstall|print [--system]
horizon-server panel the panel's address and a one-time login link
horizon-server update [--check] [--version vX.Y.Z] [--timeout S] rollback [--timeout S]
horizon-server update --archive FILE --version NAME an archive you have (your own build)
Planned:
horizon-server console attach: the live log, and send commands (Ctrl-D detaches)
horizon-server ban|pardon <player> [reason] ban-ip|pardon-ip <address> (`cmd ban …` works now)
horizon-server update [--check] [--version vX.Y.Z] rollback
horizon-server import-resources <dir> prepare --server-jar PATH
horizon-server mcp MCP server on stdio (section 8)
```
@@ -350,8 +352,11 @@ line), and backups (list, back up now, restore with confirmation), with restart
the supervisor, so it is up exactly when the server is: starting a stopped server stays a command (or the
service manager's job). Whitelist and bans go through the console for now.
**Later:** bans and IP bans, worlds, updates with rollback, `server.properties` import, logs and crash
reports, and modpacks (with the modpack work).
**Updates:** when a newer release is out, the panel says so with an Update button, which runs the same
path as `horizon-server update` (section 7) and then shows how it went.
**Later:** bans and IP bans, worlds, `server.properties` import, logs and crash reports, and modpacks (with
the modpack work).
**Tech:** one HTML page with plain JS and CSS (`crates/horizon-server/panel/`), embedded in the binary with
`include_str!`. No build step, no framework, no CDN. It uses Horizon's design system tokens (`horizon-theme`'s
@@ -393,16 +398,29 @@ runtime or new dependency. Server-sent events can replace the polling later if a
lines and the engine's crash report (`crash-reports/`), restarts it after 5 s, and doubles the wait up to
5 minutes. It gives up after 5 crashes in 10 minutes, so it doesn't loop on a broken world, and shows the
reason in `status` and the panel.
- **Updates.** `update --check` compares with the latest GitHub release. `update`:
1. downloads the server archive and checks its SHA-256;
2. backs up the world;
3. keeps the current binaries as `.horizon/previous/`;
4. swaps in the new ones and restarts;
5. watches for `Done` within the start timeout and a first status reply.
- **Updates** (`crates/horizon-server/src/update.rs`), for a `horizon-server` installed by `install.sh` or
`install.ps1`. Releases ship often (release-flow.md), so updates stay opt-in: a running server looks for a
newer release a minute after it starts and then every 6 hours, and only says so, in its log, in `status`
and in the panel (`HORIZON_NO_UPDATE_CHECK=1` turns the check off). `update --check` asks GitHub once.
`update`:
1. downloads the release archive for this computer (on Linux the server build) and checks it against the
SHA-256 GitHub publishes for it;
2. unpacks it into `<dir>/releases/<tag>`, beside the others, with its game files linked to
`<dir>/game-files` as the installers do;
3. stops the game, backs up the world (`backups/<time>-before-<tag>.zip`), records the release in use in
`<dir>/previous` and points `<dir>/current` at the new one;
4. checks that the new game loads on this system (`--help`), then starts it;
5. waits until it has logged `Done` and answered a status request, for 300 s (`--timeout`).
If that check fails, it puts the previous binaries back, restores the world if the new engine touched it,
and restarts. `rollback` does the same by hand. Releases ship often (release-flow.md), so updates stay
opt-in, with `update --check` in `status` and a notice in the panel.
If the new game doesn't load, stops, or isn't up in time, the supervisor goes back by itself: `current`
points at the release before, `previous` is left as it was, the world is put back from the backup (the
one the new game left is kept in `backups/replaced-<time>/`), and the game starts again on the old
release. `rollback` switches to `previous` by hand, through the same path (the world is backed up first
and kept as it is). The supervisor keeps running as it was: the new `horizon-server` itself takes over
the next time the server starts (`stop` and `start`, or the service's restart). A stopped server is
switched and its new game checked to load; it starts on the new release next time. One install serves
every server folder on the machine, so each one runs the new release from its next start. Old releases
stay in `<dir>/releases/` until they are deleted by hand (keep `current` and `previous`).
## 8. Control API and MCP
@@ -411,7 +429,9 @@ runtime or new dependency. Server-sent events can replace the polling later if a
`.horizon/api.json`. It's plain HTTP/1.1 on `std::net` (`crates/horizon-server/src/http.rs`), no runtime.
- built (PR 2b, 2c): `GET status` (phase, uptime, crashes, RSS, CPU, and the engine's TPS, MSPT
average/P50/P95/P99, players, chunks), `GET logs?since=`, `POST command {line}` (returns the output),
`POST stop`, `POST restart`, `GET backups`, `POST backups {name}`, `POST restore {name}`;
`POST stop`, `POST restart`, `GET backups`, `POST backups {name}`, `POST restore {name}`, `POST update
{tag, timeout}` (without a tag: the newest release, downloaded first; `status` has an `update` object
that says how it went);
- planned: `GET metrics?since=` (the panel's graphs), `GET events` (SSE: log lines and metrics),
`GET`/`PATCH config` (server.toml fields, validated).
- **Auth.** Every call needs `Authorization: Bearer <token from .horizon/api.json>` (file mode 0600), and the
@@ -567,10 +587,7 @@ machine, then published in `benchmarks/`; and item 5.
- the Nether and End for remote players;
- the headless engine and its RAM win;
- a server-only prepare without a JDK;
- updates and rollback (the design is above; they ship right after);
- a Windows service, hot reload, modpacks in the panel;
- the website's "host a server" page;
- retiring `tools/server.py` and `docs/server-quickstart.txt` (once the benchmark replaces them).
Online mode works, so a public server can check accounts. An offline server should still run only on a
LAN, a tailnet, or behind a whitelist.