Mods: capability storage, a quota'd per-mod key/value folder

A mod with capability storage gets get(key)/set(key, value)/delete(key),
backed by real files beside horizon-mods/ (.horizon-mod-data/<id>/, 4 MiB
quota per mod). Keys are a single path segment so they can't leave the
mod's own directory. Unlike in-memory mod state, this survives a
cargo-horizon-mod dev reload, since it's keyed by the mod's path and id
rather than its Store.
This commit is contained in:
yvonne
2026-10-19 19:15:08 +02:00
parent defaa7cd2a
commit 8d55af7cae
7 changed files with 173 additions and 25 deletions
+7 -6
View File
@@ -11,7 +11,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
| Part | Where | State |
|---|---|---|
| The contract (WIT) | `crates/horizon-mod-sdk/wit/horizon.wit` | 0.1: log, game-read, chat, hud; tick, frame, chat and command hooks |
| The contract (WIT) | `crates/horizon-mod-sdk/wit/horizon.wit` | 0.1: log, game-read, chat, hud, storage; tick, frame, chat and command hooks |
| SDK for mod authors | `crates/horizon-mod-sdk` | 0.1 |
| Example mod | `crates/horizon-mod-sdk/examples/coords-hud` | coordinates, facing and time HUD, `/where`, `/coords` |
| Runtime | `crates/horizon-mods` | wasmtime 36 LTS, component model |
@@ -82,6 +82,7 @@ folder, loads no runtime and plays exactly like vanilla 26.3.
| `game` | `game-read` | `get-player()`: x y z, yaw, pitch, health, food, dimension; `get-clock()`: game time, day time |
| `chat` | `chat` | `show(text)`: a line only the local player sees, after the mod's name (8 per call) |
| `hud` | `hud` | `set-panel(corner, lines)`, `clear()`: up to 16 lines of 256 characters |
| `storage` | `storage` | `get(key)`, `set(key, value)`, `delete(key)`: a per-mod folder of files, 4 MiB total |
| Hook (export) | When |
|---|---|
@@ -111,7 +112,6 @@ loading. Ordered by what the first native ports need ([research](research/java-m
| `ui` | widgets: text, item icons, lists, a screen the mod owns, a settings page in Options > Mods | built on `ui_theme` so it matches the menus |
| `world-read` | blocks and biomes around the player, within the render distance | minimaps, schematics |
| `render` | world-space lines, boxes and ghost blocks in a per-frame budget | Litematica-style placement, waypoints |
| `storage` | a per-mod folder of key/value files, quota'd | settings, waypoints |
| `registries` | new blocks, items, entities and recipes, mostly data: JSON models, textures, loot and recipes in the `.hmod`'s `assets/` and `data/` | server side; see [Multiplayer](#multiplayer) |
| `server` | world events (block break/place, entity spawn/death, player join), game rules, server commands | runs where the world is simulated |
| `net` | a mod's own client↔server channel (custom payloads) | only between the two halves of the same mod |
@@ -208,8 +208,8 @@ cargo horizon-mod build # again after an edit: the running game relo
`run` starts `horizon-client` (on `PATH`, or `--game PATH`, or
`HORIZON_CLIENT`) with `--dev-mod target/horizon-mod/<id>.hmod`. A dev mod is
always on, and the game checks its file once a second: rebuild and it restarts
with "Mods reloaded" in chat. Its state starts over (persisted state comes with
`storage`).
with "Mods reloaded" in chat. Its in-memory state starts over; whatever it
saved with capability `storage` survives the reload.
### Template layout
@@ -398,8 +398,9 @@ none.
1. Design (this page) and the Java research.
2. SDK, example mod, runtime, `cargo horizon-mod`, the game's Mods page: API 0.1.
3. `keys`, `target`, `inventory-read`, `storage`, `ui`: enough for the first
native ports (zoom presets, AppleSkin-style food HUD, Jade-style tooltips).
3. `storage` (done), `keys`, `target`, `inventory-read`, `ui`: enough for the
first native ports (zoom presets, AppleSkin-style food HUD, Jade-style
tooltips).
4. Launcher Mods tab, the index, signatures; the Mods page shows cost and
update state.
5. `recipes`, `world-read`, `render`: recipe viewer and schematics ports.