ECS Framework API / WorkerEntitySystem

Abstract Class: WorkerEntitySystem<TEntityData>

Defined in: ECS/Systems/WorkerEntitySystem.ts:191

支持Worker并行处理的EntitySystem基类

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

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

用户需要实现：

extractEntityData - 定义数据提取逻辑
workerProcess - 编写处理函数（纯函数，可序列化）
applyResult - 定义结果应用逻辑
(可选) 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

EntitySystem

Type Parameters

TEntityData

TEntityData = any

Constructors

Constructor

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

Defined in: ECS/Systems/WorkerEntitySystem.ts:202

Parameters

matcher?

Matcher

config?

WorkerSystemConfig = {}

Returns

WorkerEntitySystem<TEntityData>

Overrides

EntitySystem.constructor

Properties

logger

protected logger: ILogger

Defined in: ECS/Systems/EntitySystem.ts:54

Inherited from

EntitySystem.logger

config

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

Defined in: ECS/Systems/WorkerEntitySystem.ts:192

Type Declaration

systemConfig?

optional systemConfig: any

entitiesPerWorker?

optional entitiesPerWorker: number

sharedBuffer

protected sharedBuffer: null | SharedArrayBuffer = null

Defined in: ECS/Systems/WorkerEntitySystem.ts:198

sharedFloatArray

protected sharedFloatArray: null | Float32Array<ArrayBufferLike> = null

Defined in: ECS/Systems/WorkerEntitySystem.ts:199

Accessors

entities

Get Signature

get entities(): readonly Entity[]

Defined in: ECS/Systems/EntitySystem.ts:79

获取系统处理的实体列表

Returns

readonly Entity[]

Inherited from

EntitySystem.entities

updateOrder

Get Signature

get updateOrder(): number

Defined in: ECS/Systems/EntitySystem.ts:96

获取系统的更新时序

Returns

number

Set Signature

set updateOrder(value): void

Defined in: ECS/Systems/EntitySystem.ts:100

更新顺序/优先级

Parameters

value

number

Returns

void

更新顺序/优先级

Inherited from

EntitySystem.updateOrder

enabled

Get Signature

get enabled(): boolean

Defined in: ECS/Systems/EntitySystem.ts:107

获取系统的启用状态

Returns

boolean

Set Signature

set enabled(value): void

Defined in: ECS/Systems/EntitySystem.ts:114

设置系统的启用状态

Parameters

value

boolean

Returns

void

系统启用状态

Inherited from

EntitySystem.enabled

systemName

Get Signature

get systemName(): string

Defined in: ECS/Systems/EntitySystem.ts:121

获取系统名称

Returns

string

系统名称

Inherited from

EntitySystem.systemName

scene

Get Signature

get scene(): null | Scene

Defined in: ECS/Systems/EntitySystem.ts:164

这个系统所属的场景

Returns

null | Scene

Set Signature

set scene(value): void

Defined in: ECS/Systems/EntitySystem.ts:168

Parameters

value

null | Scene

Returns

void

Inherited from

EntitySystem.scene

matcher

Get Signature

get matcher(): Matcher

Defined in: ECS/Systems/EntitySystem.ts:175

获取实体匹配器

Returns

Matcher

Inherited from

EntitySystem.matcher

Methods

setUpdateOrder()

setUpdateOrder(order): void

Defined in: ECS/Systems/EntitySystem.ts:183

设置更新时序

Parameters

order

number

更新时序

Returns

void

Inherited from

EntitySystem.setUpdateOrder

initialize()

initialize(): void

Defined in: ECS/Systems/EntitySystem.ts:195

系统初始化（框架调用）

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

Returns

void

Inherited from

EntitySystem.initialize

onInitialize()

protected onInitialize(): void

Defined in: ECS/Systems/EntitySystem.ts:219

系统初始化回调

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

Returns

void

Inherited from

EntitySystem.onInitialize

clearEntityCache()

clearEntityCache(): void

Defined in: ECS/Systems/EntitySystem.ts:227

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

Returns

void

Inherited from

EntitySystem.clearEntityCache

reset()

reset(): void

Defined in: ECS/Systems/EntitySystem.ts:236

重置系统状态

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

Returns

void

Inherited from

EntitySystem.reset

update()

update(): void

Defined in: ECS/Systems/EntitySystem.ts:508

更新系统

