从零到一吃透 bitECS：实体是整数、组件是数组，JavaScript 极速 ECS 系统的终极拆解

从零到一吃透 bitECS：实体是整数、组件是数组，JavaScript 极速 ECS 系统的终极拆解

【免费下载链接】bitECSFlexible, minimal,>项目地址: https://gitcode.com/gh_mirrors/bi/bitECS

先抛一个反常识的事实：在 bitECS 这个专为 JavaScript 打造的超高性能 ECS（实体组件系统）库里，"实体"不是对象，而是一个普通的整数；"组件"也不是对象，而是一个个 TypedArray；甚至"世界"就是一个你可以随意挂属性的空对象。当你用惯了一切皆对象的 OOP 思维，这三个反直觉的设计恰恰是它性能恐怖如斯的全部秘密。bitECS 用约 5KB（minzipped）的体积、零第三方依赖，把数据导向设计（Data-Oriented Design）践行到了极致——Mozilla Hubs 这类万人规模的多人实时 3D 场景，就是靠它在浏览器里扛住成百上千实体的高频更新。这篇文章不按常规套路介绍 API，而是从一个真实的性能痛点出发，带你亲手把它跑起来，再拆开引擎盖看清它的每一颗螺丝。

一、当 10 万只实体需要同屏更新：传统写法为什么会卡

假设你正在写一个粒子系统，10 万个粒子，每个粒子有位置、速度、生命值。用普通对象实现，一个粒子长这样：

// 传统的 AoS（Array of Structures）写法 const particle = { x: 0, y: 0, z: 0, vx: 1, vy: 1, vz: 1, life: 1, }

问题出在循环里：遍历 10 万个粒子时，CPU 需要频繁地在内存里"跳来跳去"访问不同对象的属性。现代 CPU 有缓存行（cache line）机制，一次能预读一小段连续内存；而对象在堆上是零散分布的，每次访问几乎都会触发缓存未命中（cache miss），性能随之断崖式下跌。

bitECS 的思路是把数据"翻转"过来：不存"一个对象拥有所有属性"，而是"每个属性是一整块连续数组"，这叫做 SoA（Structure of Arrays）。它在源码里通过 TypedArray 实现——src/Storage.js中的createStore就是干这个的。你可以直接通过Position.x[eid]读写某个实体的 x 坐标，连续内存 + 顺序访问，正好喂饱 CPU 缓存。

一句话小结：数据连续摆放，CPU 缓存命中率拉满——这是 bitECS 所有性能优势的地基。

二、实体是整数：用位掩码判断"拥有什么组件"

明确了数据布局，第二个反常识点来了：实体就是数字。addEntity(world)返回一个整数 eid，它本质上是一个"指针"，指向各组件数组中的一行。

import { createWorld, addEntity, addComponent, defineComponent, Types } from 'bitecs' // 定义一个三维向量组件：x/y/z 各占一块 Float32Array const Position = defineComponent({ x: Types.f32, y: Types.f32, z: Types.f32 }) const Velocity = defineComponent({ x: Types.f32, y: Types.f32, z: Types.f32 }) const world = createWorld() const eid = addEntity(world) addComponent(world, Position, eid) addComponent(world, Velocity, eid) // 直接操作底层数组——这就是"高性能迭代"的来源 Position.x[eid] = 10 Velocity.y[eid] = 5

那 bitECS 怎么知道"这个实体有没有 Position"？答案藏在一个叫**位掩码（bitmask）**的机制里。每个组件在注册到世界时会被分配一个独立的 bitflag（src/Component.js中的registerComponent），而每个实体在自己的掩码数组中用一个 32 位整数记录"我身上有哪些组件"。判断归属只需一次按位与运算(mask & bitflag) === bitflag，速度堪比 O(1)。

你可以想象成：每个实体发了一张"积木登记卡"，卡片上每一位对应一种组件类型，添加组件就是拨一个开关。查询系统就是拿这张卡片做位运算比对，快得离谱。

三、查询、系统、管道：把"找出符合条件的实体"变成一次位运算

现在数据就位了，关键问题变成：如何高效地"找出同时拥有 Position 和 Velocity 的所有实体"？朴素方案是遍历 10 万个实体逐个检查，而 bitECS 的查询（Query）把组件掩码提前按位或成一张"目标卡"，然后逐实体做位与比较。src/Query.js里queryCheckEntity就是核心判断逻辑。

import { defineQuery, enterQuery, exitQuery, pipe } from 'bitecs' // 查询定义一次，之后每次调用都走位运算快路径 const movementQuery = defineQuery([Position, Velocity]) // 想知道"刚满足条件"和"刚失去条件"的实体？包一层就行 const movementEntered = enterQuery(movementQuery) const movementExited = exitQuery(movementQuery) // 系统就是一个普通函数：拿查询结果，直接改数组，返回 world const movementSystem = (world) => { const ents = movementQuery(world) for (let i = 0; i < ents.length; i++) { const eid = ents[i] Position.x[eid] += Velocity.x[eid] Position.y[eid] += Velocity.y[eid] Position.z[eid] += Velocity.z[eid] } return world } // pipe 把多个系统串成一条流水线，一次调用依次执行 const pipeline = pipe(movementSystem, anotherSystem) pipeline(world)

这段代码解决了什么问题？它演示了 bitECS 的核心工作流：查询负责筛选实体，系统负责纯函数式地修改数据，管道把多个系统按顺序编排。三者解耦，各管一摊，完全符合"数据与逻辑分离"的 ECS 哲学。你注意到系统里没有任何 new、没有对象创建，因此也几乎没有垃圾回收（GC）压力。

值得注意：查询结果返回的是 dense 数组，直接复用同一个数组，避免每帧分配新内存——这是又一个被隐藏的优化细节。

