0 Fork 0

mirror of https://github.com/horizon-rust/horizon.git synced 2026-11-07 11:06:11 -10:00

Files

T

Ludovic MarieandClaude Opus 5.5 0a1d3a7534 Horizon APIs: the docs portal and the stability and versioning policy

docs/api/ gets one page per surface other programs build on (mods,
shaders, agent control, servers, the launcher, data formats), each with an
overview measured from the source, the guide, the generated reference, examples,
its stability, what is not there yet and a changelog, plus the policy every
API follows (docs/api/stability.md): a version per API, semver lines,
experimental / preview / stable, deprecation windows, compatibility tests and
the level of every part today.

The website gets a "Build on Horizon" page (website/docs/apis.md) that
summarises them and links the repository's pages.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

2026-10-24 20:50:20 +02:00

2.9 KiB

Raw Blame History

Agent control API

How a program drives a running game: an AI agent through MCP, a script through horizon-ctl, a test through the control socket. Design and inventory: agent-control.md; for players: playhorizon.dev/docs/agents.

Overview

The game listens on a local control socket (a Unix socket, or localhost TCP with a token on Windows), takes one command per text line and answers one JSON line. horizon-ctl wraps it: it starts the game, sends commands and serves the same commands as MCP tools. The launcher's MCP server offers them too, as game_<tool>.

	Count
`horizon-ctl` commands	96, in 8 groups (session, observe, move and look, act, screens and chat, multiplayer, world and cheats, scripting and benchmarks)
MCP tools	88 (8 commands are CLI only)
Destructive commands (need `--confirm`)	3
Command names the game's socket answers	about 160, test hooks included (`horizon-ctl help --game`)

Guide

Build horizon-ctl (cargo build --profile fast -p horizon-client), then horizon-ctl --socket $PWD/ctl.sock launch --world W --creative --wait --resources <prepared files>.
horizon-ctl --socket … state, keys, turn, command, screenshot, quit.
For an agent: horizon-ctl mcp, or the launcher's horizon-launcher mcp with agent-config to connect a client (launcher-commands.md).

Reference

horizon-ctl-commands.md, generated from the command table in crates/horizon-client/src/bin/horizon-ctl/commands.rs: every command, its MCP tool and its arguments.

Examples

tools/agent_control_e2e.py: starts a game and drives it end to end through horizon-ctl and MCP.
tools/lan_e2e.py: two games over LAN, both driven through their sockets.

Stability

Preview (stability.md). The commands in horizon-ctl's table and their MCP tool names are what the API offers; the other commands the game's socket answers are test hooks and experimental.

Not there yet

A version. A hello command that answers the protocol version, the game's release and the features it has; MCP serverInfo carries the same version; horizon-ctl refuses a game whose major it doesn't speak.
Reply schemas. Each command's reply described in the table (fields, types, units), so the reference documents replies as well as arguments and MCP tools declare an output schema.
Events as a stream. events --since polls today; a subscription that pushes events as they happen.
Test hooks apart. The hooks only harnesses use move under their own prefix, out of the agent's tool list.
Compatibility tests. A transcript per protocol version: commands and the reply keys each must keep.

Changelog

Unversioned so far: the command table and the generated reference are the contract.

2.9 KiB Raw Blame History