CocosPlugin/esengine

Fork 0

Files

YHH e4e38ee4e6 更新api文档

2025-08-15 13:47:11 +08:00

13 KiB

Raw Blame History

技术概念详解

本文档用通俗易懂的语言解释ECS框架中的关键技术概念，帮助开发者理解这些技术的作用和应用场景。

ECS 架构基础

什么是 ECS？

ECS (Entity-Component-System) 是一种编程架构模式，将游戏对象分解为三个独立的部分：

传统面向对象方式：

// 传统继承方式 - 问题很多
class GameObject {
    x: number; y: number;
    render() { ... }
    update() { ... }
}

class Player extends GameObject {
    health: number;
    shoot() { ... }
}

class Enemy extends Player {  // 敌人需要射击但不需要玩家控制？
    ai() { ... }
}

ECS 方式：

// 数据和逻辑分离，灵活组合
const player = scene.createEntity("Player")
    .addComponent(new PositionComponent())    // 位置数据
    .addComponent(new HealthComponent())      // 生命值数据  
    .addComponent(new PlayerInputComponent()) // 玩家输入标记

const enemy = scene.createEntity("Enemy")
    .addComponent(new PositionComponent())    // 复用位置数据
    .addComponent(new HealthComponent())      // 复用生命值数据
    .addComponent(new AIComponent())          // AI标记

// 系统自动处理具有特定组件的实体
class MovementSystem extends EntitySystem {
    onUpdate() {
        // 处理具有Position和Velocity组件的实体
    }
}

ECS 的优势

灵活组合 - 像搭积木一样组装功能
代码复用 - 组件可以在不同实体间复用
性能优化 - 数据连续存储，缓存友好
并行处理 - 系统间相互独立，可以并行执行
易于测试 - 组件和系统可以独立测试

实际应用场景

游戏开发中的例子：

RPG游戏：玩家、NPC、怪物都有位置和生命值，但只有玩家有输入组件
射击游戏：子弹、玩家、敌人都有位置和碰撞体，但行为完全不同
策略游戏：建筑、单位、资源都是实体，通过不同组件组合实现功能

性能优化技术

组件索引系统

问题： 没有索引时，查找组件需要遍历所有实体

// 慢的方式：线性搜索 O(n)
function findEntitiesWithHealth() {
    const result = [];
    for (const entity of allEntities) {  // 遍历10万个实体
        if (entity.hasComponent(HealthComponent)) {
            result.push(entity);
        }
    }
    return result;
}

解决方案： 查询系统，直接访问

// 快的方式：使用查询系统 O(1)
const entitiesWithHealth = entityManager.query()
    .withAll(HealthComponent)
    .execute(); // 直接获取，SparseSet自动优化

应用场景：

频繁查询特定组件的实体
大规模实体场景（数千到数万个实体）
实时游戏中的系统更新

SparseSet 组件索引

什么是 SparseSet？ SparseSet是一种高效的数据结构，结合了哈希表的快速访问和数组的缓存友好特性。

SparseSet 的优势：

O(1) 添加/删除/查找 - 所有基本操作都是常数时间
缓存友好遍历 - 密集数组存储，提高遍历性能
内存高效 - 自动管理稀疏和密集数据
无需配置 - 框架自动选择最优策略

// 统一的查询API，无需手动配置
const entitiesWithHealth = entityManager.query()
    .withAll(HealthComponent)
    .execute(); // O(1) 访问，SparseSet自动优化

应用场景：

任意规模的实体场景（从几十到数万）
频繁的组件添加/删除操作
高性能的批量查询需求

Archetype 系统

什么是 Archetype？ Archetype（原型）是具有相同组件组合的实体分组。

没有 Archetype 的问题：

// 每次都要检查每个实体的组件组合
for (const entity of allEntities) {
    if (entity.has(Position) && entity.has(Velocity) && !entity.has(Frozen)) {
        // 处理移动
    }
}

Archetype 的解决方案：

// 实体按组件组合自动分组
const movableArchetype = [Position, Velocity, !Frozen];
const movableEntities = archetypeSystem.getEntities(movableArchetype);
// 直接处理，无需逐个检查

应用场景：

大量实体的游戏（RTS、MMO）
频繁的实体查询操作
批量处理相同类型的实体

脏标记系统

什么是脏标记？ 脏标记（Dirty Tracking）追踪哪些数据发生了变化，避免处理未变化的数据。

没有脏标记的问题：

