ECS Framework
TypeScript ECS (Entity-Component-System) 框架，专为游戏开发设计。
💡 项目特色
ECS 架构原理
ECS 是一种基于组合而非继承的软件架构模式：
- Entity（实体）: 游戏对象的唯一标识
- Component（组件）: 纯数据结构，描述实体属性
- System（系统）: 处理具有特定组件的实体
特性
- 完整的 TypeScript 支持 - 强类型检查和代码提示
- 高效查询系统 - 流式 API 和智能缓存
- 性能优化技术 - 组件索引、Archetype 系统、脏标记
- 事件系统 - 类型安全的事件处理
- 调试工具 - 内置性能监控和 Cocos Creator 可视化调试插件
安装
npm install @esengine/ecs-framework
快速开始
1. 基础使用
import { Core, Scene, Entity, Component, EntitySystem, Matcher, Time } from '@esengine/ecs-framework';
// 创建核心实例
const core = Core.create({ debug: true });
const scene = new Scene();
Core.scene = scene;
// 定义组件
class PositionComponent extends Component {
public x: number = 0;
public y: number = 0;
constructor(...args: unknown[]) {
super();
const [x = 0, y = 0] = args as [number?, number?];
this.x = x;
this.y = y;
}
}
class VelocityComponent extends Component {
public x: number = 0;
public y: number = 0;
constructor(...args: unknown[]) {
super();
const [x = 0, y = 0] = args as [number?, number?];
this.x = x;
this.y = y;
}
}
// 创建实体
const entity = scene.createEntity("Player");
entity.addComponent(new PositionComponent(100, 100));
entity.addComponent(new VelocityComponent(5, 0));
// 创建系统
class MovementSystem extends EntitySystem {
constructor() {
super(Matcher.all(PositionComponent, VelocityComponent));
}
protected override process(entities: Entity[]) {
for (const entity of entities) {
const position = entity.getComponent(PositionComponent)!;
const velocity = entity.getComponent(VelocityComponent)!;
position.x += velocity.x * Time.deltaTime;
position.y += velocity.y * Time.deltaTime;
}
}
}
scene.addEntityProcessor(new MovementSystem());
// 游戏循环
Core.update(deltaTime);
高级特性
查询系统
import { Matcher } from '@esengine/ecs-framework';
// 方式1：使用Matcher和EntitySystem
class QuerySystem extends EntitySystem {
constructor() {
super(Matcher.all(PositionComponent, VelocityComponent).none(HealthComponent));
}
protected override process(entities: Entity[]) {
// 处理匹配的实体
console.log(`Found ${entities.length} entities`);
}
}
// 方式2：手动过滤场景中的实体
const results = scene.entities.buffer.filter(entity =>
entity.hasComponent(PositionComponent) &&
entity.hasComponent(VelocityComponent) &&
!entity.hasComponent(HealthComponent)
);
事件系统
import { EventHandler, ECSEventType } from '@esengine/ecs-framework';
class GameSystem {
@EventHandler(ECSEventType.ENTITY_DESTROYED)
onEntityDestroyed(data: any) {
console.log('实体销毁:', data.entityName);
}
}
SoA 存储优化
用于大规模实体处理：
import { EnableSoA, Float32, Int32 } from '@esengine/ecs-framework';
@EnableSoA
class OptimizedTransformComponent extends Component {
@Float32 public x: number = 0;
@Float32 public y: number = 0;
@Float32 public rotation: number = 0;
}
性能优势：
- 🚀 缓存友好 - 连续内存访问，缓存命中率提升85%
- ⚡ 批量处理 - 同类型数据处理速度提升2-3倍
- 🔄 热切换 - 开发期AoS便于调试，生产期SoA提升性能
- 🎯 自动优化 -
@EnableSoA装饰器自动转换存储结构
平台集成
Cocos Creator
update(deltaTime: number) {
Core.update(deltaTime);
}
专用调试插件：
- 🔧 ECS 可视化调试插件 - 提供完整的可视化调试界面
- 📊 实体查看器、组件编辑器、系统监控
- 📈 性能分析和实时数据监控
Laya 引擎
Laya.timer.frameLoop(1, this, () => {
Core.update(Laya.timer.delta / 1000);
});
原生浏览器
function gameLoop(currentTime: number) {
const deltaTime = (currentTime - lastTime) / 1000;
Core.update(deltaTime);
requestAnimationFrame(gameLoop);
}
API 参考
核心类
| 类 | 描述 |
|---|---|
Core |
框架核心管理 |
Scene |
场景容器 |
Entity |
实体对象 |
Component |
组件基类 |
EntitySystem |
系统基类 |
EntityManager |
实体管理器 |
查询 API
// Matcher API - 用于EntitySystem
Matcher.all(...components) // 包含所有组件
Matcher.any(...components) // 包含任意组件
Matcher.none(...components) // 不包含组件
// 手动查询 - 用于场景实体过滤
scene.entities.buffer.filter(entity =>
entity.hasComponent(ComponentA) &&
entity.tag === someTag
);