Skip to content

ECS Framework API v2.2.13


ECS Framework API / WorkerEntitySystem

Abstract Class: WorkerEntitySystem<TEntityData>

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:190

支持Worker并行处理的EntitySystem基类

支持传统Worker和SharedArrayBuffer两种优化模式:

  • 传统模式:数据序列化传输,适用于复杂计算
  • SharedArrayBuffer模式:零拷贝数据共享,适用于大量简单计算

用户需要实现:

  1. extractEntityData - 定义数据提取逻辑
  2. workerProcess - 编写处理函数(纯函数,可序列化)
  3. applyResult - 定义结果应用逻辑
  4. (可选) SharedArrayBuffer相关方法

Example

typescript
class PhysicsSystem extends WorkerEntitySystem<PhysicsData> {
    constructor() {
        super(Matcher.all(Transform, Velocity), {
            enableWorker: true,
            workerCount: 8, // 指定8个worker,系统会自动限制在系统最大值内
            entitiesPerWorker: 100, // 每个worker处理100个实体
            useSharedArrayBuffer: true,
            entityDataSize: 6, // x, y, vx, vy, radius, mass
            maxEntities: 10000,
            systemConfig: { gravity: 100, friction: 0.95 }
        });
    }

    protected getDefaultEntityDataSize(): number {
        return 6; // x, y, vx, vy, radius, mass
    }

    protected extractEntityData(entity: Entity): PhysicsData {
        const transform = entity.getComponent(Transform);
        const velocity = entity.getComponent(Velocity);
        const physics = entity.getComponent(PhysicsComponent);
        return {
            x: transform.x,
            y: transform.y,
            vx: velocity.x,
            vy: velocity.y,
            radius: physics.radius,
            mass: physics.mass
        };
    }

    protected workerProcess(entities: PhysicsData[], deltaTime: number, config: any): PhysicsData[] {
        return entities.map(entity => {
            // 应用重力
            entity.vy += config.gravity * deltaTime;

            // 更新位置
            entity.x += entity.vx * deltaTime;
            entity.y += entity.vy * deltaTime;

            // 应用摩擦力
            entity.vx *= config.friction;
            entity.vy *= config.friction;

            return entity;
        });
    }

    protected applyResult(entity: Entity, result: PhysicsData): void {
        const transform = entity.getComponent(Transform);
        const velocity = entity.getComponent(Velocity);

        transform.x = result.x;
        transform.y = result.y;
        velocity.x = result.vx;
        velocity.y = result.vy;
    }

    // SharedArrayBuffer优化支持
    protected writeEntityToBuffer(entityData: PhysicsData, offset: number): void {
        if (!this.sharedFloatArray) return;

        this.sharedFloatArray[offset] = entityData.x;
        this.sharedFloatArray[offset + 1] = entityData.y;
        this.sharedFloatArray[offset + 2] = entityData.vx;
        this.sharedFloatArray[offset + 3] = entityData.vy;
        this.sharedFloatArray[offset + 4] = entityData.radius;
        this.sharedFloatArray[offset + 5] = entityData.mass;
    }

    protected readEntityFromBuffer(offset: number): PhysicsData | null {
        if (!this.sharedFloatArray) return null;

        return {
            x: this.sharedFloatArray[offset],
            y: this.sharedFloatArray[offset + 1],
            vx: this.sharedFloatArray[offset + 2],
            vy: this.sharedFloatArray[offset + 3],
            radius: this.sharedFloatArray[offset + 4],
            mass: this.sharedFloatArray[offset + 5]
        };
    }

    protected getSharedArrayBufferProcessFunction(): SharedArrayBufferProcessFunction {
        return function(sharedFloatArray: Float32Array, startIndex: number, endIndex: number, deltaTime: number, config: any) {
            const entitySize = 6;
            for (let i = startIndex; i < endIndex; i++) {
                const offset = i * entitySize;

                // 读取数据
                let x = sharedFloatArray[offset];
                let y = sharedFloatArray[offset + 1];
                let vx = sharedFloatArray[offset + 2];
                let vy = sharedFloatArray[offset + 3];
                const radius = sharedFloatArray[offset + 4];
                const mass = sharedFloatArray[offset + 5];

                // 物理计算
                vy += config.gravity * deltaTime;
                x += vx * deltaTime;
                y += vy * deltaTime;
                vx *= config.friction;
                vy *= config.friction;

                // 写回数据
                sharedFloatArray[offset] = x;
                sharedFloatArray[offset + 1] = y;
                sharedFloatArray[offset + 2] = vx;
                sharedFloatArray[offset + 3] = vy;
            }
        };
    }
}

