CHAPTER 07 // RENDERERS & API

零绑定渲染协议与 API 手册

WorldSnapshot 数据契约、Web 涌现实验室 REST 接口与核心 TypeScript 类型参考。

7.1 WorldSnapshot 零绑定渲染协议

无论是终端字符界面（cyberpsychosis-tui）、Web 实验室画布（cyberpsychosis-web），还是外部游戏引擎（Three.js / Godot / PixiJS），都只需要消费 kernel.getSnapshot() 返回的纯 JSON 数据结构：

// TYPESCRIPT CYBERPSYCHOSIS SDK

export interface WorldSnapshot {
  tick: number;
  seed: number;
  prngState: number;
  grid: { width: number; height: number };
  entities: SerializedEntity[];
  activeRules: ActiveRuleSummary[];
  overrides: GlobalTagOverride[];
  graphEdges: SerializedGraphEdge[];
  recentEvents: CausalNode[];
  metrics: {
    entityCount: number;
    burningCount: number;
    panickedAgentCount: number;
    logisticsThroughput: number;
    brokenPipeCount: number;
    activeRuleCount: number;
  };
}

7.2 Web 涌现实验室 HTTP / REST 接口

cyberpsychosis-web 内置基于 node:http 的零依赖服务端，对外提供完整的沙盒控制与可观测 REST 接口：

HTTP 方法与路径	请求体示例	功能说明
GET /api/snapshot	—	获取当前帧 WorldSnapshot 及可用历史 Checkpoint 帧列表
POST /api/step	{ "count": 5 }	向前推进指定数量的确定性逻辑帧
POST /api/rewind	{ "tick": 2 }	时间旅行回滚到指定的历史 Tick 快照
POST /api/push-word	{ "preset": "WATER_IS_HOT" }	推动网格词块改写全局元规则或移动指定实体
POST /api/inject-dsl	{ "input": "Make smoke calm", "previewTicks": 5 }	编译自然语言/DSL、执行 WorldFork 平行推演并注入规则
GET /api/causal/:id	—	查询任意实体 ID 或事件 ID 的完整因果溯源链 (CausalLineageReport)
POST /api/reset	{}	重置微缩生态站至初始 Tick 0 状态