Live at https://playhorizon.dev. The game, the launcher and their developer docs are in horizon-rust/horizon; this repository is only the site.
The site is a Next.js 16 app (App Router with Cache Components, React 19, Tailwind CSS 4), designed and developed by Anthony S of DezerX.
You need Node 22 or newer.
git clone https://github.com/horizon-rust/horizon-site && cd horizon-site
npm ci
npm run dev # http://localhost:3000
npm run build && npm start # the production build, as Railway runs it
npm run lint- A push to
maingoes live. Railway builds theDockerfileand deploys https://playhorizon.dev within a few minutes of every push tomain. If the build or the healthcheck fails, the previous version stays online. For anything bigger than a typo, push a branch and open a pull request first.
app/ the routes: /, /download, /hub, /mods, /mods/<id>, /mods/submit, /mods/mine, /mods/policy,
/releases, /benchmarks, /stats, /docs, /docs/<page>, /privacy, /apply, and the staff's
pages inside the hub: /hub/team, /hub/mod, /hub/sign-in, /hub/setup, /hub/staff-help
(the old /staff/* addresses redirect there; /hub/mod has a Cases tab: Kira's numbered mod
cases and appeals), and /hub/appeal: the appeal form for people banned from the Discord
server or the official Minecraft server (the link Kira DMs, or Discord sign-in; Kira's
appeal/* routes behind the same proxy; timeouts and quarantines are appealed on Discord)
app/api/ the registry and players proxies, release view counts, and an account's registry
submissions (/api/mod-submissions, read from horizon-mods' pull requests for /mods/mine)
app/staff/api/ the staff dashboards' proxy to Kira's service
app/data/ /data/roadmap.json and /data/journal.json, which Kira reads
app/sitemap.ts, robots.ts, manifest.ts, opengraph-image.tsx, llms.txt/, og/docs/
search and sharing: sitemap, robots, share cards, the summary for AI search
app/perf/, lib/perf/ /perf: the performance capture viewer (its own root layout; strings in messages/perf/)
vendor/perf/ the pinned reader bundle's provenance and checksums
components/ every section, page part and data loader
components/site.ts the canonical address (SITE_URL), titles, descriptions and pageMetadata()
content/docs/ the player docs (*.md) and their navigation (nav.json)
content/benchmarks/ our benchmark runs
vendor/horizon-site/ the previous site's hub code, unchanged; it builds /data/journal.json
public/ images, icons and /benchmarks.json
Dockerfile, railway.json the Railway service
The /docs/api/* pages come from docs/api/ in the game's repository, read from GitHub.
/perf opens .hzperf captures recorded by the game's /profiler, horizon-ctl profile or a server's profile
command. The file is read in the browser by the game's capture reader, built to WebAssembly: pick a file, paste or
drop one. Compare takes a second capture the same ways. The game's [Open] (and horizon-perf open) serves the
file once on 127.0.0.1 behind a random token and opens /perf#local=http://127.0.0.1:<port>/<token>: the viewer
checks the address has exactly that form, drops the fragment, fetches the file once and opens it like a dropped one.
Only /perf's CSP allows connect-src to http://127.0.0.1:* and http://localhost:*. The Ticks, Spans, Functions, GPU, Memory, Network and World
tabs read the same capture.
The reader is not built here. public/perf/horizon_perf.wasm and its wrapper lib/perf/generated/horizon_perf.js
are checked in with the fonts and icon, so a build needs only Node. vendor/perf/manifest.json records the game
revision they were built from and each file's checksum; vendor/perf/source.patch holds any reader change that was
not committed when the bundle was imported. npm run perf:check verifies the bundle and runs before dev and
build. To update it, check out the game revision, then:
cargo xtask perf-wasm # in the game repository
npm run perf:import -- /path/to/horizon /path/to/perf-wasm-output
npm test && npm run typecheck && npm run lint && npm run buildImport the wasm and its wrapper together. npm test runs the viewer's unit tests (lib/perf/**/*.test.ts) and the
site's (components/*.test.ts).
Share shows what a capture can contain and asks before uploading; it is the only upload, and a link opens at
/perf/c/<id>. The upload API keeps the original bytes in an S3-compatible bucket and its metadata in SQLite
(node:sqlite); both need persistent storage, backed up together.
| Method | Path | Result |
|---|---|---|
| POST | /api/perf/captures |
Validates the raw bytes, stores them unchanged; returns an id, a temporary link and a delete token |
| GET | /api/perf/captures/<id> |
The original bytes, cached as immutable |
| GET | /api/perf/captures/<id>/meta |
Size, creation, expiry, share state and a summary from the reader |
| POST | /api/perf/captures/<id>/share |
Keeps it for PERF_SHARED_DAYS; needs Authorization: Bearer <delete_token> |
| DELETE | /api/perf/captures/<id> |
Deletes it; needs the same token |
| POST | /api/perf/sweep |
Removes expired or abandoned uploads; needs Authorization: Bearer $PERF_SWEEP_TOKEN |
An upload is validated by the same bundled reader in a worker, with a timeout and bounded inflation, at most two at a
time. Unshared uploads expire after an hour; sharing keeps one for 30 days from the first share. Expired links stop
answering at once; call the sweep endpoint every few minutes to free their bytes. New uploads stop at 90% of
PERF_STORAGE_BYTES, and shared captures are never evicted early. Replies: 415 not a capture, 422 a newer format,
413 too large, 403 wrong token, 507 storage full, 429 too many uploads. JSON replies are no-store.
| Variable | Default or requirement |
|---|---|
PERF_S3_ENDPOINT, PERF_S3_BUCKET |
Required |
PERF_S3_ACCESS_KEY, PERF_S3_SECRET_KEY |
Required |
PERF_S3_REGION |
us-east-1 |
PERF_PUBLIC_URL |
The public origin for share links; falls back to SITE_URL |
PERF_DATABASE |
.data/perf.sqlite |
PERF_MAX_BYTES |
67108864 (64 MiB per capture) |
PERF_STORAGE_BYTES |
1073741824 (1 GiB of captures in all) |
PERF_SHARED_DAYS |
30 |
PERF_HOURLY_UPLOADS |
20 uploads per address an hour |
PERF_TRUST_PROXY |
false; true only behind a proxy that sets X-Forwarded-For (its last entry is the client) |
PERF_SWEEP_TOKEN |
Required by /api/perf/sweep |
Without the PERF_S3_* variables the viewer still opens local files; only the API answers 503.
npm run test:api runs the built standalone server (.next/standalone, with public/ and .next/static copied in)
against the S3 endpoint in those variables: it uploads, reads, shares, deletes and rejects bad captures.
The summary shows 1% and 0.1% lows for frames and ticks, and the mean of each slow tail. A low is 1000 divided by the
mean duration of the slowest ceil(count × fraction) frames or ticks; tick lows are work-based TPS capped at 20. The
count and the rounding are shown so a short capture is not read as a large sample. Captures from before the recorder
kept every duration (SpanSummary.timing) show the lows as unavailable: the viewer never estimates them.
- GitHub's API: releases, contributors, the roadmap's issues and pull requests. Cached for about 15 minutes.
GITHUB_TOKENlifts the rate limit. - Fresh within a minute: every GitHub loader carries a cache tag (
components/github-fresh.ts: the game's main, its issues and pull requests, its releases, horizon-mods' main). Kira gets GitHub's organization webhook and callsPOST /api/revalidate(Authorization: Bearer $REVALIDATE_SECRET, body{"tags": [...]}) for what changed; the tagged data expires at once and Kira loads the main pages again. Files of a main branch are read at its current commit (rawMainUrl), because raw.githubusercontent.com keeps a branch's files for five minutes. Without the call, each loader's owncacheLifeapplies, as before. - Through Kira:
components/github-api.tssends the REST reads toGITHUB_PROXY_URL(Kira's allowlisted proxy), so revalidating on every change doesn't run into the 60 requests an hour this host gets without a token. - The game's
main:README.md(parity numbers),roadmap/roadmap.json(the hub) anddocs/api/*.md. - The mod registry: the index at horizon-rust.github.io/horizon-mods, ratings and submissions through
REGISTRY_UPSTREAM. - The official server's market:
/hub/marketreads Kira's/smp/market.json(the page the SMP mod writes on the server, read by Kira once a minute) through/api/market. - Telemetry: the Players page reads
telemetry.playhorizon.dev(orTELEMETRY_URL) through this site's server. - Cosmetics:
/shop(the founder set, free to claim in the launcher) readscosmetics.playhorizon.dev's/v1/catalogueand the items' files through this site's server, cached for a minute. The page, its nav entry and its sitemap line exist only while the service says the claim window is open; otherwise/shopis a 404. Nobody signs in on the site.
/data/roadmap.json is the game repository's roadmap/roadmap.json as it is. /data/journal.json is built by
journalJson() in vendor/horizon-site/hub.js, the previous site's code, from the same GitHub requests the previous
build made. Kira posts each entry id once, so the ids must not change: leave vendor/ and
components/journal-feed.ts alone unless Kira is changed with them. When GitHub does not answer, both feeds answer
503 instead of a partial feed.
Railway service variables:
| Variable | What it does |
|---|---|
GITHUB_TOKEN |
Lifts GitHub's rate limit at build and at run time |
REVALIDATE_SECRET |
The bearer token Kira sends to POST /api/revalidate (1Password Site revalidate secret; the same value is Kira's KIRA_SITE_REVALIDATE_SECRET). Without it the route answers 404 |
GITHUB_PROXY_URL |
https://mcp.playhorizon.dev/github/proxy: GitHub's REST API read through Kira (its GitHub App and ETag cache, with REVALIDATE_SECRET as the bearer), since this service has no GitHub token; when Kira doesn't answer, reads go to api.github.com directly |
REGISTRY_UPSTREAM |
The registry's submission service; /api/mods/* is proxied to it |
STAFF_UPSTREAM, STAFF_PROXY_KEY |
Kira's staff service and the key both sides hold; /staff/api/* is proxied to it |
RELEASE_VIEWS_SALT |
Salt for the hashed release views. Without it the server keeps one in .data/ |
TELEMETRY_URL |
Optional, defaults to https://telemetry.playhorizon.dev |
KIRA_URL |
Optional, Kira's address for /api/market; defaults to https://kira-production-500e.up.railway.app |
SITE_URL |
Optional, defaults to https://playhorizon.dev; used for canonical links, the sitemap and share cards |
COSMETICS_UPSTREAM |
Optional, defaults to https://cosmetics.playhorizon.dev: the cosmetics service /shop reads (server side only). Point it at a local stand-in for development and tests only, never on production |
SHOP_PREVIEW |
1 shows /shop with a sample seven-day claim window (from the start of the current hour) while the service's window is closed, for previews. Never set it on production (it is ignored where RAILWAY_ENVIRONMENT_NAME is production) |
Release view counts live in .data/, which is reset by every deploy unless a volume is mounted at /app/.data.
- The disclaimer, "Not an official Minecraft product. Not approved by or associated with Mojang or Microsoft.", is under the headline, in the phone menu, the footer and the 404 page.
- No Minecraft logo or wordmark; "Minecraft" appears only descriptively ("for Minecraft: Java Edition 26.3"). No game files are offered or linked.
- Parity is worded as what the harnesses compare, never as a percentage or a "100% parity" claim (decided 2026-11-09); the parity section's numbers are where the project started.
- No cookies, analytics, trackers or third-party fonts and scripts.
- Motion stops under
prefers-reduced-motion; nothing hijacks the scroll.
Every asset is listed in LEGAL.md.