interface PhysicsData {
    x: number;
    y: number;
    vx: number;
    vy: number;
    radius: number;
    mass: number;
}

Extends

Type Parameters

TEntityData

TEntityData = any

Constructors

Constructor

new WorkerEntitySystem<TEntityData>(matcher?, config?): WorkerEntitySystem<TEntityData>

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:202

Parameters

matcher?

Matcher

config?

WorkerSystemConfig = {}

Returns

WorkerEntitySystem<TEntityData>

Overrides

EntitySystem.constructor

Properties

logger

protected logger: ILogger

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:77

Inherited from

EntitySystem.logger


config

protected config: Required<Omit<WorkerSystemConfig, "systemConfig" | "entitiesPerWorker">> & object

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:191

Type Declaration

systemConfig?

optional systemConfig: any

entitiesPerWorker?

optional entitiesPerWorker: number


sharedBuffer

protected sharedBuffer: null | SharedArrayBuffer = null

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:197


sharedFloatArray

protected sharedFloatArray: null | Float32Array<ArrayBufferLike> = null

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:198

Accessors

entities

Get Signature

get entities(): readonly Entity[]

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:93

获取系统处理的实体列表

Returns

readonly Entity[]

Inherited from

EntitySystem.entities


updateOrder

Get Signature

get updateOrder(): number

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:111

获取系统的更新时序

Returns

number

Set Signature

set updateOrder(value): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:115

更新顺序/优先级

Parameters
value

number

Returns

void

更新顺序/优先级

Inherited from

EntitySystem.updateOrder


enabled

Get Signature

get enabled(): boolean

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:122

获取系统的启用状态

Returns

boolean

Set Signature

set enabled(value): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:129

设置系统的启用状态

Parameters
value

boolean

Returns

void

系统启用状态

Inherited from

EntitySystem.enabled


systemName

Get Signature

get systemName(): string

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:136

获取系统名称

Returns

string

系统名称

Inherited from

EntitySystem.systemName


scene

Get Signature

get scene(): null | Scene

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:163

这个系统所属的场景

Returns

null | Scene

Set Signature

set scene(value): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:167

Parameters
value

null | Scene

Returns

void

Inherited from

EntitySystem.scene


matcher

Get Signature

get matcher(): Matcher

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:193

获取实体匹配器

Returns

Matcher

Inherited from

EntitySystem.matcher

Methods

setPerformanceMonitor()

setPerformanceMonitor(monitor): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:174

设置性能监控器

Parameters

monitor

PerformanceMonitor

Returns

void

Inherited from

EntitySystem.setPerformanceMonitor


setUpdateOrder()

setUpdateOrder(order): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:201

设置更新时序

Parameters

order

number

更新时序

Returns

void

Inherited from

EntitySystem.setUpdateOrder


initialize()

initialize(): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:212

系统初始化(框架调用)

在系统创建时调用。框架内部使用,用户不应直接调用。

Returns

void

Inherited from

EntitySystem.initialize


onInitialize()

protected onInitialize(): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:236

系统初始化回调

子类可以重写此方法进行初始化操作。

Returns

void

Inherited from

EntitySystem.onInitialize


clearEntityCache()

clearEntityCache(): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:244

清除实体缓存(内部使用) 当Scene中的实体发生变化时调用

Returns

void

Inherited from

EntitySystem.clearEntityCache


reset()

reset(): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:257

重置系统状态

当系统从场景中移除时调用,重置初始化状态以便重新添加时能正确初始化。

