Mod API 0.3: capability world for server mods (blocks, biomes)

Server mods get interface world: get-block(dimension, x, y, z) reads a
loaded chunk's block state as "minecraft:oak_log[axis=y]", get-biome its
biome ("minecraft:plains"), and
set-blocks(dimension, changes) sets up to 4096 blocks per call, checked at
once, made as /setblock makes them (place_state: neighbours, light, block
entities, every client told through the block log) after the call, before
that dimension's next tick.

Reads cost no copy: for a mod call the game lends Mods the levels' chunk
maps (moved out with mem::take and put back after), only while a running
mod has world. Writes for a level that isn't ticking (another dimension,
in-frame) wait for it, up to 65,536.

Test scripts get blocks (setup) and expect.blocks; cargo horizon-mod check
reports a trial run's block writes. Example beacons: /beacon builds a
glowstone pillar beside the player, /ground reads the block underfoot and the biome.
parse_state is now a free function so the mod path shares it.

Docs: docs/mods.md (the capability, script keys), docs/api/mods.md and the
regenerated reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Ludovic Marie
2026-10-25 18:48:38 +01:00
parent 3a35e147e5
commit 35a89eaebe
20 changed files with 658 additions and 50 deletions
+7 -5
View File
@@ -84,11 +84,11 @@ release.
What real mods need next, in the order modpacks and servers need it:
- **More for server mods** (`api = "0.3"`, [Server mods](../mods.md#server-mods-api-03-experimental)): they run
on the server thread, a LAN host and the dedicated server today, with joins, chat, commands and players' block
breaking and placing; next entity events, game rules, server commands with typed arguments sent to clients'
command trees.
- **World and blocks**: read blocks, block states and biomes in loaded chunks; change them through the server's block
log, so clients and the parity harnesses see vanilla's updates.
on the server thread, a LAN host and the dedicated server today, with joins, chat, commands, players' block
breaking and placing, and `world` (read blocks and biomes, set blocks as `/setblock` does); next entity events, game rules,
server commands with typed arguments sent to clients' command trees.
- **World and blocks**: blocks, block states and biomes are there for server mods (`world`); next block entities,
and `world` for client mods (raycasts, single player and LAN hosts).
- **Items and inventories**: the player's inventory, held item and open container; item stacks with components.
- **Entities**: query and change entities near a position; spawn from a mod's own entity types (data first).
- **Block entities and menus**: ticking machines with slots and their screens.
@@ -102,6 +102,8 @@ What real mods need next, in the order modpacks and servers need it:
## Changelog
- API 0.3: capability `world` (`get-block`, `get-biome`, `set-blocks`); example `beacons`; test scripts' `blocks` and
`expect.blocks`.
- Server mods run in the game: single player (server thread and in-frame), LAN hosts, the dedicated server.
- API 0.3 (server mods, experimental): world `horizon-server-mod`, capability `players`, the `server-events`
hooks; SDK `server::ServerMod`; example `welcome`.