3.5 KiB
Normalized module API v1
Conventions
All operations are cancellable and receive a host-enforced deadline. IDs and text returned by a game are untrusted, size-bounded UTF-8. Timestamps use RFC 3339 UTC. Unknown fields are rejected at typed ABI boundaries for V1.
Standard errors:
unsupported
invalid_configuration
unauthorized
unreachable
timeout
rate_limited
invalid_response
conflict
game_error
internal_module_error
Errors contain a safe user message, stable code and optional retryability. Raw credentials, authorization headers and unbounded game responses are prohibited.
Required exports
initialize(config) -> module_info
Validates declared configuration and returns module ID/version, API version and capabilities. It must not perform long-lived background work.
test_connection() -> connection_result
Makes the smallest safe request needed to validate reachability/authentication and reports server/API version hints when available.
get_server_status() -> server_status
Returns starting, ready, degraded, stopping, offline or unknown, plus a bounded safe reason.
Every module implements these three exports.
Optional capability exports
| Capability | Export | Result |
|---|---|---|
server_info |
get_server_info() |
name, game version, max players, optional world/version fields |
metrics |
get_metrics() |
bounded current gauges/counters, no long-term history |
player_list |
list_players() |
stable game player ID, display name, optional joined time/ping |
online_save |
save_world() |
acknowledgement that the game completed/persisted the save |
graceful_shutdown |
shutdown(request) |
accepted/completed state and safe message |
announcement |
send_announcement(message) |
accepted result |
kick |
kick_player(player_id, reason?) |
action result |
ban |
ban_player(player_id, reason?) |
action result |
unban |
unban_player(player_id) |
action result |
An optional export cannot exist as an enabled UI action unless manifest, runtime report, template and permission agree.
Host functions
http_request(instance_api, request)
Request fields: relative path, allow-listed method, bounded headers excluding host/connection overrides, bounded body and timeout not exceeding runtime maximum. The host fixes scheme, authority and destination port, validates redirects and bounds the response.
tcp_exchange(instance_api, request)
Available only when declared. Sends and receives bounded bytes on the bound declared TCP integration port with fixed connect/read/write deadlines. It is not a general socket handle.
get_secret(key)
Returns only a manifest-declared secret configuration item for the current instance. The value cannot be logged through diagnostics and should be consumed immediately.
emit_diagnostic(level, code, message)
Accepts bounded structured diagnostic data. The host redacts and rate-limits it. Modules cannot write directly to application logs.
Semantic requirements
save_worldsuccess means the game acknowledged completion, not merely request dispatch.shutdownnever stops a Docker container directly; lifecycle code observes container exit and uses the agent for timeout fallback.- Player actions use stable game IDs, not only display names.
- Metrics use documented normalized names/units. Unknown game-specific metrics may be omitted rather than smuggled into arbitrary maps in V1.
- All calls are side-effect-free except save, shutdown, announcement and player-action exports.