CocosPlugin/esengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

文档及教程更新

Browse Source
This commit is contained in:
YHH
2025-06-10 13:12:14 +08:00
parent ef023d27bf
commit 0c8f232282
21 changed files with 5470 additions and 2017 deletions
Download Patch File Download Diff File Expand all files Collapse all files

585
docs/entity-manager-example.md
View File

@@ -1,421 +1,370 @@
# EntityManager 使用指南
EntityManager 是 ECS Framework 的核心管理系统，提供统一的实体管理、高性能查询和自动优化功能。
本文档详细介绍 EntityManager 的使用方法和最佳实践。
## 快速开始
## 目录
### 创建实体管理器
1. [基础用法](#基础用法)
2. [查询系统](#查询系统)
3. [实体管理](#实体管理)
4. [性能监控](#性能监控)
5. [最佳实践](#最佳实践)
## 基础用法
### 创建 EntityManager
```typescript
import { EntityManager, Scene } from '@esengine/ecs-framework';
// 通常在游戏管理器中创建
// 创建场景和实体管理器
const scene = new Scene();
const entityManager = new EntityManager(scene);
```
const entityManager = new EntityManager();
### 基础实体操作
// 批量创建实体（使用Scene方法）
const enemies = scene.createEntities(50, "Enemy");
```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";
enemy.addComponent(new HealthComponent(100));
enemy.addComponent(new VelocityComponent(
(Math.random() - 0.5) * 100,
(Math.random() - 0.5) * 100
));
enemy.tag = 2; // 敌人标签
});
// 销毁实体
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
]);
// 按标签查询
const enemies = entityManager.getEntitiesByTag(2);
const players = entityManager.getEntitiesByTag(1);
// 按名称查询
const boss = entityManager.getEntityByName("BossEnemy");
// 获取所有实体
const allEntities = entityManager.getAllEntities();
```
### 流式查询API
EntityManager 提供强大的流式查询构建器：
### 流式查询 API
```typescript
// 基础查询构建
const results = entityManager
// 复杂查询条件
const movingEnemies = entityManager
.query()
.withAll([PositionComponent, HealthComponent]) // 必须包含这些组件
.withoutTag("dead") // 不能有死亡标签
.active(true) // 必须激活
.withAll(PositionComponent, VelocityComponent, HealthComponent)
.withTag(2) // 敌人标签
.execute();
// 复杂条件查询
const livingEnemies = entityManager
// 查询活跃的玩家
const activePlayers = entityManager
.query()
.withAll([PositionComponent, HealthComponent])
.withTag("enemy")
.withoutTag("dead")
.where(entity => {
const health = entity.getComponent(HealthComponent);
return health && health.currentHealth > 0;
})
.withAll(PositionComponent)
.withTag(1) // 玩家标签
.active() // 只查询活跃实体
.execute();
// 查询变体
const firstEnemy = entityManager
// 排除特定组件的实体
const nonCombatEntities = 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)
.withAll(PositionComponent)
.without(WeaponComponent, HealthComponent)
.execute();
// 使用自定义过滤器
// 自定义条件查询
const nearbyEnemies = entityManager
.query()
.withAll([PositionComponent])
.withTag("enemy")
.withAll(PositionComponent)
.withTag(2)
.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像素内
return pos && Math.abs(pos.x - playerX) < 100;
})
.execute();
```
## 批量操作
## 实体管理
EntityManager 提供高效的批量操作方法：
### 创建和销毁实体
```typescript
// 遍历所有实体
entityManager.forEachEntity(entity => {
// 处理每个实体
if (entity.position.x < 0) {
entity.position.x = 0;
}
});
// 创建单个实体
const player = entityManager.createEntity("Player");
player.addComponent(new PositionComponent(400, 300));
player.addComponent(new HealthComponent(100));
player.tag = 1;
// 遍历特定组件的实体
entityManager.forEachEntityWithComponent(HealthComponent, (entity, health) => {
if (health.currentHealth <= 0) {
entity.addTag("dead");
entity.enabled = false;
}
});
// 销毁实体
entityManager.destroyEntity(player);
// 批量创建并配置实体
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.destroyEntity("Enemy_1");
// 按ID销毁
entityManager.destroyEntity(123);
```
## 性能优化系统
EntityManager 内置了三个性能优化系统：
### 1. 组件索引系统
自动为组件查询提供O(1)性能：
### 实体查找
```typescript
// 获取组件索引统计
const componentIndex = entityManager.getComponentIndex();
const stats = componentIndex.getPerformanceStats();
// 按ID查找
const entity = entityManager.getEntity(123);
console.log('组件索引统计:', {
totalQueries: stats.totalQueries,
indexHits: stats.indexHits,
hitRate: (stats.indexHits / stats.totalQueries * 100).toFixed(2) + '%'
});
// 按名称查找
const player = entityManager.getEntityByName("Player");
// 手动优化（通常自动进行）
componentIndex.optimize();
// 检查实体是否存在
if (entity && !entity.isDestroyed) {
// 实体有效
}
```
### 2. Archetype系统
## 性能监控
按组件组合分组实体，优化批量查询：
### 基础统计
```typescript
// 获取Archetype统计
const archetypeSystem = entityManager.getArchetypeSystem();
const archetypeStats = archetypeSystem.getStatistics();
// 获取实体数量
console.log('总实体数:', entityManager.entityCount);
console.log('活跃实体数:', entityManager.activeEntityCount);
console.log('Archetype统计:', {
totalArchetypes: archetypeStats.totalArchetypes,
totalEntities: archetypeStats.totalEntities,
queryCacheSize: archetypeStats.queryCacheSize
// 获取场景统计
const sceneStats = scene.getStats();
console.log('场景统计:', {
实体数量: sceneStats.entityCount,
系统数量: sceneStats.processorCount
});
// 查看所有原型
console.log('当前原型:', archetypeSystem.getAllArchetypes());
// 获取查询系统统计
const queryStats = scene.querySystem.getStats();
console.log('查询统计:', queryStats);
```
### 3. 脏标记系统
## 最佳实践
追踪实体变更，避免不必要的更新：
### 1. 高效查询
```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);
}
// ✅ 好的做法：缓存查询结果
class CombatSystem extends EntitySystem {
private cachedEnemies: Entity[] = [];
private lastUpdateFrame = 0;
protected process(entities: Entity[]): void {
// 使用高效查询获取移动实体
const movingEntities = this.entityManager
.query()
.withAll([PositionComponent, VelocityComponent])
.active(true)
.execute();
// 每5帧更新一次缓存
if (Time.frameCount - this.lastUpdateFrame > 5) {
this.cachedEnemies = this.entityManager
.query()
.withAll(PositionComponent, HealthComponent)
.withTag(2)
.execute();
this.lastUpdateFrame = Time.frameCount;
}
// 批量处理
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;
// 使用缓存的结果
this.cachedEnemies.forEach(enemy => {
// 处理敌人逻辑
});
}
}
```
### 复杂查询示例
### 2. 批量操作
```typescript
// 战斗系统：查找攻击范围内的敌人
class CombatSystem {
private entityManager: EntityManager;
// ✅ 好的做法：批量创建和配置
function createBulletWave(count: number): Entity[] {
// 使用Scene的批量创建
const bullets = scene.createEntities(count, "Bullet");
// 批量配置组件
bullets.forEach((bullet, index) => {
const angle = (index / count) * Math.PI * 2;
bullet.addComponent(new PositionComponent(400, 300));
bullet.addComponent(new VelocityComponent(
Math.cos(angle) * 200,
Math.sin(angle) * 200
));
bullet.addComponent(new BulletComponent());
bullet.tag = 3; // 子弹标签
});
return bullets;
}
```
### 3. 内存管理
```typescript
// ✅ 好的做法：及时清理无用实体
class CleanupSystem extends EntitySystem {
protected process(entities: Entity[]): void {
// 清理超出边界的子弹
const bullets = this.entityManager.getEntitiesByTag(3);
bullets.forEach(bullet => {
const pos = bullet.getComponent(PositionComponent);
if (pos && (pos.x < -100 || pos.x > 900 || pos.y < -100 || pos.y > 700)) {
this.entityManager.destroyEntity(bullet);
}
});
// 清理死亡的敌人
const deadEnemies = this.entityManager
.query()
.withAll(HealthComponent)
.withTag(2)
.where(entity => {
const health = entity.getComponent(HealthComponent);
return health && health.currentHealth <= 0;
})
.execute();
deadEnemies.forEach(enemy => {
this.entityManager.destroyEntity(enemy);
});
}
}
```
### 4. 查询优化
```typescript
// ✅ 好的做法：使用合适的查询方法
class GameSystem extends EntitySystem {
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);
.getEntitiesByTag(2) // 敌人标签
.filter(enemy => {
const enemyPos = enemy.getComponent(PositionComponent);
if (!enemyPos) return false;
const distance = Math.sqrt(
Math.pow(pos.x - attackerPos.x, 2) +
Math.pow(pos.y - attackerPos.y, 2)
Math.pow(attackerPos.x - enemyPos.x, 2) +
Math.pow(attackerPos.y - enemyPos.y, 2)
);
return distance <= range;
})
.execute();
});
}
}
```
## 完整示例
```typescript
import {
EntityManager,
Scene,
Entity,
Component,
EntitySystem,
Matcher
} from '@esengine/ecs-framework';
// 组件定义
class PositionComponent extends Component {
constructor(public x: number = 0, public y: number = 0) {
super();
}
}
class HealthComponent extends Component {
constructor(
public maxHealth: number = 100,
public currentHealth: number = 100
) {
super();
}
}
// 游戏管理器
class GameManager {
private scene: Scene;
private entityManager: EntityManager;
constructor() {
this.scene = new Scene();
this.entityManager = new EntityManager();
this.setupGame();
}
// 优化版本：使用空间分区（如果实现了的话）
findTargetsInRangeOptimized(attacker: Entity, range: number): Entity[] {
// 首先通过空间查询缩小范围
const nearbyEntities = this.spatialIndex.queryRange(
attackerPos.x - range,
attackerPos.y - range,
attackerPos.x + range,
attackerPos.y + range
);
private setupGame(): void {
// 创建玩家
const player = this.entityManager.createEntity("Player");
player.addComponent(new PositionComponent(400, 300));
player.addComponent(new HealthComponent(100));
player.tag = 1;
// 然后使用EntityManager进行精确过滤
return this.entityManager
.query()
.withAll([HealthComponent])
.withTag("enemy")
.withoutTag("dead")
.where(entity => nearbyEntities.includes(entity))
.execute();
// 创建敌人
const enemies = this.scene.createEntities(10, "Enemy");
enemies.forEach(enemy => {
enemy.addComponent(new PositionComponent(
Math.random() * 800,
Math.random() * 600
));
enemy.addComponent(new HealthComponent(50));
enemy.tag = 2;
});
// 添加系统
this.scene.addEntityProcessor(new HealthSystem());
}
public update(): void {
this.scene.update();
// 输出统计信息
console.log('实体数量:', this.entityManager.entityCount);
console.log('活跃实体数:', this.entityManager.activeEntityCount);
}
}
```
## 性能建议
### 查询优化
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");
// 生命值系统
class HealthSystem extends EntitySystem {
constructor() {
super(Matcher.empty().all(HealthComponent));
}
protected process(entities: Entity[]): void {
const healthEntities = this.scene.querySystem.queryAll(HealthComponent);
healthEntities.entities.forEach(entity => {
const health = entity.getComponent(HealthComponent);
if (health && health.currentHealth <= 0) {
console.log(`实体 ${entity.name} 死亡`);
entity.destroy();
}
});
}
}
```
### 内存管理
```typescript
// 定期清理
setInterval(() => {
entityManager.cleanup();
}, 30000); // 每30秒清理一次
// 监控性能
const stats = entityManager.getStatistics();
if (stats.indexHits / stats.totalQueries < 0.8) {
console.warn('查询命中率较低，考虑优化查询策略');
}
// 启动游戏
const game = new GameManager();
setInterval(() => game.update(), 16); // 60 FPS
```
## 总结
EntityManager 提供了：
EntityManager 提供了强大的实体管理功能：
- **统一接口**: 所有实体操作通过一个管理器完成
- **自动优化**: 内置三个性能优化系统
- **灵活查询**: 从简单的ID查找到复杂的条件查询
- **性能监控**: 完整的统计和诊断信息
- **批量操作**: 高效的批量处理能力
- **创建管理**：`createEntity()`, `destroyEntity()`
- **查询功能**：`getEntitiesWithComponent()`, `getEntitiesByTag()`, `query()`
- **实体查找**：`getEntity()`, `getEntityByName()`
- **统计信息**：`entityCount`, `activeEntityCount`
通过合理使用EntityManager，您可以构建高性能、可维护的ECS游戏系统。
通过合理使用这些API，可以构建高性能的游戏系统。记住要及时清理无用实体，缓存频繁查询的结果，并使用合适的查询方法来优化性能。