docs: 更新项目文档 - 添加EntityManager、事件系统、性能优化使用示例和说明

2025-06-09 13:25:10 +08:00
parent 4095f1e946
commit 40b3fe7165
5 changed files with 1824 additions and 527 deletions
--- a/docs/entity-manager-example.md
+++ b/docs/entity-manager-example.md
@@ -0,0 +1,421 @@
+# EntityManager 使用指南
+
+EntityManager 是 ECS Framework 的核心管理系统，提供统一的实体管理、高性能查询和自动优化功能。
+
+## 快速开始
+
+### 创建实体管理器
+
+```typescript
+import { EntityManager, Scene } from '@esengine/ecs-framework';
+
+// 通常在游戏管理器中创建
+const scene = new Scene();
+const entityManager = new EntityManager(scene);
+```
+
+### 基础实体操作
+
+```typescript
+// 创建单个实体
+const player = entityManager.createEntity("Player");
+player.addComponent(new PositionComponent(100, 100));
+player.addComponent(new HealthComponent(100));
+player.tag = "player";
+
+// 批量创建实体
+const enemies = entityManager.createEntities(50, "Enemy");
+enemies.forEach((enemy, index) => {
+    enemy.addComponent(new PositionComponent(
+        Math.random() * 800, 
+        Math.random() * 600
+    ));
+    enemy.addComponent(new HealthComponent(30));
+    enemy.tag = "enemy";
+});
+
+// 销毁实体
+entityManager.destroyEntity(player);
+```
+
+## 高性能查询系统
+
+EntityManager 提供多种查询方式，自动选择最优的查询策略。
+
+### 基础查询
+
+```typescript
+// 通过ID查询（O(1)）
+const entity = entityManager.getEntity(123);
+
+// 通过名称查询（O(1) 哈希查找）
+const player = entityManager.getEntityByName("Player");
+
+// 通过标签查询（O(1) 索引查找）
+const enemies = entityManager.getEntitiesByTag("enemy");
+
+// 组件查询（使用O(1)组件索引）
+const healthEntities = entityManager.getEntitiesWithComponent(HealthComponent);
+
+// 多组件查询（使用Archetype优化）
+const movingEntities = entityManager.getEntitiesWithComponents([
+    PositionComponent, 
+    VelocityComponent
+]);
+```
+
+### 流式查询API
+
+EntityManager 提供强大的流式查询构建器：
+
+```typescript
+// 基础查询构建
+const results = entityManager
+    .query()
+    .withAll([PositionComponent, HealthComponent])  // 必须包含这些组件
+    .withoutTag("dead")                             // 不能有死亡标签
+    .active(true)                                   // 必须激活
+    .execute();
+
+// 复杂条件查询
+const livingEnemies = entityManager
+    .query()
+    .withAll([PositionComponent, HealthComponent])
+    .withTag("enemy")
+    .withoutTag("dead")
+    .where(entity => {
+        const health = entity.getComponent(HealthComponent);
+        return health && health.currentHealth > 0;
+    })
+    .execute();
+
+// 查询变体
+const firstEnemy = entityManager
+    .query()
+    .withTag("enemy")
+    .first();                                       // 获取第一个匹配
+
+const enemyCount = entityManager
+    .query()
+    .withTag("enemy")
+    .count();                                       // 获取数量
+
+// 直接处理查询结果
+entityManager
+    .query()
+    .withAll([HealthComponent])
+    .forEach(entity => {
+        const health = entity.getComponent(HealthComponent);
+        if (health.currentHealth <= 0) {
+            entity.addTag("dead");
+        }
+    });
+```
+
+### 高级查询选项
+
+```typescript
+// 组合条件查询
+const combatUnits = entityManager
+    .query()
+    .withAll([PositionComponent, HealthComponent])   // AND条件
+    .withAny([WeaponComponent, MagicComponent])      // OR条件
+    .without([DeadComponent])                        // NOT条件
+    .withTag("combatant")
+    .withoutTag("peaceful")
+    .active(true)
+    .enabled(true)
+    .execute();
+
+// 使用自定义过滤器
+const nearbyEnemies = entityManager
+    .query()
+    .withAll([PositionComponent])
+    .withTag("enemy")
+    .where(entity => {
+        const pos = entity.getComponent(PositionComponent);
+        const distance = Math.sqrt(
+            Math.pow(pos.x - playerPos.x, 2) + 
+            Math.pow(pos.y - playerPos.y, 2)
+        );
+        return distance < 100; // 距离玩家100像素内
+    })
+    .execute();
+```
+
+## 批量操作
+
+EntityManager 提供高效的批量操作方法：
+
+```typescript
+// 遍历所有实体
+entityManager.forEachEntity(entity => {
+    // 处理每个实体
+    if (entity.position.x < 0) {
+        entity.position.x = 0;
+    }
+});
+
+// 遍历特定组件的实体
+entityManager.forEachEntityWithComponent(HealthComponent, (entity, health) => {
+    if (health.currentHealth <= 0) {
+        entity.addTag("dead");
+        entity.enabled = false;
+    }
+});
+
+// 批量创建并配置实体
+const bullets = entityManager.createEntities(100, "Bullet", (bullet, index) => {
+    bullet.addComponent(new PositionComponent(
+        100 + index * 10, 
+        100
+    ));
+    bullet.addComponent(new VelocityComponent(0, -200));
+    bullet.tag = "projectile";
+});
+```
+
+## 性能优化系统
+
+EntityManager 内置了三个性能优化系统：
+
+### 1. 组件索引系统
+
+自动为组件查询提供O(1)性能：
+
+```typescript
+// 获取组件索引统计
+const componentIndex = entityManager.getComponentIndex();
+const stats = componentIndex.getPerformanceStats();
+
+console.log('组件索引统计:', {
+    totalQueries: stats.totalQueries,
+    indexHits: stats.indexHits,
+    hitRate: (stats.indexHits / stats.totalQueries * 100).toFixed(2) + '%'
+});
+
+// 手动优化（通常自动进行）
+componentIndex.optimize();
+```
+
+### 2. Archetype系统
+
+按组件组合分组实体，优化批量查询：
+
+```typescript
+// 获取Archetype统计
+const archetypeSystem = entityManager.getArchetypeSystem();
+const archetypeStats = archetypeSystem.getStatistics();
+
+console.log('Archetype统计:', {
+    totalArchetypes: archetypeStats.totalArchetypes,
+    totalEntities: archetypeStats.totalEntities,
+    queryCacheSize: archetypeStats.queryCacheSize
+});
+
+// 查看所有原型
+console.log('当前原型:', archetypeSystem.getAllArchetypes());
+```
+
+### 3. 脏标记系统
+
+追踪实体变更，避免不必要的更新：
+
+```typescript
+// 获取脏标记统计
+const dirtyTracking = entityManager.getDirtyTrackingSystem();
+const dirtyStats = dirtyTracking.getPerformanceStats();
+
+console.log('脏标记统计:', {
+    totalMarks: dirtyStats.totalMarks,
+    batchesProcessed: dirtyStats.batchesProcessed,
+    listenersNotified: dirtyStats.listenersNotified
+});
+
+// 手动处理脏标记
+dirtyTracking.processDirtyMarks();
+```
+
+## 实体管理器统计
+
+获取EntityManager的综合性能数据：
+
+```typescript
+const stats = entityManager.getStatistics();
+
+console.log('EntityManager统计:', {
+    // 基础统计
+    entityCount: stats.entityCount,
+    activeEntityCount: stats.activeEntityCount,
+    
+    // 查询统计
+    totalQueries: stats.totalQueries,
+    indexHits: stats.indexHits,
+    archetypeHits: stats.archetypeHits,
+    
+    // 性能指标
+    averageQueryTime: stats.averageQueryTime,
+    hitRate: (stats.indexHits / stats.totalQueries * 100).toFixed(2) + '%'
+});
+```
+
+## 系统优化和清理
+
+```typescript
+// 手动触发优化
+entityManager.optimize();
+
+// 内存清理
+entityManager.cleanup();
+
+// 压缩数据结构
+entityManager.compact();
+
+// 获取内存使用情况
+const memoryStats = entityManager.getMemoryUsage();
+console.log('内存使用:', {
+    entityIndexSize: memoryStats.entityIndex,
+    componentIndexSize: memoryStats.componentIndex,
+    archetypeSize: memoryStats.archetype
+});
+```
+
+## 实际使用案例
+
+### 游戏系统集成
+
+```typescript
+class MovementSystem extends EntitySystem {
+    private entityManager: EntityManager;
+    
+    constructor(scene: Scene) {
+        super();
+        this.entityManager = new EntityManager(scene);
+    }
+    
+    protected process(entities: Entity[]): void {
+        // 使用高效查询获取移动实体
+        const movingEntities = this.entityManager
+            .query()
+            .withAll([PositionComponent, VelocityComponent])
+            .active(true)
+            .execute();
+        
+        // 批量处理
+        movingEntities.forEach(entity => {
+            const position = entity.getComponent(PositionComponent);
+            const velocity = entity.getComponent(VelocityComponent);
+            
+            position.x += velocity.dx * Time.deltaTime;
+            position.y += velocity.dy * Time.deltaTime;
+        });
+    }
+}
+```
+
+### 复杂查询示例
+
+```typescript
+// 战斗系统：查找攻击范围内的敌人
+class CombatSystem {
+    private entityManager: EntityManager;
+    
+    findTargetsInRange(attacker: Entity, range: number): Entity[] {
+        const attackerPos = attacker.getComponent(PositionComponent);
+        if (!attackerPos) return [];
+        
+        return this.entityManager
+            .query()
+            .withAll([PositionComponent, HealthComponent])
+            .withTag("enemy")
+            .withoutTag("dead")
+            .where(entity => {
+                const pos = entity.getComponent(PositionComponent);
+                const distance = Math.sqrt(
+                    Math.pow(pos.x - attackerPos.x, 2) + 
+                    Math.pow(pos.y - attackerPos.y, 2)
+                );
+                return distance <= range;
+            })
+            .execute();
+    }
+    
+    // 优化版本：使用空间分区（如果实现了的话）
+    findTargetsInRangeOptimized(attacker: Entity, range: number): Entity[] {
+        // 首先通过空间查询缩小范围
+        const nearbyEntities = this.spatialIndex.queryRange(
+            attackerPos.x - range, 
+            attackerPos.y - range,
+            attackerPos.x + range, 
+            attackerPos.y + range
+        );
+        
+        // 然后使用EntityManager进行精确过滤
+        return this.entityManager
+            .query()
+            .withAll([HealthComponent])
+            .withTag("enemy")
+            .withoutTag("dead")
+            .where(entity => nearbyEntities.includes(entity))
+            .execute();
+    }
+}
+```
+
+## 性能建议
+
+### 查询优化
+
+1. **利用索引**: 优先使用组件查询和标签查询，它们具有O(1)性能
+2. **减少自定义过滤**: `where()`条件虽然灵活，但会降低性能
+3. **缓存查询结果**: 对于不经常变化的查询结果，考虑缓存
+
+```typescript
+// ✅ 推荐：使用索引查询
+const enemies = entityManager.getEntitiesByTag("enemy");
+
+// ⚠️ 谨慎：自定义过滤
+const enemies = entityManager
+    .query()
+    .where(entity => entity.name.includes("Enemy"))
+    .execute();
+```
+
+### 批量操作优化
+
+```typescript
+// ✅ 推荐：批量创建
+const bullets = entityManager.createEntities(100, "Bullet");
+
+// ❌ 避免：循环单独创建
+for (let i = 0; i < 100; i++) {
+    entityManager.createEntity("Bullet");
+}
+```
+
+### 内存管理
+
+```typescript
+// 定期清理
+setInterval(() => {
+    entityManager.cleanup();
+}, 30000); // 每30秒清理一次
+
+// 监控性能
+const stats = entityManager.getStatistics();
+if (stats.indexHits / stats.totalQueries < 0.8) {
+    console.warn('查询命中率较低，考虑优化查询策略');
+}
+```
+
+## 总结
+
+EntityManager 提供了：
+
+- **统一接口**: 所有实体操作通过一个管理器完成
+- **自动优化**: 内置三个性能优化系统
+- **灵活查询**: 从简单的ID查找到复杂的条件查询
+- **性能监控**: 完整的统计和诊断信息
+- **批量操作**: 高效的批量处理能力
+
+通过合理使用EntityManager，您可以构建高性能、可维护的ECS游戏系统。