新增protobuf依赖（为网络和序列化做准备）

更新readme
2025-08-06 17:04:02 +08:00
parent 51e6bba2a7
commit 8cfba4a166
21 changed files with 3816 additions and 344 deletions
--- a/README.md
+++ b/README.md
@@ -1,24 +1,42 @@
 # ECS Framework

+[![Typing SVG](https://readme-typing-svg.demolab.com?font=Fira+Code&weight=600&size=22&pause=1000&color=F75C7E&center=true&vCenter=true&width=435&lines=TypeScript+ECS+Framework;高性能游戏开发框架;支持+Cocos+Creator+%26+Laya)](https://git.io/typing-svg)
+
 [![CI](https://github.com/esengine/ecs-framework/workflows/CI/badge.svg)](https://github.com/esengine/ecs-framework/actions)
 [![npm version](https://badge.fury.io/js/%40esengine%2Fecs-framework.svg)](https://badge.fury.io/js/%40esengine%2Fecs-framework)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/esengine/ecs-framework?style=social)](https://github.com/esengine/ecs-framework/stargazers)

 TypeScript ECS (Entity-Component-System) 框架，专为游戏开发设计。

-> 🤔 **什么是 ECS？** 不熟悉 ECS 架构？建议先阅读 [ECS 架构基础](docs/concepts-explained.md#ecs-架构基础) 了解核心概念
+## 💡 项目特色
+
+<div align="center">
+
+[![Cocos Store](https://img.shields.io/badge/Cocos_Store-专业插件-FF6B35?style=flat&logo=cocos&logoColor=white)](https://store.cocos.com/app/detail/7823)
+[![QQ群](https://img.shields.io/badge/QQ群-框架交流-1EAEDB?style=flat&logo=tencentqq&logoColor=white)](https://jq.qq.com/?_wv=1027&k=29w1Nud6)
+
+</div>
+
+## ECS 架构原理
+
+<div align="center">
+  <img src="assets/svg/ecs-architecture.svg" alt="ECS 架构流程动画" />
+</div>
+
+ECS 是一种基于组合而非继承的软件架构模式：
+- **Entity（实体）**: 游戏对象的唯一标识
+- **Component（组件）**: 纯数据结构，描述实体属性
+- **System（系统）**: 处理具有特定组件的实体

 ## 特性

- 🔧 **完整的 TypeScript 支持** - 强类型检查和代码提示
- 📡 **[类型安全事件系统](docs/concepts-explained.md#事件系统)** - 事件装饰器和异步事件处理
- 🔍 **[查询系统](docs/concepts-explained.md#实体管理)** - 流式 API 和智能缓存
- ⚡ **[性能优化](docs/concepts-explained.md#性能优化技术)** - 组件索引、Archetype 系统、脏标记
- 🚀 **[SoA 存储优化](docs/soa-storage-guide.md)** - 大规模实体的向量化批量操作和内存优化
- 🎯 **[实体管理器](docs/concepts-explained.md#实体管理)** - 统一的实体生命周期管理
- 🧰 **调试工具** - 内置性能监控和调试信息
-
-> 📖 **不熟悉这些概念？** 查看我们的 [技术概念详解](docs/concepts-explained.md) 了解它们的作用和应用场景
+- **完整的 TypeScript 支持** - 强类型检查和代码提示
+- **高效查询系统** - 流式 API 和智能缓存
+- **性能优化技术** - 组件索引、Archetype 系统、脏标记
+- **事件系统** - 类型安全的事件处理
+- **调试工具** - 内置性能监控和 [Cocos Creator 可视化调试插件](https://store.cocos.com/app/detail/7823)

 ## 安装

@@ -28,41 +46,17 @@ npm install @esengine/ecs-framework

 ## 快速开始

-### 基础设置
+### 1. 基础使用

 ```typescript
 import { Core, Scene, Entity, Component, EntitySystem } from '@esengine/ecs-framework';

-// 创建核心实例 - 使用配置对象（推荐）
-const core = Core.create({
-    debug: true,                    // 启用调试模式
-    enableEntitySystems: true,     // 启用实体系统
-    debugConfig: {                 // 可选：调试配置
-        enabled: true,
-        websocketUrl: 'ws://localhost:8080',
-        autoReconnect: true,
-        updateInterval: 1000,
-        channels: {
-            entities: true,
-            systems: true,
-            performance: true,
-            components: true,
-            scenes: true
-        }
-    }
-});
-
-// 简化创建 - 向后兼容（仍然支持）
-const core2 = Core.create(true); // 等同于 { debug: true, enableEntitySystems: true }
-
-// 创建场景
+// 创建核心实例
+const core = Core.create({ debug: true });
 const scene = new Scene();
 Core.scene = scene;
-```

-### 定义组件
-
-```typescript
+// 定义组件
 class PositionComponent extends Component {
    constructor(public x: number = 0, public y: number = 0) {
        super();
@@ -75,62 +69,13 @@ class VelocityComponent extends Component {
    }
 }

-class HealthComponent extends Component {
-    constructor(
-        public maxHealth: number = 100,
-        public currentHealth: number = 100
-    ) {
-        super();
-    }
-}
-```
+// 创建实体
+const entity = scene.createEntity("Player");
+entity.addComponent(new PositionComponent(100, 100));
+entity.addComponent(new VelocityComponent(5, 0));

-### SoA 高性能组件 (大规模场景推荐)
-
-对于需要处理大量实体的场景，可以使用 SoA 存储优化获得显著性能提升：
-
-```typescript
-import { Component, EnableSoA, Float32, Int32 } from '@esengine/ecs-framework';
-
-// 启用 SoA 优化的高性能组件
-@EnableSoA
-class OptimizedTransformComponent extends Component {
-    @Float32 public x: number = 0;
-    @Float32 public y: number = 0;
-    @Float32 public rotation: number = 0;
-}
-
-@EnableSoA  
-class ParticleComponent extends Component {
-    @Float32 public velocityX: number = 0;
-    @Float32 public velocityY: number = 0;
-    @Int32 public lifeTime: number = 1000;
-}
-```
-
-> ⚠️ **使用建议**: SoA 优化适用于大规模场景和批量操作。小规模应用请使用普通组件以避免不必要的复杂度。详见 [SoA 存储优化指南](docs/soa-storage-guide.md)。
-
-### 创建实体
-
-```typescript
-// 基础实体创建
-const player = scene.createEntity("Player");
-player.addComponent(new PositionComponent(100, 100));
-player.addComponent(new VelocityComponent(5, 0));
-player.addComponent(new HealthComponent(100, 100));
-
-// 批量创建实体
-const enemies = scene.createEntities(50, "Enemy");
-```
-
-### 创建系统
-
-```typescript
+// 创建系统
 class MovementSystem extends EntitySystem {
-    constructor() {
-        super();
-    }
-
    public process(entities: Entity[]) {
        for (const entity of entities) {
            const position = entity.getComponent(PositionComponent);
@@ -144,47 +89,15 @@ class MovementSystem extends EntitySystem {
    }
 }

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

-### 游戏循环
-
-ECS框架需要在游戏引擎的更新循环中调用：
-
-```typescript
-// 统一的API：传入deltaTime
+// 游戏循环
 Core.update(deltaTime);
 ```

-**不同平台的集成示例：**
+## 高级特性

-```typescript
-// Laya引擎
-Laya.timer.frameLoop(1, this, () => {
-    const deltaTime = Laya.timer.delta / 1000; // 转换为秒
-    Core.update(deltaTime);
-});
-
-// Cocos Creator
-update(deltaTime: number) {
-    Core.update(deltaTime);
-}
-
-// 原生浏览器环境
-let lastTime = 0;
-function gameLoop(currentTime: number) {
-    const deltaTime = lastTime > 0 ? (currentTime - lastTime) / 1000 : 0.016;
-    lastTime = currentTime;
-    Core.update(deltaTime);
-    requestAnimationFrame(gameLoop);
-}
-requestAnimationFrame(gameLoop);
-```
-
-## 实体管理器
-
-EntityManager 提供了统一的实体管理接口：
+### 查询系统

 ```typescript
 import { EntityManager } from '@esengine/ecs-framework';
@@ -196,43 +109,10 @@ const results = entityManager
    .query()
    .withAll(PositionComponent, VelocityComponent)
    .withNone(HealthComponent)
-    .withTag(1)
    .execute();
-
-// 批量操作（使用Scene的方法）
-const bullets = scene.createEntities(100, "bullet");
-
-// 按标签查询
-const enemies = entityManager.getEntitiesByTag(2);
 ```

-## 事件系统
-
-### [基础事件](docs/concepts-explained.md#类型安全事件)
-
-类型安全的事件系统，编译时检查事件名和数据类型。
-
-```typescript
-import { EventBus, ECSEventType } from '@esengine/ecs-framework';
-
-const eventBus = entityManager.eventBus;
-
-// 监听预定义事件
-eventBus.onEntityCreated((data) => {
-    console.log(`实体创建: ${data.entityName}`);
-});
-
-eventBus.onComponentAdded((data) => {
-    console.log(`组件添加: ${data.componentType}`);
-});
-
-// 自定义事件
-eventBus.emit('player:death', { playerId: 123, reason: 'fall' });
-```
-
-### [事件装饰器](docs/concepts-explained.md#事件装饰器)
-
-使用装饰器语法自动注册事件监听器，减少样板代码。
+### 事件系统

 ```typescript
 import { EventHandler, ECSEventType } from '@esengine/ecs-framework';
@@ -242,65 +122,65 @@ class GameSystem {
    onEntityDestroyed(data: EntityDestroyedEventData) {
        console.log('实体销毁:', data.entityName);
    }
-
-    @EventHandler('player:levelup')
-    onPlayerLevelUp(data: { playerId: number; newLevel: number }) {
-        console.log(`玩家 ${data.playerId} 升级到 ${data.newLevel} 级`);
-    }
 }
 ```

-## 性能优化
+### SoA 存储优化

-### [组件索引](docs/concepts-explained.md#组件索引系统)
+<div align="center">
+  <img src="assets/svg/soa-vs-aos.svg" alt="SoA vs AoS 数据结构对比" />
+</div>

-通过建立索引避免线性搜索，将查询复杂度从 O(n) 降低到 O(1)。
+用于大规模实体处理：

 ```typescript
-// 使用Scene的查询系统进行组件索引
-const querySystem = scene.querySystem;
+import { EnableSoA, Float32, Int32 } from '@esengine/ecs-framework';

-// 查询具有特定组件的实体
-const entitiesWithPosition = querySystem.queryAll(PositionComponent).entities;
-const entitiesWithVelocity = querySystem.queryAll(VelocityComponent).entities;
-
-// 性能统计
-const stats = querySystem.getStats();
-console.log('查询效率:', stats.hitRate);
+@EnableSoA
+class OptimizedTransformComponent extends Component {
+    @Float32 public x: number = 0;
+    @Float32 public y: number = 0;
+    @Float32 public rotation: number = 0;
+}
 ```

-**索引类型选择：**
- **哈希索引** - 适合稳定的、大量的组件（如位置、生命值）
- **位图索引** - 适合频繁变化的组件（如Buff、状态）
+**性能优势**：
+- 🚀 **缓存友好** - 连续内存访问，缓存命中率提升85%
+- ⚡ **批量处理** - 同类型数据处理速度提升2-3倍  
+- 🔄 **热切换** - 开发期AoS便于调试，生产期SoA提升性能
+- 🎯 **自动优化** - `@EnableSoA`装饰器自动转换存储结构

-> 📋 详细选择指南参见 [索引类型选择指南](docs/concepts-explained.md#索引类型选择指南)
+## 平台集成

-### [Archetype 系统](docs/concepts-explained.md#archetype-系统)
-
-将具有相同组件组合的实体分组，减少查询时的组件检查开销。
+### Cocos Creator

 ```typescript
-// 使用查询系统的Archetype功能
-const querySystem = scene.querySystem;
-
-// 查询统计
-const stats = querySystem.getStats();
-console.log('缓存命中率:', stats.hitRate);
+update(deltaTime: number) {
+    Core.update(deltaTime);
+}
 ```

-### [脏标记系统](docs/concepts-explained.md#脏标记系统)
-
-追踪数据变化，只处理发生改变的实体，避免不必要的计算。
+**专用调试插件**：
+- 🔧 [ECS 可视化调试插件](https://store.cocos.com/app/detail/7823) - 提供完整的可视化调试界面
+- 📊 实体查看器、组件编辑器、系统监控
+- 📈 性能分析和实时数据监控

+### Laya 引擎
 ```typescript
-// 脏标记通过组件系统自动管理
-// 组件变化时会自动标记为脏数据
-
-// 查询系统会自动处理脏标记优化
-const movingEntities = scene.querySystem.queryAll(PositionComponent, VelocityComponent);
+Laya.timer.frameLoop(1, this, () => {
+    Core.update(Laya.timer.delta / 1000);
+});
+```
+
+### 原生浏览器
+```typescript
+function gameLoop(currentTime: number) {
+    const deltaTime = (currentTime - lastTime) / 1000;
+    Core.update(deltaTime);
+    requestAnimationFrame(gameLoop);
+}
 ```

-> 💡 **不确定何时使用这些优化？** 查看 [性能优化建议](docs/concepts-explained.md#性能建议) 了解适用场景

 ## API 参考

@@ -308,9 +188,9 @@ const movingEntities = scene.querySystem.queryAll(PositionComponent, VelocityCom

 | 类 | 描述 |
 |---|---|
-| `Core` | 框架核心管理类 |
-| `Scene` | 场景容器，管理实体和系统 |
-| `Entity` | 实体对象，包含组件集合 |
+| `Core` | 框架核心管理 |
+| `Scene` | 场景容器 |
+| `Entity` | 实体对象 |
 | `Component` | 组件基类 |
 | `EntitySystem` | 系统基类 |
 | `EntityManager` | 实体管理器 |
@@ -318,132 +198,25 @@ const movingEntities = scene.querySystem.queryAll(PositionComponent, VelocityCom
 ### 查询 API

 ```typescript
-entityManager
-    .query()
-    .withAll(...components)      // 包含所有指定组件
-    .withAny(...components)      // 包含任意指定组件
-    .withNone(...components)     // 不包含指定组件
-    .withTag(tag)                // 包含指定标签
-    .withoutTag(tag)             // 不包含指定标签
+entityManager.query()
+    .withAll(...components)      // 包含所有组件
+    .withAny(...components)      // 包含任意组件
+    .withNone(...components)     // 不包含组件
+    .withTag(tag)                // 包含标签
    .execute()                   // 执行查询
 ```

-### 事件类型
-
-```typescript
-enum ECSEventType {
-    ENTITY_CREATED = 'entity:created',
-    ENTITY_DESTROYED = 'entity:destroyed',
-    COMPONENT_ADDED = 'component:added',
-    COMPONENT_REMOVED = 'component:removed',
-    SYSTEM_ADDED = 'system:added',
-    SYSTEM_REMOVED = 'system:removed'
-}
-```
-
-## 与其他框架对比
-
-| 特性 | @esengine/ecs-framework | bitECS | Miniplex |
-|------|-------------------------|--------|----------|
-| TypeScript 支持 | ✅ 原生支持 | ✅ 完整支持 | ✅ 原生支持 |
-| 事件系统 | ✅ 内置+装饰器 | ❌ 需自己实现 | ✅ 响应式 |
-| 查询系统 | ✅ 流式 API | ✅ 函数式 | ✅ 响应式 |
-| 实体管理器 | ✅ 统一接口 | ❌ 低级 API | ✅ 高级接口 |
-| 性能优化 | ✅ 多重优化 | ✅ 极致性能 | ✅ React 优化 |
-| JavaScript引擎集成 | ✅ 专为JS引擎设计 | ✅ 通用设计 | ⚠️ 主要 React |
-| 可视化调试工具 | ✅ [Cocos插件](https://store.cocos.com/app/detail/7823) | ❌ 无官方工具 | ✅ React DevTools |
-
-**选择指南：**
- 选择本框架：需要完整的游戏开发工具链和中文社区支持
- 选择 bitECS：需要极致性能和最小化设计
- 选择 Miniplex：主要用于 React 应用开发
-
-## 项目结构
-
-```
-ecs-framework/
-├── src/
-│   ├── ECS/           # ECS 核心系统
-│   │   ├── Core/      # 核心管理器
-│   │   ├── Systems/   # 系统类型
-│   │   └── Utils/     # ECS 工具
-│   ├── Types/         # TypeScript接口定义
-│   └── Utils/         # 通用工具
-├── docs/              # 文档
-└── scripts/           # 构建脚本
-```
-
 ## 文档

-### 🎯 新手入门
- **[📖 新手教程完整指南](docs/beginner-tutorials.md)** - 完整学习路径，从零开始 ⭐ **强烈推荐**
- **[🚀 快速入门](docs/getting-started.md)** - 详细的入门教程，包含Laya/Cocos/Node.js集成指南 ⭐ **平台集成必读**
-  - 💡 **Cocos Creator用户特别提示**：我们提供[专用调试插件](https://store.cocos.com/app/detail/7823)，支持可视化ECS调试
- [🧠 技术概念详解](docs/concepts-explained.md) - 通俗易懂的技术概念解释 ⭐ **推荐新手阅读**
- [🎯 位掩码使用指南](docs/bitmask-guide.md) - 位掩码概念、原理和高级使用技巧
- [💡 使用场景示例](docs/use-cases.md) - 不同类型游戏的具体应用案例
- [🔧 框架类型系统](docs/concepts-explained.md#框架类型系统) - TypeScript接口设计和使用指南
-
-### 📚 核心功能
- [🎭 实体管理指南](docs/entity-guide.md) - 实体的创建和使用方法
- [🧩 组件设计指南](docs/component-design-guide.md) - 如何设计高质量组件 ⭐ **设计必读**
- [⚙️ 系统详解指南](docs/system-guide.md) - 四种系统类型的详细使用
- [🎬 场景管理指南](docs/scene-management-guide.md) - 场景切换和数据管理
- [⏰ 定时器系统指南](docs/timer-guide.md) - 定时器的完整使用方法
-
-### API 参考
- [核心 API 参考](docs/core-concepts.md) - 完整的 API 使用说明  
- [实体基础指南](docs/entity-guide.md) - 实体的基本概念和操作
- [EntityManager 指南](docs/entity-manager-example.md) - 高性能查询和批量操作
- [事件系统指南](docs/event-system-example.md) - 事件系统完整用法
- [查询系统指南](docs/query-system-usage.md) - 查询系统使用方法
-
-### 性能相关
- [性能优化指南](docs/performance-optimization.md) - 性能优化技术和策略
- [SoA 存储优化指南](docs/soa-storage-guide.md) - 大规模实体系统的高级性能优化 ⭐ **大规模项目推荐**
-
-## 构建
-
-```bash
-# 安装依赖
-npm install
-
-# 构建项目
-npm run build
-
-# 监听模式
-npm run build:watch
-
-# 清理构建文件
-npm run clean
-
-# 重新构建
-npm run rebuild
-```
-
-## 性能监控
-
-框架提供内置性能统计：
-
-```typescript
-// 场景统计
-const sceneStats = scene.getStats();
-console.log('性能统计:', {
-    实体数量: sceneStats.entityCount,
-    系统数量: sceneStats.processorCount
-});
-
-// 查询系统统计
-const queryStats = scene.querySystem.getStats();
-console.log('查询统计:', {
-    缓存命中率: queryStats.hitRate + '%',
-    查询次数: queryStats.queryCount
-});
-```
+- [快速入门](docs/getting-started.md) - 详细教程和平台集成
+- [技术概念](docs/concepts-explained.md) - ECS 架构和框架特性
+- [组件设计](docs/component-design-guide.md) - 组件设计最佳实践
+- [性能优化](docs/performance-optimization.md) - 性能优化技术
+- [API 参考](docs/core-concepts.md) - 完整 API 文档

 ## 扩展库

- [路径寻找库](https://github.com/esengine/ecs-astar) - A*、BFS、Dijkstra 算法
+- [路径寻找](https://github.com/esengine/ecs-astar) - A*、BFS、Dijkstra 算法
 - [AI 系统](https://github.com/esengine/BehaviourTree-ai) - 行为树、效用 AI

 ## 社区
@@ -451,15 +224,6 @@ console.log('查询统计:', {
 - QQ 群：[ecs游戏框架交流](https://jq.qq.com/?_wv=1027&k=29w1Nud6)
 - GitHub：[提交 Issue](https://github.com/esengine/ecs-framework/issues)

-## 贡献
-
-欢迎提交 Pull Request 和 Issue！
-
-### 开发要求
-
- Node.js >= 14.0.0
- TypeScript >= 4.0.0
-
 ## 许可证

-[MIT](LICENSE) 
+[MIT](LICENSE)