// 每帧都重新计算所有实体，即使它们没有移动
function renderSystem() {
    for (const entity of entities) {
        updateRenderPosition(entity);  // 浪费计算
        updateRenderRotation(entity);  // 浪费计算
        updateRenderScale(entity);     // 浪费计算
    }
}

脏标记的解决方案：

// 只处理发生变化的实体
function renderSystem() {
    const dirtyEntities = dirtyTracking.getDirtyEntities();
    for (const entity of dirtyEntities) {
        if (dirtyTracking.isDirty(entity, PositionComponent)) {
            updateRenderPosition(entity);  // 只在需要时计算
        }
        if (dirtyTracking.isDirty(entity, RotationComponent)) {
            updateRenderRotation(entity);
        }
    }
    dirtyTracking.clearDirtyFlags();
}

应用场景：

渲染系统优化（只更新变化的物体）
物理系统优化（只计算移动的物体）
UI更新优化（只刷新变化的界面元素）
网络同步优化（只发送变化的数据）

实际例子：

// 游戏中的应用
class MovementSystem {
    process() {
        // 玩家移动时标记为脏
        if (playerInput.moved) {
            dirtyTracking.markDirty(player, PositionComponent);
        }
        
        // 静止的敌人不会被标记为脏，渲染系统会跳过它们
    }
}

事件系统

类型安全事件

传统事件的问题：

// 类型不安全，容易出错
eventEmitter.emit('player_died', playerData);
eventEmitter.on('player_dead', handler); // 事件名拼写错误！

类型安全事件的解决方案：

// 编译时检查，避免错误
enum GameEvents {
    PLAYER_DIED = 'player:died',
    LEVEL_COMPLETED = 'level:completed'
}

eventBus.emit(GameEvents.PLAYER_DIED, { playerId: 123 });
eventBus.on(GameEvents.PLAYER_DIED, (data) => {
    // data 类型自动推断
});

事件装饰器

什么是装饰器？ 装饰器让你用简单的语法自动注册事件监听器。

传统方式：

class GameManager {
    constructor() {
        // 手动注册事件
        eventBus.on('entity:created', this.onEntityCreated.bind(this));
        eventBus.on('entity:destroyed', this.onEntityDestroyed.bind(this));
        eventBus.on('component:added', this.onComponentAdded.bind(this));
    }
    
    onEntityCreated(data) { ... }
    onEntityDestroyed(data) { ... }
    onComponentAdded(data) { ... }
}

装饰器方式：

class GameManager {
    @EventHandler('entity:created')
    onEntityCreated(data) { ... }    // 自动注册
    
    @EventHandler('entity:destroyed')
    onEntityDestroyed(data) { ... }  // 自动注册
    
    @EventHandler('component:added')
    onComponentAdded(data) { ... }   // 自动注册
}

应用场景：

游戏状态管理
UI更新响应
音效播放触发
成就系统检查

实体管理

实体生命周期

创建实体的方式：

// 单个创建 - 适用于重要实体
const player = scene.createEntity("Player");
player.addComponent(new PositionComponent());
player.addComponent(new HealthComponent());

// 批量创建 - 需要循环处理
const bullets: Entity[] = [];
for (let i = 0; i < 100; i++) {
    const bullet = scene.createEntity(`Bullet_${i}`);
    bullet.addComponent(new PositionComponent());
    bullet.addComponent(new VelocityComponent());
    bullets.push(bullet);
}

查询系统

流式API的优势：

// 传统方式：复杂的条件判断
const result = [];
for (const entity of entities) {
    if (entity.has(Position) && 
        entity.has(Velocity) && 
        !entity.has(Frozen) && 
        entity.tag === EntityTag.ENEMY) {
        result.push(entity);
    }
}

// 流式API：清晰表达意图
const result = entityManager
    .query()
    .withAll(Position, Velocity)
    .withNone(Frozen)
    .withTag(EntityTag.ENEMY)
    .execute();

批量操作

批量操作的优化：

// 优化的批量创建方式
const bullets: Entity[] = [];
for (let i = 0; i < 1000; i++) {
    const bullet = scene.createEntity(`Bullet_${i}`);
    bullet.addComponent(new PositionComponent());
    bullet.addComponent(new VelocityComponent());
    bullets.push(bullet);
}

// 批量查询操作
const allMovableEntities = entityManager.query()
    .withAll(PositionComponent, VelocityComponent)
    .execute();

应用场景：

