《游戏引擎实现原理》附录 A helio 内核 API 与模块速查

这份速查怎么用

本卷 18 章会一路往 helio 内核里加零件。零件多了以后，最常见的困惑不是「这个算法怎么实现」，而是「这个类型叫什么、在哪一章、签名长什么样」。这份附录就是为这种时刻准备的：把全书出现过的类型与关键 API 按模块铺开，每一行给签名、一句话说明、出自哪一章三样东西，读到哪一节想不起来，回头扫一眼即可。

用法上，它是查阅表不是教程：不要从第一行读到最后一行，而是带着问题跳——想找句柄就翻到「句柄与容器」，想找任务系统就翻到 src/jobs/。真正讲原理的内容在正文各节，本表只做索引与备忘。

模块与章节的对应关系如下：

表中的「出处」列写的是章节号（如 6.2 指 6.2 节），而不是文件路径——因为同一份 API 可能被多节复用，章节号才是它「第一次被讲清楚」的地方。

src/core/ 内存、容器与数学

内核最底层的一层，也是全书代码量最大的一层。第 4 章讲分配器，第 5 章讲池化，第 6 章讲句柄，第 7 章讲自研容器，第 8–10 章讲数学与数值。

内存分配

句柄与容器

时间与主循环

数学与数值

src/ecs/ 实体、组件与系统

这一层把 src/core/ 的句柄与稀疏集组装成 ECS。实体是句柄，组件存进稀疏集，系统声明读写依赖后被调度器并行分组。

src/jobs/ 任务系统

第 14 章把计算搬出主线程，第 15 章把任务排成有依赖的图。整层都建立在 worker_threads（Node）或 Web Worker（浏览器）之上，通过 IWorkerPool 抽象掉差异。

src/reflect/ 反射与序列化

第 16 章用显式注册表（不用装饰器元数据）描述类型，第 17 章让序列化由这些类型信息驱动。生成器脚本在构建期扫描源码，把注册表写成一个普通 .ts 文件。

src/platform/ 平台抽象与基础设施

内核其余部分只依赖这里的接口，不直接 import node:fs 或 window。子系统编排、日志、配置也都收敛在这一层，作为启动期的公共设施注入。

模块依赖方向

helio 只有一条铁律：依赖只能向下。任何「上层被下层 import」都是错误，1.1 节的 findUpwardDeps() 会在构建期把它抓出来。

platform   ← 宿主边界：IPlatform / Logger / CVar / SubsystemRegistry
    ↑
  core     ← 内存、句柄、容器、数学、主循环（不依赖任何上层）
    ↑
   ecs     ← 依赖 core 的句柄与稀疏集
    ↑
  jobs     ← 依赖 core 的容器；ecs 借 jobs 并行跑系统
    ↑
 reflect   ← 依赖 core 与 ecs 暴露的类型信息

分层与依赖方向的完整讨论在1.1 引擎的分层与模块边界 ；这里只需记住：core 永远不知道 ecs 的存在，platform 永远不知道上面有谁。

典型组合用法

查表不如看一次真实的串联。下面三段是全书最常见的组合，展示这些 API 怎么拼在一起。

创建世界、生成实体、挂组件、查询——ECS 的日常：

// snippet: ECS 的典型四步
const world = new World();
const e = world.createEntity();
world.add(e, { x: 0, y: 0, vx: 1, vy: 0 }); // Transform 组件
new Query(world, [Transform, Velocity]).forEach((entity, t, v) => {
  t.x += v.x * dt;
  t.y += v.y * dt;
});

用 arena 兜住一帧内的临时分配，帧末整体回收：

// snippet: 帧内临时内存走 ScratchArena
const scratch = new ScratchArena(64 * 1024);
const mark = scratch.mark();
const tmp = scratch.alloc(1024, 16); // 帧内临时数据
// ... 本帧用完即弃 ...
scratch.release(mark); // 偏移回到标记点，下一帧继续用

把一批互相独立的任务交给 JobSystem，最后等齐：

// snippet: 提交任务并等待
const jobs = new JobSystem(4);
const handles = entities.map((e) => jobs.submit(() => updateEntity(e, dt)));
await Promise.all(handles);
jobs.waitAll();

命名约定速记

• 句柄一律是 32 位 number，用 NULL_HANDLE（0）表示「空」，绝不用 -1 或 undefined 混着来。
• 分配器一律「只前进不回收」；回收的语义是「标记为空闲、允许复用」（reset / free / swap-remove），不是把内存还给系统。
• 时间一律从 Clock 或 IPlatform.time 取，正文代码里不出现直接的 performance.now()。
• 类型用 interface / type；级别枚举用 const 对象 + as const，因为 Node 26 的 erasable syntax 禁止 enum。
• 容器把「值」和「身份」分开：SlotMap 管身份（带世代），SparseSet 管存储（dense 紧凑）。

按章反查

只想按章节找对应零件时，看这张表：

一处提醒：本表列的是接口与签名，不是实现。同一个名字在正文里可能有更细的字段与更严的边界检查（例如 SlotMap.remove 会先判 has、ObjectPool.release 会拦截重复归还），以正文的可编译代码为准。

阅读下一节：附录 B 环境与复现速查