Merge remote-tracking branch 'origin/main' into feat/server-bench-paper-fabric
# Conflicts: # docs/server.md
This commit is contained in:
+1
-1
@@ -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
@@ -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
@@ -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
@@ -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:
|
||||
|
||||
|
||||
@@ -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
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user