注意:此方法由 Scene.removeEntityProcessor 调用,在 unregister(触发dispose)之后调用。 dispose 已经调用了 onDestroy 并设置了 _destroyed 标志,所以这里不需要重置该标志。 重置 _destroyed 会违反服务容器的语义(dispose 后不应重用)。

Returns

void

Inherited from

EntitySystem.reset


update()

update(): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:542

更新系统

Returns

void

Inherited from

EntitySystem.update


lateUpdate()

lateUpdate(): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:568

后期更新系统

Returns

void

Inherited from

EntitySystem.lateUpdate


onBegin()

protected onBegin(): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:595

在系统处理开始前调用

子类可以重写此方法进行预处理操作。

Returns

void

Inherited from

EntitySystem.onBegin


lateProcess()

protected lateProcess(_entities): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:617

后期处理实体列表

在主要处理逻辑之后执行,子类可以重写此方法。

Parameters

_entities

readonly Entity[]

Returns

void

Inherited from

EntitySystem.lateProcess


onEnd()

protected onEnd(): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:626

系统处理完毕后调用

子类可以重写此方法进行后处理操作。

Returns

void

Inherited from

EntitySystem.onEnd


onCheckProcessing()

protected onCheckProcessing(): boolean

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:638

检查系统是否需要处理

在启用系统时有用,但仅偶尔需要处理。 这只影响处理,不影响事件或订阅列表。

Returns

boolean

如果系统应该处理,则为true,如果不处理则为false

Inherited from

EntitySystem.onCheckProcessing


getPerformanceData()

getPerformanceData(): undefined | PerformanceData

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:647

获取系统的性能数据

Returns

undefined | PerformanceData

性能数据或undefined

Inherited from

EntitySystem.getPerformanceData


getPerformanceStats()

getPerformanceStats(): undefined | PerformanceStats

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:656

获取系统的性能统计

Returns

undefined | PerformanceStats

性能统计或undefined

Inherited from

EntitySystem.getPerformanceStats


resetPerformanceData()

resetPerformanceData(): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:663

重置系统的性能数据

Returns

void

Inherited from

EntitySystem.resetPerformanceData


toString()

toString(): string

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:672

获取系统信息的字符串表示

Returns

string

系统信息字符串

Inherited from

EntitySystem.toString


onAdded()

protected onAdded(_entity): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:718

当实体被添加到系统时调用

子类可以重写此方法来处理实体添加事件。

Parameters

_entity

Entity

Returns

void

Inherited from

EntitySystem.onAdded


onRemoved()

protected onRemoved(_entity): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:729

当实体从系统中移除时调用

子类可以重写此方法来处理实体移除事件。

Parameters

_entity

Entity

Returns

void

Inherited from

EntitySystem.onRemoved


dispose()

dispose(): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:747

释放系统资源

实现IService接口要求的dispose方法。 当系统从Scene中移除或Scene销毁时调用。

默认行为:

  • 移除所有事件监听器
  • 调用 onDestroy 回调(仅首次)
  • 清空所有缓存
  • 重置初始化状态

子类可以重写此方法来清理自定义资源,但应该调用super.dispose()。

Returns

void

Inherited from

EntitySystem.dispose


addEventListener()

protected addEventListener<T>(eventType, handler, config?): null | string

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:782

添加事件监听器

推荐使用此方法而不是直接调用eventSystem.on(), 这样可以确保系统移除时自动清理监听器,避免内存泄漏。

Type Parameters

T

T

Parameters

eventType

string

事件类型

handler

EventHandler<T>

事件处理函数

config?

EventListenerConfig

监听器配置

Returns

null | string

监听器引用ID,可用于手动移除监听器

Inherited from

EntitySystem.addEventListener


removeEventListener()

protected removeEventListener(eventType, listenerRef): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:812

移除特定的事件监听器

Parameters

eventType

string

事件类型

listenerRef

string

监听器引用ID(由 addEventListener 返回)

Returns

void

Inherited from

EntitySystem.removeEventListener


destroy()

destroy(): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:849

框架内部销毁方法 由框架调用,处理系统的完整销毁流程

Returns

void

Inherited from

EntitySystem.destroy


requireComponent()

protected requireComponent<T>(entity, componentType): ComponentInstance<T>

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:903