四、进阶技巧：序列化、变化检测与实体回收

基础的增删改查只是开胃菜。真正让 bitECS 与众不同的，是几个"免费附赠"的高级能力。

1. 内置高性能序列化：多人同步不用再自己拼 JSON

当你要把整个世界的状态发给网络对端，常规做法是 JSON.stringify，但对十万级实体来说，字符串序列化慢且体积大。bitECS 内置了直接读写二进制 ArrayBuffer 的序列化器（src/Serialize.js）：

import { defineSerializer, defineDeserializer, DESERIALIZE_MODE } from 'bitecs' // 只序列化 Position 和 Velocity 这两块数据 const serialize = defineSerializer([Position, Velocity]) const deserialize = defineDeserializer([Position, Velocity]) // 拿到一个二进制包，直接塞进网络协议里 const packet = serialize(movementQuery(world)) const newEnts = deserialize(world, packet, DESERIALIZE_MODE.MAP)

反序列化有三种模式，理解它们能帮你避开最常见的坑：

第三种模式尤其适合"服务端是世界 A、客户端是世界 B"的场景：服务端的实体 ID 被映射成客户端的本地 ID，且用Types.eid声明的实体引用关系也能自动跟随，父子的关联不会断。

2. Changed 与 Not：精确筛选，不做多余工作

查询还能套修饰符。Changed(Position)只返回"自上次调用以来数据变过"的实体，配合脏标记做网络增量同步非常顺手；Not(Velocity)则筛选"明确没有某组件"的实体，常用于给"静止物体"批量挂上新行为：

const changedQuery = defineQuery([Changed(Position)]) const staticQuery = defineQuery([Position, Not(Velocity)])

需要提醒的是，Changed内部靠"影子副本比对"实现，源码里叫createShadow，属于按需 diff，频繁调用会有额外开销。如果你的变更路径非常明确，手动维护脏标记数组反而更快——这点官方文档docs/FAQ.md也有说明。

3. 实体回收：让"删了又建"不再折磨 GC

游戏里敌人死亡、子弹消失是高频操作。bitECS 默认在移除实体数量超过全局大小 1% 时才开始复用 EID，你也可以手动接管回收时机：

import { enableManualEntityRecycling, flushRemovedEntities, setDefaultSize } from 'bitecs' setDefaultSize(50000) // 预估实体上限，避免频繁扩容 enableManualEntityRecycling(world) // 开启手动回收 // ... 在合适的时机统一归还 EID flushRemovedEntities(world)

注意setDefaultSize会影响所有世界的存储容量（src/Entity.js中的resizeWorlds会同步扩容所有组件表），所以尽量在一开始就设置好。

五、答新手问：三个最容易踩的坑

Q1：可以直接Position.x[eid] = 10，那 addComponent 还有必要吗？有必要。addComponent 做的核心事情是"在实体的位掩码上打标记"，查询依赖这个标记来筛选实体。只写数据不打标记，查询就找不到这个实体。

Q2：能不能给实体挂一个对象/字符串？不能直接挂。bitECS 的一切数据都必须落在数值型 TypedArray 里。存储字符串可以拆成字符编码存 ui8 数组，或者自己维护一张"ID 到字符串"的映射表放在 world 上。这是数据导向设计的取舍：放弃灵活性，换取性能。

Q3：多个世界之间数据会串吗？不会。每个createWorld()都是独立上下文（src/World.js），组件表是全局共享的，但"哪个实体属于哪个世界、拥有什么组件"是各世界独立的。多世界并行管理是它的设计亮点之一。

六、动手时间：从克隆到跑通第一个 Demo

最快上手方式：

git clone https://gitcode.com/gh_mirrors/bi/bitECS cd bitECS npm install npm test # 跑一遍自带测试，约数百个用例验证 API 行为

然后打开README.md里的完整示例（一个带时间系统与移动系统的粒子 Demo），把movementSystem改成你自己想验证的逻辑——比如把 10 万个实体放进循环，对比一下浏览器里的帧率表现，你会对"数据导向"四个字有直观体感。

想深入源码的读者，我建议按这个顺序阅读，逻辑刚好成一条线：

1. src/Storage.js—— 组件数据如何被铺平成 TypedArray
2. src/Entity.js—— 实体 ID 与回收机制
3. src/Component.js—— 位掩码的注册与增删
4. src/Query.js—— 位运算筛选与 enter/exit 追踪
5. src/Serialize.js—— 二进制序列化与三种反序列化模式

配套的docs/INTRO.md有完整 API 示例，docs/API.md是函数级参考，docs/FAQ.md汇集了常见设计取舍说明。

七、下一步该往哪走

如果你想把这套知识落地成真实项目，我建议从这三个方向选一个：

• 做一个小游戏：用 bitECS 重写一个你熟悉的 2D 游戏循环，重点体会"系统改数据、渲染层只读数据"的分离带来的测试便利。
• 做一次性能实验：对比普通对象数组与 bitECS 在 10 万实体下的迭代耗时，把数据记录下来，你会得到一张很有说服力的性能曲线。
• 读一遍它的 benchmark 对照：bitECS 官方维护的 ECS benchmark 数据可以作为你选型时的横向参考。

最后留一个思考题：为什么enterQuery/exitQuery返回的实体数组只在调用之间短暂有效？想通了这一点，你就真正理解了 bitECS"用空间换时间、用约定换性能"的设计哲学。带着这个问题去读src/Query.js里的 SparseSet 实现，你会收获比本文更深的乐趣。

【免费下载链接】bitECSFlexible, minimal,>项目地址: https://gitcode.com/gh_mirrors/bi/bitECS