Returns

void

Inherited from

EntitySystem.update

lateUpdate()

lateUpdate(): void

Defined in: ECS/Systems/EntitySystem.ts:531

后期更新系统

Returns

void

Inherited from

EntitySystem.lateUpdate

onBegin()

protected onBegin(): void

Defined in: ECS/Systems/EntitySystem.ts:557

在系统处理开始前调用

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

Returns

void

Inherited from

EntitySystem.onBegin

lateProcess()

protected lateProcess(_entities): void

Defined in: ECS/Systems/EntitySystem.ts:579

后期处理实体列表

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

Parameters

_entities

readonly Entity[]

Returns

void

Inherited from

EntitySystem.lateProcess

onEnd()

protected onEnd(): void

Defined in: ECS/Systems/EntitySystem.ts:588

系统处理完毕后调用

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

Returns

void

Inherited from

EntitySystem.onEnd

onCheckProcessing()

protected onCheckProcessing(): boolean

Defined in: ECS/Systems/EntitySystem.ts:600

检查系统是否需要处理

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

Returns

boolean

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

Inherited from

EntitySystem.onCheckProcessing

getPerformanceData()

getPerformanceData(): undefined | PerformanceData

Defined in: ECS/Systems/EntitySystem.ts:609

获取系统的性能数据

Returns

undefined | PerformanceData

性能数据或undefined

Inherited from

EntitySystem.getPerformanceData

getPerformanceStats()

getPerformanceStats(): undefined | PerformanceStats

Defined in: ECS/Systems/EntitySystem.ts:618

获取系统的性能统计

Returns

undefined | PerformanceStats

性能统计或undefined

Inherited from

EntitySystem.getPerformanceStats

resetPerformanceData()

resetPerformanceData(): void

Defined in: ECS/Systems/EntitySystem.ts:625

重置系统的性能数据

Returns

void

Inherited from

EntitySystem.resetPerformanceData

toString()

toString(): string

Defined in: ECS/Systems/EntitySystem.ts:634

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

Returns

string

系统信息字符串

Inherited from

EntitySystem.toString

onAdded()

protected onAdded(entity): void

Defined in: ECS/Systems/EntitySystem.ts:680

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

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

Parameters

entity

Entity

被添加的实体

Returns

void

Inherited from

EntitySystem.onAdded

onRemoved()

protected onRemoved(entity): void

Defined in: ECS/Systems/EntitySystem.ts:691

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

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

Parameters

entity

Entity

被移除的实体

Returns

void

Inherited from

EntitySystem.onRemoved

addEventListener()

protected addEventListener<T>(eventType, handler, config?): void

Defined in: ECS/Systems/EntitySystem.ts:705

添加事件监听器

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

Type Parameters

T

T = any

Parameters

eventType

string

事件类型

handler

EventHandler<T>

事件处理函数

config?

EventListenerConfig

监听器配置

Returns

void

Inherited from

EntitySystem.addEventListener

removeEventListener()

protected removeEventListener<T>(eventType, handler): void

Defined in: ECS/Systems/EntitySystem.ts:734

移除特定的事件监听器

Type Parameters

T

T = any

Parameters

eventType

string

事件类型

handler

EventHandler<T>

事件处理函数

Returns

void

Inherited from

EntitySystem.removeEventListener

destroy()

destroy(): void

Defined in: ECS/Systems/EntitySystem.ts:773

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

Returns

void

Inherited from

EntitySystem.destroy

getDefaultEntityDataSize()

abstract protected getDefaultEntityDataSize(): number

Defined in: ECS/Systems/WorkerEntitySystem.ts:264

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

Returns

number

process()

protected process(entities): void

Defined in: ECS/Systems/WorkerEntitySystem.ts:428

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

Parameters

entities

readonly Entity[]

Returns

void

Overrides

EntitySystem.process

writeEntityToBuffer()

abstract protected writeEntityToBuffer(entityData, offset): void

Defined in: ECS/Systems/WorkerEntitySystem.ts:607

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

Parameters

entityData

TEntityData

实体数据

offset

number

在SharedArrayBuffer中的偏移位置（Float32索引）

Returns

void

readEntityFromBuffer()

abstract protected readEntityFromBuffer(offset): null | TEntityData

Defined in: ECS/Systems/WorkerEntitySystem.ts:684

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

Parameters

