基于CocosCreator的ECS实现架构说明

ECS架构类图 - 简化版

核心架构图

graph TB subgraph "应用层" APP[Application
单例应用] end subgraph "世界层" WORLD[World
基础世界] GAME_WORLD[GameWorld
游戏世界] BATTLE_WORLD[BattleWorld
战斗世界] end subgraph "实体层" ENTITY[Entity
基础实体] SINGLE_ENTITY[SingletonEntity
单例实体] SCENE_ENTITY[SceneNodeEntity
场景节点实体] end subgraph "组件层" COMPONENT[Component
基础组件] SINGLETON[Singleton
标识组件] RESOURCE_MGR[ResourceManager
资源管理器] GAME_MGR[GameManager
游戏管理器] UNIT[Unit
兵种组件] MOVEMENT[Movement
移动组件] COMBAT[Combat
战斗组件] end subgraph "系统层" SYSTEM[System
基础系统] GAME_SYSTEM[GameSystem
游戏系统] SPAWN_SYSTEM[SpawnSystem
召唤系统] MOVE_SYSTEM[MovementSystem
移动系统] end subgraph "查询层" CONTEXT[IContext
实体上下文] GROUP[IGroup
实体组] MATCHER[IMatcher
匹配器] COLLECTOR[ICollector
响应收集器] end subgraph "管理层" SYS_MGR[SystemManager
系统管理器] TIME_MGR[TimeManager
时间管理器] TIME_CHANNEL[TimeChannel
时间通道] end subgraph "集成层" SCHEDULER[ECSScheduler
ECS调度器] LAUNCHER[GameLauncher
游戏启动器] end APP --> WORLD WORLD --> GAME_WORLD WORLD --> BATTLE_WORLD WORLD --> CONTEXT CONTEXT --> ENTITY ENTITY --> COMPONENT WORLD --> SYS_MGR WORLD --> TIME_MGR TIME_MGR --> TIME_CHANNEL SYSTEM --> GROUP GROUP --> MATCHER SYSTEM --> COLLECTOR GAME_WORLD --> SINGLE_ENTITY SINGLE_ENTITY --> RESOURCE_MGR SINGLE_ENTITY --> GAME_MGR BATTLE_WORLD --> SCENE_ENTITY SCENE_ENTITY --> UNIT SCENE_ENTITY --> MOVEMENT SCENE_ENTITY --> COMBAT SYSTEM --> GAME_SYSTEM SYSTEM --> SPAWN_SYSTEM SYSTEM --> MOVE_SYSTEM LAUNCHER --> APP SCHEDULER --> APP style APP fill:#ff6b6b style WORLD fill:#4ecdc4 style ENTITY fill:#95e1d3 style COMPONENT fill:#f38181 style SYSTEM fill:#aa96da style CONTEXT fill:#fcbad3 style SYS_MGR fill:#a8d8ea style TIME_MGR fill:#a8d8ea

类关系详细图

classDiagram %% 核心应用 Application "1" o-- "*" World : manages %% 世界继承关系 World <|-- GameWorld World <|-- BattleWorld %% 实体继承关系 Entity <|-- SingletonEntity Entity <|-- SceneNodeEntity %% 组件继承关系 Component <|-- System Component <|-- Singleton Component <|-- ResourceManager Component <|-- GameManager Component <|-- Unit Component <|-- Movement Component <|-- Combat %% 系统继承关系 System <|-- GameSystem System <|-- SpawnSystem System <|-- MovementSystem %% 世界包含关系 World "1" *-- "*" IContext : contains World "1" *-- "1" TimeManager : has World "1" *-- "1" SystemManager : has %% 上下文管理实体 IContext "1" *-- "*" Entity : manages IContext "1" *-- "*" IGroup : creates IContext "1" *-- "*" IMatcher : creates %% 实体包含组件 Entity "1" *-- "*" Component : contains %% 系统使用组和收集器 System "1" *-- "*" IGroup : uses System "1" *-- "*" ICollector : uses %% 组使用匹配器 IGroup "1" *-- "1" IMatcher : uses IGroup "1" *-- "*" Entity : contains %% 时间管理 TimeManager "1" *-- "*" TimeChannel : manages %% 单例关系 GameWorld "1" *-- "1" ResourceManager : singleton GameWorld "1" *-- "1" GameManager : singleton

