RustNotMC/docs/api/data-formats.md

Data formats

The files Horizon writes that other tools may read: benchmark reports, telemetry, settings, mods, release checksums and worlds. Each entry names its version field, its documentation and its level (stability.md).

Overview

Format	Where	Version	Level	Documented in
Benchmark report	the benchmark's output, the local log, uploads	"format": "horizon-benchmark-report", "version": 1	stable	benchmark-report.md
Telemetry batch	POST /v1/batch from the launcher	"schema": 1	stable	telemetry.md
Telemetry consent	telemetry/consent.json in the game folder	"version": 2	stable	telemetry.md
Mod package	.hmod: a zip with horizon-mod.toml, mod.wasm, assets/, data/	the manifest's api	preview	mods.md, mods-reference.md
Mods turned on	horizon-mods.txt	none	preview	mods.md
Horizon settings	horizon-graphics.txt, horizon-extras.txt (key:value, as options.txt)	none: unknown keys fall back to defaults	preview	graphics.md, extras.md
Server settings	server.toml	its keys	stable	server-reference.md
Control endpoints	the game's socket file (TCP form), .horizon/api.json	none	preview	agent-control.md, server-reference.md
Release checksums	SHA256SUMS, SHA256SUMS.sig on releases since signing began (#1011)	the signed text names the tag	stable	security.md
Worlds	the world folder	vanilla 26.3's (DataVersion)	vanilla's	world-data.md

Worlds are vanilla's format, so any tool that reads a 26.3 world reads a Horizon world; Horizon adds itself to level.dat's ServerBrands as vanilla's server does.

Rules for every format

• A reader ignores fields it doesn't know, and refuses a version newer than it knows with a clear message.
• An optional field may be added in the same version; renaming, removing or changing the meaning of a field makes the next version, and Horizon's own readers keep reading the older ones for the deprecation window.
• Each versioned format has a sample file of every version its reader accepts, read by a test.

Not there yet

• Versions for the settings files and the control endpoint files (a version line or field).
• Sample files and reader tests for every versioned format.
• A generated schema for the benchmark report and the telemetry batch from their Rust types, checked by a test like the references.

Changelog

• Benchmark report version 1; telemetry schema 1, consent version 2.