文档及教程更新
This commit is contained in:
YHH
@@ -1,6 +1,8 @@
|
||||
# 实体使用指南
|
||||
# 实体基础指南
|
||||
|
||||
本指南详细介绍 ECS Framework 中实体（Entity）的所有功能和使用方法。
|
||||
本指南介绍实体（Entity）的基本概念和基础使用方法。
|
||||
|
||||
> 📖 **需要高级实体管理？** 请参考 [EntityManager 指南](entity-manager-example.md) 了解高性能查询和批量操作
|
||||
|
||||
## 实体概述
|
||||
|
||||
@@ -155,7 +157,7 @@ if (entity.hasComponent(HealthComponent)) {
|
||||
|
||||
// 检查组件掩码（高性能）
|
||||
const mask = entity.componentMask;
|
||||
console.log(`组件掩码: ${mask.toString(2)}`);
|
||||
console.log(`组件掩码: ${mask.toString(2)}`); // 二进制表示
|
||||
```
|
||||
|
||||
### 移除组件
|
||||
@@ -295,80 +297,20 @@ if (entity.isDestroyed) {
|
||||
// 4. 从场景中移除
|
||||
```
|
||||
|
||||
## 性能优化
|
||||
# 高级特性请参考其他指南
|
||||
|
||||
### 组件缓存
|
||||
> 📚 **更多功能：**
|
||||
> - **高性能查询和批量操作** → [EntityManager 指南](entity-manager-example.md)
|
||||
> - **性能优化技术** → [性能优化指南](performance-optimization.md)
|
||||
> - **组件索引和缓存** → [技术概念详解](concepts-explained.md)
|
||||
|
||||
```typescript
|
||||
// 预热组件缓存（提高后续访问性能）
|
||||
entity.warmUpComponentCache();
|
||||
|
||||
// 清理组件缓存
|
||||
entity.cleanupComponentCache();
|
||||
|
||||
// 获取缓存统计信息
|
||||
const cacheStats = entity.getComponentCacheStats();
|
||||
console.log(`缓存命中率: ${cacheStats.cacheStats.hitRate}`);
|
||||
console.log(`组件访问统计:`, cacheStats.accessStats);
|
||||
```
|
||||
|
||||
### 批量操作
|
||||
|
||||
```typescript
|
||||
// 批量添加组件（比单个添加更高效）
|
||||
const components = entity.addComponents([
|
||||
new PositionComponent(0, 0),
|
||||
new VelocityComponent(50, 0),
|
||||
new HealthComponent(100)
|
||||
]);
|
||||
|
||||
// 批量移除组件
|
||||
const removed = entity.removeComponentsByTypes([
|
||||
HealthComponent,
|
||||
VelocityComponent
|
||||
]);
|
||||
```
|
||||
|
||||
## 调试和监控
|
||||
|
||||
### 调试信息
|
||||
|
||||
```typescript
|
||||
// 获取详细的调试信息
|
||||
const debugInfo = entity.getDebugInfo();
|
||||
console.log("实体调试信息:", debugInfo);
|
||||
|
||||
// 调试信息包含：
|
||||
// - 基本属性（名称、ID、状态等）
|
||||
// - 组件信息（数量、类型、掩码等）
|
||||
// - 层次结构信息（父子关系、深度等）
|
||||
// - 性能统计（缓存命中率、访问统计等）
|
||||
```
|
||||
|
||||
### 实体比较
|
||||
|
||||
```typescript
|
||||
// 比较两个实体的优先级
|
||||
const result = entity1.compareTo(entity2);
|
||||
if (result < 0) {
|
||||
// entity1 优先级更高
|
||||
} else if (result > 0) {
|
||||
// entity2 优先级更高
|
||||
} else {
|
||||
// 优先级相同
|
||||
}
|
||||
|
||||
// 实体的字符串表示
|
||||
console.log(entity.toString()); // "Entity[Player:1]"
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
## 基础最佳实践
|
||||
|
||||
### 1. 合理使用标签
|
||||
|
||||
```typescript
|
||||
// 定义标签常量
|
||||
const Tags = {
|
||||
const EntityTags = {
|
||||
PLAYER: 1,
|
||||
ENEMY: 2,
|
||||
PROJECTILE: 3,
|
||||
@@ -376,70 +318,42 @@ const Tags = {
|
||||
} as const;
|
||||
|
||||
// 使用标签进行分类
|
||||
player.tag = Tags.PLAYER;
|
||||
enemy.tag = Tags.ENEMY;
|
||||
player.tag = EntityTags.PLAYER;
|
||||
enemy.tag = EntityTags.ENEMY;
|
||||
```
|
||||
|
||||
### 2. 优化更新顺序
|
||||
|
||||
```typescript
|
||||
// 设置合理的更新顺序
|
||||
player.updateOrder = 0; // 玩家最先更新
|
||||
enemy.updateOrder = 1; // 敌人其次
|
||||
projectile.updateOrder = 2; // 投射物最后
|
||||
```
|
||||
|
||||
### 3. 合理使用层次结构
|
||||
|
||||
```typescript
|
||||
// 创建复合实体
|
||||
const tank = scene.createEntity("Tank");
|
||||
const turret = scene.createEntity("Turret");
|
||||
const barrel = scene.createEntity("Barrel");
|
||||
|
||||
// 建立层次关系
|
||||
tank.addChild(turret);
|
||||
turret.addChild(barrel);
|
||||
|
||||
// 这样可以通过控制父实体来影响整个层次结构
|
||||
tank.active = false; // 整个坦克都会被停用
|
||||
```
|
||||
|
||||
### 4. 组件缓存优化
|
||||
|
||||
```typescript
|
||||
// 对于频繁访问的组件，预热缓存
|
||||
entity.warmUpComponentCache();
|
||||
|
||||
// 定期清理不常用的缓存
|
||||
setInterval(() => {
|
||||
entity.cleanupComponentCache();
|
||||
}, 5000);
|
||||
```
|
||||
|
||||
### 5. 避免内存泄漏
|
||||
### 2. 正确的销毁处理
|
||||
|
||||
```typescript
|
||||
// 确保正确销毁实体
|
||||
if (!entity.isDestroyed) {
|
||||
entity.destroy(); // 自动移除组件和层次关系
|
||||
}
|
||||
|
||||
// 检查实体状态
|
||||
if (entity.isDestroyed) {
|
||||
return; // 避免操作已销毁的实体
|
||||
}
|
||||
```
|
||||
|
||||
// 在适当的时候销毁不需要的实体
|
||||
if (enemy.getComponent(HealthComponent)?.isDead()) {
|
||||
enemy.destroy();
|
||||
### 3. 组件生命周期
|
||||
|
||||
```typescript
|
||||
// 正确添加组件
|
||||
const health = entity.addComponent(new HealthComponent(100));
|
||||
|
||||
// 安全获取组件
|
||||
const healthComp = entity.getComponent(HealthComponent);
|
||||
if (healthComp && healthComp.currentHealth <= 0) {
|
||||
entity.destroy();
|
||||
}
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 实体可以在不同场景间移动吗？
|
||||
### Q: 实体如何实现位置、旋转等变换？
|
||||
|
||||
A: 不可以。实体与场景紧密绑定，如果需要在场景间传递数据，应该序列化实体的组件数据，然后在新场景中重新创建。
|
||||
|
||||
### Q: 如何实现实体的位置、旋转、缩放？
|
||||
|
||||
A: 框架本身不提供这些属性，需要通过组件来实现：
|
||||
A: 通过添加相应的组件：
|
||||
|
||||
```typescript
|
||||
class TransformComponent extends Component {
|
||||
@@ -448,35 +362,9 @@ class TransformComponent extends Component {
|
||||
public scale = { x: 1, y: 1 };
|
||||
}
|
||||
|
||||
const transform = entity.addComponent(new TransformComponent());
|
||||
transform.position.x = 100;
|
||||
transform.rotation = Math.PI / 4;
|
||||
entity.addComponent(new TransformComponent());
|
||||
```
|
||||
|
||||
### Q: 实体的更新顺序如何影响性能？
|
||||
### Q: 实体可以在场景间移动吗？
|
||||
|
||||
A: 更新顺序主要影响游戏逻辑的执行顺序，对性能影响较小。但合理的更新顺序可以避免一些逻辑问题，比如确保输入处理在移动之前执行。
|
||||
|
||||
### Q: 如何处理大量实体的性能问题？
|
||||
|
||||
A:
|
||||
1. 使用对象池重用实体
|
||||
2. 合理使用组件缓存
|
||||
3. 避免不必要的组件查询
|
||||
4. 使用批量操作
|
||||
5. 定期清理销毁的实体
|
||||
|
||||
```typescript
|
||||
// 使用对象池
|
||||
class EntityPool extends Pool<Entity> {
|
||||
protected createObject(): Entity {
|
||||
return scene.createEntity("PooledEntity");
|
||||
}
|
||||
|
||||
protected resetObject(entity: Entity): void {
|
||||
entity.removeAllComponents();
|
||||
entity.active = true;
|
||||
entity.enabled = true;
|
||||
}
|
||||
}
|
||||
```
|
||||
A: 不可以。实体与场景绑定，需要在新场景中重新创建。
|
||||
Reference in New Issue
Block a user