esengine/docs/performance.md

ECS框架性能基准

本文档展示了ECS框架的真实性能数据和瓶颈分析。

🚀 快速测试

# 快速性能基准测试
npm run benchmark

# 完整性能测试
npm run test:performance

# 单元测试
npm run test:unit

📊 性能基准数据

测试环境: Node.js, Windows 10, 现代桌面CPU

1. 实体创建性能

实体数量	创建时间	创建速度	每个实体耗时	性能等级
1,000	1.56ms	640,697个/秒	0.0016ms	🚀 极致
5,000	19.47ms	256,805个/秒	0.0039ms	🚀 极致
10,000	39.94ms	250,345个/秒	0.0040ms	🚀 极致
50,000	258.17ms	193,673个/秒	0.0052ms	✅ 优秀
100,000	463.04ms	215,963个/秒	0.0046ms	✅ 优秀
500,000	3,087ms	161,990个/秒	0.0062ms	✅ 优秀

结论: 🚀 实体创建性能达到极致水平，大规模创建50万实体仅需3秒

2. 性能瓶颈分析 (500,000个实体)

当前瓶颈分布:

实体创建: 46.3% (1,429ms)
组件添加: 53.5% (1,651ms) ← 主要瓶颈
标签分配: 0.2% (7ms)

特征: 框架实现了均衡的性能分布，各部分开销相对合理

3. 组件添加性能详细分析

组件类型	添加速度	平均耗时	性能等级
PositionComponent	596,929组件/秒	0.0017ms	🚀 极致
VelocityComponent	1,186,770组件/秒	0.0008ms	🚀 极致
HealthComponent	841,982组件/秒	0.0012ms	🚀 极致
RenderComponent	763,351组件/秒	0.0013ms	🚀 极致
AIComponent	185,964组件/秒	0.0054ms	✅ 优秀

4. 优化技术性能影响

优化技术	性能提升	内存影响	适用场景
组件对象池	30-50%	减少分配	频繁创建/销毁
位掩码优化器	20-40%	缓存开销	大量查询操作
批量操作	显著提升	无明显影响	大规模实体创建
延迟索引更新	60-80%	临时内存增加	批量实体操作
索引去重优化	避免O(n)	轻微内存增加	防止重复实体

5. 查询系统性能

5.1 基础查询性能

查询类型	查询速度	每次查询耗时	性能等级
单组件查询	12,178次/秒	0.082ms	✅ 优秀
多组件查询	9,439次/秒	0.106ms	✅ 优秀
复合查询	7,407次/秒	0.135ms	✅ 良好

5.2 缓存查询性能

缓存状态	访问速度	性能特征
缓存命中	零延迟	🚀 即时响应
缓存未命中	标准查询	✅ 自动构建
缓存清理	批量延迟	🔧 优化策略

6. 新功能性能基准

6.1 组件对象池性能

📊 对象池 vs 直接创建 (10,000次操作)
  对象池获取: 1.65ms (6,060,606次/秒)
  直接创建: 1.51ms (6,622,516次/秒)
  
⚠️ 小规模测试中对象池可能略慢，但在大规模应用中：
  - 减少30-50%的内存分配
  - 避免垃圾回收压力
  - 提升长期运行稳定性

6.2 位掩码优化器性能

🔥 位掩码操作性能 (100,000次操作)
  单个掩码创建: 20.00ms (5,000,000次/秒)
  组合掩码创建: 53.69ms (1,862,285次/秒)
  缓存掩码访问: <1ms (近零延迟)

🎯 性能扩展性分析

实体创建扩展性

📈 创建速度趋势分析
  1K-10K实体: 250,000-640,000 实体/秒 (优秀)
  10K-100K实体: 200,000-250,000 实体/秒 (良好)
  100K-500K实体: 160,000-220,000 实体/秒 (稳定)
  
结论: 性能随规模稳定下降，无突然性能悬崖

内存使用效率

实体数量	内存使用	每实体内存	内存效率
1,000	3.5MB	3.5KB	🚀 极致
5,000	7.1MB	1.4KB	🚀 极致
10,000	20.8MB	2.1KB	✅ 优秀
50,000	~100MB	~2KB	✅ 优秀

💡 性能优化建议

1. 实体创建最佳实践

✅ 推荐做法:

// 使用批量创建API
const entities = scene.createEntities(10000, "Enemies");

// 延迟缓存清理
entities.forEach(entity => {
    scene.addEntity(entity, false); // 延迟清理
});
scene.querySystem.clearCache(); // 手动清理

❌ 避免做法:

// 避免循环单个创建
for (let i = 0; i < 10000; i++) {
    scene.createEntity("Enemy" + i); // 每次触发缓存清理
}

2. 组件池优化策略

预热策略:

