デバッグプロトコル

リモートデバッグプロトコルは、debug モジュールをリンクするすべての Turian ゲームビルドに組み込まれた軽量な JSON-RPC 2.0 サーバーです。ランタイムイントロスペクションレイヤーを TCP 経由で公開し、CLI、MCP サーバー、カスタムスクリプトなどの外部ツールがライブのエンジン状態をクエリしたり（オプションで）変更したりできるようにします。

ワイヤフォーマット

1 行に 1 つの JSON オブジェクト（\n で終端）。Content-Length ヘッダーはありません。

リクエスト：

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

成功レスポンス：

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

エラーレスポンス：

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

メソッド

シーン

エンティティ

コンポーネント

アセット

診断

変更（読み書きモードのみ）

変更メソッドは { "ok": bool, "message": string } を返します。サーバーが読み書きモード（allow_write / CLI --rw）で起動されている必要があります。そうでない場合は READONLY を返します。Studio では、すべての変更はエディターのアンドゥスタックを通じてルーティングされるため、AI/CLI による編集は元に戻すことができ、UI と一貫性が保たれます。

セッションとイベント

購読中のクライアントは、イベント発火時に JSON-RPC 通知（id なし）を受信します：

Turian Studio では、シーンタブを開く、切り替える、閉じる際に scene.loaded / scene.unloaded が発火し、fps.changed はエディター自身のフレームタイミングに基づいて駆動されます。そのため、Play モードだけでなく編集中にも刻みます。

エラーコード

デバッグサーバーの起動

const debug = @import("debug");

var srv = debug.Server.init(allocator, .{
    .port = 7777,
    .localhost_only = true,
    .auth_token = "",            // 空 = 認証なし
    .allow_write = false,        // true で変更を許可
    .max_clients = 8,
    .rate_limit_per_sec = 0,     // 0 = 無制限
    .max_outbound_queue = 2048,  // クライアントごとのイベントバックログ上限
    .max_outbound_bytes = 16 << 20,
    .max_inbound_queue = 4096,   // 全クライアントの保留中リクエスト
});
defer srv.deinit(io);
try srv.start(io);          // 受け入れループのみを起動

// メインスレッドで毎フレーム：
srv.pump(world, applier);   // ライブ状態に対してキューされた読み取り/書き込みを実行

受け入れループはバックグラウンドスレッドで実行されますが、すべてのリクエストはメインスレッドの pump 内で実行されます。そのため、読み取りは競合がなく、書き込みはロックなしでライブのエンジン状態を操作できます。複数のクライアントを同時にサポートします。変更はホスト提供の MutationApplier を通じて適用されます。イベントは srv.emit(...) で発行されます。srv.stop(io) を呼び出してクリーンにシャットダウンします。

大きなレスポンスとバックプレッシャー

大規模なシーンの完全な snapshot は 64 KiB をはるかに超えてシリアライズされます。メッセージは改行区切りですが、64 KiB に制限されていません。クライアントとサーバーの両方が読み取りバッファをヒープ上で 16 MiB のハード上限まで拡張するため、大きなレスポンスも失敗せずに完全に到着します。

各接続の送信イベントキューには上限があります（max_outbound_queue / max_outbound_bytes）。読み取りを停止した購読者の最も古いイベントはドロップされます（イベントは本質的に非保証です）。これにより、サーバーメモリが無制限に増加するのを防ぎます。保留中のレスポンスを受信できないほど遅れているクライアントは切断されます。共有の受信キューは max_inbound_queue で制限されています。満杯になると、新しいリクエストは明確な「サーバー繁忙」エラーで拒否されます。

ネットワーク露出。 localhost_only = false を設定すると 0.0.0.0 にバインドされ、TLS はありません。auth_token（およびすべてのトラフィック）は平文で送信され、それが唯一のゲートです。ファイアウォール/VPN の背後にある信頼できる LAN 上でのみ使用し、デバッグサーバーをパブリックインターネットに公開しないでください。

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
# 変更（サーバーは読み書きモードである必要があります）：
turian-cli debug set Player Light intensity 2.5
turian-cli debug spawn Crate
turian-cli debug destroy Crate
# イベントとセッション：
turian-cli debug watch entity.created fps.changed
turian-cli debug record session.jsonl
turian-cli debug replay session.jsonl

完全なサブコマンド一覧については turian-cli debug --help を参照してください。

デフォルトポート

7777。サーバー側とクライアント側の両方で --port で上書きできます。

← すべてのドキュメント このページを編集