SuperAPI AI 工具集

gaia-ecs

编程与开发

查看项目

更新于 11-08 15:40

技能介绍

gaia-ecs 是一套面向 TypeScript 游戏开发的使用规范,指导开发者用 EliCS 这一轻量级、高性能的实体-组件-系统(Entity Component System,ECS)框架来组织游戏状态。EliCS 采用数据导向设计,强调组合优于继承,通过高效的位掩码和类型化数组(typed array)存储数据。

核心概念

规范中的基本概念包括:实体(Entity,唯一对象)、组件(Component,数据容器)、系统(System,逻辑处理器)、查询(Query,实体选择器)和世界(World,管理上述一切的容器)。

推荐架构:Input / State / View 三层

规范建议把游戏拆成三层:

  1. 输入映射到状态(Input Systems):接收用户输入、将其归一化,并应用到状态上。复杂输入可以拆成多个系统处理,例如原始事件→归一化动作→状态更新。每个输入系统都应提供方法,可以以命令方式触发全部输入,从而便于用程序模拟和测试用户输入。
  2. 每帧推进状态(State Systems):每帧推进游戏状态,例如敌人追击玩家。
  3. 状态同步到视图(View Systems):把状态反映到视图。需要在初始化时按需订阅实体的创建与移除(例如创建或销毁 3D 对象、UI),并每帧更新频繁变化的数据。

推荐文件结构

  • src/components/*.ts:一个组件一个文件(如 position.ts、velocity.ts)。组件只保存状态,行为放在系统里。
  • src/systems/*.ts:一个系统一个文件(如 input.ts、physics.ts)。每个系统导出初始化函数和逐帧更新函数。
  • src/seed.ts:构造启动时的实体并挂载组件,使游戏一启动即可游玩。
  • src/main.ts:组装游戏:加载 seed、注册系统、执行初始化,然后每帧推进所有状态并同步到视图。

创建世界

世界是所有 ECS 元素共存的场所:

import { World } from 'elics'
const world = new World()

定义组件

组件是定义实体属性的数据容器。规范列出了可用的字段类型:标量(Types.Float32、Types.Int16、Types.Boolean、Types.String)、向量(Types.Vec2、Types.Vec3、Types.Vec4、Types.Color,RGBA 取值 0-1)、引用(Types.Entity、Types.Object、Types.Enum)。可以用 const 断言定义枚举,以实现类型安全的状态管理。创建组件后应立即通过 world.registerComponent 注册。

示例中包含 Position(Vec3 三维坐标)、Velocity(Vec3 速度向量)、Health(Float32 生命值)、Unit(含枚举类型、状态、伤害、护甲、士气等字段,并带 min/max 约束)以及 Target(Entity 引用)等组件。

重要提示:向量类型(Vec2、Vec3、Vec4、Color)必须通过 getVectorView() 访问,不能使用 getValue()/setValue();用错访问器时 EliCS 会在运行时抛错。

创建实体

通过 world.createEntity() 实例化实体,再用 addComponent 挂载组件并传入初始值。标量值用 getValue/setValue 读写;向量值用 getVectorView 取得 TypedArray 子数组后直接按下标修改;用 hasComponent 检查组件是否存在;用 removeComponent 移除组件;用 destroy() 销毁实体(销毁后 entity.active 变为 false)。

创建系统

系统承载核心逻辑。通过 createSystem 并传入查询配置来定义系统类,例如 movementQueryConfig 声明 movables 查询需要 Position 与 Velocity 组件;系统在 update(delta, time) 中遍历 this.queries.movables.entities 并更新位置。视图系统则可在 init() 中为已有实体创建 3D 模型,并通过 queries.units.subscribe('qualify', create) 与 subscribe('disqualify', destroy) 订阅实体进入/离开查询,在 update 中同步模型位置。

系统通过 world.registerSystem 注册,可指定 priority(数值越小越先执行)。注册后可用 world.getSystem(...) 取得系统实例,访问其属性与方法,例如调用 spawnEnemy(position)。

系统资源加载

系统可定义异步 load() 方法加载资源,生命周期顺序为 init() → load() → update()。示例中 EnemySystem 在 load() 中用 GLTFLoader 加载模型。在 main.ts 中应先注册系统(自动调用 init()),再 await 该系统的 load(),之后才启动渲染循环。

系统生命周期控制

可用 stop() 暂停系统、用 play() 恢复,并用 isPaused 检查是否已暂停。示例场景:对话序列期间暂停物理系统,玩家恢复控制后再恢复。

查询谓词

查询配置支持用 where 子句按组件字段值过滤实体,并可指定 required(必需组件)与 excluded(排除含某组件的实体)。支持的运算符有:eq(等于)、ne(不等于)、lt(小于)、le(小于等于)、gt(大于)、ge(大于等于)、in(在数组中)、nin(不在数组中)。示例中 lowHealth 查询筛选生命值小于 30、且不含 Target 组件的实体。

更新世界

在渲染循环中计算 delta,并调用 world.update(delta, clock.elapsedTime) 推进世界。

适用场景与限制

该规范面向使用 Three.js 等渲染层、以 TypeScript 开发游戏的场景,示例围绕单位移动、视图同步、敌人加载与暂停控制展开。关于具体平台支持、性能上限、版本兼容性及已知限制,资料暂未提供。