esengine/COCOS_USAGE.md

Cocos Creator 使用指南

本指南专门针对在 Cocos Creator 3.8+ 中使用 @esengine/ecs-framework。

安装

npm install @esengine/ecs-framework

重要说明

⚠️ Cocos Creator 环境下无法直接使用 WASM 加速

由于 Cocos Creator 的特殊 WASM 加载机制，框架会自动检测 Cocos 环境并回退到 JavaScript 实现。这不会影响功能，只是性能稍有差异。

基本使用

1. 创建 ECS 核心

import { Core } from '@esengine/ecs-framework';

// 在Cocos组件中初始化
export class GameManager extends Component {
    private core: Core;
    
    onLoad() {
        // 创建核心实例（Cocos环境会自动禁用WASM）
        this.core = Core.create(true);
        console.log('ECS核心已初始化');
    }
}

2. 创建组件

import { Component } from '@esengine/ecs-framework';

// 位置组件
export class Position extends Component {
    constructor(public x: number = 0, public y: number = 0) {
        super();
    }
}

// 速度组件
export class Velocity extends Component {
    constructor(public dx: number = 0, public dy: number = 0) {
        super();
    }
}

// 精灵组件（关联Cocos节点）
export class SpriteComponent extends Component {
    constructor(public node: Node) {
        super();
    }
}

3. 创建系统

import { EntitySystem, Family } from '@esengine/ecs-framework';

export class MovementSystem extends EntitySystem {
    constructor() {
        super(Family.all(Position, Velocity).get());
    }
    
    public processEntity(entity: Entity, deltaTime: number): void {
        const pos = entity.getComponent(Position);
        const vel = entity.getComponent(Velocity);
        
        pos.x += vel.dx * deltaTime;
        pos.y += vel.dy * deltaTime;
    }
}

export class SpriteRenderSystem extends EntitySystem {
    constructor() {
        super(Family.all(Position, SpriteComponent).get());
    }
    
    public processEntity(entity: Entity, deltaTime: number): void {
        const pos = entity.getComponent(Position);
        const sprite = entity.getComponent(SpriteComponent);
        
        // 同步位置到Cocos节点
        sprite.node.setPosition(pos.x, pos.y);
    }
}

4. 创建场景

import { Scene } from '@esengine/ecs-framework';

export class GameScene extends Scene {
    private movementSystem: MovementSystem;
    private spriteRenderSystem: SpriteRenderSystem;
    
    public initialize(): void {
        // 添加系统
        this.movementSystem = this.addEntityProcessor(new MovementSystem());
        this.spriteRenderSystem = this.addEntityProcessor(new SpriteRenderSystem());
        
        // 创建一些实体用于测试
        this.createTestEntities();
    }
    
    private createTestEntities(): void {
        for (let i = 0; i < 10; i++) {
            const entity = this.createEntity();
            
            // 添加位置组件
            entity.addComponent(new Position(
                Math.random() * 800, 
                Math.random() * 600
            ));
            
            // 添加速度组件
            entity.addComponent(new Velocity(
                (Math.random() - 0.5) * 200,
                (Math.random() - 0.5) * 200
            ));
            
            // 创建Cocos节点并添加精灵组件
            const node = new Node();
            const sprite = node.addComponent(Sprite);
            // 设置精灵贴图...
            
            entity.addComponent(new SpriteComponent(node));
        }
    }
}

5. 在Cocos组件中集成

import { Component, _decorator } from 'cc';
import { Core } from '@esengine/ecs-framework';

const { ccclass } = _decorator;

@ccclass('ECSGameManager')
export class ECSGameManager extends Component {
    private core: Core;
    private gameScene: GameScene;
    
    onLoad() {
        // 初始化ECS核心
        this.core = Core.create(true);
        
        // 创建游戏场景
        this.gameScene = new GameScene();
        Core.scene = this.gameScene;
        
        console.log('ECS系统已启动');
    }
    
    update(deltaTime: number) {
        // ECS系统会自动处理更新
        // Core.emitter 会自动触发 frameUpdated 事件
    }
    
    onDestroy() {
        // 清理资源
        if (this.core) {
            // 执行必要的清理
        }
    }
}

高级功能

事件系统

import { EventBus, ECSEventType } from '@esengine/ecs-framework';

// 监听实体创建事件
EventBus.subscribe(ECSEventType.EntityCreated, (data) => {
    console.log('实体已创建:', data.entityId);
});

// 发射自定义事件
EventBus.emit('player-scored', { score: 100, playerId: 'player1' });

性能监控

import { PerformanceMonitor } from '@esengine/ecs-framework';

// 获取性能统计
const stats = PerformanceMonitor.instance.getStats();
console.log('系统性能:', stats);

对象池

import { PoolManager } from '@esengine/ecs-framework';

// 获取对象池管理器
const poolManager = PoolManager.getInstance();

// 创建对象池
const bulletPool = poolManager.createPool('bullets', () => new BulletComponent(), 100);

// 获取对象
const bullet = bulletPool.obtain();

// 归还对象
bulletPool.free(bullet);

性能建议

1. 合理使用Family查询: 避免过于复杂的组件查询
2. 批量操作: 使用事件系统进行批量更新
3. 对象池: 频繁创建/销毁的对象使用对象池
4. 定期清理: 及时移除不需要的实体和组件

注意事项

1. 🔧 WASM 支持: 在 Cocos Creator 中自动禁用，使用 JavaScript 实现
2. 🎯 内存管理: 注意及时清理不需要的实体，避免内存泄漏
3. 🔄 更新循环: ECS 系统会自动集成到 Cocos 的更新循环中
4. 📦 模块化: 建议按功能拆分不同的系统和组件

故障排除

常见问题

Q: 为什么看到"检测到Cocos Creator环境，WASM需要手动配置"的警告？ A: 这是正常的。框架会自动回退到JavaScript实现，功能完全正常。

Q: 如何确认ECS系统正在运行？ A: 查看控制台输出，应该能看到"ECS核心已初始化"等日志。

Q: 性能是否受到影响？ A: JavaScript实现的性能已经很好，对于大多数游戏场景足够使用。

示例项目

完整的示例项目请参考：GitHub示例仓库

技术支持

如遇问题，请访问：

• GitHub Issues
• 官方文档