Ludovic Marie
0a1d3a7534
docs/api/ gets one page per surface other programs build on (mods, shaders, agent control, servers, the launcher, data formats), each with an overview measured from the source, the guide, the generated reference, examples, its stability, what is not there yet and a changelog, plus the policy every API follows (docs/api/stability.md): a version per API, semver lines, experimental / preview / stable, deprecation windows, compatibility tests and the level of every part today. The website gets a "Build on Horizon" page (website/docs/apis.md) that summarises them and links the repository's pages. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
41 lines
2.8 KiB
Markdown
41 lines
2.8 KiB
Markdown
# 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](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](../benchmark-report.md) |
|
|
| Telemetry batch | `POST /v1/batch` from the launcher | `"schema": 1` | stable | [telemetry.md](../telemetry.md) |
|
|
| Telemetry consent | `telemetry/consent.json` in the game folder | `"version": 2` | stable | [telemetry.md](../telemetry.md) |
|
|
| Mod package | `.hmod`: a zip with `horizon-mod.toml`, `mod.wasm`, `assets/`, `data/` | the manifest's `api` | preview | [mods.md](../mods.md#the-manifest), [mods-reference.md](mods-reference.md) |
|
|
| Mods turned on | `horizon-mods.txt` | none | preview | [mods.md](../mods.md#playing-with-mods) |
|
|
| Horizon settings | `horizon-graphics.txt`, `horizon-extras.txt` (`key:value`, as `options.txt`) | none: unknown keys fall back to defaults | preview | [graphics.md](../graphics.md), [extras.md](../extras.md#options-storage) |
|
|
| Server settings | `server.toml` | its keys | stable | [server-reference.md](server-reference.md) |
|
|
| Control endpoints | the game's socket file (TCP form), `.horizon/api.json` | none | preview | [agent-control.md](agent-control.md), [server-reference.md](server-reference.md) |
|
|
| Release checksums | `SHA256SUMS`, `SHA256SUMS.sig` on releases since signing began (#1011) | the signed text names the tag | stable | [security.md](../security.md) |
|
|
| Worlds | the world folder | vanilla 26.3's (`DataVersion`) | vanilla's | [world-data.md](../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.
|