自省

运行时自省层（engine.introspect）提供结构化、可 JSON 序列化的实时引擎状态视图，无需全局变量或分配。它是远程调试协议、MCP 服务器和 Studio 检查器所消费的单一数据源。

关键类型

const engine = @import("engine");

// 宿主提供给检查器的单个已加载场景的只读视图。
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,
    };
}

该回调在调试服务器的后台线程上每个请求调用一次。它必须返回一个安全的只读视图以供并发访问——帧快照就足够了。

序列化辅助函数

// 将整个世界快照为 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);   // 每帧调用一次
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 通过其撤销栈连接该功能——有关完整方法和事件列表，请参阅远程调试协议页面。

← 所有文档 编辑此页面