Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

The release

Every SDK is the release sdk-<build id> of this repository, at https://github.com/arismoko/horizon/releases/download/sdk-<build id>/<file>. Its files:

FileKindHolds
surface.jsonsurfaceThe stable surface: everything an API-only mod can name, each item with its fingerprint (surface.json).
build-data.tar.xzbuild-datapoints.json, internals.json, loops.json and functions.json: data pinned to this build, with no compatibility promise.
api-source.tar.xzapi-sourceThe mod API's crates with their generated code written out: what a mod project's .horizon/sdk/api/ holds.
runtime-aarch64-apple-darwin.tar.xz, runtime-x86_64-pc-windows-gnu.tar.xz, runtime-x86_64-unknown-linux-gnu-server.tar.xz, runtime-x86_64-unknown-linux-gnu.tar.xzruntimeThe game's libraries, the prebuilt program the API route links mods into, its stub mods library and the package's identity file.
api-aarch64-apple-darwin.tar.xz, api-x86_64-pc-windows-gnu.tar.xz, api-x86_64-unknown-linux-gnu-server.tar.xz, api-x86_64-unknown-linux-gnu.tar.xzapiMetadata of the mod API's crates and their procedural macros, the point data and the mods library's template: what a mod on the mod API alone builds against.
engine-aarch64-apple-darwin.tar.xz, engine-x86_64-pc-windows-gnu.tar.xz, engine-x86_64-unknown-linux-gnu-server.tar.xz, engine-x86_64-unknown-linux-gnu.tar.xzengineEvery other file of the prebuilt game: what a mod with a [native.*] table, game internals or a registry dependency builds against as well.
sdk.jsonThe index: the build, every other asset with its SHA-256, size, kind and codec (fields).
SHA256SUMSThe SHA-256 of every file of the release.
SHA256SUMS.sigHorizon's signature over SHA256SUMS for the tag sdk-<build id>.

The compiled slices exist once per host; a file named …-server.tar.xz is the dedicated server's. Everything else exists once per build. .tar.xz files are tar archives compressed with xz; surface.json is the file itself.

A Nightly carries a copy of its build's sdk.json in its own signed sums. The launcher learns which build a game is from the copy in that game's release, and keeps the answer, so it is known offline afterwards.

Which slices a build needs

The launcher fetches only the compiled slices the instance's mods need, decided once for the whole set of enabled mods. The routes and their slices come from the same input list the launcher and the packager read:

RouteWhenSlices it fetches
apiEvery enabled mod uses the mod API alone.runtime, api
engineA mod has a [native.*] table, names game internals, or depends on a registry (crates.io) crate.runtime, api, engine

Each slice unpacks into its own folder. Using a kept slice again checks only its files' names and sizes against a stamp written after its verified unpack; it does not hash them again.

sdk.json

The index. Readers ignore fields they don't know and refuse a schema they don't know: adding a field keeps the number, removing or redefining one changes it.

FieldWhat it is
schemaThe index's schema number (1).
build.commitThe build id: the game's full commit sha.
build.gameThe vanilla version the build implements (26.3).
build.dateThe commit's date, YYYY-MM-DD, UTC.
build.nightlyThe Nightly name that ships this build, when one does.
package_formatThe prebuilt package's layout number. A reader takes only the number it was made for.
toolchain.rustThe Rust release everything in the SDK was compiled with.
content_apiThe content manifest's version: the api key of horizon-mod.toml.
surface.hashsurface.json's own hash: equal hashes, equal surface.
surface.previousThe build id of the SDK published before this one, which it is compared with. Absent on the first.
surface.sourceThat comparison in one word, its worst change: identical, additive, conditional or breaking (classes).
surface.changesThe ids of the records that changed, breaking ones first.
surface.notesThe change notes attached to them, each { ids, why, migrate } (notes).
mixins.rev, mixins.patchThe pinned horizon-mixins tool's revision and the SHA-256 of the patch carried on it.
assetsEvery file of the release but sdk.json and the sums, by name: sha256, size, kind, codec (none or xz), and for a compiled slice its target and side (client or server).
inputsThe files each route needs, named before any download, build or packaging starts: its SDK slices, the programs beside the game and the checkout files, how to make each, and what each slice must hold.

How a download is checked

The mod tool and the launcher check an SDK the same way, whatever the base it came from, and refuse it by name at the first step that fails:

  1. SHA256SUMS carries Horizon's signature for the tag sdk-<build id>. That signature never passes for a game release, and a game release's never passes for an SDK.
  2. sdk.json is the file those sums list, names this build, has a schema and package format the reader knows, and lists only assets of known kinds and codecs under plain file names.
  3. Every other file has the size and SHA-256 sdk.json gives, checked before it is decoded. An archive unpacks into a temporary folder, renamed into place only when every entry unpacked, and is refused past an unpacked size limit or for any entry that is not a plain file or folder inside it.

An SDK newer than the launcher reads (its schema, package format or Rust) asks for a launcher update; one made with an older Rust than the launcher compiles with asks for a newer game build.