# @flare-engine/ecs 中文文档

规范地址：https://npmcn.com/package/%40flare-engine/ecs/

版本：0\.4\.12
npm 元数据更新时间：2026-11-12T19:45:50.310Z
中文译文更新时间：2026-11-14T21:26:50.100Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40flare-engine/ecs
原文对照：https://npmcn.com/package/%40flare-engine/ecs/?lang=original
项目主页：https://github.com/grzott/flare-engine#readme
源码仓库：https://github.com/grzott/flare-engine

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：169 kB，12 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-06-09T16:19:40.253Z
- 最新版本发布：2026-11-12T19:45:49.949Z
- 近 30 天下载量：3451（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

包含类型查询的实体- 组件- 系统

## 安装

```sh
npm install @flare-engine/ecs
```

也可以使用：`pnpm add @flare-engine/ecs`、`yarn add @flare-engine/ecs`、`bun add @flare-engine/ecs`

## README

# @flare-engine/ ecs (英语)

拱形比特面具ECS - `World` (弹出/销毁, `query` + 键 `queryBuilder` + 键 `removeQuery`, (中文(简体) ), `forEachEntity`, (中文(简体) ), `entityCount`, (中文(简体) ), `Query` 零分数c `entities` 走着走着 `onEntityAdded` 编号 : `onEntityRemoved` 信号, `defineComponent`, (中文(简体) ), `defineSystem`, (中文(简体) ), `definePrefab`, (中文(简体) ), `FSM`。内置组件: `Position`, (中文(简体) ), `Velocity`, (中文(简体) ), `Rotation`, (中文(简体) ), `Scale`, (中文(简体) ), `Parent`, (中文(简体) ), `Lifetime`, (中文(简体) ), `Follower`五个系统工厂: `createMovementSystem`, (中文(简体) ), `createLifetimeSystem`, (中文(简体) ), `createBoundsCullSystem`, (中文(简体) ), `createFollowerSystem`, (中文(简体) ), `createOrphanCullSystem`. 最大 32 个组件类型总计—— 组件- id 位模是模块- 全球, 由所有组件共享 `World` 实例.

## 安装

```sh
bun add @flare-engine/ecs
```

## 使用量

```ts
import { World, defineComponent, Position, Velocity } from '@flare-engine/ecs';

const Health = defineComponent<{ hp: number }>('Health', () => ({ hp: 100 }));

const world = new World();
const e = world.spawn();
world.add(e, Position, { x: 0, y: 0 });
world.add(e, Velocity, { x: 1, y: 0 });
world.add(e, Health);

const movers = world.query(Position, Velocity);
const ids = movers.entities;
for (let i = 0; i < ids.length; i++) {
  const id = ids[i]!;
  /* ... */
}
```

## 正在查询

`query.entities` 是现场直播 `readonly number[]` 匹配的标识符——按指数排列,如上,没有分配. `for (const id of query)` 也可以工作,在框架外很好,但它每回循环生成一个执行器,在Hermes(反应原生)上,每个实体有一个结果对象,所以使其远离系统并渲染代码. 阵列是活的:摧毁一个实体或改变其组件中行走将另一个实体移动入你下面的槽中——首先收集,然后行动.

## 系统

`defineSystem` 将查询绑定为每帧函数; 登记返回的 `worldFn` 与 `world.addSystem` (优先级别较低者优先) `removeSystem`。 。 。 .

```ts
import { World, defineSystem, Position, Velocity } from '@flare-engine/ecs';

const world = new World();
const movers = world.query(Position, Velocity);
const moveSys = defineSystem(movers, (query, dt, w) => {
  const ids = query.entities;
  for (let i = 0; i < ids.length; i++) {
    const id = ids[i]!;
    const pos = w.get(id, Position)!;
    const vel = w.get(id, Velocity)!;
    pos.x += vel.x * dt;
    pos.y += vel.y * dt;
  }
});
world.addSystem(moveSys.worldFn, 0);
world.step(1 / 60);
world.removeSystem(moveSys.worldFn);
```

## 预发数据

`definePrefab` plain-object数据通过参考存储,由每个产卵共享;通过 `() => T` 每实体可变状态:

```ts
import { definePrefab, Position, Velocity } from '@flare-engine/ecs';

// Every bullet gets its own Position and Velocity object.
const Bullet = definePrefab(
  'Bullet',
  [Position, () => ({ x: 0, y: 0 })],
  [Velocity, () => ({ x: 0, y: -300 })],
);
```

见 [API 规格](https://github.com/grzott/flare-engine/blob/main/docs/design/api-specs.md#flare-engineecs--8kb-gzip)。 。 。 .

## 许可证

阿帕奇 - 2.0

## 常见问题

### @flare-engine/ecs 是什么？

包含类型查询的实体- 组件- 系统

### 如何安装 @flare-engine/ecs？

在项目目录运行 npm install @flare-engine/ecs，或使用 pnpm add / yarn add / bun add。

### @flare-engine/ecs 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @flare-engine/ecs 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @flare-engine/ecs 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @flare-engine/ecs 可以商用吗？

@flare-engine/ecs 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @flare-engine/ecs 的下载量有多少？

根据 npm 官方下载统计，@flare-engine/ecs 在 2026/10/15 – 2026/11/13 这 30 天内被下载 3,451 次，日均约 115 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @flare-engine/ecs 还在维护吗？

最新版本 0\.4\.12 发布于 2026/11/13（3 天前）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/06/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。