ECS Framework

一个轻量级的 TypeScript ECS（Entity-Component-System）框架，专为小游戏开发设计，适用于 Laya、Cocos 等游戏引擎。

✨ 特性

• 🚀 轻量级 ECS 架构 - 基于实体组件系统，提供清晰的代码结构
• ⚡ 高性能 - 可处理20万个实体@165.8FPS，组件访问7200万次/秒
• 📡 事件系统 - 内置 Emitter 事件发射器，支持类型安全的事件管理
• ⏰ 定时器系统 - 完整的定时器管理，支持延迟和重复任务
• 🔍 查询系统 - 基于位掩码的高性能实体查询
• 🛠️ 性能监控 - 内置性能监控工具，帮助优化游戏性能
• 🎯 对象池 - 内存管理优化，减少垃圾回收压力

📦 安装

npm install @esengine/ecs-framework

📊 性能基准

# 运行性能基准测试
node benchmark.js

框架性能数据:

• 🚀 实体创建: 220万+个/秒 (50000个实体/22.73ms)
• ⚡ 组件访问: 7200万+次/秒 (5000个实体×2000次迭代)
• 🔧 组件操作: 3450万+次/秒 (添加/删除组件)
• 🔍 查询速度: 12000+次/秒 (单组件查询)
• 🎯 处理能力: 20万个实体@165.8FPS

详细性能测试结果:

📊 实体创建性能
  50000 个实体: 22.73ms (2199659个/秒)

🔍 组件访问性能  
  2000 次迭代: 139.67ms (71598669次访问/秒)

🧪 组件添加/删除性能
  1000 次迭代: 289.66ms (34522936次操作/秒)

🔎 查询系统性能
  单组件查询: 82.11ms/1000次 (12178次/秒)
  多组件查询: 105.94ms/1000次 (9439次/秒)
  复合查询: 135.01ms/1000次 (7407次/秒)

🎯 性能极限测试 (1秒钟固定时间测试)
  5万个实体: 1.219ms/帧 (820.0FPS)
  10万个实体: 2.976ms/帧 (335.9FPS)
  20万个实体: 6.031ms/帧 (165.8FPS)

🚀 快速开始

1. 初始化框架

import { Core, CoreEvents } from '@esengine/ecs-framework';

// 创建 Core 实例
const core = Core.create(true); // true 表示开启调试模式

// 在游戏循环中更新框架
function gameLoop() {
    // 发送帧更新事件
    Core.emitter.emit(CoreEvents.frameUpdated);
}

2. 创建场景

import { Scene, EntitySystem } from '@esengine/ecs-framework';

class GameScene extends Scene {
    public initialize() {
        // 创建玩家实体
        const player = this.createEntity("Player");
        
        // 添加自定义组件
        const position = player.addComponent(new PositionComponent(100, 100));
        const movement = player.addComponent(new MovementComponent());
        
        // 添加系统
        this.addEntityProcessor(new MovementSystem());
    }
    
    public onStart() {
        console.log("游戏场景已启动");
    }
}

// 设置当前场景
Core.scene = new GameScene();

3. 创建组件

import { Component, Time } from '@esengine/ecs-framework';

class MovementComponent extends Component {
    public speed: number = 100;
    public direction = { x: 0, y: 0 };
    
    public update() {
        const position = this.entity.getComponent(PositionComponent);
        if (position && (this.direction.x !== 0 || this.direction.y !== 0)) {
            position.x += this.direction.x * this.speed * Time.deltaTime;
            position.y += this.direction.y * this.speed * Time.deltaTime;
        }
    }
}

class PositionComponent extends Component {
    constructor(public x: number = 0, public y: number = 0) {
        super();
    }
}

4. 创建系统

import { EntitySystem, Entity } from '@esengine/ecs-framework';

class MovementSystem extends EntitySystem {
    protected process(entities: Entity[]) {
        for (const entity of entities) {
            const movement = entity.getComponent(MovementComponent);
            if (movement) {
                movement.update();
            }
        }
    }
}

📚 核心概念

Entity（实体）