数据流图

sequenceDiagram participant GL as GameLauncher participant ES as ECSScheduler participant APP as Application participant W as World participant TM as TimeManager participant SM as SystemManager participant SYS as System participant G as IGroup participant E as Entity Note over GL: 游戏启动 GL->>ES: active = true GL->>APP: world("main", GameWorld) APP->>W: initialize() W->>W: launch() W->>SYS: onAwake() W->>SYS: onEnable() Note over ES: 每帧更新 ES->>APP: update(timestamp) APP->>W: update(timestamp) W->>TM: update(timestamp) TM->>SM: update() SM->>SYS: onUpdate(deltaTime) SYS->>G: 查询实体 G->>E: 遍历匹配的实体 SYS->>E: 处理组件数据

实体创建流程

flowchart TD A[开始] --> B[Context.createEntity] B --> C[Entity.initialize] C --> D[Entity.addComponent] D --> E[Component.onAdd] E --> F{匹配Group?} F -->|是| G[Group.handleEvent] F -->|否| H[完成] G --> I{配置Collector?} I -->|是| J[Collector响应] I -->|否| H J --> H style A fill:#90EE90 style H fill:#FFB6C1

系统执行流程

flowchart LR A[TimeManager.update] --> B[Core Channel] B --> C[Logic Channel] C --> D[Update Channel] D --> E[Render Channel] E --> F[Clear Channel] B --> B1[系统1] B --> B2[系统2] C --> C1[系统3] D --> D1[系统4] D --> D2[系统5] E --> E1[系统6] F --> F1[系统7] style A fill:#FFE4B5 style B fill:#E0FFFF style C fill:#E0FFFF style D fill:#E0FFFF style E fill:#E0FFFF style F fill:#E0FFFF

关键接口说明

IMatcher (匹配器)

• allOf(...components): 必须包含所有指定组件
• anyOf(...components): 必须包含任一指定组件
• noneOf(...components): 不能包含任一指定组件
• extraOf(...components): 额外包含的组件（用于监听变化）

IGroup (实体组)

• entities: 匹配的实体列表
• component(id): 通过ID获取组件（需要配置componentGetter）
• sort(priorityCompare): 按优先级排序

ICollector (响应收集器)

• onEntityAdd: 实体添加时触发
• onEntityRemove: 实体移除时触发
• onComponentAdd: 组件添加时触发
• onComponentRemove: 组件移除时触发

TimeChannel (时间通道)

• Core: 核心周期，与世界更新频率同步
• Logic: 逻辑周期，固定时间间隔更新
• Update: 绘制周期，非固定时间间隔
• Render: 渲染周期
• Clear: 清理周期

使用示例

创建系统

@ecs.system({ world: "battle" })
export class SpawnSystem extends ecs.System<BattleWorldType> {
    protected getMatchers() {
        return {
            units: this.getMatcher(sg.SceneNodeEntity, true, Unit, Movement)
        };
    }
    
    onUpdate(deltaTime: float): void {
        this.groups.units.forEach(entity => {
            const unit = entity.getComponent(Unit)!;
            const movement = entity.getComponent(Movement)!;
            // 处理逻辑
        });
    }
}

创建实体

const context = world.context(sg.SceneNodeEntity);
const entity = context.createEntity(true);
entity.addComponent(Unit);
entity.addComponent(Movement);

使用匹配器

const matcher = context.matcher(true, Unit, Movement)
    .allOf(Unit, Movement)  // 必须同时有Unit和Movement
    .noneOf(Dead);          // 不能有Dead组件
const group = context.group(matcher);