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/performance-optimization.md
+++ b/docs/performance-optimization.md
@@ -0,0 +1,497 @@
+# 性能优化指南
+
+ECS Framework 提供了多层性能优化系统，确保在各种规模的游戏中都能提供卓越的性能表现。
+
+## 性能优化架构
+
+### 三大核心优化系统
+
+1. **组件索引系统 (ComponentIndex)** - 提供 O(1) 组件查询性能
+2. **Archetype系统** - 按组件组合分组实体，减少查询遍历
+3. **脏标记系统 (DirtyTracking)** - 细粒度变更追踪，避免不必要更新
+
+这三个系统协同工作，为不同场景提供最优的性能表现。
+
+## 性能基准
+
+### 核心操作性能
+
+```
+实体创建: 640,000+ 个/秒
+组件查询: O(1) 复杂度（使用索引）
+内存优化: 30-50% 减少分配
+批量操作: 显著提升处理效率
+```
+
+### 查询性能对比
+
+| 查询类型 | 传统方式 | 使用索引 | 性能提升 |
+|----------|----------|----------|----------|
+| 单组件查询 | O(n) | O(1) | 1000x+ |
+| 多组件查询 | O(n*m) | O(k) | 100x+ |
+| 标签查询 | O(n) | O(1) | 1000x+ |
+| 复合查询 | O(n*m*k) | O(min(k1,k2)) | 500x+ |
+
+*n=实体数量, m=组件种类, k=匹配实体数量*
+
+## 组件索引系统
+
+### 索引类型选择
+
+框架提供两种索引实现：
+
+#### 哈希索引 (HashComponentIndex)
+- **适用场景**: 通用查询，平衡的读写性能
+- **优势**: O(1) 查询，较低内存开销
+- **缺点**: 哈希冲突时性能下降
+
+```typescript
+// 自动选择最优索引类型
+const componentIndex = entityManager.getComponentIndex();
+
+// 手动配置哈希索引
+componentIndex.setIndexType(HealthComponent, 'hash');
+```
+
+#### 位图索引 (BitmapComponentIndex)
+- **适用场景**: 大规模实体，频繁的组合查询
+- **优势**: 超快的 AND/OR 操作，空间压缩
+- **缺点**: 更新成本较高，内存开销随实体数量增长
+
+```typescript
+// 配置位图索引用于大规模查询
+componentIndex.setIndexType(PositionComponent, 'bitmap');
+```
+
+### 智能索引管理
+
+ComponentIndexManager 会根据使用模式自动优化：
+
+```typescript
+// 获取索引性能统计
+const stats = componentIndex.getPerformanceStats();
+console.log('索引性能:', {
+    queriesPerSecond: stats.queriesPerSecond,
+    hitRate: stats.hitRate,
+    indexType: stats.recommendedType
+});
+
+// 自动优化索引类型
+componentIndex.optimize(); // 根据使用模式切换索引类型
+```
+
+## Archetype系统优化
+
+### 原型分组策略
+
+Archetype系统将实体按组件组合分组，实现快速批量操作：
+
+```typescript
+// 获取Archetype统计
+const archetypeSystem = entityManager.getArchetypeSystem();
+const stats = archetypeSystem.getStatistics();
+
+console.log('Archetype优化:', {
+    totalArchetypes: stats.totalArchetypes,    // 原型数量
+    avgEntitiesPerArchetype: stats.averageEntitiesPerArchetype,
+    queryCacheHits: stats.queryCacheHits      // 缓存命中次数
+});
+```
+
+### 查询缓存机制
+
+```typescript
+// 启用查询缓存（默认开启）
+archetypeSystem.enableQueryCache(true);
+
+// 缓存大小限制（避免内存泄漏）
+archetypeSystem.setMaxCacheSize(1000);
+
+// 清理过期缓存
+archetypeSystem.cleanCache();
+```
+
+### 最佳实践
+
+1. **组件设计**: 避免创建过多单独的原型
+2. **批量操作**: 利用原型批量处理相同组件组合的实体
+3. **缓存管理**: 定期清理查询缓存
+
+```typescript
+// ✅ 好的设计：复用组件组合
+class MovementSystem extends EntitySystem {
+    process() {
+        // 一次查询处理所有移动实体
+        const movingEntities = this.entityManager
+            .query()
+            .withAll([PositionComponent, VelocityComponent])
+            .execute(); // 利用Archetype快速获取
+        
+        // 批量处理
+        movingEntities.forEach(entity => {
+            // 更新逻辑
+        });
+    }
+}
+
+// ❌ 避免：频繁查询不同组合
+class BadSystem extends EntitySystem {
+    process() {
+        // 多次小查询，无法充分利用Archetype
+        const players = this.queryPlayers();
+        const enemies = this.queryEnemies();
+        const bullets = this.queryBullets();
+    }
+}
+```
+
+## 脏标记系统优化
+
+### 脏标记类型
+
+系统提供细粒度的脏标记追踪：
+
+```typescript
+enum DirtyType {
+    COMPONENT_ADDED,      // 组件添加
+    COMPONENT_REMOVED,    // 组件移除
+    COMPONENT_MODIFIED,   // 组件修改
+    ENTITY_ENABLED,       // 实体启用
+    ENTITY_DISABLED,      // 实体禁用
+    TAG_ADDED,           // 标签添加
+    TAG_REMOVED          // 标签移除
+}
+```
+
+### 批量处理配置
+
+```typescript
+const dirtyTracking = entityManager.getDirtyTrackingSystem();
+
+// 配置批量处理参数
+dirtyTracking.configure({
+    batchSize: 100,           // 每批处理100个脏标记
+    timeSliceMs: 16,          // 每帧最多处理16ms
+    processingInterval: 1     // 每帧处理一次
+});
+
+// 监听脏标记事件
+dirtyTracking.addListener(DirtyType.COMPONENT_MODIFIED, (entity, component) => {
+    // 响应组件修改
+    this.invalidateRenderCache(entity);
+}, { priority: 10 });
+```
+
+### 性能监控
+
+```typescript
+const dirtyStats = dirtyTracking.getPerformanceStats();
+console.log('脏标记性能:', {
+    totalMarks: dirtyStats.totalMarks,
+    batchesProcessed: dirtyStats.batchesProcessed,
+    averageBatchTime: dirtyStats.averageBatchTime,
+    queueSize: dirtyStats.currentQueueSize
+});
+```
+
+## 查询优化策略
+
+### 查询层次选择
+
+根据查询复杂度选择最优方法：
+
+```typescript
+// 1. 简单查询：直接使用索引
+const healthEntities = entityManager.getEntitiesWithComponent(HealthComponent);
+
+// 2. 双组件查询：使用Archetype
+const movingEntities = entityManager.getEntitiesWithComponents([
+    PositionComponent, 
+    VelocityComponent
+]);
+
+// 3. 复杂查询：组合使用
+const combatants = entityManager
+    .query()
+    .withAll([PositionComponent, HealthComponent])  // Archetype预筛选
+    .withTag("combat")                              // 索引过滤
+    .where(entity => {                              // 自定义精确过滤
+        const health = entity.getComponent(HealthComponent);
+        return health.currentHealth > health.maxHealth * 0.3;
+    })
+    .execute();
+```
+
+### 查询缓存策略
+
+```typescript
+class CombatSystem extends EntitySystem {
+    private cachedEnemies: Entity[] = [];
+    private lastEnemyCacheUpdate = 0;
+    
+    process() {
+        const currentTime = performance.now();
+        
+        // 每200ms更新一次敌人缓存
+        if (currentTime - this.lastEnemyCacheUpdate > 200) {
+            this.cachedEnemies = this.entityManager
+                .getEntitiesByTag("enemy");
+            this.lastEnemyCacheUpdate = currentTime;
+        }
+        
+        // 使用缓存的结果
+        this.processCombat(this.cachedEnemies);
+    }
+}
+```
+
+## 内存优化
+
+### 内存使用监控
+
+```typescript
+// 获取各系统内存使用情况
+const memoryStats = entityManager.getMemoryUsage();
+console.log('内存使用情况:', {
+    entityIndex: memoryStats.entityIndex,        // 实体索引
+    componentIndex: memoryStats.componentIndex,  // 组件索引
+    archetype: memoryStats.archetype,           // 原型系统
+    dirtyTracking: memoryStats.dirtyTracking,   // 脏标记
+    total: memoryStats.total
+});
+```
+
+### 内存清理策略
+
+```typescript
+// 定期内存清理
+setInterval(() => {
+    entityManager.cleanup();      // 清理无效引用
+    entityManager.compact();      // 压缩数据结构
+}, 30000); // 每30秒清理一次
+
+// 游戏场景切换时的深度清理
+function switchScene() {
+    entityManager.destroyAllEntities();
+    entityManager.cleanup();
+    entityManager.compact();
+    
+    // 重置优化系统
+    entityManager.getComponentIndex().reset();
+    entityManager.getArchetypeSystem().clearCache();
+    entityManager.getDirtyTrackingSystem().clear();
+}
+```
+
+## 实战优化案例
+
+### 大规模射击游戏优化
+
+```typescript
+class BulletSystem extends EntitySystem {
+    private bulletPool: Entity[] = [];
+    private maxBullets = 1000;
+    
+    constructor(entityManager: EntityManager) {
+        super();
+        this.prewarmBulletPool();
+    }
+    
+    private prewarmBulletPool() {
+        // 预创建子弹池
+        this.bulletPool = this.entityManager.createEntities(
+            this.maxBullets, 
+            "Bullet"
+        );
+        
+        // 初始化为非激活状态
+        this.bulletPool.forEach(bullet => {
+            bullet.enabled = false;
+            bullet.addComponent(new PositionComponent());
+            bullet.addComponent(new VelocityComponent());
+            bullet.addComponent(new BulletComponent());
+        });
+    }
+    
+    public spawnBullet(x: number, y: number, vx: number, vy: number): Entity | null {
+        // 从池中获取非激活子弹（使用索引快速查询）
+        const availableBullet = this.entityManager
+            .query()
+            .withAll([BulletComponent])
+            .active(false)
+            .first();
+        
+        if (availableBullet) {
+            // 重用现有子弹
+            const pos = availableBullet.getComponent(PositionComponent);
+            const vel = availableBullet.getComponent(VelocityComponent);
+            
+            pos.x = x; pos.y = y;
+            vel.x = vx; vel.y = vy;
+            availableBullet.enabled = true;
+            
+            return availableBullet;
+        }
+        
+        return null; // 池已满
+    }
+    
+    process() {
+        // 批量处理所有激活的子弹
+        this.entityManager.forEachEntityWithComponent(
+            BulletComponent, 
+            (entity, bullet) => {
+                if (!entity.enabled) return;
+                
+                // 更新位置
+                const pos = entity.getComponent(PositionComponent);
+                const vel = entity.getComponent(VelocityComponent);
+                
+                pos.x += vel.x * Time.deltaTime;
+                pos.y += vel.y * Time.deltaTime;
+                
+                // 边界检查，回收到池中
+                if (pos.x < 0 || pos.x > 800 || pos.y < 0 || pos.y > 600) {
+                    entity.enabled = false; // 回收而不是销毁
+                }
+            }
+        );
+    }
+}
+```
+
+### AI系统性能优化
+
+```typescript
+class AISystem extends EntitySystem {
+    private spatialGrid: SpatialGrid;
+    private updateFrequency = 60; // 60Hz更新频率
+    private lastUpdate = 0;
+    
+    process() {
+        const currentTime = performance.now();
+        
+        // 控制更新频率
+        if (currentTime - this.lastUpdate < 1000 / this.updateFrequency) {
+            return;
+        }
+        
+        // 使用空间分区优化邻居查询
+        const aiEntities = this.entityManager
+            .query()
+            .withAll([PositionComponent, AIComponent])
+            .active(true)
+            .execute();
+        
+        // 分批处理AI实体
+        const batchSize = 50;
+        for (let i = 0; i < aiEntities.length; i += batchSize) {
+            const batch = aiEntities.slice(i, i + batchSize);
+            this.processBatch(batch);
+            
+            // 时间片控制，避免单帧卡顿
+            if (performance.now() - currentTime > 10) { // 10ms时间片
+                break; // 下一帧继续处理
+            }
+        }
+        
+        this.lastUpdate = currentTime;
+    }
+    
+    private processBatch(entities: Entity[]) {
+        entities.forEach(entity => {
+            const pos = entity.getComponent(PositionComponent);
+            const ai = entity.getComponent(AIComponent);
+            
+            // 空间查询优化邻居搜索
+            const neighbors = this.spatialGrid.queryRadius(pos.x, pos.y, ai.sightRange);
+            
+            // AI决策逻辑
+            ai.update(neighbors);
+        });
+    }
+}
+```
+
+## 性能监控工具
+
+### 实时性能仪表板
+
+```typescript
+class PerformanceDashboard {
+    private stats: any = {};
+    private updateInterval = 1000; // 1秒更新一次
+    
+    constructor(private entityManager: EntityManager) {
+        setInterval(() => this.updateStats(), this.updateInterval);
+    }
+    
+    private updateStats() {
+        this.stats = {
+            // 基础统计
+            entities: this.entityManager.getStatistics(),
+            
+            // 组件索引
+            componentIndex: this.entityManager.getComponentIndex().getPerformanceStats(),
+            
+            // Archetype系统
+            archetype: this.entityManager.getArchetypeSystem().getStatistics(),
+            
+            // 脏标记系统
+            dirtyTracking: this.entityManager.getDirtyTrackingSystem().getPerformanceStats(),
+            
+            // 内存使用
+            memory: this.entityManager.getMemoryUsage(),
+            
+            // 计算性能指标
+            performance: this.calculatePerformanceMetrics()
+        };
+        
+        this.displayStats();
+    }
+    
+    private calculatePerformanceMetrics() {
+        const componentStats = this.stats.componentIndex;
+        const archetypeStats = this.stats.archetype;
+        
+        return {
+            queryHitRate: componentStats.hitRate,
+            archetypeEfficiency: archetypeStats.averageEntitiesPerArchetype,
+            memoryEfficiency: this.stats.memory.compressionRatio,
+            overallPerformance: this.calculateOverallScore()
+        };
+    }
+    
+    private displayStats() {
+        console.log('=== ECS性能仪表板 ===');
+        console.log('查询命中率:', this.stats.performance.queryHitRate.toFixed(2) + '%');
+        console.log('内存使用:', (this.stats.memory.total / 1024 / 1024).toFixed(2) + 'MB');
+        console.log('整体性能评分:', this.stats.performance.overallPerformance.toFixed(1) + '/10');
+    }
+}
+```
+
+## 优化检查清单
+
+### 开发阶段
+
+- [ ] 使用EntityManager而不是直接操作Scene
+- [ ] 优先使用组件查询和标签查询
+- [ ] 设计合理的组件组合，避免过度碎片化
+- [ ] 实现对象池机制减少频繁创建/销毁
+
+### 运行时优化
+
+- [ ] 监控查询命中率，保持在80%以上
+- [ ] 控制Archetype数量，避免过度分散
+- [ ] 配置适当的脏标记批量处理参数
+- [ ] 定期进行内存清理和数据压缩
+
+### 性能监控
+
+- [ ] 定期检查性能统计数据
+- [ ] 监控内存使用趋势
+- [ ] 设置性能预警阈值
+- [ ] 在不同设备上进行性能测试
+
+通过系统性地应用这些优化策略，您可以构建出在各种规模下都能提供卓越性能的ECS游戏系统。