类型安全地获取单个组件

相比Entity.getComponent,此方法保证返回非空值, 如果组件不存在会抛出错误而不是返回null

Type Parameters

T

T extends ComponentConstructor

Parameters

entity

Entity

实体

componentType

T

组件类型

Returns

ComponentInstance<T>

组件实例(保证非空)

Throws

如果组件不存在则抛出错误

Example

typescript
protected process(entities: readonly Entity[]): void {
    for (const entity of entities) {
        const transform = this.requireComponent(entity, Transform);
        // transform 保证非空,类型为 Transform
    }
}

Inherited from

EntitySystem.requireComponent


getComponents()

protected getComponents<T>(entity, ...components): { [K in string | number | symbol]: ComponentInstance<T[K<K>]> }

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:934

批量获取实体的所有必需组件

根据泛型参数TComponents推断返回类型, 返回一个元组,包含所有组件实例

Type Parameters

T

T extends readonly ComponentConstructor[]

Parameters

entity

Entity

实体

components

...T

组件类型数组

Returns

{ [K in string | number | symbol]: ComponentInstance<T[K<K>]> }

组件实例元组

Example

typescript
class MySystem extends EntitySystem<[typeof Position, typeof Velocity]> {
    protected process(entities: readonly Entity[]): void {
        for (const entity of entities) {
            const [pos, vel] = this.getComponents(entity, Position, Velocity);
            // pos: Position, vel: Velocity (自动类型推断)
            pos.x += vel.x;
        }
    }
}

Inherited from

EntitySystem.getComponents


forEach()

protected forEach(entities, processor): void

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:961

遍历实体并处理每个实体

提供更简洁的语法糖,避免手动遍历

Parameters

entities

readonly Entity[]

实体列表

processor

(entity, index) => void

处理函数

Returns

void

Example

typescript
protected process(entities: readonly Entity[]): void {
    this.forEach(entities, (entity) => {
        const transform = this.requireComponent(entity, Transform);
        transform.position.y -= 9.8 * Time.deltaTime;
    });
}

Inherited from

EntitySystem.forEach


filterEntities()

protected filterEntities(entities, predicate): Entity[]

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:984

过滤实体

Parameters

entities

readonly Entity[]

实体列表

predicate

(entity, index) => boolean

过滤条件

Returns

Entity[]

过滤后的实体数组

Example

typescript
protected process(entities: readonly Entity[]): void {
    const activeEntities = this.filterEntities(entities, (entity) => {
        const health = this.requireComponent(entity, Health);
        return health.value > 0;
    });
}

Inherited from

EntitySystem.filterEntities


mapEntities()

protected mapEntities<R>(entities, mapper): R[]

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:1008

映射实体到另一种类型

Type Parameters

R

R

Parameters

entities

readonly Entity[]

实体列表

mapper

(entity, index) => R

映射函数

Returns

R[]

映射后的结果数组

Example

typescript
protected process(entities: readonly Entity[]): void {
    const positions = this.mapEntities(entities, (entity) => {
        const transform = this.requireComponent(entity, Transform);
        return transform.position;
    });
}

Inherited from

EntitySystem.mapEntities


findEntity()

protected findEntity(entities, predicate): undefined | Entity

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:1028

查找第一个满足条件的实体

Parameters

entities

readonly Entity[]

实体列表

predicate

(entity, index) => boolean

查找条件

Returns

undefined | Entity

第一个满足条件的实体,或undefined

Example

typescript
protected process(entities: readonly Entity[]): void {
    const player = this.findEntity(entities, (entity) =>
        entity.hasComponent(PlayerTag)
    );
}

Inherited from

EntitySystem.findEntity


someEntity()

protected someEntity(entities, predicate): boolean

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:1057

检查是否存在满足条件的实体

Parameters

entities

readonly Entity[]

实体列表

predicate

(entity, index) => boolean

检查条件

Returns

boolean

是否存在满足条件的实体

Example

typescript
protected process(entities: readonly Entity[]): void {
    const hasLowHealth = this.someEntity(entities, (entity) => {
        const health = this.requireComponent(entity, Health);
        return health.value < 20;
    });
}