生成大量子弹/粒子
加载关卡时创建大量实体
清理场景时删除大量实体

总结

ECS框架包含以下核心技术概念：

ECS架构 - 组件化设计模式
SparseSet索引 - 高效的组件查询
Archetype系统 - 实体分组优化
脏标记系统 - 变化检测机制
事件系统 - 组件间通信
实体管理 - 生命周期管理

框架类型系统

TypeScript接口设计

ECS框架采用了精简的TypeScript接口设计，提供类型安全保障的同时保持实现的灵活性。

核心接口

IComponent接口

interface IComponent {
    readonly id: number;
    enabled: boolean;
    updateOrder: number;
    
    onAddedToEntity(): void;
    onRemovedFromEntity(): void;
    onEnabled(): void;
    onDisabled(): void;
    update(): void;
}

定义所有组件的基本契约
Component基类实现此接口
确保组件生命周期方法的一致性

ISystemBase接口

interface ISystemBase {
    readonly systemName: string;
    readonly entities: readonly any[];
    updateOrder: number;
    enabled: boolean;
    
    initialize(): void;
    update(): void;
    lateUpdate?(): void;
}

为EntitySystem类提供类型约束
定义系统的核心执行方法
支持可选的延迟更新

IEventBus接口

interface IEventBus {
    emit<T>(eventType: string, data: T): void;
    emitAsync<T>(eventType: string, data: T): Promise<void>;
    on<T>(eventType: string, handler: (data: T) => void, config?: IEventListenerConfig): string;
    // ... 其他事件方法
}

提供类型安全的事件系统契约
支持同步和异步事件处理
EventBus类完整实现此接口

事件数据接口

事件数据层次结构

// 基础事件数据
interface IEventData {
    timestamp: number;
    source?: string;
    eventId?: string;
}

// 实体相关事件
interface IEntityEventData extends IEventData {
    entityId: number;
    entityName?: string;
    entityTag?: string;
}

// 组件相关事件
interface IComponentEventData extends IEntityEventData {
    componentType: string;
    component?: IComponent;
}

清晰的继承层次
类型安全的事件数据传递
便于事件处理器的实现

类型别名

ComponentType

type ComponentType<T extends IComponent = IComponent> = new (...args: any[]) => T;

用于类型安全的组件操作
支持泛型约束
广泛用于实体和查询系统

设计原则

1. 接口简化原则

只保留实际使用的接口
移除了未使用的复杂接口（如IEntityManager、IEntityQueryBuilder等）
减少认知负担，提高开发效率

2. 实现灵活性原则

接口作为类型约束而非强制实现
允许具体类有更丰富的实现
保持向后兼容性

3. 类型安全原则

编译时类型检查
泛型支持提供精确的类型推断
事件系统的完整类型安全

使用指南

在项目中使用接口

// 作为类型约束
function processComponent<T extends IComponent>(component: T) {
    if (component.enabled) {
        component.update();
    }
}

// 作为参数类型
function registerSystem(system: ISystemBase) {
    scene.addEntityProcessor(system);
}

// 作为泛型约束
function getComponent<T extends IComponent>(type: ComponentType<T>): T | null {
    return entity.getComponent(type);
}

扩展框架接口

// 如果需要扩展组件接口
interface IAdvancedComponent extends IComponent {
    priority: number;
    category: string;
}

class AdvancedComponent extends Component implements IAdvancedComponent {
    public priority: number = 0;
    public category: string = "default";
    
    // 实现基础接口方法
}

接口维护

当前的接口设计已经过精心清理，包含：

12个核心接口 - 涵盖组件、系统、事件等核心概念
0个冗余接口 - 移除了所有未使用的接口定义
完整的类型覆盖 - 为所有主要功能提供类型支持

这种设计确保了框架的类型安全性，同时保持了代码的简洁性和可维护性。

13 KiB Raw Blame History Unescape Escape

技术概念详解

目录

ECS 架构基础

什么是 ECS？

ECS 的优势

实际应用场景

性能优化技术

组件索引系统

SparseSet 组件索引

Archetype 系统

脏标记系统

事件系统

类型安全事件

事件装饰器

实体管理

实体生命周期

查询系统

批量操作

总结

框架类型系统

TypeScript接口设计

核心接口

事件数据接口

类型别名

设计原则

1. 接口简化原则

2. 实现灵活性原则

3. 类型安全原则

使用指南

在项目中使用接口

扩展框架接口

接口维护

13 KiB

Raw Blame History