Mod API levels: refuse a mod made for a newer Horizon, list each version's level

Every function the game offers mods has the API level it arrived at
(crates/horizon-mods/src/api_level.rs): level 0 is the contract of
Horizon 0.2.67 and 0.2.68, level 1 adds render.set-minimap. A mod needs
the level of the newest function it imports, read from its component.

- The game refuses a mod that calls a function it doesn't have with
  "made for a newer Horizon (it uses ...): update Horizon to run it"
  instead of wasmtime's linking error.
- The registry index lists each mod version's level (api_level, read
  from the file by CI); check_file compares it when the entry has one,
  and the moved extras' installer takes the newest version this game
  can run.
- cargo horizon-mod check prints the level.
- The api_reference test fails until a new WIT function has a level.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-26 10:38:57 +01:00
parent 45bc45b396
commit 8cc8c6180d
17 changed files with 412 additions and 16 deletions
+16
View File
@@ -34,6 +34,22 @@ Not breaking: a new function, interface, capability, command, endpoint, tool or
argument or JSON field (readers must ignore fields they don't know); a new WIT function or type (mods built earlier
don't import it); faster, or fixing behaviour to what the reference already says.
### Mod API levels
A new WIT function doesn't break older mods, but a mod that calls it can't run on a Horizon from before it. So every
function the game offers mods has an **API level**, the one it arrived at (`crates/horizon-mods/src/api_level.rs`):
level 0 is the contract of Horizon 0.2.67 and 0.2.68, level 1 adds `render.set-minimap`. A mod needs the level of
the newest function it imports (a component imports only the functions it calls). The level is read from the file,
never declared:
- the game refuses a mod that needs a function it doesn't have, with "made for a newer Horizon (it uses
render.set-minimap): update Horizon to run it", instead of a linking error;
- the registry's CI writes each mod version's level into the index (`api_level`), and installers take the newest
version the running game can run.
A pull request that adds a function lists it in `api_level.rs` at the next level and raises `LEVEL`; the
`api_reference` test fails until it does.
## Stability levels
Every part of an API has one level, shown in its reference and its surface page.