Inherited from

EntitySystem.someEntity


everyEntity()

protected everyEntity(entities, predicate): boolean

Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:1083

检查是否所有实体都满足条件

Parameters

entities

readonly Entity[]

实体列表

predicate

(entity, index) => boolean

检查条件

Returns

boolean

是否所有实体都满足条件

Example

typescript
protected process(entities: readonly Entity[]): void {
    const allHealthy = this.everyEntity(entities, (entity) => {
        const health = this.requireComponent(entity, Health);
        return health.value > 50;
    });
}

Inherited from

EntitySystem.everyEntity


getDefaultEntityDataSize()

abstract protected getDefaultEntityDataSize(): number

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:264

获取实体数据大小 - 子类必须实现 返回每个实体在SharedArrayBuffer中占用的Float32数量

Returns

number


process()

protected process(entities): void

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:425

重写process方法,支持Worker并行处理

Parameters

entities

readonly Entity[]

Returns

void

Overrides

EntitySystem.process


writeEntityToBuffer()

abstract protected writeEntityToBuffer(entityData, offset): void

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:607

将单个实体数据写入SharedArrayBuffer - 子类必须实现

Parameters

entityData

TEntityData

实体数据

offset

number

在SharedArrayBuffer中的偏移位置(Float32索引)

Returns

void


readEntityFromBuffer()

abstract protected readEntityFromBuffer(offset): null | TEntityData

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:684

从SharedArrayBuffer读取单个实体数据 - 子类必须实现

Parameters

offset

number

在SharedArrayBuffer中的偏移位置(Float32索引)

Returns

null | TEntityData

实体数据或null


getSharedArrayBufferProcessFunction()?

protected optional getSharedArrayBufferProcessFunction(): SharedArrayBufferProcessFunction

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:690

获取SharedArrayBuffer处理函数 - 子类可选实现 返回一个函数,该函数将被序列化到Worker中执行

Returns

SharedArrayBufferProcessFunction


extractEntityData()

abstract protected extractEntityData(entity): TEntityData

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:697

提取实体数据 - 子类必须实现

将Entity转换为可序列化的数据对象

Parameters

entity

Entity

Returns

TEntityData


workerProcess()

abstract protected workerProcess(entities, deltaTime, systemConfig?): TEntityData[] | Promise<TEntityData[]>

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:707

Worker处理函数 - 子类必须实现

这个函数会被序列化并在Worker中执行,因此:

  1. 必须是纯函数,不能访问外部变量
  2. 不能使用闭包或this
  3. 只能使用标准JavaScript API

Parameters

entities

TEntityData[]

deltaTime

number

systemConfig?

any

Returns

TEntityData[] | Promise<TEntityData[]>


applyResult()

abstract protected applyResult(entity, result): void

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:718

应用处理结果 - 子类必须实现

将Worker处理的结果应用回Entity的组件

Parameters

entity

Entity

result

TEntityData

Returns

void


updateConfig()

updateConfig(newConfig): void

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:723

更新Worker配置

Parameters

newConfig

Partial<WorkerSystemConfig>

Returns

void


getWorkerInfo()

getWorkerInfo(): object

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:807

获取系统性能信息

Returns

object

enabled

enabled: boolean

workerCount

workerCount: number

entitiesPerWorker?

optional entitiesPerWorker: number

maxSystemWorkerCount

maxSystemWorkerCount: number

isProcessing

isProcessing: boolean

sharedArrayBufferSupported

sharedArrayBufferSupported: boolean

sharedArrayBufferEnabled

sharedArrayBufferEnabled: boolean

currentMode

currentMode: "worker" | "shared-buffer" | "sync"


onDestroy()

protected onDestroy(): void

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:842

销毁系统时清理Worker池

Returns

void

Overrides

EntitySystem.onDestroy


getLoggerName()

protected getLoggerName(): string

Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:851

获取Logger名称 默认返回类的构造函数名称, 子类可以重写此方法来自定义logger名称

Returns

string

Overrides

EntitySystem.getLoggerName

Released under the MIT License.