更新文档
This commit is contained in:
YHH
359
docs/guide/component.md
Normal file
359
docs/guide/component.md
Normal file
@@ -0,0 +1,359 @@
|
||||
# 组件系统
|
||||
|
||||
在 ECS 架构中，组件（Component）是数据和行为的载体。组件定义了实体具有的属性和功能，是 ECS 架构的核心构建块。
|
||||
|
||||
## 基本概念
|
||||
|
||||
组件是继承自 `Component` 抽象基类的具体类，用于：
|
||||
- 存储实体的数据（如位置、速度、健康值等）
|
||||
- 定义与数据相关的行为方法
|
||||
- 提供生命周期回调钩子
|
||||
- 支持序列化和调试
|
||||
|
||||
## 创建组件
|
||||
|
||||
### 基础组件定义
|
||||
|
||||
```typescript
|
||||
import { Component, ECSComponent } from '@esengine/ecs-framework';
|
||||
|
||||
@ECSComponent('Position')
|
||||
class Position extends Component {
|
||||
x: number = 0;
|
||||
y: number = 0;
|
||||
|
||||
constructor(x: number = 0, y: number = 0) {
|
||||
super();
|
||||
this.x = x;
|
||||
this.y = y;
|
||||
}
|
||||
}
|
||||
|
||||
@ECSComponent('Health')
|
||||
class Health extends Component {
|
||||
current: number;
|
||||
max: number;
|
||||
|
||||
constructor(max: number = 100) {
|
||||
super();
|
||||
this.max = max;
|
||||
this.current = max;
|
||||
}
|
||||
|
||||
// 组件可以包含行为方法
|
||||
takeDamage(damage: number): void {
|
||||
this.current = Math.max(0, this.current - damage);
|
||||
}
|
||||
|
||||
heal(amount: number): void {
|
||||
this.current = Math.min(this.max, this.current + amount);
|
||||
}
|
||||
|
||||
isDead(): boolean {
|
||||
return this.current <= 0;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 组件装饰器
|
||||
|
||||
**必须使用 `@ECSComponent` 装饰器**，这确保了：
|
||||
- 组件在代码混淆后仍能正确识别
|
||||
- 提供稳定的类型名称用于序列化和调试
|
||||
- 框架能正确管理组件注册
|
||||
|
||||
```typescript
|
||||
// ✅ 正确的用法
|
||||
@ECSComponent('Velocity')
|
||||
class Velocity extends Component {
|
||||
dx: number = 0;
|
||||
dy: number = 0;
|
||||
}
|
||||
|
||||
// ❌ 错误的用法 - 没有装饰器
|
||||
class BadComponent extends Component {
|
||||
// 这样定义的组件可能在生产环境出现问题
|
||||
}
|
||||
```
|
||||
|
||||
## 组件生命周期
|
||||
|
||||
组件提供了生命周期钩子，可以重写来执行特定的逻辑：
|
||||
|
||||
```typescript
|
||||
@ECSComponent('ExampleComponent')
|
||||
class ExampleComponent extends Component {
|
||||
private resource: SomeResource | null = null;
|
||||
|
||||
/**
|
||||
* 组件被添加到实体时调用
|
||||
* 用于初始化资源、建立引用等
|
||||
*/
|
||||
onAddedToEntity(): void {
|
||||
console.log(`组件 ${this.constructor.name} 被添加到实体 ${this.entity.name}`);
|
||||
this.resource = new SomeResource();
|
||||
}
|
||||
|
||||
/**
|
||||
* 组件从实体移除时调用
|
||||
* 用于清理资源、断开引用等
|
||||
*/
|
||||
onRemovedFromEntity(): void {
|
||||
console.log(`组件 ${this.constructor.name} 从实体 ${this.entity.name} 移除`);
|
||||
if (this.resource) {
|
||||
this.resource.cleanup();
|
||||
this.resource = null;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 访问实体
|
||||
|
||||
组件可以通过 `this.entity` 访问其所属的实体：
|
||||
|
||||
```typescript
|
||||
@ECSComponent('Damage')
|
||||
class Damage extends Component {
|
||||
damage: number;
|
||||
|
||||
constructor(damage: number) {
|
||||
super();
|
||||
this.damage = damage;
|
||||
}
|
||||
|
||||
// 在组件方法中访问实体和其他组件
|
||||
applyDamage(): void {
|
||||
const health = this.entity.getComponent(Health);
|
||||
if (health) {
|
||||
health.takeDamage(this.damage);
|
||||
|
||||
// 如果生命值为0，销毁实体
|
||||
if (health.isDead()) {
|
||||
this.entity.destroy();
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 组件属性
|
||||
|
||||
每个组件都有一些内置属性：
|
||||
|
||||
```typescript
|
||||
@ECSComponent('ExampleComponent')
|
||||
class ExampleComponent extends Component {
|
||||
someData: string = "example";
|
||||
|
||||
showComponentInfo(): void {
|
||||
console.log(`组件ID: ${this.id}`); // 唯一的组件ID
|
||||
console.log(`所属实体: ${this.entity.name}`); // 所属实体引用
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## 复杂组件示例
|
||||
|
||||
### 状态机组件
|
||||
|
||||
```typescript
|
||||
enum EntityState {
|
||||
Idle,
|
||||
Moving,
|
||||
Attacking,
|
||||
Dead
|
||||
}
|
||||
|
||||
@ECSComponent('StateMachine')
|
||||
class StateMachine extends Component {
|
||||
private _currentState: EntityState = EntityState.Idle;
|
||||
private _previousState: EntityState = EntityState.Idle;
|
||||
private _stateTimer: number = 0;
|
||||
|
||||
get currentState(): EntityState {
|
||||
return this._currentState;
|
||||
}
|
||||
|
||||
get previousState(): EntityState {
|
||||
return this._previousState;
|
||||
}
|
||||
|
||||
get stateTimer(): number {
|
||||
return this._stateTimer;
|
||||
}
|
||||
|
||||
changeState(newState: EntityState): void {
|
||||
if (this._currentState !== newState) {
|
||||
this._previousState = this._currentState;
|
||||
this._currentState = newState;
|
||||
this._stateTimer = 0;
|
||||
}
|
||||
}
|
||||
|
||||
updateTimer(deltaTime: number): void {
|
||||
this._stateTimer += deltaTime;
|
||||
}
|
||||
|
||||
isInState(state: EntityState): boolean {
|
||||
return this._currentState === state;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 配置数据组件
|
||||
|
||||
```typescript
|
||||
interface WeaponData {
|
||||
damage: number;
|
||||
range: number;
|
||||
fireRate: number;
|
||||
ammo: number;
|
||||
}
|
||||
|
||||
@ECSComponent('WeaponConfig')
|
||||
class WeaponConfig extends Component {
|
||||
data: WeaponData;
|
||||
|
||||
constructor(weaponData: WeaponData) {
|
||||
super();
|
||||
this.data = { ...weaponData }; // 深拷贝避免共享引用
|
||||
}
|
||||
|
||||
// 提供便捷的访问方法
|
||||
getDamage(): number {
|
||||
return this.data.damage;
|
||||
}
|
||||
|
||||
canFire(): boolean {
|
||||
return this.data.ammo > 0;
|
||||
}
|
||||
|
||||
consumeAmmo(): boolean {
|
||||
if (this.data.ammo > 0) {
|
||||
this.data.ammo--;
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 保持组件简单
|
||||
|
||||
```typescript
|
||||
// ✅ 好的组件设计 - 单一职责
|
||||
@ECSComponent('Position')
|
||||
class Position extends Component {
|
||||
x: number = 0;
|
||||
y: number = 0;
|
||||
}
|
||||
|
||||
@ECSComponent('Velocity')
|
||||
class Velocity extends Component {
|
||||
dx: number = 0;
|
||||
dy: number = 0;
|
||||
}
|
||||
|
||||
// ❌ 避免的组件设计 - 职责过多
|
||||
@ECSComponent('GameObject')
|
||||
class GameObject extends Component {
|
||||
x: number;
|
||||
y: number;
|
||||
dx: number;
|
||||
dy: number;
|
||||
health: number;
|
||||
damage: number;
|
||||
sprite: string;
|
||||
// 太多不相关的属性
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 使用构造函数初始化
|
||||
|
||||
```typescript
|
||||
@ECSComponent('Transform')
|
||||
class Transform extends Component {
|
||||
x: number;
|
||||
y: number;
|
||||
rotation: number;
|
||||
scale: number;
|
||||
|
||||
constructor(x = 0, y = 0, rotation = 0, scale = 1) {
|
||||
super();
|
||||
this.x = x;
|
||||
this.y = y;
|
||||
this.rotation = rotation;
|
||||
this.scale = scale;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 明确的类型定义
|
||||
|
||||
```typescript
|
||||
interface InventoryItem {
|
||||
id: string;
|
||||
name: string;
|
||||
quantity: number;
|
||||
type: 'weapon' | 'consumable' | 'misc';
|
||||
}
|
||||
|
||||
@ECSComponent('Inventory')
|
||||
class Inventory extends Component {
|
||||
items: InventoryItem[] = [];
|
||||
maxSlots: number;
|
||||
|
||||
constructor(maxSlots: number = 20) {
|
||||
super();
|
||||
this.maxSlots = maxSlots;
|
||||
}
|
||||
|
||||
addItem(item: InventoryItem): boolean {
|
||||
if (this.items.length < this.maxSlots) {
|
||||
this.items.push(item);
|
||||
return true;
|
||||
}
|
||||
return false;
|
||||
}
|
||||
|
||||
removeItem(itemId: string): InventoryItem | null {
|
||||
const index = this.items.findIndex(item => item.id === itemId);
|
||||
if (index !== -1) {
|
||||
return this.items.splice(index, 1)[0];
|
||||
}
|
||||
return null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 避免在组件中存储实体引用
|
||||
|
||||
```typescript
|
||||
// ❌ 避免：在组件中存储其他实体的引用
|
||||
@ECSComponent('BadFollower')
|
||||
class BadFollower extends Component {
|
||||
target: Entity; // 直接引用可能导致内存泄漏
|
||||
}
|
||||
|
||||
// ✅ 推荐：存储实体ID，通过场景查找
|
||||
@ECSComponent('Follower')
|
||||
class Follower extends Component {
|
||||
targetId: number;
|
||||
followDistance: number = 50;
|
||||
|
||||
constructor(targetId: number) {
|
||||
super();
|
||||
this.targetId = targetId;
|
||||
}
|
||||
|
||||
getTarget(): Entity | null {
|
||||
return this.entity.scene?.findEntityById(this.targetId) || null;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
组件是 ECS 架构的数据载体，正确设计组件能让你的游戏代码更模块化、可维护和高性能。
|
||||
288
docs/guide/entity.md
Normal file
288
docs/guide/entity.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# 实体类
|
||||
|
||||
在 ECS 架构中，实体（Entity）是游戏世界中的基本对象。实体本身不包含游戏逻辑或数据，它只是一个容器，用来组合不同的组件来实现各种功能。
|
||||
|
||||
## 基本概念
|
||||
|
||||
实体是一个轻量级的对象，主要用于：
|
||||
- 作为组件的容器
|
||||
- 提供唯一标识（ID）
|
||||
- 管理组件的生命周期
|
||||
|
||||
## 创建实体
|
||||
|
||||
**重要提示：实体必须通过场景创建，不支持手动创建！**
|
||||
|
||||
实体必须通过场景的 `createEntity()` 方法来创建，这样才能确保：
|
||||
- 实体被正确添加到场景的实体管理系统中
|
||||
- 实体被添加到查询系统中，供系统使用
|
||||
- 实体获得正确的场景引用
|
||||
- 触发相关的生命周期事件
|
||||
|
||||
```typescript
|
||||
// 正确的方式：通过场景创建实体
|
||||
const player = scene.createEntity("Player");
|
||||
|
||||
// ❌ 错误的方式：手动创建实体
|
||||
// const entity = new Entity("MyEntity", 1); // 这样创建的实体系统无法管理
|
||||
```
|
||||
|
||||
## 添加组件
|
||||
|
||||
实体通过添加组件来获得功能：
|
||||
|
||||
```typescript
|
||||
import { Component, ECSComponent } from '@esengine/ecs-framework';
|
||||
|
||||
// 定义位置组件
|
||||
@ECSComponent('Position')
|
||||
class Position extends Component {
|
||||
x: number = 0;
|
||||
y: number = 0;
|
||||
|
||||
constructor(x: number = 0, y: number = 0) {
|
||||
super();
|
||||
this.x = x;
|
||||
this.y = y;
|
||||
}
|
||||
}
|
||||
|
||||
// 定义健康组件
|
||||
@ECSComponent('Health')
|
||||
class Health extends Component {
|
||||
current: number = 100;
|
||||
max: number = 100;
|
||||
|
||||
constructor(max: number = 100) {
|
||||
super();
|
||||
this.max = max;
|
||||
this.current = max;
|
||||
}
|
||||
}
|
||||
|
||||
// 给实体添加组件
|
||||
const player = scene.createEntity("Player");
|
||||
player.addComponent(new Position(100, 200));
|
||||
player.addComponent(new Health(150));
|
||||
```
|
||||
|
||||
## 获取组件
|
||||
|
||||
```typescript
|
||||
// 获取组件（传入组件类，不是实例）
|
||||
const position = player.getComponent(Position); // 返回 Position | null
|
||||
const health = player.getComponent(Health); // 返回 Health | null
|
||||
|
||||
// 检查组件是否存在
|
||||
if (position) {
|
||||
console.log(`玩家位置: x=${position.x}, y=${position.y}`);
|
||||
}
|
||||
|
||||
// 检查是否有某个组件
|
||||
if (player.hasComponent(Position)) {
|
||||
console.log("玩家有位置组件");
|
||||
}
|
||||
|
||||
// 获取所有组件实例（直接访问 components 属性）
|
||||
const allComponents = player.components; // Component[]
|
||||
|
||||
// 获取指定类型的所有组件（支持同类型多组件）
|
||||
const allHealthComponents = player.getComponents(Health); // Health[]
|
||||
|
||||
// 获取或创建组件（如果不存在则自动创建）
|
||||
const position = player.getOrCreateComponent(Position, 0, 0); // 传入构造参数
|
||||
const health = player.getOrCreateComponent(Health, 100); // 如果存在则返回现有的，不存在则创建新的
|
||||
```
|
||||
|
||||
## 移除组件
|
||||
|
||||
```typescript
|
||||
// 方式1：通过组件类型移除
|
||||
const removedHealth = player.removeComponentByType(Health);
|
||||
if (removedHealth) {
|
||||
console.log("健康组件已被移除");
|
||||
}
|
||||
|
||||
// 方式2：通过组件实例移除
|
||||
const healthComponent = player.getComponent(Health);
|
||||
if (healthComponent) {
|
||||
player.removeComponent(healthComponent);
|
||||
}
|
||||
|
||||
// 批量移除多种组件类型
|
||||
const removedComponents = player.removeComponentsByTypes([Position, Health]);
|
||||
|
||||
// 检查组件是否被移除
|
||||
if (!player.hasComponent(Health)) {
|
||||
console.log("健康组件已被移除");
|
||||
}
|
||||
```
|
||||
|
||||
## 实体查找
|
||||
|
||||
场景提供了多种方式来查找实体：
|
||||
|
||||
### 通过名称查找
|
||||
|
||||
```typescript
|
||||
// 查找单个实体
|
||||
const player = scene.findEntity("Player");
|
||||
// 或使用别名方法
|
||||
const player2 = scene.getEntityByName("Player");
|
||||
|
||||
if (player) {
|
||||
console.log("找到玩家实体");
|
||||
}
|
||||
```
|
||||
|
||||
### 通过 ID 查找
|
||||
|
||||
```typescript
|
||||
// 通过实体 ID 查找
|
||||
const entity = scene.findEntityById(123);
|
||||
```
|
||||
|
||||
### 通过标签查找
|
||||
|
||||
实体支持标签系统，用于快速分类和查找：
|
||||
|
||||
```typescript
|
||||
// 设置标签
|
||||
player.tag = 1; // 玩家标签
|
||||
enemy.tag = 2; // 敌人标签
|
||||
|
||||
// 通过标签查找所有相关实体
|
||||
const players = scene.findEntitiesByTag(1);
|
||||
const enemies = scene.findEntitiesByTag(2);
|
||||
// 或使用别名方法
|
||||
const allPlayers = scene.getEntitiesByTag(1);
|
||||
```
|
||||
|
||||
|
||||
## 实体生命周期
|
||||
|
||||
```typescript
|
||||
// 销毁实体
|
||||
player.destroy();
|
||||
|
||||
// 检查实体是否已销毁
|
||||
if (player.isDestroyed) {
|
||||
console.log("实体已被销毁");
|
||||
}
|
||||
```
|
||||
|
||||
## 实体事件
|
||||
|
||||
实体的组件变化会触发事件：
|
||||
|
||||
```typescript
|
||||
// 监听组件添加事件
|
||||
scene.eventSystem.on('component:added', (data) => {
|
||||
console.log('组件已添加:', data);
|
||||
});
|
||||
|
||||
// 监听实体创建事件
|
||||
scene.eventSystem.on('entity:created', (data) => {
|
||||
console.log('实体已创建:', data.entityName);
|
||||
});
|
||||
```
|
||||
|
||||
## 性能优化
|
||||
|
||||
|
||||
### 批量创建实体
|
||||
|
||||
框架提供了高性能的批量创建方法：
|
||||
|
||||
```typescript
|
||||
// 批量创建 100 个子弹实体（高性能版本）
|
||||
const bullets = scene.createEntities(100, "Bullet");
|
||||
|
||||
// 为每个子弹添加组件
|
||||
bullets.forEach((bullet, index) => {
|
||||
bullet.addComponent(new Position(Math.random() * 800, Math.random() * 600));
|
||||
bullet.addComponent(new Velocity(Math.random() * 100 - 50, Math.random() * 100 - 50));
|
||||
});
|
||||
```
|
||||
|
||||
`createEntities()` 方法会：
|
||||
- 批量分配实体 ID
|
||||
- 批量添加到实体列表
|
||||
- 优化查询系统更新
|
||||
- 减少系统缓存清理次数
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 合理的组件粒度
|
||||
|
||||
```typescript
|
||||
// 好的做法：功能单一的组件
|
||||
@ECSComponent('Position')
|
||||
class Position extends Component {
|
||||
x: number = 0;
|
||||
y: number = 0;
|
||||
}
|
||||
|
||||
@ECSComponent('Velocity')
|
||||
class Velocity extends Component {
|
||||
dx: number = 0;
|
||||
dy: number = 0;
|
||||
}
|
||||
|
||||
// 避免：功能过于复杂的组件
|
||||
@ECSComponent('Player')
|
||||
class Player extends Component {
|
||||
// 避免在一个组件中包含太多不相关的属性
|
||||
x: number;
|
||||
y: number;
|
||||
health: number;
|
||||
inventory: Item[];
|
||||
skills: Skill[];
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 使用装饰器
|
||||
|
||||
始终使用 `@ECSComponent` 装饰器：
|
||||
|
||||
```typescript
|
||||
@ECSComponent('Transform')
|
||||
class Transform extends Component {
|
||||
// 组件实现
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 合理命名
|
||||
|
||||
```typescript
|
||||
// 清晰的实体命名
|
||||
const mainCharacter = scene.createEntity("MainCharacter");
|
||||
const enemy1 = scene.createEntity("Goblin_001");
|
||||
const collectible = scene.createEntity("HealthPotion");
|
||||
```
|
||||
|
||||
### 4. 及时清理
|
||||
|
||||
```typescript
|
||||
// 不再需要的实体应该及时销毁
|
||||
if (enemy.getComponent(Health).current <= 0) {
|
||||
enemy.destroy();
|
||||
}
|
||||
```
|
||||
|
||||
## 调试实体
|
||||
|
||||
框架提供了调试功能来帮助开发：
|
||||
|
||||
```typescript
|
||||
// 获取实体调试信息
|
||||
const debugInfo = entity.getDebugInfo();
|
||||
console.log('实体信息:', debugInfo);
|
||||
|
||||
// 列出实体的所有组件
|
||||
entity.components.forEach(component => {
|
||||
console.log('组件:', component.constructor.name);
|
||||
});
|
||||
```
|
||||
|
||||
实体是 ECS 架构的核心概念之一，理解如何正确使用实体将帮助你构建高效、可维护的游戏代码。
|
||||
595
docs/guide/event-system.md
Normal file
595
docs/guide/event-system.md
Normal file
@@ -0,0 +1,595 @@
|
||||
# 事件系统
|
||||
|
||||
ECS 框架内置了强大的类型安全事件系统，支持同步/异步事件、优先级、批处理等高级功能。事件系统是实现组件间通信、系统间协作的核心机制。
|
||||
|
||||
## 基本概念
|
||||
|
||||
事件系统提供了发布-订阅模式的实现，包含以下核心概念：
|
||||
- **事件发布者**：发射事件的对象
|
||||
- **事件监听者**：监听并处理特定事件的对象
|
||||
- **事件类型**：字符串标识，用于区分不同类型的事件
|
||||
- **事件数据**：事件携带的相关信息
|
||||
|
||||
## 事件系统架构
|
||||
|
||||
框架提供了两层事件系统：
|
||||
|
||||
1. **TypeSafeEventSystem** - 底层高性能事件系统
|
||||
2. **EventBus** - 上层增强事件总线，提供更多便利功能
|
||||
|
||||
## 基本使用
|
||||
|
||||
### 在场景中使用事件系统
|
||||
|
||||
每个场景都有内置的事件系统：
|
||||
|
||||
```typescript
|
||||
class GameScene extends Scene {
|
||||
protected initialize(): void {
|
||||
// 监听事件
|
||||
this.eventSystem.on('player_died', this.onPlayerDied.bind(this));
|
||||
this.eventSystem.on('enemy_spawned', this.onEnemySpawned.bind(this));
|
||||
this.eventSystem.on('score_changed', this.onScoreChanged.bind(this));
|
||||
}
|
||||
|
||||
private onPlayerDied(data: { player: Entity, cause: string }): void {
|
||||
console.log(`玩家死亡，原因: ${data.cause}`);
|
||||
// 处理玩家死亡逻辑
|
||||
}
|
||||
|
||||
private onEnemySpawned(data: { enemy: Entity, position: { x: number, y: number } }): void {
|
||||
console.log('敌人生成于:', data.position);
|
||||
// 处理敌人生成逻辑
|
||||
}
|
||||
|
||||
private onScoreChanged(data: { newScore: number, oldScore: number }): void {
|
||||
console.log(`分数变化: ${data.oldScore} -> ${data.newScore}`);
|
||||
// 更新UI显示
|
||||
}
|
||||
|
||||
// 在系统中发射事件
|
||||
someGameLogic(): void {
|
||||
// 发射同步事件
|
||||
this.eventSystem.emitSync('score_changed', {
|
||||
newScore: 1000,
|
||||
oldScore: 800
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 在系统中使用事件
|
||||
|
||||
系统可以方便地监听和发送事件：
|
||||
|
||||
```typescript
|
||||
@ECSSystem('Combat')
|
||||
class CombatSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super(Matcher.all(Health, Combat));
|
||||
}
|
||||
|
||||
protected onInitialize(): void {
|
||||
// 使用系统提供的事件监听方法（自动清理）
|
||||
this.addEventListener('player_attack', this.onPlayerAttack.bind(this));
|
||||
this.addEventListener('enemy_death', this.onEnemyDeath.bind(this));
|
||||
}
|
||||
|
||||
private onPlayerAttack(data: { damage: number, target: Entity }): void {
|
||||
// 处理玩家攻击事件
|
||||
const health = data.target.getComponent(Health);
|
||||
if (health) {
|
||||
health.current -= data.damage;
|
||||
|
||||
if (health.current <= 0) {
|
||||
// 发送敌人死亡事件
|
||||
this.scene?.eventSystem.emitSync('enemy_death', {
|
||||
enemy: data.target,
|
||||
killer: 'player'
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private onEnemyDeath(data: { enemy: Entity, killer: string }): void {
|
||||
// 处理敌人死亡
|
||||
data.enemy.destroy();
|
||||
|
||||
// 发送经验奖励事件
|
||||
this.scene?.eventSystem.emitSync('experience_gained', {
|
||||
amount: 100,
|
||||
source: 'enemy_kill'
|
||||
});
|
||||
}
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
for (const entity of entities) {
|
||||
const combat = entity.getComponent(Combat);
|
||||
if (combat && combat.shouldAttack()) {
|
||||
// 发射攻击事件
|
||||
this.scene?.eventSystem.emitSync('player_attack', {
|
||||
damage: combat.damage,
|
||||
target: combat.target
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 高级功能
|
||||
|
||||
### 一次性监听器
|
||||
|
||||
```typescript
|
||||
class GameScene extends Scene {
|
||||
protected initialize(): void {
|
||||
// 只监听一次的事件
|
||||
this.eventSystem.once('game_start', this.onGameStart.bind(this));
|
||||
|
||||
// 或者使用配置对象
|
||||
this.eventSystem.on('level_complete', this.onLevelComplete.bind(this), {
|
||||
once: true // 只执行一次
|
||||
});
|
||||
}
|
||||
|
||||
private onGameStart(): void {
|
||||
console.log('游戏开始！');
|
||||
// 这个方法只会被调用一次
|
||||
}
|
||||
|
||||
private onLevelComplete(): void {
|
||||
console.log('关卡完成！');
|
||||
// 这个方法也只会被调用一次
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 优先级控制
|
||||
|
||||
```typescript
|
||||
class GameScene extends Scene {
|
||||
protected initialize(): void {
|
||||
// 高优先级监听器先执行
|
||||
this.eventSystem.on('damage_dealt', this.onDamageDealt.bind(this), {
|
||||
priority: 100 // 高优先级
|
||||
});
|
||||
|
||||
// 普通优先级
|
||||
this.eventSystem.on('damage_dealt', this.updateUI.bind(this), {
|
||||
priority: 0 // 默认优先级
|
||||
});
|
||||
|
||||
// 低优先级最后执行
|
||||
this.eventSystem.on('damage_dealt', this.logDamage.bind(this), {
|
||||
priority: -100 // 低优先级
|
||||
});
|
||||
}
|
||||
|
||||
private onDamageDealt(data: any): void {
|
||||
// 最先执行 - 处理核心游戏逻辑
|
||||
}
|
||||
|
||||
private updateUI(data: any): void {
|
||||
// 中等优先级 - 更新界面
|
||||
}
|
||||
|
||||
private logDamage(data: any): void {
|
||||
// 最后执行 - 记录日志
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 异步事件处理
|
||||
|
||||
```typescript
|
||||
class GameScene extends Scene {
|
||||
protected initialize(): void {
|
||||
// 监听异步事件
|
||||
this.eventSystem.onAsync('save_game', this.onSaveGame.bind(this));
|
||||
this.eventSystem.onAsync('load_data', this.onLoadData.bind(this));
|
||||
}
|
||||
|
||||
private async onSaveGame(data: { saveSlot: number }): Promise<void> {
|
||||
console.log(`开始保存游戏到槽位 ${data.saveSlot}`);
|
||||
|
||||
// 模拟异步保存操作
|
||||
await this.saveGameData(data.saveSlot);
|
||||
|
||||
console.log('游戏保存完成');
|
||||
}
|
||||
|
||||
private async onLoadData(data: { url: string }): Promise<void> {
|
||||
try {
|
||||
const response = await fetch(data.url);
|
||||
const gameData = await response.json();
|
||||
// 处理加载的数据
|
||||
} catch (error) {
|
||||
console.error('数据加载失败:', error);
|
||||
}
|
||||
}
|
||||
|
||||
private async saveGameData(slot: number): Promise<void> {
|
||||
// 模拟保存操作
|
||||
return new Promise(resolve => setTimeout(resolve, 1000));
|
||||
}
|
||||
|
||||
// 发射异步事件
|
||||
public async triggerSave(): Promise<void> {
|
||||
// 使用 emit 而不是 emitSync 来触发异步监听器
|
||||
await this.eventSystem.emit('save_game', { saveSlot: 1 });
|
||||
console.log('所有异步保存操作完成');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 事件统计和调试
|
||||
|
||||
```typescript
|
||||
class GameScene extends Scene {
|
||||
protected initialize(): void {
|
||||
this.eventSystem.on('debug_event', this.onDebugEvent.bind(this));
|
||||
}
|
||||
|
||||
private onDebugEvent(): void {
|
||||
// 处理调试事件
|
||||
}
|
||||
|
||||
public showEventStats(): void {
|
||||
// 获取特定事件的统计信息
|
||||
const stats = this.eventSystem.getStats('debug_event') as any;
|
||||
if (stats) {
|
||||
console.log('事件统计:');
|
||||
console.log(`- 事件类型: ${stats.eventType}`);
|
||||
console.log(`- 监听器数量: ${stats.listenerCount}`);
|
||||
console.log(`- 触发次数: ${stats.triggerCount}`);
|
||||
console.log(`- 平均执行时间: ${stats.averageExecutionTime.toFixed(2)}ms`);
|
||||
}
|
||||
|
||||
// 获取所有事件统计
|
||||
const allStats = this.eventSystem.getStats() as Map<string, any>;
|
||||
console.log(`总共有 ${allStats.size} 种事件类型`);
|
||||
}
|
||||
|
||||
public resetEventStats(): void {
|
||||
// 重置特定事件的统计
|
||||
this.eventSystem.resetStats('debug_event');
|
||||
|
||||
// 或重置所有统计
|
||||
this.eventSystem.resetStats();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 全局事件总线
|
||||
|
||||
对于跨场景的事件通信，可以使用全局事件总线：
|
||||
|
||||
```typescript
|
||||
import { GlobalEventBus } from '@esengine/ecs-framework';
|
||||
|
||||
class GameManager {
|
||||
private eventBus = GlobalEventBus.getInstance();
|
||||
|
||||
constructor() {
|
||||
this.setupGlobalEvents();
|
||||
}
|
||||
|
||||
private setupGlobalEvents(): void {
|
||||
// 监听全局事件
|
||||
this.eventBus.on('player_level_up', this.onPlayerLevelUp.bind(this));
|
||||
this.eventBus.on('achievement_unlocked', this.onAchievementUnlocked.bind(this));
|
||||
this.eventBus.onAsync('upload_score', this.onUploadScore.bind(this));
|
||||
}
|
||||
|
||||
private onPlayerLevelUp(data: { level: number, experience: number }): void {
|
||||
console.log(`玩家升级到 ${data.level} 级！`);
|
||||
// 处理全局升级逻辑
|
||||
}
|
||||
|
||||
private onAchievementUnlocked(data: { achievementId: string, name: string }): void {
|
||||
console.log(`解锁成就: ${data.name}`);
|
||||
// 显示成就通知
|
||||
}
|
||||
|
||||
private async onUploadScore(data: { score: number, playerName: string }): Promise<void> {
|
||||
// 异步上传分数到服务器
|
||||
try {
|
||||
await this.uploadToServer(data);
|
||||
console.log('分数上传成功');
|
||||
} catch (error) {
|
||||
console.error('分数上传失败:', error);
|
||||
}
|
||||
}
|
||||
|
||||
public triggerGlobalEvent(): void {
|
||||
// 发射全局事件
|
||||
this.eventBus.emit('player_level_up', {
|
||||
level: 10,
|
||||
experience: 2500
|
||||
});
|
||||
}
|
||||
|
||||
private async uploadToServer(data: any): Promise<void> {
|
||||
// 模拟服务器上传
|
||||
return new Promise(resolve => setTimeout(resolve, 2000));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 事件装饰器
|
||||
|
||||
使用装饰器自动注册事件监听器：
|
||||
|
||||
```typescript
|
||||
import { EventHandler, AsyncEventHandler } from '@esengine/ecs-framework';
|
||||
|
||||
class PlayerController {
|
||||
constructor() {
|
||||
// 自动调用事件监听器注册
|
||||
this.initEventListeners();
|
||||
}
|
||||
|
||||
@EventHandler('player_input')
|
||||
private onPlayerInput(data: { action: string, value: number }): void {
|
||||
console.log(`玩家输入: ${data.action} = ${data.value}`);
|
||||
// 处理玩家输入
|
||||
}
|
||||
|
||||
@EventHandler('player_attack', { priority: 100 })
|
||||
private onPlayerAttack(data: { damage: number, target: string }): void {
|
||||
console.log(`玩家攻击 ${data.target}，造成 ${data.damage} 伤害`);
|
||||
// 处理攻击逻辑
|
||||
}
|
||||
|
||||
@AsyncEventHandler('save_progress')
|
||||
private async onSaveProgress(data: { checkpointId: string }): Promise<void> {
|
||||
console.log(`保存进度到检查点: ${data.checkpointId}`);
|
||||
// 异步保存进度
|
||||
await this.saveToCloud(data.checkpointId);
|
||||
}
|
||||
|
||||
@EventHandler('game_over', { once: true })
|
||||
private onGameOver(): void {
|
||||
console.log('游戏结束！');
|
||||
// 这个方法只会被调用一次
|
||||
}
|
||||
|
||||
private async saveToCloud(checkpointId: string): Promise<void> {
|
||||
// 模拟云端保存
|
||||
return new Promise(resolve => setTimeout(resolve, 1500));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 批处理事件
|
||||
|
||||
对于高频事件，可以使用批处理来提升性能：
|
||||
|
||||
```typescript
|
||||
class MovementSystem extends EntitySystem {
|
||||
protected onInitialize(): void {
|
||||
// 设置位置更新事件的批处理
|
||||
this.scene?.eventSystem.setBatchConfig('position_updated', {
|
||||
batchSize: 50, // 批处理大小
|
||||
delay: 16, // 延迟时间（毫秒）
|
||||
enabled: true
|
||||
});
|
||||
|
||||
// 监听批处理事件
|
||||
this.addEventListener('position_updated:batch', this.onPositionBatch.bind(this));
|
||||
}
|
||||
|
||||
private onPositionBatch(batchData: any): void {
|
||||
console.log(`批处理位置更新，共 ${batchData.count} 个事件`);
|
||||
|
||||
// 批量处理所有位置更新
|
||||
for (const event of batchData.events) {
|
||||
this.updateMinimap(event.entityId, event.position);
|
||||
}
|
||||
}
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
for (const entity of entities) {
|
||||
const position = entity.getComponent(Position);
|
||||
if (position && position.hasChanged) {
|
||||
// 发射高频位置更新事件（会被批处理）
|
||||
this.scene?.eventSystem.emitSync('position_updated', {
|
||||
entityId: entity.id,
|
||||
position: { x: position.x, y: position.y }
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private updateMinimap(entityId: number, position: { x: number, y: number }): void {
|
||||
// 更新小地图显示
|
||||
}
|
||||
|
||||
public flushPositionUpdates(): void {
|
||||
// 立即处理所有待处理的位置更新
|
||||
this.scene?.eventSystem.flushBatch('position_updated');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 预定义的 ECS 事件
|
||||
|
||||
框架提供了一些预定义的 ECS 生命周期事件：
|
||||
|
||||
```typescript
|
||||
import { ECSEventType } from '@esengine/ecs-framework';
|
||||
|
||||
class ECSMonitor {
|
||||
private eventBus = GlobalEventBus.getInstance();
|
||||
|
||||
constructor() {
|
||||
this.setupECSEvents();
|
||||
}
|
||||
|
||||
private setupECSEvents(): void {
|
||||
// 监听实体生命周期事件
|
||||
this.eventBus.onEntityCreated(this.onEntityCreated.bind(this));
|
||||
this.eventBus.on(ECSEventType.ENTITY_DESTROYED, this.onEntityDestroyed.bind(this));
|
||||
|
||||
// 监听组件生命周期事件
|
||||
this.eventBus.onComponentAdded(this.onComponentAdded.bind(this));
|
||||
this.eventBus.on(ECSEventType.COMPONENT_REMOVED, this.onComponentRemoved.bind(this));
|
||||
|
||||
// 监听系统事件
|
||||
this.eventBus.on(ECSEventType.SYSTEM_ADDED, this.onSystemAdded.bind(this));
|
||||
this.eventBus.onSystemError(this.onSystemError.bind(this));
|
||||
|
||||
// 监听性能警告
|
||||
this.eventBus.onPerformanceWarning(this.onPerformanceWarning.bind(this));
|
||||
}
|
||||
|
||||
private onEntityCreated(data: any): void {
|
||||
console.log(`实体创建: ${data.entityName} (ID: ${data.entity.id})`);
|
||||
}
|
||||
|
||||
private onEntityDestroyed(data: any): void {
|
||||
console.log(`实体销毁: ${data.entity.name} (ID: ${data.entity.id})`);
|
||||
}
|
||||
|
||||
private onComponentAdded(data: any): void {
|
||||
console.log(`组件添加: ${data.componentType} 到实体 ${data.entity.name}`);
|
||||
}
|
||||
|
||||
private onComponentRemoved(data: any): void {
|
||||
console.log(`组件移除: ${data.componentType} 从实体 ${data.entity.name}`);
|
||||
}
|
||||
|
||||
private onSystemAdded(data: any): void {
|
||||
console.log(`系统添加: ${data.systemName}`);
|
||||
}
|
||||
|
||||
private onSystemError(data: any): void {
|
||||
console.error(`系统错误: ${data.systemName}`, data.error);
|
||||
}
|
||||
|
||||
private onPerformanceWarning(data: any): void {
|
||||
console.warn(`性能警告: ${data.systemName} 执行时间过长 (${data.executionTime}ms)`);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 事件命名规范
|
||||
|
||||
```typescript
|
||||
// ✅ 好的事件命名
|
||||
this.eventSystem.emitSync('player:health_changed', data);
|
||||
this.eventSystem.emitSync('enemy:spawned', data);
|
||||
this.eventSystem.emitSync('ui:score_updated', data);
|
||||
this.eventSystem.emitSync('game:paused', data);
|
||||
|
||||
// ❌ 避免的事件命名
|
||||
this.eventSystem.emitSync('event1', data);
|
||||
this.eventSystem.emitSync('update', data);
|
||||
this.eventSystem.emitSync('change', data);
|
||||
```
|
||||
|
||||
### 2. 类型安全的事件数据
|
||||
|
||||
```typescript
|
||||
// 定义事件数据接口
|
||||
interface PlayerHealthChangedEvent {
|
||||
entityId: number;
|
||||
oldHealth: number;
|
||||
newHealth: number;
|
||||
cause: 'damage' | 'healing';
|
||||
}
|
||||
|
||||
interface EnemySpawnedEvent {
|
||||
enemyType: string;
|
||||
position: { x: number, y: number };
|
||||
level: number;
|
||||
}
|
||||
|
||||
// 使用类型安全的事件
|
||||
class HealthSystem extends EntitySystem {
|
||||
private onHealthChanged(data: PlayerHealthChangedEvent): void {
|
||||
// TypeScript 会提供完整的类型检查
|
||||
console.log(`生命值变化: ${data.oldHealth} -> ${data.newHealth}`);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 避免事件循环
|
||||
|
||||
```typescript
|
||||
// ❌ 避免：可能导致无限循环
|
||||
class BadEventHandler {
|
||||
private onScoreChanged(data: any): void {
|
||||
// 在处理分数变化时又触发分数变化事件
|
||||
this.scene?.eventSystem.emitSync('score_changed', newData); // 危险！
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ 正确：使用不同的事件类型或条件判断
|
||||
class GoodEventHandler {
|
||||
private isProcessingScore = false;
|
||||
|
||||
private onScoreChanged(data: any): void {
|
||||
if (this.isProcessingScore) return; // 防止循环
|
||||
|
||||
this.isProcessingScore = true;
|
||||
// 处理分数变化
|
||||
this.updateUI(data);
|
||||
this.isProcessingScore = false;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 及时清理事件监听器
|
||||
|
||||
```typescript
|
||||
class TemporaryUI {
|
||||
private listenerId: string;
|
||||
|
||||
constructor(scene: Scene) {
|
||||
// 保存监听器ID用于后续清理
|
||||
this.listenerId = scene.eventSystem.on('ui_update', this.onUpdate.bind(this));
|
||||
}
|
||||
|
||||
private onUpdate(data: any): void {
|
||||
// 处理UI更新
|
||||
}
|
||||
|
||||
public destroy(): void {
|
||||
// 清理事件监听器
|
||||
if (this.listenerId) {
|
||||
scene.eventSystem.off('ui_update', this.listenerId);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 性能考虑
|
||||
|
||||
```typescript
|
||||
class OptimizedEventHandler {
|
||||
protected onInitialize(): void {
|
||||
// 对于高频事件，使用批处理
|
||||
this.scene?.eventSystem.setBatchConfig('movement_update', {
|
||||
batchSize: 100,
|
||||
delay: 16,
|
||||
enabled: true
|
||||
});
|
||||
|
||||
// 对于低频但重要的事件，使用高优先级
|
||||
this.addEventListener('game_over', this.onGameOver.bind(this), {
|
||||
priority: 1000
|
||||
});
|
||||
|
||||
// 对于一次性事件，使用 once
|
||||
this.addEventListener('level_start', this.onLevelStart.bind(this), {
|
||||
once: true
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
事件系统是 ECS 框架中实现松耦合架构的重要工具，正确使用事件系统能让你的游戏代码更加模块化、可维护和可扩展。
|
||||
394
docs/guide/getting-started.md
Normal file
394
docs/guide/getting-started.md
Normal file
@@ -0,0 +1,394 @@
|
||||
# 快速开始
|
||||
|
||||
本指南将帮助你快速上手 ECS Framework，从安装到创建第一个 ECS 应用。
|
||||
|
||||
## 安装
|
||||
|
||||
### NPM 安装
|
||||
|
||||
```bash
|
||||
# 使用 npm
|
||||
npm install @esengine/ecs-framework
|
||||
```
|
||||
|
||||
## 初始化 Core
|
||||
|
||||
### 基础初始化
|
||||
|
||||
ECS Framework 的核心是 `Core` 类，它是一个单例模式，负责管理整个框架的生命周期。
|
||||
|
||||
```typescript
|
||||
import { Core } from '@esengine/ecs-framework'
|
||||
|
||||
// 方式1：使用配置对象（推荐）
|
||||
const core = Core.create({
|
||||
debug: true, // 启用调试模式，提供详细的日志和性能监控
|
||||
enableEntitySystems: true, // 启用实体系统，这是ECS的核心功能
|
||||
debugConfig: { // 可选：高级调试配置
|
||||
enabled: false, // 是否启用WebSocket调试服务器
|
||||
websocketUrl: 'ws://localhost:8080',
|
||||
debugFrameRate: 30, // 调试数据发送帧率
|
||||
channels: {
|
||||
entities: true,
|
||||
systems: true,
|
||||
performance: true,
|
||||
components: true,
|
||||
scenes: true
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// 方式2：简化创建（向后兼容）
|
||||
const core = Core.create(true); // 等同于 { debug: true, enableEntitySystems: true }
|
||||
|
||||
// 方式3：生产环境配置
|
||||
const core = Core.create({
|
||||
debug: false, // 生产环境关闭调试
|
||||
enableEntitySystems: true
|
||||
});
|
||||
```
|
||||
|
||||
### Core 配置详解
|
||||
|
||||
```typescript
|
||||
interface ICoreConfig {
|
||||
/** 是否启用调试模式 - 影响日志级别和性能监控 */
|
||||
debug?: boolean;
|
||||
|
||||
/** 是否启用实体系统 - 核心ECS功能开关 */
|
||||
enableEntitySystems?: boolean;
|
||||
|
||||
/** 高级调试配置 - 用于开发工具集成 */
|
||||
debugConfig?: {
|
||||
enabled: boolean; // 是否启用调试服务器
|
||||
websocketUrl: string; // WebSocket服务器地址
|
||||
autoReconnect?: boolean; // 是否自动重连
|
||||
debugFrameRate?: 60 | 30 | 15; // 调试数据发送帧率
|
||||
channels: { // 数据通道配置
|
||||
entities: boolean; // 实体数据
|
||||
systems: boolean; // 系统数据
|
||||
performance: boolean; // 性能数据
|
||||
components: boolean; // 组件数据
|
||||
scenes: boolean; // 场景数据
|
||||
};
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Core 实例管理
|
||||
|
||||
Core 采用单例模式，创建后可以通过静态属性获取：
|
||||
|
||||
```typescript
|
||||
// 创建实例
|
||||
const core = Core.create(true);
|
||||
|
||||
// 获取已创建的实例
|
||||
const instance = Core.Instance; // 获取当前实例，如果未创建则为 null
|
||||
```
|
||||
|
||||
### 游戏循环集成
|
||||
|
||||
**重要**: 在创建实体和系统之前，你需要先了解如何将 ECS Framework 集成到你的游戏引擎中。
|
||||
|
||||
`Core.update(deltaTime)` 是整个框架的心跳，必须在游戏引擎的每一帧中调用。它负责：
|
||||
- 更新框架内置的 Time 类
|
||||
- 更新所有全局管理器（定时器、对象池等）
|
||||
- 更新所有场景中的实体系统
|
||||
- 处理实体的创建和销毁
|
||||
- 收集性能数据（调试模式下）
|
||||
|
||||
各引擎集成示例请参考：[与游戏引擎集成](#与游戏引擎集成)
|
||||
|
||||
## 创建第一个 ECS 应用
|
||||
|
||||
### 1. 定义组件
|
||||
|
||||
组件是纯数据容器，用于存储实体的状态：
|
||||
|
||||
```typescript
|
||||
import { Component, ECSComponent } from '@esengine/ecs-framework'
|
||||
|
||||
// 位置组件
|
||||
@ECSComponent('Position')
|
||||
class Position extends Component {
|
||||
x: number = 0
|
||||
y: number = 0
|
||||
|
||||
constructor(x: number = 0, y: number = 0) {
|
||||
super()
|
||||
this.x = x
|
||||
this.y = y
|
||||
}
|
||||
}
|
||||
|
||||
// 速度组件
|
||||
@ECSComponent('Velocity')
|
||||
class Velocity extends Component {
|
||||
dx: number = 0
|
||||
dy: number = 0
|
||||
|
||||
constructor(dx: number = 0, dy: number = 0) {
|
||||
super()
|
||||
this.dx = dx
|
||||
this.dy = dy
|
||||
}
|
||||
}
|
||||
|
||||
// 渲染组件
|
||||
@ECSComponent('Sprite')
|
||||
class Sprite extends Component {
|
||||
texture: string = ''
|
||||
width: number = 32
|
||||
height: number = 32
|
||||
|
||||
constructor(texture: string, width: number = 32, height: number = 32) {
|
||||
super()
|
||||
this.texture = texture
|
||||
this.width = width
|
||||
this.height = height
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 创建实体系统
|
||||
|
||||
系统包含游戏逻辑，处理具有特定组件的实体。ECS Framework 提供了基于 Matcher 的实体过滤机制：
|
||||
|
||||
```typescript
|
||||
import { EntitySystem, Matcher, Time, ECSSystem } from '@esengine/ecs-framework'
|
||||
|
||||
// 移动系统 - 处理位置和速度
|
||||
@ECSSystem('MovementSystem')
|
||||
class MovementSystem extends EntitySystem {
|
||||
|
||||
constructor() {
|
||||
// 使用 Matcher 定义要处理的实体：必须同时拥有 Position 和 Velocity 组件
|
||||
super(Matcher.empty().all(Position, Velocity))
|
||||
}
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
// process 方法接收所有匹配的实体
|
||||
for (const entity of entities) {
|
||||
const position = entity.getComponent(Position)!
|
||||
const velocity = entity.getComponent(Velocity)!
|
||||
|
||||
// 更新位置（使用框架的Time类）
|
||||
position.x += velocity.dx * Time.deltaTime
|
||||
position.y += velocity.dy * Time.deltaTime
|
||||
|
||||
// 边界检查示例
|
||||
if (position.x < 0) position.x = 0
|
||||
if (position.y < 0) position.y = 0
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 渲染系统 - 处理可见对象
|
||||
@ECSSystem('RenderSystem')
|
||||
class RenderSystem extends EntitySystem {
|
||||
|
||||
constructor() {
|
||||
// 必须有 Position 和 Sprite，可选 Velocity（用于方向判断）
|
||||
super(Matcher.empty().all(Position, Sprite).any(Velocity))
|
||||
}
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
for (const entity of entities) {
|
||||
const position = entity.getComponent(Position)!
|
||||
const sprite = entity.getComponent(Sprite)!
|
||||
const velocity = entity.getComponent(Velocity) // 可能为 null
|
||||
|
||||
// 根据速度方向翻转精灵（可选逻辑）
|
||||
let flipX = false
|
||||
if (velocity && velocity.dx < 0) {
|
||||
flipX = true
|
||||
}
|
||||
|
||||
// 渲染逻辑（这里是伪代码）
|
||||
this.drawSprite(sprite.texture, position.x, position.y, sprite.width, sprite.height, flipX)
|
||||
}
|
||||
}
|
||||
|
||||
private drawSprite(texture: string, x: number, y: number, width: number, height: number, flipX: boolean = false) {
|
||||
// 实际的渲染实现将取决于你使用的游戏引擎
|
||||
const direction = flipX ? '←' : '→'
|
||||
console.log(`渲染 ${texture} 在位置 (${x.toFixed(1)}, ${y.toFixed(1)}) 方向: ${direction}`)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### 3. 创建场景
|
||||
|
||||
推荐继承 Scene 类来创建自定义场景：
|
||||
|
||||
```typescript
|
||||
import { Scene } from '@esengine/ecs-framework'
|
||||
|
||||
// 推荐：继承Scene创建自定义场景
|
||||
class GameScene extends Scene {
|
||||
|
||||
initialize(): void {
|
||||
// 场景初始化逻辑
|
||||
this.name = "MainScene";
|
||||
|
||||
// 添加系统到场景
|
||||
this.addSystem(new MovementSystem());
|
||||
this.addSystem(new RenderSystem());
|
||||
}
|
||||
|
||||
onStart(): void {
|
||||
// 场景开始运行时的逻辑
|
||||
console.log("游戏场景已启动");
|
||||
}
|
||||
|
||||
unload(): void {
|
||||
// 场景卸载时的清理逻辑
|
||||
console.log("游戏场景已卸载");
|
||||
}
|
||||
}
|
||||
|
||||
// 创建并设置场景
|
||||
const gameScene = new GameScene();
|
||||
Core.setScene(gameScene);
|
||||
```
|
||||
|
||||
### 4. 创建实体
|
||||
|
||||
```typescript
|
||||
// 创建玩家实体
|
||||
const player = gameScene.createEntity("Player");
|
||||
player.addComponent(new Position(100, 100));
|
||||
player.addComponent(new Velocity(50, 30)); // 每秒移动 50 像素（x方向），30 像素（y方向）
|
||||
player.addComponent(new Sprite("player.png", 64, 64));
|
||||
```
|
||||
|
||||
## World 概念
|
||||
|
||||
World 是 Scene 的容器，用于管理多个独立的游戏世界。这种设计特别适用于：
|
||||
- 多人游戏房间（每个房间一个 World）
|
||||
- 不同的游戏模式
|
||||
- 独立的模拟环境
|
||||
|
||||
### 基本用法
|
||||
|
||||
```typescript
|
||||
import { World, Scene } from '@esengine/ecs-framework'
|
||||
|
||||
// 创建游戏房间的World
|
||||
const roomWorld = new World({ name: 'Room_001' });
|
||||
|
||||
// 在World中创建多个Scene
|
||||
class GameScene extends Scene {
|
||||
initialize(): void {
|
||||
this.name = "GamePlay";
|
||||
this.addSystem(new MovementSystem());
|
||||
this.addSystem(new RenderSystem());
|
||||
}
|
||||
}
|
||||
|
||||
class UIScene extends Scene {
|
||||
initialize(): void {
|
||||
this.name = "UI";
|
||||
// UI相关系统
|
||||
}
|
||||
}
|
||||
|
||||
// 添加Scene到World
|
||||
const gameScene = roomWorld.createScene('game', new GameScene());
|
||||
const uiScene = roomWorld.createScene('ui', new UIScene());
|
||||
|
||||
// 激活Scene
|
||||
roomWorld.setSceneActive('game', true);
|
||||
roomWorld.setSceneActive('ui', true);
|
||||
|
||||
// 启动World
|
||||
roomWorld.start();
|
||||
```
|
||||
|
||||
### World 生命周期
|
||||
|
||||
World 提供了完整的生命周期管理：
|
||||
- `start()`: 启动 World 和所有全局系统
|
||||
- `updateGlobalSystems()`: 更新全局系统（由 Core.update() 调用）
|
||||
- `updateScenes()`: 更新所有激活的 Scene（由 Core.update() 调用）
|
||||
- `stop()`: 停止 World
|
||||
- `destroy()`: 销毁 World 和所有资源
|
||||
|
||||
## 与游戏引擎集成
|
||||
|
||||
### Laya 引擎集成
|
||||
|
||||
```typescript
|
||||
import { Stage } from "laya/display/Stage"
|
||||
import { Stat } from "laya/utils/Stat"
|
||||
import { Laya } from "Laya"
|
||||
|
||||
// 初始化 Laya
|
||||
Laya.init(800, 600).then(() => {
|
||||
// 初始化 ECS
|
||||
const core = Core.create(true)
|
||||
|
||||
// 设置场景...
|
||||
|
||||
// 启动游戏循环
|
||||
Laya.timer.frameLoop(1, this, () => {
|
||||
const deltaTime = Laya.timer.delta / 1000 // 转换为秒
|
||||
Core.update(deltaTime)
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
### Cocos Creator 集成
|
||||
|
||||
```typescript
|
||||
import { Component, _decorator } from 'cc'
|
||||
|
||||
const { ccclass } = _decorator
|
||||
|
||||
@ccclass('ECSGameManager')
|
||||
export class ECSGameManager extends Component {
|
||||
|
||||
onLoad() {
|
||||
// 初始化 ECS
|
||||
const core = Core.create(true)
|
||||
|
||||
// 设置场景...
|
||||
}
|
||||
|
||||
update(deltaTime: number) {
|
||||
// 更新 ECS
|
||||
Core.update(deltaTime)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## 下一步
|
||||
|
||||
现在你已经成功创建了第一个 ECS 应用！接下来可以：
|
||||
|
||||
- 查看完整的 [API 文档](/api/README)
|
||||
- 探索更多[实际应用示例](/examples/)
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 为什么我的系统没有执行？
|
||||
|
||||
确保：
|
||||
1. 系统已添加到场景：`this.addSystem(system)` （在 Scene 的 initialize 方法中）
|
||||
2. 场景已设置为当前场景：`Core.setScene(scene)`
|
||||
3. 游戏循环在调用：`Core.update(deltaTime)`
|
||||
|
||||
### 如何调试 ECS 应用？
|
||||
|
||||
启用调试模式：
|
||||
|
||||
```typescript
|
||||
Core.create({ debug: true })
|
||||
|
||||
// 获取调试数据
|
||||
const debugData = Core.getDebugData()
|
||||
console.log(debugData)
|
||||
```
|
||||
26
docs/guide/index.md
Normal file
26
docs/guide/index.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# 指南
|
||||
|
||||
欢迎使用 ECS Framework 指南。这里将详细介绍框架的各个核心概念和使用方法。
|
||||
|
||||
## 核心概念
|
||||
|
||||
### [实体类 (Entity)](./entity.md)
|
||||
了解 ECS 架构的基础 - 实体类的使用方法、生命周期管理和最佳实践。
|
||||
|
||||
### [组件系统 (Component)](./component.md)
|
||||
学习如何创建和使用组件，实现游戏功能的模块化设计。
|
||||
|
||||
### [系统架构 (System)](./system.md)
|
||||
掌握系统的编写方法，实现游戏逻辑的处理。
|
||||
|
||||
### [场景管理 (Scene)](./scene.md)
|
||||
了解场景的生命周期、系统管理和实体容器功能。
|
||||
|
||||
### [事件系统 (Event)](./event-system.md)
|
||||
掌握类型安全的事件系统，实现组件间通信和系统协作。
|
||||
|
||||
### [时间和定时器 (Time)](./time-and-timers.md)
|
||||
学习时间管理和定时器系统，实现游戏逻辑的精确时间控制。
|
||||
|
||||
### [日志系统 (Logger)](./logging.md)
|
||||
掌握分级日志系统，用于调试、监控和错误追踪。
|
||||
550
docs/guide/logging.md
Normal file
550
docs/guide/logging.md
Normal file
@@ -0,0 +1,550 @@
|
||||
# 日志系统
|
||||
|
||||
ECS 框架提供了功能强大的分级日志系统，支持多种日志级别、颜色输出、自定义前缀和灵活的配置选项。日志系统可以帮助开发者调试代码和监控应用运行状态。
|
||||
|
||||
## 基本概念
|
||||
|
||||
日志系统包含以下核心概念：
|
||||
- **日志级别**：Debug < Info < Warn < Error < Fatal < None
|
||||
- **日志器**：具名的日志输出器，每个模块可以有自己的日志器
|
||||
- **日志管理器**：全局管理所有日志器的单例
|
||||
- **颜色配置**：支持控制台颜色输出
|
||||
|
||||
## 日志级别
|
||||
|
||||
```typescript
|
||||
import { LogLevel } from '@esengine/ecs-framework';
|
||||
|
||||
// 日志级别从低到高
|
||||
LogLevel.Debug // 0 - 调试信息
|
||||
LogLevel.Info // 1 - 一般信息
|
||||
LogLevel.Warn // 2 - 警告信息
|
||||
LogLevel.Error // 3 - 错误信息
|
||||
LogLevel.Fatal // 4 - 致命错误
|
||||
LogLevel.None // 5 - 不输出任何日志
|
||||
```
|
||||
|
||||
## 基本使用
|
||||
|
||||
### 使用默认日志器
|
||||
|
||||
```typescript
|
||||
import { Logger } from '@esengine/ecs-framework';
|
||||
|
||||
class GameSystem extends EntitySystem {
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
// 输出不同级别的日志
|
||||
Logger.debug('处理实体数量:', entities.length);
|
||||
Logger.info('系统正常运行');
|
||||
Logger.warn('检测到性能问题');
|
||||
Logger.error('处理过程中发生错误', new Error('示例错误'));
|
||||
Logger.fatal('致命错误，系统即将停止');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 创建命名日志器
|
||||
|
||||
```typescript
|
||||
import { createLogger } from '@esengine/ecs-framework';
|
||||
|
||||
class MovementSystem extends EntitySystem {
|
||||
private logger = createLogger('MovementSystem');
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
this.logger.info(`处理 ${entities.length} 个移动实体`);
|
||||
|
||||
for (const entity of entities) {
|
||||
const position = entity.getComponent(Position);
|
||||
const velocity = entity.getComponent(Velocity);
|
||||
|
||||
if (position && velocity) {
|
||||
position.x += velocity.dx * Time.deltaTime;
|
||||
position.y += velocity.dy * Time.deltaTime;
|
||||
|
||||
this.logger.debug(`实体 ${entity.id} 移动到位置 (${position.x}, ${position.y})`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
protected onAdded(entity: Entity): void {
|
||||
this.logger.info(`实体 ${entity.name} 加入移动系统`);
|
||||
}
|
||||
|
||||
protected onRemoved(entity: Entity): void {
|
||||
this.logger.warn(`实体 ${entity.name} 离开移动系统`);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 系统内置日志器
|
||||
|
||||
框架的各个系统都有自己的日志器：
|
||||
|
||||
```typescript
|
||||
// 框架内部使用示例
|
||||
class Scene {
|
||||
private static readonly _logger = createLogger('Scene');
|
||||
|
||||
public addSystem(system: EntitySystem): void {
|
||||
Scene._logger.info(`添加系统: ${system.systemName}`);
|
||||
// 系统添加逻辑
|
||||
}
|
||||
|
||||
public removeSystem(system: EntitySystem): void {
|
||||
Scene._logger.warn(`移除系统: ${system.systemName}`);
|
||||
// 系统移除逻辑
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 日志配置
|
||||
|
||||
### 设置全局日志级别
|
||||
|
||||
```typescript
|
||||
import { setGlobalLogLevel, LogLevel } from '@esengine/ecs-framework';
|
||||
|
||||
// 在开发环境显示所有日志
|
||||
setGlobalLogLevel(LogLevel.Debug);
|
||||
|
||||
// 在生产环境只显示警告及以上级别
|
||||
setGlobalLogLevel(LogLevel.Warn);
|
||||
|
||||
// 完全禁用日志输出
|
||||
setGlobalLogLevel(LogLevel.None);
|
||||
```
|
||||
|
||||
### 创建自定义配置的日志器
|
||||
|
||||
```typescript
|
||||
import { ConsoleLogger, LogLevel } from '@esengine/ecs-framework';
|
||||
|
||||
class CustomLoggerExample {
|
||||
private debugLogger: ConsoleLogger;
|
||||
private productionLogger: ConsoleLogger;
|
||||
|
||||
constructor() {
|
||||
// 开发环境日志器
|
||||
this.debugLogger = new ConsoleLogger({
|
||||
level: LogLevel.Debug,
|
||||
enableTimestamp: true,
|
||||
enableColors: true,
|
||||
prefix: 'DEV'
|
||||
});
|
||||
|
||||
// 生产环境日志器
|
||||
this.productionLogger = new ConsoleLogger({
|
||||
level: LogLevel.Error,
|
||||
enableTimestamp: true,
|
||||
enableColors: false,
|
||||
prefix: 'PROD'
|
||||
});
|
||||
}
|
||||
|
||||
public logDevelopmentInfo(): void {
|
||||
this.debugLogger.debug('这是调试信息');
|
||||
this.debugLogger.info('开发环境信息');
|
||||
}
|
||||
|
||||
public logProductionError(): void {
|
||||
this.productionLogger.error('生产环境错误');
|
||||
this.productionLogger.fatal('致命错误');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 颜色配置
|
||||
|
||||
### 使用预定义颜色
|
||||
|
||||
```typescript
|
||||
import { Colors, setLoggerColors } from '@esengine/ecs-framework';
|
||||
|
||||
// 自定义颜色方案
|
||||
setLoggerColors({
|
||||
debug: Colors.BRIGHT_BLACK,
|
||||
info: Colors.BLUE,
|
||||
warn: Colors.YELLOW,
|
||||
error: Colors.RED,
|
||||
fatal: Colors.BRIGHT_RED
|
||||
});
|
||||
```
|
||||
|
||||
### 完整颜色示例
|
||||
|
||||
```typescript
|
||||
import { LoggerManager, Colors, LogLevel } from '@esengine/ecs-framework';
|
||||
|
||||
class ColorLoggerDemo {
|
||||
private logger = createLogger('ColorDemo');
|
||||
|
||||
constructor() {
|
||||
// 设置自定义颜色
|
||||
const manager = LoggerManager.getInstance();
|
||||
manager.setGlobalColors({
|
||||
debug: Colors.CYAN,
|
||||
info: Colors.GREEN,
|
||||
warn: Colors.YELLOW,
|
||||
error: Colors.RED,
|
||||
fatal: `${Colors.BOLD}${Colors.BRIGHT_RED}`
|
||||
});
|
||||
}
|
||||
|
||||
public demonstrateColors(): void {
|
||||
this.logger.debug('这是蓝绿色的调试信息');
|
||||
this.logger.info('这是绿色的信息');
|
||||
this.logger.warn('这是黄色的警告');
|
||||
this.logger.error('这是红色的错误');
|
||||
this.logger.fatal('这是加粗的亮红色致命错误');
|
||||
}
|
||||
|
||||
public resetToDefaults(): void {
|
||||
// 重置为默认颜色
|
||||
LoggerManager.getInstance().resetColors();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 高级功能
|
||||
|
||||
### 分层日志器
|
||||
|
||||
```typescript
|
||||
import { LoggerManager } from '@esengine/ecs-framework';
|
||||
|
||||
class HierarchicalLoggingExample {
|
||||
private systemLogger = createLogger('GameSystems');
|
||||
private movementLogger: ILogger;
|
||||
private renderLogger: ILogger;
|
||||
|
||||
constructor() {
|
||||
const manager = LoggerManager.getInstance();
|
||||
|
||||
// 创建子日志器
|
||||
this.movementLogger = manager.createChildLogger('GameSystems', 'Movement');
|
||||
this.renderLogger = manager.createChildLogger('GameSystems', 'Render');
|
||||
}
|
||||
|
||||
public demonstrateHierarchy(): void {
|
||||
this.systemLogger.info('游戏系统启动');
|
||||
|
||||
// 子日志器会显示完整路径：[GameSystems.Movement]
|
||||
this.movementLogger.debug('移动系统初始化');
|
||||
|
||||
// 子日志器会显示完整路径：[GameSystems.Render]
|
||||
this.renderLogger.info('渲染系统启动');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 自定义输出
|
||||
|
||||
```typescript
|
||||
import { ConsoleLogger, LogLevel } from '@esengine/ecs-framework';
|
||||
|
||||
class CustomOutputLogger {
|
||||
private fileLogger: ConsoleLogger;
|
||||
private networkLogger: ConsoleLogger;
|
||||
|
||||
constructor() {
|
||||
// 输出到文件的日志器（模拟）
|
||||
this.fileLogger = new ConsoleLogger({
|
||||
level: LogLevel.Info,
|
||||
output: (level: LogLevel, message: string) => {
|
||||
this.writeToFile(LogLevel[level], message);
|
||||
}
|
||||
});
|
||||
|
||||
// 发送到网络的日志器（模拟）
|
||||
this.networkLogger = new ConsoleLogger({
|
||||
level: LogLevel.Error,
|
||||
output: (level: LogLevel, message: string) => {
|
||||
this.sendToServer(LogLevel[level], message);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
private writeToFile(level: string, message: string): void {
|
||||
// 模拟文件写入
|
||||
console.log(`[FILE] ${level}: ${message}`);
|
||||
}
|
||||
|
||||
private sendToServer(level: string, message: string): void {
|
||||
// 模拟网络发送
|
||||
console.log(`[NETWORK] ${level}: ${message}`);
|
||||
}
|
||||
|
||||
public logToFile(message: string): void {
|
||||
this.fileLogger.info(message);
|
||||
}
|
||||
|
||||
public logCriticalError(error: Error): void {
|
||||
this.networkLogger.error('Critical error occurred', error);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 实际应用示例
|
||||
|
||||
### 游戏系统日志
|
||||
|
||||
```typescript
|
||||
class GameWithLogging {
|
||||
private gameLogger = createLogger('Game');
|
||||
private performanceLogger = createLogger('Performance');
|
||||
private networkLogger = createLogger('Network');
|
||||
|
||||
constructor() {
|
||||
// 在开发环境启用详细日志
|
||||
if (process.env.NODE_ENV === 'development') {
|
||||
setGlobalLogLevel(LogLevel.Debug);
|
||||
} else {
|
||||
setGlobalLogLevel(LogLevel.Warn);
|
||||
}
|
||||
}
|
||||
|
||||
public startGame(): void {
|
||||
this.gameLogger.info('游戏开始启动');
|
||||
|
||||
try {
|
||||
this.initializeSystems();
|
||||
this.loadResources();
|
||||
this.startGameLoop();
|
||||
|
||||
this.gameLogger.info('游戏启动成功');
|
||||
} catch (error) {
|
||||
this.gameLogger.fatal('游戏启动失败', error);
|
||||
throw error;
|
||||
}
|
||||
}
|
||||
|
||||
private initializeSystems(): void {
|
||||
this.gameLogger.debug('初始化游戏系统');
|
||||
|
||||
const systems = [
|
||||
new MovementSystem(),
|
||||
new RenderSystem(),
|
||||
new PhysicsSystem()
|
||||
];
|
||||
|
||||
for (const system of systems) {
|
||||
const startTime = performance.now();
|
||||
|
||||
// 初始化系统
|
||||
system.initialize();
|
||||
|
||||
const endTime = performance.now();
|
||||
this.performanceLogger.debug(
|
||||
`系统 ${system.systemName} 初始化耗时: ${(endTime - startTime).toFixed(2)}ms`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
private loadResources(): void {
|
||||
this.gameLogger.info('开始加载资源');
|
||||
|
||||
const resources = ['textures', 'sounds', 'data'];
|
||||
for (const resource of resources) {
|
||||
try {
|
||||
this.loadResource(resource);
|
||||
this.gameLogger.debug(`资源 ${resource} 加载成功`);
|
||||
} catch (error) {
|
||||
this.gameLogger.error(`资源 ${resource} 加载失败`, error);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private startGameLoop(): void {
|
||||
this.gameLogger.info('启动游戏循环');
|
||||
this.performanceLogger.debug('开始性能监控');
|
||||
}
|
||||
|
||||
private loadResource(name: string): void {
|
||||
// 模拟资源加载
|
||||
if (Math.random() < 0.1) {
|
||||
throw new Error(`Failed to load ${name}`);
|
||||
}
|
||||
}
|
||||
|
||||
public handleNetworkEvent(event: string, data: any): void {
|
||||
this.networkLogger.info(`网络事件: ${event}`, data);
|
||||
|
||||
if (event === 'connection_lost') {
|
||||
this.networkLogger.warn('网络连接丢失，尝试重连');
|
||||
} else if (event === 'sync_error') {
|
||||
this.networkLogger.error('数据同步错误', data);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 错误追踪和调试
|
||||
|
||||
```typescript
|
||||
class ErrorTrackingSystem extends EntitySystem {
|
||||
private logger = createLogger('ErrorTracker');
|
||||
private errorCounts = new Map<string, number>();
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
for (const entity of entities) {
|
||||
try {
|
||||
this.processEntity(entity);
|
||||
} catch (error) {
|
||||
this.handleError(entity, error as Error);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private processEntity(entity: Entity): void {
|
||||
// 模拟可能出错的实体处理
|
||||
if (Math.random() < 0.01) { // 1% 概率出错
|
||||
throw new Error(`Processing error for entity ${entity.id}`);
|
||||
}
|
||||
|
||||
this.logger.debug(`成功处理实体 ${entity.id}`);
|
||||
}
|
||||
|
||||
private handleError(entity: Entity, error: Error): void {
|
||||
const errorKey = error.message;
|
||||
const count = this.errorCounts.get(errorKey) || 0;
|
||||
this.errorCounts.set(errorKey, count + 1);
|
||||
|
||||
this.logger.error(
|
||||
`实体 ${entity.id} 处理失败 (第${count + 1}次): ${error.message}`,
|
||||
{
|
||||
entityId: entity.id,
|
||||
entityName: entity.name,
|
||||
componentCount: entity.components.length,
|
||||
errorStack: error.stack
|
||||
}
|
||||
);
|
||||
|
||||
// 如果同一类型错误发生太多次，升级为警告
|
||||
if (count >= 5) {
|
||||
this.logger.warn(`错误 "${errorKey}" 已发生 ${count + 1} 次，可能需要关注`);
|
||||
}
|
||||
|
||||
// 如果错误次数过多，升级为致命错误
|
||||
if (count >= 20) {
|
||||
this.logger.fatal(`错误 "${errorKey}" 发生次数过多，系统可能存在严重问题`);
|
||||
}
|
||||
}
|
||||
|
||||
public getErrorSummary(): void {
|
||||
this.logger.info('=== 错误统计 ===');
|
||||
for (const [error, count] of this.errorCounts) {
|
||||
this.logger.info(`${error}: ${count} 次`);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 合理的日志级别选择
|
||||
|
||||
```typescript
|
||||
class LoggingBestPractices {
|
||||
private logger = createLogger('BestPractices');
|
||||
|
||||
public demonstrateLogLevels(): void {
|
||||
// ✅ Debug - 详细的调试信息
|
||||
this.logger.debug('变量值', { x: 10, y: 20 });
|
||||
|
||||
// ✅ Info - 重要的状态变化
|
||||
this.logger.info('系统启动完成');
|
||||
|
||||
// ✅ Warn - 异常但不致命的情况
|
||||
this.logger.warn('资源未找到，使用默认值');
|
||||
|
||||
// ✅ Error - 错误但程序可以继续
|
||||
this.logger.error('保存失败，将重试', new Error('Network timeout'));
|
||||
|
||||
// ✅ Fatal - 致命错误，程序无法继续
|
||||
this.logger.fatal('内存不足，程序即将退出');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 结构化日志数据
|
||||
|
||||
```typescript
|
||||
class StructuredLogging {
|
||||
private logger = createLogger('Structured');
|
||||
|
||||
public logWithStructuredData(): void {
|
||||
// ✅ 提供结构化的上下文信息
|
||||
this.logger.info('用户操作', {
|
||||
userId: 12345,
|
||||
action: 'move',
|
||||
position: { x: 100, y: 200 },
|
||||
timestamp: Date.now()
|
||||
});
|
||||
|
||||
// ✅ 包含相关的错误上下文
|
||||
this.logger.error('数据库查询失败', {
|
||||
query: 'SELECT * FROM users',
|
||||
parameters: { id: 123 },
|
||||
connectionId: 'conn_456',
|
||||
retryCount: 3
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 避免日志性能问题
|
||||
|
||||
```typescript
|
||||
class PerformanceConsciousLogging {
|
||||
private logger = createLogger('Performance');
|
||||
|
||||
public efficientLogging(): void {
|
||||
// ✅ 检查日志级别避免不必要的计算
|
||||
if (this.logger.debug) {
|
||||
const expensiveData = this.calculateExpensiveDebugInfo();
|
||||
this.logger.debug('详细调试信息', expensiveData);
|
||||
}
|
||||
|
||||
// ❌ 避免：总是计算昂贵的日志数据
|
||||
// this.logger.debug('调试信息', this.calculateExpensiveDebugInfo());
|
||||
}
|
||||
|
||||
private calculateExpensiveDebugInfo(): any {
|
||||
// 模拟昂贵的计算
|
||||
return { /* 复杂的调试数据 */ };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 日志配置管理
|
||||
|
||||
```typescript
|
||||
class LoggingConfiguration {
|
||||
public static setupLogging(): void {
|
||||
// 根据环境配置日志级别
|
||||
const isDevelopment = process.env.NODE_ENV === 'development';
|
||||
const isProduction = process.env.NODE_ENV === 'production';
|
||||
|
||||
if (isDevelopment) {
|
||||
setGlobalLogLevel(LogLevel.Debug);
|
||||
setLoggerColors({
|
||||
debug: Colors.CYAN,
|
||||
info: Colors.GREEN,
|
||||
warn: Colors.YELLOW,
|
||||
error: Colors.RED,
|
||||
fatal: Colors.BRIGHT_RED
|
||||
});
|
||||
} else if (isProduction) {
|
||||
setGlobalLogLevel(LogLevel.Warn);
|
||||
// 生产环境禁用颜色
|
||||
LoggerManager.getInstance().resetColors();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 在应用启动时配置日志
|
||||
LoggingConfiguration.setupLogging();
|
||||
```
|
||||
|
||||
日志系统是调试和监控应用的重要工具，正确使用日志系统能大大提高开发效率和问题排查能力。
|
||||
510
docs/guide/scene.md
Normal file
510
docs/guide/scene.md
Normal file
@@ -0,0 +1,510 @@
|
||||
# 场景管理
|
||||
|
||||
在 ECS 架构中，场景（Scene）是游戏世界的容器，负责管理实体、系统和组件的生命周期。场景提供了完整的 ECS 运行环境。
|
||||
|
||||
## 基本概念
|
||||
|
||||
场景是 ECS 框架的核心容器，提供：
|
||||
- 实体的创建、管理和销毁
|
||||
- 系统的注册和执行调度
|
||||
- 组件的存储和查询
|
||||
- 事件系统支持
|
||||
- 性能监控和调试信息
|
||||
|
||||
## 创建场景
|
||||
|
||||
### 继承 Scene 类
|
||||
|
||||
**推荐做法：继承 Scene 类来创建自定义场景**
|
||||
|
||||
```typescript
|
||||
import { Scene, EntitySystem } from '@esengine/ecs-framework';
|
||||
|
||||
class GameScene extends Scene {
|
||||
protected initialize(): void {
|
||||
// 设置场景名称
|
||||
this.name = "GameScene";
|
||||
|
||||
// 添加系统
|
||||
this.addSystem(new MovementSystem());
|
||||
this.addSystem(new RenderSystem());
|
||||
this.addSystem(new PhysicsSystem());
|
||||
|
||||
// 创建初始实体
|
||||
this.createInitialEntities();
|
||||
}
|
||||
|
||||
private createInitialEntities(): void {
|
||||
// 创建玩家
|
||||
const player = this.createEntity("Player");
|
||||
player.addComponent(new Position(400, 300));
|
||||
player.addComponent(new Health(100));
|
||||
player.addComponent(new PlayerController());
|
||||
|
||||
// 创建敌人
|
||||
for (let i = 0; i < 5; i++) {
|
||||
const enemy = this.createEntity(`Enemy_${i}`);
|
||||
enemy.addComponent(new Position(Math.random() * 800, Math.random() * 600));
|
||||
enemy.addComponent(new Health(50));
|
||||
enemy.addComponent(new EnemyAI());
|
||||
}
|
||||
}
|
||||
|
||||
public onStart(): void {
|
||||
console.log("游戏场景已启动");
|
||||
// 场景启动时的逻辑
|
||||
}
|
||||
|
||||
public unload(): void {
|
||||
console.log("游戏场景已卸载");
|
||||
// 场景卸载时的清理逻辑
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 使用场景配置
|
||||
|
||||
```typescript
|
||||
import { ISceneConfig } from '@esengine/ecs-framework';
|
||||
|
||||
const config: ISceneConfig = {
|
||||
name: "MainGame",
|
||||
enableEntityDirectUpdate: false
|
||||
};
|
||||
|
||||
class ConfiguredScene extends Scene {
|
||||
constructor() {
|
||||
super(config);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 场景生命周期
|
||||
|
||||
场景提供了完整的生命周期管理：
|
||||
|
||||
```typescript
|
||||
class ExampleScene extends Scene {
|
||||
protected initialize(): void {
|
||||
// 场景初始化：设置系统和初始实体
|
||||
console.log("场景初始化");
|
||||
}
|
||||
|
||||
public onStart(): void {
|
||||
// 场景开始运行：游戏逻辑开始执行
|
||||
console.log("场景开始运行");
|
||||
}
|
||||
|
||||
public unload(): void {
|
||||
// 场景卸载：清理资源
|
||||
console.log("场景卸载");
|
||||
}
|
||||
}
|
||||
|
||||
// 使用场景（由框架自动管理生命周期）
|
||||
const scene = new ExampleScene();
|
||||
// 场景的 initialize(), begin(), update(), end() 由框架自动调用
|
||||
```
|
||||
|
||||
## 实体管理
|
||||
|
||||
### 创建实体
|
||||
|
||||
```typescript
|
||||
class EntityScene extends Scene {
|
||||
createGameEntities(): void {
|
||||
// 创建单个实体
|
||||
const player = this.createEntity("Player");
|
||||
|
||||
// 批量创建实体（高性能）
|
||||
const bullets = this.createEntities(100, "Bullet");
|
||||
|
||||
// 为批量创建的实体添加组件
|
||||
bullets.forEach((bullet, index) => {
|
||||
bullet.addComponent(new Position(index * 10, 100));
|
||||
bullet.addComponent(new Velocity(Math.random() * 200 - 100, -300));
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 查找实体
|
||||
|
||||
```typescript
|
||||
class SearchScene extends Scene {
|
||||
findEntities(): void {
|
||||
// 按名称查找
|
||||
const player = this.findEntity("Player");
|
||||
const player2 = this.getEntityByName("Player"); // 别名方法
|
||||
|
||||
// 按 ID 查找
|
||||
const entity = this.findEntityById(123);
|
||||
|
||||
// 按标签查找
|
||||
const enemies = this.findEntitiesByTag(2);
|
||||
const enemies2 = this.getEntitiesByTag(2); // 别名方法
|
||||
|
||||
if (player) {
|
||||
console.log(`找到玩家: ${player.name}`);
|
||||
}
|
||||
|
||||
console.log(`找到 ${enemies.length} 个敌人`);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 销毁实体
|
||||
|
||||
```typescript
|
||||
class DestroyScene extends Scene {
|
||||
cleanupEntities(): void {
|
||||
// 销毁所有实体
|
||||
this.destroyAllEntities();
|
||||
|
||||
// 单个实体的销毁通过实体本身
|
||||
const enemy = this.findEntity("Enemy_1");
|
||||
if (enemy) {
|
||||
enemy.destroy(); // 实体会自动从场景中移除
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 系统管理
|
||||
|
||||
### 添加和移除系统
|
||||
|
||||
```typescript
|
||||
class SystemScene extends Scene {
|
||||
protected initialize(): void {
|
||||
// 添加系统
|
||||
const movementSystem = new MovementSystem();
|
||||
this.addSystem(movementSystem);
|
||||
|
||||
// 设置系统更新顺序
|
||||
movementSystem.updateOrder = 1;
|
||||
|
||||
// 添加更多系统
|
||||
this.addSystem(new PhysicsSystem());
|
||||
this.addSystem(new RenderSystem());
|
||||
}
|
||||
|
||||
public removeUnnecessarySystems(): void {
|
||||
// 获取系统
|
||||
const physicsSystem = this.getEntityProcessor(PhysicsSystem);
|
||||
|
||||
// 移除系统
|
||||
if (physicsSystem) {
|
||||
this.removeSystem(physicsSystem);
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 系统访问
|
||||
|
||||
```typescript
|
||||
class SystemAccessScene extends Scene {
|
||||
public pausePhysics(): void {
|
||||
const physicsSystem = this.getEntityProcessor(PhysicsSystem);
|
||||
if (physicsSystem) {
|
||||
physicsSystem.enabled = false;
|
||||
}
|
||||
}
|
||||
|
||||
public getAllSystems(): EntitySystem[] {
|
||||
return this.systems; // 获取所有系统
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 事件系统
|
||||
|
||||
场景内置了类型安全的事件系统：
|
||||
|
||||
```typescript
|
||||
class EventScene extends Scene {
|
||||
protected initialize(): void {
|
||||
// 监听事件
|
||||
this.eventSystem.on('player_died', this.onPlayerDied.bind(this));
|
||||
this.eventSystem.on('enemy_spawned', this.onEnemySpawned.bind(this));
|
||||
this.eventSystem.on('level_complete', this.onLevelComplete.bind(this));
|
||||
}
|
||||
|
||||
private onPlayerDied(data: any): void {
|
||||
console.log('玩家死亡事件');
|
||||
// 处理玩家死亡
|
||||
}
|
||||
|
||||
private onEnemySpawned(data: any): void {
|
||||
console.log('敌人生成事件');
|
||||
// 处理敌人生成
|
||||
}
|
||||
|
||||
private onLevelComplete(data: any): void {
|
||||
console.log('关卡完成事件');
|
||||
// 处理关卡完成
|
||||
}
|
||||
|
||||
public triggerGameEvent(): void {
|
||||
// 发送事件
|
||||
this.eventSystem.emitSync('custom_event', {
|
||||
message: "这是自定义事件",
|
||||
timestamp: Date.now()
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 场景统计和调试
|
||||
|
||||
### 获取场景统计
|
||||
|
||||
```typescript
|
||||
class StatsScene extends Scene {
|
||||
public showStats(): void {
|
||||
const stats = this.getStats();
|
||||
console.log(`实体数量: ${stats.entityCount}`);
|
||||
console.log(`系统数量: ${stats.processorCount}`);
|
||||
console.log('组件存储统计:', stats.componentStorageStats);
|
||||
}
|
||||
|
||||
public showDebugInfo(): void {
|
||||
const debugInfo = this.getDebugInfo();
|
||||
console.log('场景调试信息:', debugInfo);
|
||||
|
||||
// 显示所有实体信息
|
||||
debugInfo.entities.forEach(entity => {
|
||||
console.log(`实体 ${entity.name}(${entity.id}): ${entity.componentCount} 个组件`);
|
||||
console.log('组件类型:', entity.componentTypes);
|
||||
});
|
||||
|
||||
// 显示所有系统信息
|
||||
debugInfo.processors.forEach(processor => {
|
||||
console.log(`系统 ${processor.name}: 处理 ${processor.entityCount} 个实体`);
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 场景集成到框架
|
||||
|
||||
场景可以通过两种方式运行：
|
||||
|
||||
### 1. 简单的单场景应用
|
||||
|
||||
```typescript
|
||||
import { Core } from '@esengine/ecs-framework';
|
||||
|
||||
// 创建游戏场景
|
||||
class GameScene extends Scene {
|
||||
protected initialize(): void {
|
||||
this.name = "GameScene";
|
||||
this.addSystem(new MovementSystem());
|
||||
this.addSystem(new RenderSystem());
|
||||
}
|
||||
}
|
||||
|
||||
// 启动游戏
|
||||
Core.create();
|
||||
const gameScene = new GameScene();
|
||||
Core.setScene(gameScene);
|
||||
```
|
||||
|
||||
### 2. 复杂的多场景应用
|
||||
|
||||
```typescript
|
||||
import { WorldManager } from '@esengine/ecs-framework';
|
||||
|
||||
// 获取WorldManager实例
|
||||
const worldManager = WorldManager.getInstance();
|
||||
|
||||
// 创建World
|
||||
const gameWorld = worldManager.createWorld('game', {
|
||||
name: 'MainGame',
|
||||
maxScenes: 5
|
||||
});
|
||||
|
||||
// 在World中创建场景
|
||||
const menuScene = gameWorld.createScene('menu', new MenuScene());
|
||||
const gameScene = gameWorld.createScene('game', new GameScene());
|
||||
|
||||
// 激活场景
|
||||
gameWorld.setSceneActive('menu', true);
|
||||
```
|
||||
|
||||
## 多场景管理
|
||||
|
||||
在World中可以管理多个场景，通过激活/停用来切换：
|
||||
|
||||
```typescript
|
||||
class GameWorld extends World {
|
||||
private menuScene: Scene;
|
||||
private gameScene: Scene;
|
||||
private gameOverScene: Scene;
|
||||
|
||||
public initialize(): void {
|
||||
// 创建多个场景
|
||||
this.menuScene = this.createScene('menu', new MenuScene());
|
||||
this.gameScene = this.createScene('game', new GameScene());
|
||||
this.gameOverScene = this.createScene('gameover', new GameOverScene());
|
||||
|
||||
// 设置初始场景
|
||||
this.showMenu();
|
||||
}
|
||||
|
||||
public showMenu(): void {
|
||||
this.deactivateAllScenes();
|
||||
this.setSceneActive('menu', true);
|
||||
}
|
||||
|
||||
public startGame(): void {
|
||||
this.deactivateAllScenes();
|
||||
this.setSceneActive('game', true);
|
||||
}
|
||||
|
||||
public showGameOver(): void {
|
||||
this.deactivateAllScenes();
|
||||
this.setSceneActive('gameover', true);
|
||||
}
|
||||
|
||||
private deactivateAllScenes(): void {
|
||||
this.setSceneActive('menu', false);
|
||||
this.setSceneActive('game', false);
|
||||
this.setSceneActive('gameover', false);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 与 World 的关系
|
||||
|
||||
Scene 的运行架构层次：
|
||||
|
||||
```typescript
|
||||
// Core -> WorldManager -> World -> Scene -> EntitySystem -> Entity -> Component
|
||||
|
||||
// 1. 简单应用：Core直接管理单个Scene
|
||||
Core.setScene(new GameScene());
|
||||
|
||||
// 2. 复杂应用：WorldManager管理多个World，每个World管理多个Scene
|
||||
const worldManager = WorldManager.getInstance();
|
||||
const world = worldManager.createWorld('gameWorld');
|
||||
const scene = world.createScene('mainScene', new GameScene());
|
||||
world.setSceneActive('mainScene', true);
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 场景职责分离
|
||||
|
||||
```typescript
|
||||
// ✅ 好的场景设计 - 职责清晰
|
||||
class MenuScene extends Scene {
|
||||
// 只处理菜单相关逻辑
|
||||
}
|
||||
|
||||
class GameScene extends Scene {
|
||||
// 只处理游戏玩法逻辑
|
||||
}
|
||||
|
||||
class InventoryScene extends Scene {
|
||||
// 只处理物品栏逻辑
|
||||
}
|
||||
|
||||
// ❌ 避免的场景设计 - 职责混乱
|
||||
class MegaScene extends Scene {
|
||||
// 包含菜单、游戏、物品栏等所有逻辑
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 合理的系统组织
|
||||
|
||||
```typescript
|
||||
class OrganizedScene extends Scene {
|
||||
protected initialize(): void {
|
||||
// 按功能和依赖关系添加系统
|
||||
this.addInputSystems();
|
||||
this.addLogicSystems();
|
||||
this.addRenderSystems();
|
||||
}
|
||||
|
||||
private addInputSystems(): void {
|
||||
this.addSystem(new InputSystem());
|
||||
}
|
||||
|
||||
private addLogicSystems(): void {
|
||||
this.addSystem(new MovementSystem());
|
||||
this.addSystem(new PhysicsSystem());
|
||||
this.addSystem(new CollisionSystem());
|
||||
}
|
||||
|
||||
private addRenderSystems(): void {
|
||||
this.addSystem(new RenderSystem());
|
||||
this.addSystem(new UISystem());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 资源管理
|
||||
|
||||
```typescript
|
||||
class ResourceScene extends Scene {
|
||||
private textures: Map<string, any> = new Map();
|
||||
private sounds: Map<string, any> = new Map();
|
||||
|
||||
protected initialize(): void {
|
||||
this.loadResources();
|
||||
}
|
||||
|
||||
private loadResources(): void {
|
||||
// 加载场景所需资源
|
||||
}
|
||||
|
||||
public unload(): void {
|
||||
// 清理资源
|
||||
this.textures.clear();
|
||||
this.sounds.clear();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 事件处理规范
|
||||
|
||||
```typescript
|
||||
class EventHandlingScene extends Scene {
|
||||
protected initialize(): void {
|
||||
// 集中管理事件监听
|
||||
this.setupEventListeners();
|
||||
}
|
||||
|
||||
private setupEventListeners(): void {
|
||||
this.eventSystem.on('game_pause', this.onGamePause.bind(this));
|
||||
this.eventSystem.on('game_resume', this.onGameResume.bind(this));
|
||||
this.eventSystem.on('player_input', this.onPlayerInput.bind(this));
|
||||
}
|
||||
|
||||
private onGamePause(): void {
|
||||
// 暂停游戏逻辑
|
||||
this.systems.forEach(system => {
|
||||
if (system instanceof GameLogicSystem) {
|
||||
system.enabled = false;
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
private onGameResume(): void {
|
||||
// 恢复游戏逻辑
|
||||
this.systems.forEach(system => {
|
||||
if (system instanceof GameLogicSystem) {
|
||||
system.enabled = true;
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
private onPlayerInput(data: any): void {
|
||||
// 处理玩家输入
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
场景是 ECS 框架的核心容器，正确使用场景管理能让你的游戏架构更加清晰、模块化和易于维护。
|
||||
596
docs/guide/system.md
Normal file
596
docs/guide/system.md
Normal file
@@ -0,0 +1,596 @@
|
||||
# 系统架构
|
||||
|
||||
在 ECS 架构中，系统（System）是处理业务逻辑的地方。系统负责对拥有特定组件组合的实体执行操作，是 ECS 架构的逻辑处理单元。
|
||||
|
||||
## 基本概念
|
||||
|
||||
系统是继承自 `EntitySystem` 抽象基类的具体类，用于：
|
||||
- 定义实体的处理逻辑（如移动、碰撞检测、渲染等）
|
||||
- 根据组件组合筛选需要处理的实体
|
||||
- 提供生命周期管理和性能监控
|
||||
- 管理实体的添加、移除事件
|
||||
|
||||
## 系统类型
|
||||
|
||||
框架提供了几种不同类型的系统基类：
|
||||
|
||||
### EntitySystem - 基础系统
|
||||
|
||||
最基础的系统类，所有其他系统都继承自它：
|
||||
|
||||
```typescript
|
||||
import { EntitySystem, ECSSystem, Matcher } from '@esengine/ecs-framework';
|
||||
|
||||
@ECSSystem('Movement')
|
||||
class MovementSystem extends EntitySystem {
|
||||
constructor() {
|
||||
// 使用 Matcher 定义需要处理的实体条件
|
||||
super(Matcher.all(Position, Velocity));
|
||||
}
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
for (const entity of entities) {
|
||||
const position = entity.getComponent(Position);
|
||||
const velocity = entity.getComponent(Velocity);
|
||||
|
||||
if (position && velocity) {
|
||||
position.x += velocity.dx * Time.deltaTime;
|
||||
position.y += velocity.dy * Time.deltaTime;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### ProcessingSystem - 处理系统
|
||||
|
||||
适用于不需要逐个处理实体的系统：
|
||||
|
||||
```typescript
|
||||
@ECSSystem('Physics')
|
||||
class PhysicsSystem extends ProcessingSystem {
|
||||
constructor() {
|
||||
super(); // 不需要指定 Matcher
|
||||
}
|
||||
|
||||
public processSystem(): void {
|
||||
// 执行物理世界步进
|
||||
this.physicsWorld.step(Time.deltaTime);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### PassiveSystem - 被动系统
|
||||
|
||||
被动系统不进行主动处理，主要用于监听实体的添加和移除事件：
|
||||
|
||||
```typescript
|
||||
@ECSSystem('EntityTracker')
|
||||
class EntityTrackerSystem extends PassiveSystem {
|
||||
constructor() {
|
||||
super(Matcher.all(Health));
|
||||
}
|
||||
|
||||
protected onAdded(entity: Entity): void {
|
||||
console.log(`生命值实体被添加: ${entity.name}`);
|
||||
}
|
||||
|
||||
protected onRemoved(entity: Entity): void {
|
||||
console.log(`生命值实体被移除: ${entity.name}`);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### IntervalSystem - 间隔系统
|
||||
|
||||
按固定时间间隔执行的系统：
|
||||
|
||||
```typescript
|
||||
@ECSSystem('AutoSave')
|
||||
class AutoSaveSystem extends IntervalSystem {
|
||||
constructor() {
|
||||
// 每 5 秒执行一次
|
||||
super(5.0, Matcher.all(SaveData));
|
||||
}
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
console.log('执行自动保存...');
|
||||
// 保存游戏数据
|
||||
this.saveGameData(entities);
|
||||
}
|
||||
|
||||
private saveGameData(entities: readonly Entity[]): void {
|
||||
// 保存逻辑
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 实体匹配器 (Matcher)
|
||||
|
||||
Matcher 用于定义系统需要处理哪些实体。它提供了灵活的条件组合：
|
||||
|
||||
### 基本匹配条件
|
||||
|
||||
```typescript
|
||||
// 必须同时拥有 Position 和 Velocity 组件
|
||||
const matcher1 = Matcher.all(Position, Velocity);
|
||||
|
||||
// 至少拥有 Health 或 Shield 组件之一
|
||||
const matcher2 = Matcher.any(Health, Shield);
|
||||
|
||||
// 不能拥有 Dead 组件
|
||||
const matcher3 = Matcher.none(Dead);
|
||||
```
|
||||
|
||||
### 复合匹配条件
|
||||
|
||||
```typescript
|
||||
// 复杂的组合条件
|
||||
const complexMatcher = Matcher.all(Position, Velocity)
|
||||
.any(Player, Enemy)
|
||||
.none(Dead, Disabled);
|
||||
|
||||
@ECSSystem('Combat')
|
||||
class CombatSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super(complexMatcher);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 特殊匹配条件
|
||||
|
||||
```typescript
|
||||
// 按标签匹配
|
||||
const tagMatcher = Matcher.byTag(1); // 匹配标签为 1 的实体
|
||||
|
||||
// 按名称匹配
|
||||
const nameMatcher = Matcher.byName("Player"); // 匹配名称为 "Player" 的实体
|
||||
|
||||
// 单组件匹配
|
||||
const componentMatcher = Matcher.byComponent(Health); // 匹配拥有 Health 组件的实体
|
||||
```
|
||||
|
||||
## 系统生命周期
|
||||
|
||||
系统提供了完整的生命周期回调：
|
||||
|
||||
```typescript
|
||||
@ECSSystem('Example')
|
||||
class ExampleSystem extends EntitySystem {
|
||||
protected onInitialize(): void {
|
||||
console.log('系统初始化');
|
||||
// 系统被添加到场景时调用，用于初始化资源
|
||||
}
|
||||
|
||||
protected onBegin(): void {
|
||||
// 每帧处理开始前调用
|
||||
}
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
// 主要的处理逻辑
|
||||
for (const entity of entities) {
|
||||
// 处理每个实体
|
||||
}
|
||||
}
|
||||
|
||||
protected lateProcess(entities: readonly Entity[]): void {
|
||||
// 主处理之后的后期处理
|
||||
}
|
||||
|
||||
protected onEnd(): void {
|
||||
// 每帧处理结束后调用
|
||||
}
|
||||
|
||||
protected onDestroy(): void {
|
||||
console.log('系统销毁');
|
||||
// 系统从场景移除时调用，用于清理资源
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 实体事件监听
|
||||
|
||||
系统可以监听实体的添加和移除事件：
|
||||
|
||||
```typescript
|
||||
@ECSSystem('EnemyManager')
|
||||
class EnemyManagerSystem extends EntitySystem {
|
||||
private enemyCount = 0;
|
||||
|
||||
constructor() {
|
||||
super(Matcher.all(Enemy, Health));
|
||||
}
|
||||
|
||||
protected onAdded(entity: Entity): void {
|
||||
this.enemyCount++;
|
||||
console.log(`敌人加入战斗，当前敌人数量: ${this.enemyCount}`);
|
||||
|
||||
// 可以在这里为新敌人设置初始状态
|
||||
const health = entity.getComponent(Health);
|
||||
if (health) {
|
||||
health.current = health.max;
|
||||
}
|
||||
}
|
||||
|
||||
protected onRemoved(entity: Entity): void {
|
||||
this.enemyCount--;
|
||||
console.log(`敌人被移除，剩余敌人数量: ${this.enemyCount}`);
|
||||
|
||||
// 检查是否所有敌人都被消灭
|
||||
if (this.enemyCount === 0) {
|
||||
this.scene?.eventSystem.emitSync('all_enemies_defeated');
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 系统属性和方法
|
||||
|
||||
### 重要属性
|
||||
|
||||
```typescript
|
||||
@ECSSystem('Example')
|
||||
class ExampleSystem extends EntitySystem {
|
||||
showSystemInfo(): void {
|
||||
console.log(`系统名称: ${this.systemName}`); // 系统名称
|
||||
console.log(`更新顺序: ${this.updateOrder}`); // 更新时序
|
||||
console.log(`是否启用: ${this.enabled}`); // 启用状态
|
||||
console.log(`实体数量: ${this.entities.length}`); // 匹配的实体数量
|
||||
console.log(`所属场景: ${this.scene?.name}`); // 所属场景
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 实体访问
|
||||
|
||||
```typescript
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
// 方式1：使用参数中的实体列表
|
||||
for (const entity of entities) {
|
||||
// 处理实体
|
||||
}
|
||||
|
||||
// 方式2：使用 this.entities 属性（与参数相同）
|
||||
for (const entity of this.entities) {
|
||||
// 处理实体
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 控制系统执行
|
||||
|
||||
```typescript
|
||||
@ECSSystem('Conditional')
|
||||
class ConditionalSystem extends EntitySystem {
|
||||
private shouldProcess = true;
|
||||
|
||||
protected onCheckProcessing(): boolean {
|
||||
// 返回 false 时跳过本次处理
|
||||
return this.shouldProcess && this.entities.length > 0;
|
||||
}
|
||||
|
||||
public pause(): void {
|
||||
this.shouldProcess = false;
|
||||
}
|
||||
|
||||
public resume(): void {
|
||||
this.shouldProcess = true;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 事件系统集成
|
||||
|
||||
系统可以方便地监听和发送事件：
|
||||
|
||||
```typescript
|
||||
@ECSSystem('GameLogic')
|
||||
class GameLogicSystem extends EntitySystem {
|
||||
protected onInitialize(): void {
|
||||
// 添加事件监听器（系统销毁时自动清理）
|
||||
this.addEventListener('player_died', this.onPlayerDied.bind(this));
|
||||
this.addEventListener('level_complete', this.onLevelComplete.bind(this));
|
||||
}
|
||||
|
||||
private onPlayerDied(data: any): void {
|
||||
console.log('玩家死亡，重新开始游戏');
|
||||
// 处理玩家死亡逻辑
|
||||
}
|
||||
|
||||
private onLevelComplete(data: any): void {
|
||||
console.log('关卡完成，加载下一关');
|
||||
// 处理关卡完成逻辑
|
||||
}
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
// 在处理过程中发送事件
|
||||
for (const entity of entities) {
|
||||
const health = entity.getComponent(Health);
|
||||
if (health && health.current <= 0) {
|
||||
this.scene?.eventSystem.emitSync('entity_died', { entity });
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 性能监控
|
||||
|
||||
系统内置了性能监控功能：
|
||||
|
||||
```typescript
|
||||
@ECSSystem('Performance')
|
||||
class PerformanceSystem extends EntitySystem {
|
||||
protected onEnd(): void {
|
||||
// 获取性能数据
|
||||
const perfData = this.getPerformanceData();
|
||||
if (perfData) {
|
||||
console.log(`执行时间: ${perfData.executionTime.toFixed(2)}ms`);
|
||||
}
|
||||
|
||||
// 获取性能统计
|
||||
const stats = this.getPerformanceStats();
|
||||
if (stats) {
|
||||
console.log(`平均执行时间: ${stats.averageTime.toFixed(2)}ms`);
|
||||
}
|
||||
}
|
||||
|
||||
public resetPerformance(): void {
|
||||
this.resetPerformanceData();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 系统管理
|
||||
|
||||
### 添加系统到场景
|
||||
|
||||
```typescript
|
||||
// 在场景子类中添加系统
|
||||
class GameScene extends Scene {
|
||||
protected initialize(): void {
|
||||
// 添加系统
|
||||
this.addSystem(new MovementSystem());
|
||||
this.addSystem(new RenderSystem());
|
||||
this.addSystem(new PhysicsSystem());
|
||||
|
||||
// 设置系统更新顺序
|
||||
const movementSystem = this.getSystem(MovementSystem);
|
||||
if (movementSystem) {
|
||||
movementSystem.updateOrder = 1;
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 系统更新顺序
|
||||
|
||||
```typescript
|
||||
@ECSSystem('Input')
|
||||
class InputSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super(Matcher.all(InputComponent));
|
||||
this.updateOrder = -100; // 输入系统优先执行
|
||||
}
|
||||
}
|
||||
|
||||
@ECSSystem('Physics')
|
||||
class PhysicsSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super(Matcher.all(RigidBody));
|
||||
this.updateOrder = 0; // 默认顺序
|
||||
}
|
||||
}
|
||||
|
||||
@ECSSystem('Render')
|
||||
class RenderSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super(Matcher.all(Sprite, Transform));
|
||||
this.updateOrder = 100; // 渲染系统最后执行
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 复杂系统示例
|
||||
|
||||
### 碰撞检测系统
|
||||
|
||||
```typescript
|
||||
@ECSSystem('Collision')
|
||||
class CollisionSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super(Matcher.all(Transform, Collider));
|
||||
}
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
// 简单的 n² 碰撞检测
|
||||
for (let i = 0; i < entities.length; i++) {
|
||||
for (let j = i + 1; j < entities.length; j++) {
|
||||
this.checkCollision(entities[i], entities[j]);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private checkCollision(entityA: Entity, entityB: Entity): void {
|
||||
const transformA = entityA.getComponent(Transform);
|
||||
const transformB = entityB.getComponent(Transform);
|
||||
const colliderA = entityA.getComponent(Collider);
|
||||
const colliderB = entityB.getComponent(Collider);
|
||||
|
||||
if (this.isColliding(transformA, colliderA, transformB, colliderB)) {
|
||||
// 发送碰撞事件
|
||||
this.scene?.eventSystem.emitSync('collision', {
|
||||
entityA,
|
||||
entityB
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
private isColliding(transformA: Transform, colliderA: Collider,
|
||||
transformB: Transform, colliderB: Collider): boolean {
|
||||
// 碰撞检测逻辑
|
||||
return false; // 简化示例
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 状态机系统
|
||||
|
||||
```typescript
|
||||
@ECSSystem('StateMachine')
|
||||
class StateMachineSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super(Matcher.all(StateMachine));
|
||||
}
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
for (const entity of entities) {
|
||||
const stateMachine = entity.getComponent(StateMachine);
|
||||
if (stateMachine) {
|
||||
stateMachine.updateTimer(Time.deltaTime);
|
||||
this.updateState(entity, stateMachine);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private updateState(entity: Entity, stateMachine: StateMachine): void {
|
||||
switch (stateMachine.currentState) {
|
||||
case EntityState.Idle:
|
||||
this.handleIdleState(entity, stateMachine);
|
||||
break;
|
||||
case EntityState.Moving:
|
||||
this.handleMovingState(entity, stateMachine);
|
||||
break;
|
||||
case EntityState.Attacking:
|
||||
this.handleAttackingState(entity, stateMachine);
|
||||
break;
|
||||
}
|
||||
}
|
||||
|
||||
private handleIdleState(entity: Entity, stateMachine: StateMachine): void {
|
||||
// 空闲状态逻辑
|
||||
}
|
||||
|
||||
private handleMovingState(entity: Entity, stateMachine: StateMachine): void {
|
||||
// 移动状态逻辑
|
||||
}
|
||||
|
||||
private handleAttackingState(entity: Entity, stateMachine: StateMachine): void {
|
||||
// 攻击状态逻辑
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 系统单一职责
|
||||
|
||||
```typescript
|
||||
// ✅ 好的系统设计 - 职责单一
|
||||
@ECSSystem('Movement')
|
||||
class MovementSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super(Matcher.all(Position, Velocity));
|
||||
}
|
||||
}
|
||||
|
||||
@ECSSystem('Rendering')
|
||||
class RenderingSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super(Matcher.all(Sprite, Transform));
|
||||
}
|
||||
}
|
||||
|
||||
// ❌ 避免的系统设计 - 职责过多
|
||||
@ECSSystem('GameSystem')
|
||||
class GameSystem extends EntitySystem {
|
||||
// 一个系统处理移动、渲染、音效等多种逻辑
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 使用装饰器
|
||||
|
||||
**必须使用 `@ECSSystem` 装饰器**：
|
||||
|
||||
```typescript
|
||||
// ✅ 正确的用法
|
||||
@ECSSystem('Physics')
|
||||
class PhysicsSystem extends EntitySystem {
|
||||
// 系统实现
|
||||
}
|
||||
|
||||
// ❌ 错误的用法 - 没有装饰器
|
||||
class BadSystem extends EntitySystem {
|
||||
// 这样定义的系统可能在生产环境出现问题
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 合理的更新顺序
|
||||
|
||||
```typescript
|
||||
// 按逻辑顺序设置系统的更新时序
|
||||
@ECSSystem('Input')
|
||||
class InputSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super();
|
||||
this.updateOrder = -100; // 最先处理输入
|
||||
}
|
||||
}
|
||||
|
||||
@ECSSystem('Logic')
|
||||
class GameLogicSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super();
|
||||
this.updateOrder = 0; // 处理游戏逻辑
|
||||
}
|
||||
}
|
||||
|
||||
@ECSSystem('Render')
|
||||
class RenderSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super();
|
||||
this.updateOrder = 100; // 最后进行渲染
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 避免在系统间直接引用
|
||||
|
||||
```typescript
|
||||
// ❌ 避免：系统间直接引用
|
||||
@ECSSystem('Bad')
|
||||
class BadSystem extends EntitySystem {
|
||||
private otherSystem: SomeOtherSystem; // 避免直接引用其他系统
|
||||
}
|
||||
|
||||
// ✅ 推荐：通过事件系统通信
|
||||
@ECSSystem('Good')
|
||||
class GoodSystem extends EntitySystem {
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
// 通过事件系统与其他系统通信
|
||||
this.scene?.eventSystem.emitSync('data_updated', { entities });
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 及时清理资源
|
||||
|
||||
```typescript
|
||||
@ECSSystem('Resource')
|
||||
class ResourceSystem extends EntitySystem {
|
||||
private resources: Map<string, any> = new Map();
|
||||
|
||||
protected onDestroy(): void {
|
||||
// 清理资源
|
||||
for (const [key, resource] of this.resources) {
|
||||
if (resource.dispose) {
|
||||
resource.dispose();
|
||||
}
|
||||
}
|
||||
this.resources.clear();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
系统是 ECS 架构的逻辑处理核心，正确设计和使用系统能让你的游戏代码更加模块化、高效和易于维护。
|
||||
553
docs/guide/time-and-timers.md
Normal file
553
docs/guide/time-and-timers.md
Normal file
@@ -0,0 +1,553 @@
|
||||
# 时间和定时器系统
|
||||
|
||||
ECS 框架提供了完整的时间管理和定时器系统，包括时间缩放、帧时间计算和灵活的定时器调度功能。
|
||||
|
||||
## Time 类
|
||||
|
||||
Time 类是框架的时间管理核心，提供了游戏时间相关的所有功能。
|
||||
|
||||
### 基本时间属性
|
||||
|
||||
```typescript
|
||||
import { Time } from '@esengine/ecs-framework';
|
||||
|
||||
class GameSystem extends EntitySystem {
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
// 获取帧时间（秒）
|
||||
const deltaTime = Time.deltaTime;
|
||||
|
||||
// 获取未缩放的帧时间
|
||||
const unscaledDelta = Time.unscaledDeltaTime;
|
||||
|
||||
// 获取游戏总时间
|
||||
const totalTime = Time.totalTime;
|
||||
|
||||
// 获取当前帧数
|
||||
const frameCount = Time.frameCount;
|
||||
|
||||
console.log(`第 ${frameCount} 帧，帧时间: ${deltaTime}s，总时间: ${totalTime}s`);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 时间缩放
|
||||
|
||||
Time 类支持时间缩放功能，可以实现慢动作、快进等效果：
|
||||
|
||||
```typescript
|
||||
class TimeControlSystem extends EntitySystem {
|
||||
public enableSlowMotion(): void {
|
||||
// 设置为慢动作（50%速度）
|
||||
Time.timeScale = 0.5;
|
||||
console.log('慢动作模式启用');
|
||||
}
|
||||
|
||||
public enableFastForward(): void {
|
||||
// 设置为快进（200%速度）
|
||||
Time.timeScale = 2.0;
|
||||
console.log('快进模式启用');
|
||||
}
|
||||
|
||||
public pauseGame(): void {
|
||||
// 暂停游戏（时间静止）
|
||||
Time.timeScale = 0;
|
||||
console.log('游戏暂停');
|
||||
}
|
||||
|
||||
public resumeNormalSpeed(): void {
|
||||
// 恢复正常速度
|
||||
Time.timeScale = 1.0;
|
||||
console.log('恢复正常速度');
|
||||
}
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
// deltaTime 会受到 timeScale 影响
|
||||
const scaledDelta = Time.deltaTime; // 受时间缩放影响
|
||||
const realDelta = Time.unscaledDeltaTime; // 不受时间缩放影响
|
||||
|
||||
for (const entity of entities) {
|
||||
const movement = entity.getComponent(Movement);
|
||||
if (movement) {
|
||||
// 使用缩放时间进行游戏逻辑更新
|
||||
movement.update(scaledDelta);
|
||||
}
|
||||
|
||||
const ui = entity.getComponent(UIComponent);
|
||||
if (ui) {
|
||||
// UI 动画使用真实时间，不受游戏时间缩放影响
|
||||
ui.update(realDelta);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 时间检查工具
|
||||
|
||||
```typescript
|
||||
class CooldownSystem extends EntitySystem {
|
||||
private lastAttackTime = 0;
|
||||
private lastSpawnTime = 0;
|
||||
|
||||
constructor() {
|
||||
super(Matcher.all(Weapon));
|
||||
}
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
// 检查攻击冷却
|
||||
if (Time.checkEvery(1.5, this.lastAttackTime)) {
|
||||
this.performAttack();
|
||||
this.lastAttackTime = Time.totalTime;
|
||||
}
|
||||
|
||||
// 检查生成间隔
|
||||
if (Time.checkEvery(3.0, this.lastSpawnTime)) {
|
||||
this.spawnEnemy();
|
||||
this.lastSpawnTime = Time.totalTime;
|
||||
}
|
||||
}
|
||||
|
||||
private performAttack(): void {
|
||||
console.log('执行攻击！');
|
||||
}
|
||||
|
||||
private spawnEnemy(): void {
|
||||
console.log('生成敌人！');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Core.schedule 定时器系统
|
||||
|
||||
Core 提供了强大的定时器调度功能，可以创建一次性或重复执行的定时器。
|
||||
|
||||
### 基本定时器使用
|
||||
|
||||
```typescript
|
||||
import { Core } from '@esengine/ecs-framework';
|
||||
|
||||
class GameScene extends Scene {
|
||||
protected initialize(): void {
|
||||
// 创建一次性定时器
|
||||
this.createOneTimeTimers();
|
||||
|
||||
// 创建重复定时器
|
||||
this.createRepeatingTimers();
|
||||
|
||||
// 创建带上下文的定时器
|
||||
this.createContextTimers();
|
||||
}
|
||||
|
||||
private createOneTimeTimers(): void {
|
||||
// 2秒后执行一次
|
||||
Core.schedule(2.0, false, null, (timer) => {
|
||||
console.log('2秒延迟执行');
|
||||
});
|
||||
|
||||
// 5秒后显示提示
|
||||
Core.schedule(5.0, false, this, (timer) => {
|
||||
const scene = timer.getContext<GameScene>();
|
||||
scene.showTip('游戏提示：5秒已过！');
|
||||
});
|
||||
}
|
||||
|
||||
private createRepeatingTimers(): void {
|
||||
// 每秒重复执行
|
||||
const heartbeatTimer = Core.schedule(1.0, true, null, (timer) => {
|
||||
console.log(`游戏心跳 - 总时间: ${Time.totalTime.toFixed(1)}s`);
|
||||
});
|
||||
|
||||
// 可以保存定时器引用用于后续控制
|
||||
this.saveTimerReference(heartbeatTimer);
|
||||
}
|
||||
|
||||
private createContextTimers(): void {
|
||||
const gameData = { score: 0, level: 1 };
|
||||
|
||||
// 每2秒增加分数
|
||||
Core.schedule(2.0, true, gameData, (timer) => {
|
||||
const data = timer.getContext<typeof gameData>();
|
||||
data.score += 10;
|
||||
console.log(`分数增加！当前分数: ${data.score}`);
|
||||
});
|
||||
}
|
||||
|
||||
private saveTimerReference(timer: any): void {
|
||||
// 可以稍后停止定时器
|
||||
setTimeout(() => {
|
||||
timer.stop();
|
||||
console.log('定时器已停止');
|
||||
}, 10000); // 10秒后停止
|
||||
}
|
||||
|
||||
private showTip(message: string): void {
|
||||
console.log('提示:', message);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 定时器控制
|
||||
|
||||
```typescript
|
||||
class TimerControlExample {
|
||||
private attackTimer: any;
|
||||
private spawnerTimer: any;
|
||||
|
||||
public startCombat(): void {
|
||||
// 启动攻击定时器
|
||||
this.attackTimer = Core.schedule(0.5, true, this, (timer) => {
|
||||
const self = timer.getContext<TimerControlExample>();
|
||||
self.performAttack();
|
||||
});
|
||||
|
||||
// 启动敌人生成定时器
|
||||
this.spawnerTimer = Core.schedule(3.0, true, null, (timer) => {
|
||||
this.spawnEnemy();
|
||||
});
|
||||
}
|
||||
|
||||
public stopCombat(): void {
|
||||
// 停止所有战斗相关定时器
|
||||
if (this.attackTimer) {
|
||||
this.attackTimer.stop();
|
||||
console.log('攻击定时器已停止');
|
||||
}
|
||||
|
||||
if (this.spawnerTimer) {
|
||||
this.spawnerTimer.stop();
|
||||
console.log('生成定时器已停止');
|
||||
}
|
||||
}
|
||||
|
||||
public resetAttackTimer(): void {
|
||||
// 重置攻击定时器
|
||||
if (this.attackTimer) {
|
||||
this.attackTimer.reset();
|
||||
console.log('攻击定时器已重置');
|
||||
}
|
||||
}
|
||||
|
||||
private performAttack(): void {
|
||||
console.log('执行攻击');
|
||||
}
|
||||
|
||||
private spawnEnemy(): void {
|
||||
console.log('生成敌人');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 复杂定时器场景
|
||||
|
||||
```typescript
|
||||
class AdvancedTimerUsage {
|
||||
private powerUpDuration = 0;
|
||||
private powerUpActive = false;
|
||||
|
||||
public activatePowerUp(): void {
|
||||
if (this.powerUpActive) {
|
||||
console.log('能力提升已激活');
|
||||
return;
|
||||
}
|
||||
|
||||
this.powerUpActive = true;
|
||||
this.powerUpDuration = 10; // 10秒持续时间
|
||||
|
||||
console.log('能力提升激活！');
|
||||
|
||||
// 每秒更新剩余时间
|
||||
const countdownTimer = Core.schedule(1.0, true, this, (timer) => {
|
||||
const self = timer.getContext<AdvancedTimerUsage>();
|
||||
self.powerUpDuration--;
|
||||
|
||||
console.log(`能力提升剩余时间: ${self.powerUpDuration}秒`);
|
||||
|
||||
if (self.powerUpDuration <= 0) {
|
||||
self.deactivatePowerUp();
|
||||
timer.stop(); // 停止倒计时
|
||||
}
|
||||
});
|
||||
|
||||
// 能力提升结束定时器（备用）
|
||||
Core.schedule(10.0, false, this, (timer) => {
|
||||
const self = timer.getContext<AdvancedTimerUsage>();
|
||||
if (self.powerUpActive) {
|
||||
self.deactivatePowerUp();
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
private deactivatePowerUp(): void {
|
||||
this.powerUpActive = false;
|
||||
this.powerUpDuration = 0;
|
||||
console.log('能力提升结束');
|
||||
}
|
||||
|
||||
// 创建波次攻击定时器
|
||||
public startWaveAttack(): void {
|
||||
let waveCount = 0;
|
||||
const maxWaves = 5;
|
||||
|
||||
const waveTimer = Core.schedule(2.0, true, { waveCount, maxWaves }, (timer) => {
|
||||
const context = timer.getContext<{ waveCount: number, maxWaves: number }>();
|
||||
context.waveCount++;
|
||||
|
||||
console.log(`第 ${context.waveCount} 波攻击！`);
|
||||
|
||||
if (context.waveCount >= context.maxWaves) {
|
||||
console.log('所有波次攻击完成');
|
||||
timer.stop();
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
// 创建条件定时器
|
||||
public startConditionalTimer(): void {
|
||||
Core.schedule(0.1, true, this, (timer) => {
|
||||
const self = timer.getContext<AdvancedTimerUsage>();
|
||||
|
||||
// 检查某个条件
|
||||
if (self.shouldStopTimer()) {
|
||||
console.log('条件满足，停止定时器');
|
||||
timer.stop();
|
||||
return;
|
||||
}
|
||||
|
||||
// 继续执行定时器逻辑
|
||||
self.performTimerAction();
|
||||
});
|
||||
}
|
||||
|
||||
private shouldStopTimer(): boolean {
|
||||
// 检查停止条件
|
||||
return Time.totalTime > 30; // 30秒后停止
|
||||
}
|
||||
|
||||
private performTimerAction(): void {
|
||||
console.log('执行定时器动作');
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 实际应用示例
|
||||
|
||||
### 技能冷却系统
|
||||
|
||||
```typescript
|
||||
class SkillCooldownSystem extends EntitySystem {
|
||||
constructor() {
|
||||
super(Matcher.all(SkillComponent));
|
||||
}
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
for (const entity of entities) {
|
||||
const skill = entity.getComponent(SkillComponent);
|
||||
|
||||
// 更新技能冷却
|
||||
if (skill.isOnCooldown) {
|
||||
skill.cooldownRemaining -= Time.deltaTime;
|
||||
|
||||
if (skill.cooldownRemaining <= 0) {
|
||||
skill.cooldownRemaining = 0;
|
||||
skill.isOnCooldown = false;
|
||||
console.log(`技能 ${skill.name} 冷却完成`);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
public useSkill(entity: Entity, skillName: string): boolean {
|
||||
const skill = entity.getComponent(SkillComponent);
|
||||
|
||||
if (skill.isOnCooldown) {
|
||||
console.log(`技能 ${skillName} 还在冷却中，剩余 ${skill.cooldownRemaining.toFixed(1)}秒`);
|
||||
return false;
|
||||
}
|
||||
|
||||
// 执行技能
|
||||
this.executeSkill(entity, skill);
|
||||
|
||||
// 开始冷却
|
||||
skill.isOnCooldown = true;
|
||||
skill.cooldownRemaining = skill.cooldownDuration;
|
||||
|
||||
return true;
|
||||
}
|
||||
|
||||
private executeSkill(entity: Entity, skill: SkillComponent): void {
|
||||
console.log(`执行技能: ${skill.name}`);
|
||||
// 技能效果逻辑
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 游戏状态定时器
|
||||
|
||||
```typescript
|
||||
class GameStateManager {
|
||||
private gamePhase = 'preparation';
|
||||
private phaseTimer: any;
|
||||
|
||||
public startGame(): void {
|
||||
this.startPreparationPhase();
|
||||
}
|
||||
|
||||
private startPreparationPhase(): void {
|
||||
this.gamePhase = 'preparation';
|
||||
console.log('准备阶段开始 - 10秒准备时间');
|
||||
|
||||
this.phaseTimer = Core.schedule(10.0, false, this, (timer) => {
|
||||
const self = timer.getContext<GameStateManager>();
|
||||
self.startCombatPhase();
|
||||
});
|
||||
}
|
||||
|
||||
private startCombatPhase(): void {
|
||||
this.gamePhase = 'combat';
|
||||
console.log('战斗阶段开始 - 60秒战斗时间');
|
||||
|
||||
this.phaseTimer = Core.schedule(60.0, false, this, (timer) => {
|
||||
const self = timer.getContext<GameStateManager>();
|
||||
self.startResultPhase();
|
||||
});
|
||||
|
||||
// 每10秒刷新一波敌人
|
||||
Core.schedule(10.0, true, null, (timer) => {
|
||||
if (this.gamePhase === 'combat') {
|
||||
this.spawnEnemyWave();
|
||||
} else {
|
||||
timer.stop(); // 战斗阶段结束时停止刷新
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
private startResultPhase(): void {
|
||||
this.gamePhase = 'result';
|
||||
console.log('结算阶段开始 - 5秒结算时间');
|
||||
|
||||
this.phaseTimer = Core.schedule(5.0, false, this, (timer) => {
|
||||
const self = timer.getContext<GameStateManager>();
|
||||
self.endGame();
|
||||
});
|
||||
}
|
||||
|
||||
private endGame(): void {
|
||||
console.log('游戏结束');
|
||||
this.gamePhase = 'ended';
|
||||
}
|
||||
|
||||
private spawnEnemyWave(): void {
|
||||
console.log('刷新敌人波次');
|
||||
}
|
||||
|
||||
public getCurrentPhase(): string {
|
||||
return this.gamePhase;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 合理使用时间类型
|
||||
|
||||
```typescript
|
||||
class MovementSystem extends EntitySystem {
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
for (const entity of entities) {
|
||||
const movement = entity.getComponent(Movement);
|
||||
|
||||
// ✅ 游戏逻辑使用缩放时间
|
||||
movement.position.x += movement.velocity.x * Time.deltaTime;
|
||||
|
||||
// ✅ UI动画使用真实时间（不受游戏暂停影响）
|
||||
const ui = entity.getComponent(UIAnimation);
|
||||
if (ui) {
|
||||
ui.update(Time.unscaledDeltaTime);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 定时器管理
|
||||
|
||||
```typescript
|
||||
class TimerManager {
|
||||
private timers: any[] = [];
|
||||
|
||||
public createManagedTimer(duration: number, repeats: boolean, callback: () => void): any {
|
||||
const timer = Core.schedule(duration, repeats, null, callback);
|
||||
this.timers.push(timer);
|
||||
return timer;
|
||||
}
|
||||
|
||||
public stopAllTimers(): void {
|
||||
for (const timer of this.timers) {
|
||||
timer.stop();
|
||||
}
|
||||
this.timers = [];
|
||||
}
|
||||
|
||||
public cleanupCompletedTimers(): void {
|
||||
this.timers = this.timers.filter(timer => !timer.isDone);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 避免过多的定时器
|
||||
|
||||
```typescript
|
||||
// ❌ 避免：为每个实体创建定时器
|
||||
class BadExample extends EntitySystem {
|
||||
protected onAdded(entity: Entity): void {
|
||||
Core.schedule(1.0, true, entity, (timer) => {
|
||||
// 每个实体一个定时器，性能差
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
// ✅ 推荐：在系统中统一管理时间
|
||||
class GoodExample extends EntitySystem {
|
||||
private lastUpdateTime = 0;
|
||||
|
||||
protected process(entities: readonly Entity[]): void {
|
||||
// 每秒执行一次逻辑
|
||||
if (Time.checkEvery(1.0, this.lastUpdateTime)) {
|
||||
this.processAllEntities(entities);
|
||||
this.lastUpdateTime = Time.totalTime;
|
||||
}
|
||||
}
|
||||
|
||||
private processAllEntities(entities: readonly Entity[]): void {
|
||||
// 批量处理所有实体
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 定时器上下文使用
|
||||
|
||||
```typescript
|
||||
interface TimerContext {
|
||||
entityId: number;
|
||||
duration: number;
|
||||
onComplete: () => void;
|
||||
}
|
||||
|
||||
class ContextualTimerExample {
|
||||
public createEntityTimer(entityId: number, duration: number, onComplete: () => void): void {
|
||||
const context: TimerContext = {
|
||||
entityId,
|
||||
duration,
|
||||
onComplete
|
||||
};
|
||||
|
||||
Core.schedule(duration, false, context, (timer) => {
|
||||
const ctx = timer.getContext<TimerContext>();
|
||||
console.log(`实体 ${ctx.entityId} 的定时器完成`);
|
||||
ctx.onComplete();
|
||||
});
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
时间和定时器系统是游戏开发中的重要工具，正确使用这些功能能让你的游戏逻辑更加精确和可控。
|
||||
Reference in New Issue
Block a user