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

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

// 创建场景
class GameScene extends Scene {
    public initialize() {
        // 场景初始化逻辑
    }
}

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

2. 创建实体和组件

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

// 定义组件
class PositionComponent extends Component {
    constructor(public x: number = 0, public y: number = 0) {
        super();
    }
}

class VelocityComponent extends Component {
    constructor(public dx: number = 0, public dy: number = 0) {
        super();
    }
}

// 创建实体
const entity = scene.createEntity("Player");
entity.addComponent(new PositionComponent(100, 100));
entity.addComponent(new VelocityComponent(10, 0));

3. 创建处理系统

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

class MovementSystem extends EntitySystem {
    public process(entities: Entity[]) {
        for (const entity of entities) {
            const position = entity.getComponent(PositionComponent);
            const velocity = entity.getComponent(VelocityComponent);
            
            if (position && velocity) {
                position.x += velocity.dx;
                position.y += velocity.dy;
            }
        }
    }
}

// 添加系统到场景
scene.addEntityProcessor(new MovementSystem());

4. 实体查询和管理

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

// 使用EntityManager进行高级查询
const entityManager = new EntityManager();

// 查询具有特定组件的实体
const movingEntities = entityManager
    .query()
    .withAll(PositionComponent, VelocityComponent)
    .execute();

// 查询带标签的实体
const enemies = entityManager.getEntitiesByTag(1);

// 批量创建实体
const bullets = entityManager.createEntities(100, "bullet");

5. 事件系统

import { EventBus, ECSEventType, EventHandler } from '@esengine/ecs-framework';

// 获取事件总线
const eventBus = entityManager.eventBus;

// 监听实体创建事件
eventBus.onEntityCreated((data) => {
    console.log(`Entity created: ${data.entityName}`);
});

// 监听组件添加事件
eventBus.onComponentAdded((data) => {
    console.log(`Component ${data.componentType} added to entity ${data.entityId}`);
});

// 使用装饰器自动注册事件监听器
class GameManager {
    @EventHandler(ECSEventType.ENTITY_DESTROYED)
    onEntityDestroyed(data) {
        console.log('Entity destroyed:', data.entityName);
    }
}

// 自定义事件
eventBus.emit('player:levelup', { playerId: 123, newLevel: 5 });

🆚 框架对比

与其他 TypeScript ECS 框架相比，我们的优势：

特性	@esengine/ecs-framework	bitecs	ecsy	Miniplex
TypeScript 支持	✅ 原生支持	✅ 完整支持	⚠️ 部分支持	✅ 原生支持
事件系统	✅ 类型安全+装饰器	❌ 无内置事件系统	⚠️ 基础事件	✅ 响应式事件
查询系统	✅ 智能查询+流式API	✅ 高性能	✅ 基础查询	✅ 响应式查询
性能优化	✅ 多层优化系统	✅ 高性能优化	⚠️ 基础优化	✅ React集成优化
实体管理器	✅ 统一管理接口	❌ 无统一接口	✅ 基础管理	✅ 响应式管理
组件索引	✅ 哈希+位图索引	✅ 原生支持	❌ 无索引系统	✅ 自动索引
Archetype系统	✅ 内置支持	✅ 内置支持	❌ 无Archetype	❌ 无Archetype
脏标记系统	✅ 细粒度追踪	⚠️ 基础支持	❌ 无脏标记	✅ React级追踪
批量操作	✅ 全面的批量API	✅ 批量支持	⚠️ 有限支持	⚠️ 有限支持
游戏引擎集成	✅ 通用设计	✅ 通用设计	✅ 通用设计	⚠️ 主要针对React
学习曲线	🟢 中等	🟡 较陡峭	🟢 简单	🟡 需要React知识
社区生态	🟡 成长中	🟢 活跃	🟡 稳定	🟡 小众但精品

为什么选择我们？

相比 bitecs：

更友好的 TypeScript API，无需手动管理内存
完整的实体管理器，开发体验更佳
内置类型安全事件系统，bitecs需要自己实现
多种索引系统可选，适应不同场景

相比 ecsy：

现代化的性能优化系统（组件索引、Archetype、脏标记）
更完整的 TypeScript 类型定义
增强的事件系统，支持装饰器和异步事件
活跃的维护和功能更新

相比 Miniplex：

不依赖 React 生态，可用于任何游戏引擎
专门针对游戏开发优化
更轻量级的核心设计
传统事件模式，更适合游戏开发习惯

📚 核心概念

Entity（实体）

实体是游戏世界中的基本对象，可以挂载组件和运行系统。

// 创建实体
const entity = scene.createEntity("Player");

// 设置实体属性
entity.tag = 1;
entity.updateOrder = 0;
entity.enabled = true;

// 批量创建实体
const entities = scene.createEntities(100, "Enemy");

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();
        }
    }
}

// 添加组件到实体
entity.addComponent(new HealthComponent());

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();
            }
        }
    }
}

🧪 测试

# 运行所有测试
npm run test

# 性能基准测试
npm run benchmark

📖 文档

快速入门 - 从零开始学习框架使用
EntityManager 使用指南 - 详细了解实体管理器的高级功能
事件系统使用指南 - 学习类型安全事件系统的完整用法
性能优化指南 - 深入了解三大性能优化系统
核心概念 - 深入了解 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游戏框架交流

🚀 核心性能指标

实体创建: 640,000+ 个/秒
组件查询: O(1) 复杂度（使用索引）
内存优化: 30-50% 减少分配
批量操作: 显著提升处理效率

🎯 性能优化技术

组件索引系统: 哈希和位图双重索引，支持 O(1) 查询
Archetype 系统: 按组件组合分组，减少查询开销
脏标记机制: 细粒度变更追踪，避免不必要的计算
批量操作 API: 减少函数调用开销，提升大规模操作效率
智能缓存: 查询结果缓存和延迟清理机制

🔧 性能建议

大规模场景: 使用批量API和组件索引
频繁查询: 启用Archetype系统进行快速筛选
实时游戏: 利用脏标记减少无效更新
移动端: 建议实体数量控制在20,000以内

运行 npm run benchmark 查看在您的环境中的具体性能表现。

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

Languages

TypeScript 89.7%

Rust 4.7%

CSS 4.4%

JavaScript 0.9%

HTML 0.3%

README.md Unescape Escape

ECS Framework

✨ 核心特性

📦 安装

🚀 快速开始

1. 基础设置