イントロスペクション

ランタイムイントロスペクションレイヤー（engine.introspect）は、構造化された JSON シリアライズ可能なライブエンジン状態のビューを、グローバル変数やアロケーションなしで提供します。これは、リモートデバッグプロトコル、MCP サーバー、Studio インスペクターが利用する単一の信頼できる情報源です。

主要な型

const engine = @import("engine");

// ホストからインスペクターに渡される、読み込まれた 1 つのシーンの読み取り専用ビュー。
const SceneView = engine.introspect.SceneView;

// インスペクターが一瞬で見ることができるすべての情報。
const World = engine.introspect.World;

// 変更操作のための型付き値。
const Value = engine.introspect.Value;

World スナップショットの提供

ホスト（ゲームまたは Studio）は World を返すコールバックを実装します：

fn myWorldProvider(ctx: ?*anyopaque) engine.introspect.World {
    const state: *GameState = @ptrCast(@alignCast(ctx));
    return .{
        .scenes = state.sceneViews(),
        .metrics = &state.metrics,
    };
}

コールバックはデバッグサーバーのバックグラウンドスレッドでリクエストごとに 1 回呼び出されます。同時アクセスに対して安全な読み取り専用ビューを返す必要があります。フレームスナップショットで十分です。

シリアライゼーションヘルパー

// ワールド全体を JSON としてスナップショット（ヒープ割り当て）。
const json = try engine.introspect.snapshotJsonAlloc(allocator, world);
defer allocator.free(json);

// または、任意の std.json.Stringify に直接ストリーミング：
try engine.introspect.writeSnapshot(&jw, world);

// すべての組み込みコンポーネントタイプのスキーマ：
try engine.introspect.writeSchema(&jw);

クエリ（アロケーションなし）

var indices: [128]usize = undefined;

// 名前の部分文字列で検索：
const count = engine.introspect.findByName(scene.nodes, "Player", &indices);

// コンポーネントタイプで検索：
const count = engine.introspect.findByComponent(scene.nodes, "Camera", &indices);

// コンポーネントの存在確認：
const has = engine.introspect.hasComponent(node, "Light");
const ci  = engine.introspect.componentIndex(node, "Light"); // ?usize

メトリクス

engine.Metrics はすべてのエンジンサブシステムの単一の書き込みターゲットです：

engine.Metrics.recordFrame(dt_seconds);   // フレームごとに 1 回呼び出す
engine.Metrics.beginFrame();              // フレームごとのレンダリングカウンターをリセット
engine.Metrics.draw_calls += 1;           // レンダラーが設定

デバッグサーバーと MCP サーバーは world.metrics を読み取って、metrics および get_metrics 呼び出しに応答します。

変更

// 組み込みコンポーネントのフィールドを設定：
try engine.introspect.setComponentField(node, "Camera", "fov", .{ .number = 90 });

// トランスフォームフィールドを設定：
try engine.introspect.setTransformField(node, "position.x", .{ .number = 10 });

// スポーン/破棄（キューイングされ、次のフレームで適用）：
try engine.introspect.spawnEntity(scene, "NewEnemy");
engine.introspect.destroyEntity(scene, node_index);

プロトコル経由では、デバッグサーバーが読み書きモード（allow_write / CLI --rw）で実行されている場合に変更が可能です。ホストは MutationApplier を登録し、サーバーのメインスレッド pump がそれを呼び出すことで、編集がライブ状態に安全に適用されます。Studio はこれをアンドゥスタック経由で接続します。完全なメソッドとイベントの一覧については、リモートデバッグプロトコルページを参照してください。

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