offset

number

在SharedArrayBuffer中的偏移位置（Float32索引）

Returns

null | TEntityData

实体数据或null

getSharedArrayBufferProcessFunction()?

protected optional getSharedArrayBufferProcessFunction(): SharedArrayBufferProcessFunction

Defined in: ECS/Systems/WorkerEntitySystem.ts:690

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

Returns

SharedArrayBufferProcessFunction

extractEntityData()

abstract protected extractEntityData(entity): TEntityData

Defined in: ECS/Systems/WorkerEntitySystem.ts:697

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

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

Parameters

entity

Entity

Returns

TEntityData

workerProcess()

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

Defined in: ECS/Systems/WorkerEntitySystem.ts:707

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

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

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

Parameters

entities

TEntityData[]

deltaTime

number

systemConfig?

any

Returns

TEntityData[] | Promise<TEntityData[]>

applyResult()

abstract protected applyResult(entity, result): void

Defined in: ECS/Systems/WorkerEntitySystem.ts:718

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

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

Parameters

entity

Entity

result

TEntityData

Returns

void

updateConfig()

updateConfig(newConfig): void

Defined in: ECS/Systems/WorkerEntitySystem.ts:723

更新Worker配置

Parameters

newConfig

Partial<WorkerSystemConfig>

Returns

void

getWorkerInfo()

getWorkerInfo(): object

Defined in: 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: ECS/Systems/WorkerEntitySystem.ts:842

销毁系统时清理Worker池

Returns

void

Overrides

EntitySystem.onDestroy

getLoggerName()

protected getLoggerName(): string

Defined in: ECS/Systems/WorkerEntitySystem.ts:851

获取Logger名称子类可以重写此方法来自定义logger名称

Returns

string

Overrides

EntitySystem.getLoggerName

Abstract Class: WorkerEntitySystem<TEntityData> ​

Example ​

Extends ​

Type Parameters ​

TEntityData ​

Constructors ​

Constructor ​

Parameters ​

matcher? ​

config? ​

Returns ​

Overrides ​

Properties ​

logger ​

Inherited from ​

config ​

Type Declaration ​

systemConfig? ​

entitiesPerWorker? ​

sharedBuffer ​

sharedFloatArray ​

Accessors ​

entities ​

Get Signature ​

Returns ​

Inherited from ​

updateOrder ​

Get Signature ​

Returns ​

Set Signature ​

Parameters ​

value ​

Returns ​

Inherited from ​

enabled ​

Get Signature ​

Returns ​

Set Signature ​

Parameters ​

value ​

Returns ​

Inherited from ​

systemName ​

Get Signature ​

Returns ​

Inherited from ​

scene ​

Get Signature ​

Returns ​

Set Signature ​

Parameters ​

value ​

Returns ​

Inherited from ​

matcher ​

Get Signature ​

Returns ​

Inherited from ​

Methods ​

setUpdateOrder() ​

Parameters ​

order ​

Returns ​

Inherited from ​

initialize() ​

Returns ​

Inherited from ​

onInitialize() ​

Returns ​

Inherited from ​

clearEntityCache() ​

Returns ​

Inherited from ​

reset() ​

Returns ​

Inherited from ​

update() ​

Returns ​

Inherited from ​

lateUpdate() ​

Abstract Class: WorkerEntitySystem<TEntityData>

Example

Extends

Type Parameters

TEntityData

Constructors

Constructor

Parameters

matcher?

config?

Returns

Overrides

Properties

logger

Inherited from

config

Type Declaration

systemConfig?

entitiesPerWorker?

sharedBuffer

sharedFloatArray

Accessors

entities

Get Signature

Returns

Inherited from

updateOrder

Get Signature

Returns

Set Signature

Parameters

value

Returns

Inherited from

enabled

Get Signature

Returns

Set Signature

Parameters

value

Returns

Inherited from

systemName

Get Signature

Returns

Inherited from

scene

Get Signature

Returns

Set Signature

Parameters

value

Returns

Inherited from

matcher

Get Signature

Returns

Inherited from

Methods

setUpdateOrder()

Parameters

order

Returns

Inherited from

initialize()

Returns

Inherited from

onInitialize()

Returns

Inherited from

clearEntityCache()

Returns

Inherited from

reset()

Returns

Inherited from

update()

Returns

Inherited from

lateUpdate()