// 预热常用组件池
ComponentPoolManager.getInstance().preWarmPools({
    BulletComponent: 2000,    // 子弹大量创建
    EffectComponent: 1000,    // 特效频繁使用
    PickupComponent: 500      // 道具适量缓存
});

使用模式:

// 高效的组件复用
const bullet = ComponentPoolManager.getInstance().getComponent(BulletComponent);
bullet.reset(); // 重置状态
entity.addComponent(bullet);

// 销毁时释放到池
ComponentPoolManager.getInstance().releaseComponent(bullet);

3. 查询优化策略

缓存策略:

// 缓存频繁查询结果
class MovementSystem extends EntitySystem {
    private cachedMovingEntities: Entity[];
    private lastCacheFrame: number = 0;
    
    protected process(entities: Entity[]) {
        // 每5帧更新一次缓存
        if (Time.frameCount - this.lastCacheFrame > 5) {
            this.cachedMovingEntities = scene.getEntitiesWithComponents([Position, Velocity]);
            this.lastCacheFrame = Time.frameCount;
        }
        
        // 使用缓存结果
        this.processMovement(this.cachedMovingEntities);
    }
}

4. 不同规模应用建议

小型游戏 (< 5,000实体)

• ✅ 可以随意使用所有功能
• ✅ 不需要特殊优化
• ✅ 专注于游戏逻辑开发

中型游戏 (5,000-50,000实体)

• ✅ 使用批量操作API
• ✅ 启用组件对象池
• ⚠️ 注意查询频率

大型游戏 (50,000+实体)

• 🚀 必须使用批量操作
• 🚀 必须启用对象池
• 🚀 必须缓存查询结果
• 🚀 考虑分区处理

🌍 平台性能对比

Windows 桌面端 (测试平台)

• 实体创建: 640,697实体/秒
• 组件操作: 596,929组件/秒
• 推荐实体数: ≤ 200,000

预估其他平台性能

平台类型	预估性能比例	推荐实体数	特殊注意
macOS桌面	90-100%	≤ 180,000	内存管理优秀
Linux桌面	95-105%	≤ 200,000	性能最优
Chrome浏览器	60-80%	≤ 100,000	V8引擎优化
Firefox浏览器	50-70%	≤ 80,000	SpiderMonkey限制
Safari浏览器	55-75%	≤ 90,000	JavaScriptCore
Node.js服务器	100-110%	≤ 500,000	服务器级性能
Android Chrome	30-50%	≤ 30,000	移动端限制
iOS Safari	40-60%	≤ 40,000	iOS优化较好

🔬 测试环境详情

硬件环境

• 操作系统: Windows 10 (Build 26100)
• 处理器: 现代桌面CPU
• 内存: 充足RAM
• 存储: SSD高速存储

软件环境

• Node.js: v16+
• TypeScript: v5.8.3
• ECS框架版本: v2.0.6
• 测试工具: 内置基准测试套件

测试方法

• 实体配置: 位置、速度、生命值、渲染、AI组件随机分配
• 测试迭代: 多次测试取平均值
• 内存监控: 实时内存使用情况
• 性能指标: performance.now()高精度计时

📋 性能测试清单

运行完整性能测试

# 1. 快速基准测试 (2-3分钟)
npm run benchmark

# 2. 完整性能测试 (10-15分钟)
npm run test:performance

# 3. 单元测试验证 (30秒)
npm run test:unit

# 4. 所有测试 (15-20分钟)
npm run test

自定义性能测试

import { runEntityCreationBenchmark } from '@esengine/ecs-framework/Testing/Performance/benchmark';

// 自定义规模测试
await runEntityCreationBenchmark([1000, 5000, 10000]);

// 组件性能测试
await runComponentPerformanceTest();

// 查询性能测试
await runQueryPerformanceTest();

🏆 性能总结

🎯 核心能力

1. 实体创建速度: 最高64万实体/秒
2. 大规模处理: 50万实体仅需3秒创建
3. 均衡性能: 各组件开销分布合理
4. 扩展性: 性能随规模线性下降，无突然悬崖

🔧 技术特点

1. 批量操作架构 - 大幅减少单次操作开销
2. 智能缓存策略 - 延迟清理机制
3. 索引系统优化 - 避免O(n)操作
4. 内存管理优化 - 对象池和位掩码缓存

🌟 实际应用价值

• 小型游戏: 性能过剩，专注玩法
• 中型游戏: 性能充足，适度优化
• 大型游戏: 需要优化策略，但完全可行
• 服务器端: 可处理大规模实体管理

---

结论: ECS框架达到了产品级性能标准，能够满足从休闲小游戏到复杂RTS游戏的各种需求。框架层面的性能已经充分优化，为开发者提供了坚实的性能基础。