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

更新文档及优化行为树编辑器

Browse Source
This commit is contained in:
YHH
2025-06-19 10:38:31 +08:00
parent 82cd163adc
commit 8c86d6b696
20 changed files with 1608 additions and 286 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
docs/component-design-guide.md
View File

@@ -387,16 +387,12 @@ class HealthComponent extends Component {
this.currentHealth -= damage;
// 发送事件，让其他系统响应
Core.emitter.emit('health:damaged', {
entity: this.entity,
damage: damage,
remainingHealth: this.currentHealth
});
// 注意：需要在实际使用中获取EntityManager实例
// 示例：entityManager.eventBus.emit('health:damaged', {...});
if (this.currentHealth <= 0) {
Core.emitter.emit('health:died', {
entity: this.entity
});
// 示例：entityManager.eventBus.emit('health:died', {...});
console.log('实体死亡');
}
}
}
@@ -406,12 +402,13 @@ class AnimationComponent extends Component {
onAddedToEntity() {
super.onAddedToEntity();
// 监听受伤事件
Core.emitter.addObserver('health:damaged', this.onDamaged, this);
// 监听受伤事件（需要在实际使用中获取EntityManager实例）
// 示例：entityManager.eventBus.on('health:damaged', this.onDamaged, { context: this });
}
onRemovedFromEntity() {
Core.emitter.removeObserver('health:damaged', this.onDamaged, this);
// 事件监听会在组件移除时自动清理
// 如需手动清理，保存listenerId并调用eventBus.off()
super.onRemovedFromEntity();
}

58
docs/core-concepts.md
View File

@@ -19,28 +19,64 @@ Core 是框架的核心管理类，负责游戏的生命周期管理。
### 创建和配置
```typescript
import { Core } from '@esengine/ecs-framework';
import { Core, ICoreConfig } from '@esengine/ecs-framework';
// 创建核心实例（调试模式）
const core = Core.create(true);
// 创建核心实例（使用配置对象 - 推荐）
const config: ICoreConfig = {
debug: true, // 启用调试模式
enableEntitySystems: true, // 启用实体系统
debugConfig: { // 可选：远程调试配置
enabled: true,
websocketUrl: 'ws://localhost:8080',
autoReconnect: true,
updateInterval: 1000,
channels: {
entities: true,
systems: true,
performance: true,
components: true,
scenes: true
}
}
};
const core = Core.create(config);
// 创建核心实例（发布模式）
const core = Core.create(false);
// 简化创建（向后兼容）
const core1 = Core.create(true); // 调试模式
const core2 = Core.create(false); // 发布模式
const core3 = Core.create(); // 默认调试模式
```
### 事件系统
```typescript
import { CoreEvents } from '@esengine/ecs-framework';
import { EntityManager, ECSEventType } from '@esengine/ecs-framework';
// 监听核心事件
Core.emitter.addObserver(CoreEvents.frameUpdated, this.onUpdate, this);
// 获取EntityManager的事件系统
const entityManager = new EntityManager();
const eventBus = entityManager.eventBus;
// 发送帧更新事件
Core.emitter.emit(CoreEvents.frameUpdated);
// 监听实体事件
eventBus.onEntityCreated((data) => {
console.log(`实体创建: ${data.entityName}`);
});
eventBus.onComponentAdded((data) => {
console.log(`组件添加: ${data.componentType}`);
});
// 发送自定义事件
Core.emitter.emit("customEvent", { data: "value" });
eventBus.emit("customEvent", { data: "value" });
// 使用事件装饰器（推荐）
import { EventHandler } from '@esengine/ecs-framework';
class GameSystem {
@EventHandler('entity:died')
onEntityDied(data: any) {
console.log('实体死亡:', data);
}
}
```
### 定时器系统

167
docs/getting-started.md
View File

@@ -29,6 +29,145 @@ Core.update(deltaTime);
- 更精确的时间控制
- 统一的API，简化集成
## Core配置
### 基础配置
ECS框架提供了灵活的配置选项来满足不同项目需求：
```typescript
import { Core, ICoreConfig } from '@esengine/ecs-framework';
// 方式1：简化配置（向后兼容）
Core.create(true); // 启用调试模式
Core.create(false); // 发布模式
Core.create(); // 默认调试模式
// 方式2：详细配置（推荐）
const config: ICoreConfig = {
debug: true, // 启用调试模式
enableEntitySystems: true, // 启用实体系统（默认true）
debugConfig: { // 可选：远程调试配置
enabled: true,
websocketUrl: 'ws://localhost:8080',
autoReconnect: true,
updateInterval: 1000, // 调试数据更新间隔（毫秒）
channels: { // 调试数据通道
entities: true, // 实体信息
systems: true, // 系统信息
performance: true, // 性能数据
components: true, // 组件信息
scenes: true // 场景信息
}
}
};
const core = Core.create(config);
```
### 调试功能
ECS框架内置了强大的调试功能，支持运行时监控和远程调试：
#### Cocos Creator专用调试插件
**🎯 对于Cocos Creator用户，我们提供了专门的可视化调试插件：**
- **插件地址**：[cocos-ecs-framework 调试插件](https://store.cocos.com/app/detail/7823)
- **插件版本**：v1.0.0
- **支持版本**：Cocos Creator v3.0.0+
- **支持平台**：Android | iOS | HTML5
这个插件提供了完整的ECS可视化调试界面，包括实体查看器、组件编辑器、系统监控、性能分析等功能。
#### 通用调试配置
```typescript
// 运行时启用调试
Core.enableDebug({
enabled: true,
websocketUrl: 'ws://localhost:8080',
autoReconnect: true,
updateInterval: 500,
channels: {
entities: true,
systems: true,
performance: true,
components: false, // 可以选择性禁用某些通道
scenes: true
}
});
// 获取调试数据
const debugData = Core.getDebugData();
console.log('当前实体数量:', debugData?.entities?.totalEntities);
// 禁用调试
Core.disableDebug();
// 检查调试状态
if (Core.isDebugEnabled) {
console.log('调试模式已启用');
}
```
### 生产环境配置建议
```typescript
// 开发环境 - Cocos Creator
const devConfigForCocos: ICoreConfig = {
debug: true,
enableEntitySystems: true,
debugConfig: {
enabled: true,
websocketUrl: 'ws://localhost:8080', // 连接Cocos插件
autoReconnect: true,
updateInterval: 1000,
channels: {
entities: true,
systems: true,
performance: true,
components: true,
scenes: true
}
}
};
// 开发环境 - 其他平台
const devConfig: ICoreConfig = {
debug: true,
enableEntitySystems: true,
debugConfig: {
enabled: true,
websocketUrl: 'ws://localhost:8080',
autoReconnect: true,
updateInterval: 1000,
channels: {
entities: true,
systems: true,
performance: true,
components: true,
scenes: true
}
}
};
// 生产环境
const prodConfig: ICoreConfig = {
debug: false, // 关闭调试以提升性能
enableEntitySystems: true,
// debugConfig 可以省略或设为 undefined
};
const isDevelopment = process.env.NODE_ENV === 'development';
Core.create(isDevelopment ? devConfig : prodConfig);
```
**💡 调试功能说明：**
- **Cocos Creator**：推荐使用[官方调试插件](https://store.cocos.com/app/detail/7823)获得最佳调试体验
- **其他平台**：可以通过WebSocket连接自定义调试工具
- **生产环境**：建议关闭调试功能以获得最佳性能
## 平台集成
### Laya引擎
@@ -44,8 +183,10 @@ class LayaECSGame extends LayaScene {
constructor() {
super();
// 初始化ECS框架
Core.create(true);
// 初始化ECS框架（简化方式）
Core.create(true); // 启用调试模式
// 完整配置示例: Core.create({ debug: true, enableEntitySystems: true, debugConfig: {...} })
this.ecsScene = new ECSScene();
this.ecsScene.name = "LayaGameScene";
Core.scene = this.ecsScene;
@@ -117,8 +258,10 @@ export class ECSGameManager extends CocosComponent {
private entityManager: EntityManager;
start() {
// 初始化ECS框架
Core.create(true);
// 初始化ECS框架（简化方式）
Core.create(true); // 启用调试模式
// 完整配置示例: Core.create({ debug: true, enableEntitySystems: true, debugConfig: {...} })
this.ecsScene = new ECSScene();
this.ecsScene.name = "CocosGameScene";
Core.scene = this.ecsScene;
@@ -172,6 +315,12 @@ class CocosRenderSystem extends EntitySystem {
// 将ECSGameManager脚本挂载到场景根节点
```
**🔧 Cocos Creator调试提示：**
为了获得最佳的ECS调试体验，建议安装我们的专用调试插件：
- 插件地址：[https://store.cocos.com/app/detail/7823](https://store.cocos.com/app/detail/7823)
- 支持Cocos Creator v3.0.0+
- 提供实体查看器、组件编辑器、系统监控等功能
### Node.js后端
```typescript
@@ -185,7 +334,10 @@ class ServerGameManager {
private lastUpdate: number = Date.now();
constructor() {
Core.create(true);
// 初始化ECS框架（简化方式）
Core.create(true); // 启用调试模式
// 完整配置示例: Core.create({ debug: true, enableEntitySystems: true, debugConfig: {...} })
this.scene = new Scene();
this.scene.name = "ServerScene";
Core.scene = this.scene;
@@ -276,7 +428,10 @@ class BrowserGame {
private entityManager: EntityManager;
constructor() {
Core.create(true);
// 初始化ECS框架（简化方式）
Core.create(true); // 启用调试模式
// 完整配置示例: Core.create({ debug: true, enableEntitySystems: true, debugConfig: {...} })
this.scene = new Scene();
this.scene.name = "BrowserScene";
Core.scene = this.scene;

30
docs/system-guide.md
View File

@@ -69,7 +69,8 @@ class HealthSystem extends EntitySystem {
entity.addComponent(new DeadComponent());
// 触发死亡事件
Core.emitter.emit('entity:died', {
const eventBus = this.scene.entityManager.eventBus;
eventBus.emit('entity:died', {
entityId: entity.id,
entityName: entity.name
});
@@ -235,7 +236,8 @@ class SpawnSystem extends IntervalSystem {
spawner.lastSpawnTime = Time.totalTime;
// 发送生成事件
Core.emitter.emit('enemy:spawned', {
const eventBus = this.scene.entityManager.eventBus;
eventBus.emit('enemy:spawned', {
enemyId: enemy.id,
spawnPoint: spawnPoint,
spawnerEntity: spawnerEntity.id
@@ -270,18 +272,17 @@ class ScoreSystem extends PassiveSystem {
initialize() {
super.initialize();
// 监听游戏事件（使用Core.emitter）
Core.emitter.addObserver('enemy:killed', this.onEnemyKilled, this);
Core.emitter.addObserver('item:collected', this.onItemCollected, this);
Core.emitter.addObserver('combo:broken', this.onComboBroken, this);
// 监听游戏事件（使用EntityManager的事件系统）
const eventBus = this.scene.entityManager.eventBus;
eventBus.on('enemy:killed', this.onEnemyKilled, { context: this });
eventBus.on('item:collected', this.onItemCollected, { context: this });
eventBus.on('combo:broken', this.onComboBroken, { context: this });
}
// PassiveSystem被移除时清理
destroy() {
// 清理事件监听
Core.emitter.removeObserver('enemy:killed', this.onEnemyKilled, this);
Core.emitter.removeObserver('item:collected', this.onItemCollected, this);
Core.emitter.removeObserver('combo:broken', this.onComboBroken, this);
// 事件监听会在系统销毁时自动清理
// 如需手动清理，可以保存listenerId并调用eventBus.off()
}
private onEnemyKilled(data: { enemyType: string; position: { x: number; y: number } }) {
@@ -305,7 +306,8 @@ class ScoreSystem extends PassiveSystem {
this.score += points;
// 发送分数更新事件
Core.emitter.emit('score:updated', {
const eventBus = this.scene.entityManager.eventBus;
eventBus.emit('score:updated', {
score: this.score,
points: points,
multiplier: this.multiplier,
@@ -415,7 +417,8 @@ class CollisionSystem extends EntitySystem {
if (collision) {
// 发送碰撞事件，让其他系统响应
Core.emitter.emit('collision:detected', {
const eventBus = this.scene.entityManager.eventBus;
eventBus.emit('collision:detected', {
entity1: collider1,
entity2: collider2,
collisionPoint: point
@@ -427,7 +430,8 @@ class CollisionSystem extends EntitySystem {
class HealthSystem extends PassiveSystem {
onAddedToScene() {
// 监听碰撞事件
Core.emitter.addObserver('collision:detected', this.onCollision, this);
const eventBus = this.scene.entityManager.eventBus;
eventBus.on('collision:detected', this.onCollision, { context: this });
}
private onCollision(data: CollisionEventData) {

8
docs/timer-guide.md
View File

@@ -488,8 +488,9 @@ class LevelTimer {
console.log("⏰ 时间到！游戏结束");
// 触发游戏结束
Core.emitter.emit('level:timeout');
// 触发游戏结束（需要在实际使用中获取EntityManager实例）
// 示例：entityManager.eventBus.emit('level:timeout');
console.log('触发关卡超时事件');
}
completeLevel() {
@@ -509,7 +510,8 @@ class LevelTimer {
const bonus = Math.floor(timeLeft * 10); // 每秒剩余10分
if (bonus > 0) {
console.log(`时间奖励：${bonus} 分`);
Core.emitter.emit('score:time_bonus', { bonus });
// 触发时间奖励事件（需要在实际使用中获取EntityManager实例）
// 示例：entityManager.eventBus.emit('score:time_bonus', { bonus });
}
}