Debug Protocol

The Remote Debug Protocol is a lightweight JSON-RPC 2.0 server embedded in every Turian game build that links the debug module. It exposes the Runtime Introspection Layer over TCP so external tools — the CLI, the MCP server, and custom scripts — can query and (optionally) mutate live engine state.

Wire format

One JSON object per line (\n-terminated). No Content-Length headers.

Request:

{"jsonrpc":"2.0","id":1,"method":"entity.inspect","params":{"name":"Player"}}

Success response:

{"jsonrpc":"2.0","id":1,"result":{...}}

Error response:

{"jsonrpc":"2.0","id":1,"error":{"code":-32000,"message":"Entity not found"}}

Methods

Scene

Entity

Component

Assets

Diagnostics

Mutations (read-write mode only)

Mutating methods return { "ok": bool, "message": string }. They require the server started in read-write mode (allow_write / CLI --rw); otherwise they return READONLY. In the Studio every mutation routes through the editor's undo stack, so AI/CLI edits are undoable and consistent with the UI.

Sessions & events

Subscribed clients receive JSON-RPC notifications (no id) as events fire:

In Turian Studio, scene.loaded / scene.unloaded fire as you open, switch, or close scene tabs, and fps.changed is driven from the editor's own frame timing — so it ticks while you edit, not only in Play mode.

Error codes

Starting the debug server

const debug = @import("debug");

var srv = debug.Server.init(allocator, .{
    .port = 7777,
    .localhost_only = true,
    .auth_token = "",            // empty = no auth
    .allow_write = false,        // true to permit mutations
    .max_clients = 8,
    .rate_limit_per_sec = 0,     // 0 = unlimited
    .max_outbound_queue = 2048,  // per-client event backlog cap
    .max_outbound_bytes = 16 << 20,
    .max_inbound_queue = 4096,   // pending requests across all clients
});
defer srv.deinit(io);
try srv.start(io);          // spawns the accept loop only

// Once per frame, on the main thread:
srv.pump(world, applier);   // executes queued reads/writes against live state

The accept loop runs on a background thread, but every request is executed on the main thread inside pump — so reads are race-free and writes can touch live engine state with no locking. Multiple clients are supported simultaneously. Mutations are applied through a host-supplied MutationApplier; events are emitted with srv.emit(...). Call srv.stop(io) to shut down cleanly.

Large responses & backpressure

A full snapshot of a large scene serialises well past 64 KiB. Messages are newline-framed but not capped at 64 KiB — both client and server grow the read buffer on the heap up to a 16 MiB hard ceiling, so big responses arrive intact rather than failing.

Each connection's outbound event queue is bounded (max_outbound_queue / max_outbound_bytes). A subscriber that stops reading has its oldest events dropped (events are lossy by nature) instead of growing server memory without limit; a client too far behind to take a pending response is disconnected. The shared inbound queue is bounded by max_inbound_queue; once full, new requests are rejected with a clear "server busy" error.

Network exposure. Setting localhost_only = false binds 0.0.0.0 and there is no TLS — the auth_token (and all traffic) is sent in the clear and is the only gate. Use this only on a trusted LAN behind a firewall/VPN; never expose the debug server to the public internet.

Using from turian-cli

turian-cli debug connect
turian-cli debug scenes
turian-cli debug inspect Player
turian-cli debug snapshot
turian-cli debug schema
turian-cli debug metrics
turian-cli debug assets
turian-cli debug errors
# mutations (server must be read-write):
turian-cli debug set Player Light intensity 2.5
turian-cli debug spawn Crate
turian-cli debug destroy Crate
# events & sessions:
turian-cli debug watch entity.created fps.changed
turian-cli debug record session.jsonl
turian-cli debug replay session.jsonl

See turian-cli debug --help for the full subcommand list.

Default port

7777. Override with --port on both server and client side.

← All docs Edit this page