horizon-airdef/docs/api/mods-reference.md

Mod API reference

The contract between Horizon and its mods: the WIT package horizon:mods@0.1.0, every interface, type, function and hook in it, and the capabilities a manifest may list. The guide is mods.md; stability and versions: stability.md. Manifest api lines this game serves: 0.1, 0.2.

Capabilities

In capabilities	Grants	The player reads "May …"
game-read	game	see your position, health and the time
chat	chat	show you chat messages
hud	hud	draw text on your screen
storage	storage	save its own settings to disk
command	command	run commands as you, with your permissions
registries	data files (assets/, data/), no interface	add blocks and items to your worlds

World horizon-mod

• Imports (what the game offers): log, game, chat, hud, storage, command
• Exports (what the mod provides): events

log

Access: always granted.

The mod's log, in the game's log under the mod's id. Always granted.

enum level

Case
debug
info
warn
error

Function	Signature	What it does
write	func(level: level, message: string)	One line in the game's log as [mod <id>] message, at that level.

game

Access: capability game-read.

Capability game-read: the local player and the world clock.

record player

Field	Type
x	f64	Feet position, in blocks.
y	f64
z	f64
yaw	f32	Degrees, as F3 shows them.
pitch	f32	Degrees: -90 looks straight up, 90 straight down.
health	f32	Hit points as vanilla counts them: 20 is full health without effects.
food	u32	0 to 20, as the hunger bar.
dimension	string	minecraft:overworld, minecraft:the_nether, ...

record clock

Field	Type
game-time	u64	Ticks since the world was created.
day-time	u64	24000 ticks per day; 0 is 6:00 on the first day.

Function	Signature	What it does
get-player	func() -> option<player>	None on the title screen.
get-clock	func() -> option<clock>	None on the title screen.

chat

Access: capability chat.

Capability chat: messages only the local player sees.

Function	Signature	What it does
show	func(text: string)	Shown in chat after the mod's name, like a system message.

hud

Access: capability hud.

Capability hud: one panel of text lines per mod, drawn by the game every frame until the mod changes or clears it (no call per frame).

enum corner

Case
top-left
top-right
bottom-left
bottom-right

record line

Field	Type
text	string	Plain text, up to 256 characters.
color	u32	0xRRGGBB.

Function	Signature	What it does
set-panel	func(corner: corner, lines: list<line>)	Replaces the mod's panel: up to 16 lines in that corner of the screen.
clear	func()	Removes the mod's panel.

storage

Access: capability storage.

Capability storage: a per-mod folder of small key/value files, quota'd (docs/mods.md). Keys are [a-z0-9_.-]{1,64}, one path segment.

Function	Signature	What it does
get	func(key: string) -> option<list<u8>>	None if key has never been set, or the key is not well-formed.
set	func(key: string, value: list<u8>) -> result<_, string>	Errs on a malformed key or over quota (bytes for the whole mod).
delete	func(key: string)	No error if key was already absent.

command

Access: capability command.

Capability command: vanilla commands run as the player, with the player's permissions, after the hook call returns (8 per call). A mod's own commands are not run this way.

Function	Signature	What it does
run	func(line: string)	line without its slash; its feedback goes to the chat as if typed.

events

Access: exported by the mod: the game calls it.

What the game calls. Only the hooks init asks for are ever called.

record registration

Field	Type
commands	list<string>	Chat commands, without the slash. A name vanilla already uses is refused (vanilla's command runs).
tick	bool	Call tick every game tick (20 per second while playing).
frame	bool	Call frame every rendered frame. Budget: 0.1 ms.
chat	bool	Call chat for each chat line the player receives.

Function	Signature	What it does
init	func() -> result<registration, string>	Once, after loading. An error keeps the mod off and is shown.
tick	func(tick: u64)	Each game tick while in a world, with the game's tick counter.
frame	func(seconds: f32)	Each rendered frame, with the seconds since the last one.
command	func(name: string, args: string) -> result<option<string>, string>	/name args: ok(some(text)) is shown as feedback, err(text) in red.
chat	func(text: string)	Each chat line the player receives, as plain text.