实体是游戏世界中的基本对象，作为组件的容器。实体本身不包含游戏逻辑，所有功能都通过组件来实现。

// 通过场景创建实体
const entity = scene.createEntity("MyEntity");

// 设置实体属性
entity.tag = 1;                    // 设置标签用于分类
entity.updateOrder = 0;            // 设置更新顺序
entity.enabled = true;             // 设置启用状态

// 添加组件来扩展功能
const positionComponent = entity.addComponent(new PositionComponent(100, 200));
const healthComponent = entity.addComponent(new HealthComponent(100));

Component（组件）

组件包含数据和行为，定义了实体的特性。

import { Component } from '@esengine/ecs-framework';

class HealthComponent extends Component {
    public maxHealth: number = 100;
    public currentHealth: number = 100;
    
    public takeDamage(damage: number) {
        this.currentHealth = Math.max(0, this.currentHealth - damage);
        if (this.currentHealth <= 0) {
            this.entity.destroy();
        }
    }
}

System（系统）

系统处理实体集合，实现游戏逻辑。

import { EntitySystem, Entity } from '@esengine/ecs-framework';

class HealthSystem extends EntitySystem {
    protected process(entities: Entity[]) {
        for (const entity of entities) {
            const health = entity.getComponent(HealthComponent);
            if (health && health.currentHealth <= 0) {
                entity.destroy();
            }
        }
    }
}

🎮 高级功能

事件系统

import { Core, CoreEvents } from '@esengine/ecs-framework';

// 监听事件
Core.emitter.addObserver(CoreEvents.frameUpdated, this.onFrameUpdate, this);

// 发射自定义事件
Core.emitter.emit("playerDied", { player: entity, score: 1000 });

// 移除监听
Core.emitter.removeObserver(CoreEvents.frameUpdated, this.onFrameUpdate);

定时器系统

import { Core } from '@esengine/ecs-framework';

// 延迟执行
Core.schedule(2.0, false, this, (timer) => {
    console.log("2秒后执行");
});

// 重复执行
Core.schedule(1.0, true, this, (timer) => {
    console.log("每秒执行一次");
});

实体查询

// 按名称查找
const player = scene.findEntity("Player");

// 按标签查找
const enemies = scene.findEntitiesByTag(1);

// 按ID查找
const entity = scene.findEntityById(123);

性能监控

import { PerformanceMonitor } from '@esengine/ecs-framework';

// 获取性能数据
const monitor = PerformanceMonitor.instance;
console.log("平均FPS:", monitor.averageFPS);
console.log("内存使用:", monitor.memoryUsage);

🛠️ 开发工具

对象池

// 创建对象池
class BulletPool extends es.Pool<Bullet> {
    protected createObject(): Bullet {
        return new Bullet();
    }
}

const bulletPool = new BulletPool();

// 获取对象
const bullet = bulletPool.obtain();

// 释放对象
bulletPool.free(bullet);

实体调试

// 获取实体调试信息
const debugInfo = entity.getDebugInfo();
console.log("实体信息:", debugInfo);

// 获取场景统计
const stats = scene.getStats();
console.log("场景统计:", stats);

📖 文档

• 快速入门 - 从零开始学习框架使用
• 实体使用指南 - 详细了解实体的所有功能和用法
• 核心概念 - 深入了解 ECS 架构和设计原理
• 查询系统使用指南 - 学习高性能查询系统的详细用法

🔗 扩展库

• 路径寻找库 - A*、广度优先、Dijkstra、GOAP 算法
• AI 系统 - 行为树、效用 AI 系统

🤝 贡献

欢迎提交 Issue 和 Pull Request！

开发环境设置

# 克隆项目
git clone https://github.com/esengine/ecs-framework.git
cd ecs-framework

# 运行基准测试
node benchmark.js

# 开发构建 (在source目录)
cd source && npm install && npm run build

构建要求

• Node.js >= 14.0.0
• TypeScript >= 4.0.0

📄 许可证

本项目采用 MIT 许可证。

💬 交流群

加入 QQ 群讨论：ecs游戏框架交流

---

ECS Framework - 让游戏开发更简单、更高效！