Ludovic Marie
0a1d3a7534
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 <noreply@anthropic.com>
56 lines
2.9 KiB
Markdown
56 lines
2.9 KiB
Markdown
# 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](../agent-control.md); for players:
|
|
[playhorizon.dev/docs/agents](https://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
|
|
|
|
1. 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>`.
|
|
2. `horizon-ctl --socket … state`, `keys`, `turn`, `command`, `screenshot`, `quit`.
|
|
3. For an agent: `horizon-ctl mcp`, or the launcher's `horizon-launcher mcp` with `agent-config` to connect a client
|
|
([launcher-commands.md](../launcher-commands.md)).
|
|
|
|
## Reference
|
|
|
|
[horizon-ctl-commands.md](../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](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.
|