ECS Framework API / WorkerEntitySystem
Abstract Class: WorkerEntitySystem<TEntityData>
Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:190
支持Worker并行处理的EntitySystem基类
支持传统Worker和SharedArrayBuffer两种优化模式:
- 传统模式:数据序列化传输,适用于复杂计算
- SharedArrayBuffer模式:零拷贝数据共享,适用于大量简单计算
用户需要实现:
- extractEntityData - 定义数据提取逻辑
- workerProcess - 编写处理函数(纯函数,可序列化)
- applyResult - 定义结果应用逻辑
- (可选) SharedArrayBuffer相关方法
Example
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?
config?
WorkerSystemConfig = {}
Returns
WorkerEntitySystem<TEntityData>
Overrides
Properties
logger
protectedlogger:ILogger
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:77
Inherited from
config
protectedconfig:Required<Omit<WorkerSystemConfig,"systemConfig"|"entitiesPerWorker">> &object
Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:191
Type Declaration
systemConfig?
optionalsystemConfig:any
entitiesPerWorker?
optionalentitiesPerWorker:number
sharedBuffer
protectedsharedBuffer:null|SharedArrayBuffer=null
Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:197
sharedFloatArray
protectedsharedFloatArray: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
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
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
systemName
Get Signature
get systemName():
string
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:136
获取系统名称
Returns
string
系统名称
Inherited from
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
matcher
Get Signature
get matcher():
Matcher
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:193
获取实体匹配器
Returns
Inherited from
Methods
setPerformanceMonitor()
setPerformanceMonitor(
monitor):void
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:174
设置性能监控器
Parameters
monitor
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
initialize()
initialize():
void
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:212
系统初始化(框架调用)
在系统创建时调用。框架内部使用,用户不应直接调用。
Returns
void
Inherited from
onInitialize()
protectedonInitialize():void
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:236
系统初始化回调
子类可以重写此方法进行初始化操作。
Returns
void
Inherited from
clearEntityCache()
clearEntityCache():
void
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:244
清除实体缓存(内部使用) 当Scene中的实体发生变化时调用
Returns
void
Inherited from
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
update()
update():
void
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:542
更新系统
Returns
void
Inherited from
lateUpdate()
lateUpdate():
void
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:568
后期更新系统
Returns
void
Inherited from
onBegin()
protectedonBegin():void
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:595
在系统处理开始前调用
子类可以重写此方法进行预处理操作。
Returns
void
Inherited from
lateProcess()
protectedlateProcess(_entities):void
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:617
后期处理实体列表
在主要处理逻辑之后执行,子类可以重写此方法。
Parameters
_entities
readonly Entity[]
Returns
void
Inherited from
onEnd()
protectedonEnd():void
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:626
系统处理完毕后调用
子类可以重写此方法进行后处理操作。
Returns
void
Inherited from
onCheckProcessing()
protectedonCheckProcessing():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
onAdded()
protectedonAdded(_entity):void
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:718
当实体被添加到系统时调用
子类可以重写此方法来处理实体添加事件。
Parameters
_entity
Returns
void
Inherited from
onRemoved()
protectedonRemoved(_entity):void
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:729
当实体从系统中移除时调用
子类可以重写此方法来处理实体移除事件。
Parameters
_entity
Returns
void
Inherited from
dispose()
dispose():
void
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:747
释放系统资源
实现IService接口要求的dispose方法。 当系统从Scene中移除或Scene销毁时调用。
默认行为:
- 移除所有事件监听器
- 调用 onDestroy 回调(仅首次)
- 清空所有缓存
- 重置初始化状态
子类可以重写此方法来清理自定义资源,但应该调用super.dispose()。
Returns
void
Inherited from
addEventListener()
protectedaddEventListener<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?
监听器配置
Returns
null | string
监听器引用ID,可用于手动移除监听器
Inherited from
removeEventListener()
protectedremoveEventListener(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
requireComponent()
protectedrequireComponent<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
实体
componentType
T
组件类型
Returns
组件实例(保证非空)
Throws
如果组件不存在则抛出错误
Example
protected process(entities: readonly Entity[]): void {
for (const entity of entities) {
const transform = this.requireComponent(entity, Transform);
// transform 保证非空,类型为 Transform
}
}Inherited from
getComponents()
protectedgetComponents<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
实体
components
...T
组件类型数组
Returns
{ [K in string | number | symbol]: ComponentInstance<T[K<K>]> }
组件实例元组
Example
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
forEach()
protectedforEach(entities,processor):void
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:961
遍历实体并处理每个实体
提供更简洁的语法糖,避免手动遍历
Parameters
entities
readonly Entity[]
实体列表
processor
(entity, index) => void
处理函数
Returns
void
Example
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
filterEntities()
protectedfilterEntities(entities,predicate):Entity[]
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:984
过滤实体
Parameters
entities
readonly Entity[]
实体列表
predicate
(entity, index) => boolean
过滤条件
Returns
Entity[]
过滤后的实体数组
Example
protected process(entities: readonly Entity[]): void {
const activeEntities = this.filterEntities(entities, (entity) => {
const health = this.requireComponent(entity, Health);
return health.value > 0;
});
}Inherited from
mapEntities()
protectedmapEntities<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
protected process(entities: readonly Entity[]): void {
const positions = this.mapEntities(entities, (entity) => {
const transform = this.requireComponent(entity, Transform);
return transform.position;
});
}Inherited from
findEntity()
protectedfindEntity(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
protected process(entities: readonly Entity[]): void {
const player = this.findEntity(entities, (entity) =>
entity.hasComponent(PlayerTag)
);
}Inherited from
someEntity()
protectedsomeEntity(entities,predicate):boolean
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:1057
检查是否存在满足条件的实体
Parameters
entities
readonly Entity[]
实体列表
predicate
(entity, index) => boolean
检查条件
Returns
boolean
是否存在满足条件的实体
Example
protected process(entities: readonly Entity[]): void {
const hasLowHealth = this.someEntity(entities, (entity) => {
const health = this.requireComponent(entity, Health);
return health.value < 20;
});
}Inherited from
everyEntity()
protectedeveryEntity(entities,predicate):boolean
Defined in: packages/core/src/ECS/Systems/EntitySystem.ts:1083
检查是否所有实体都满足条件
Parameters
entities
readonly Entity[]
实体列表
predicate
(entity, index) => boolean
检查条件
Returns
boolean
是否所有实体都满足条件
Example
protected process(entities: readonly Entity[]): void {
const allHealthy = this.everyEntity(entities, (entity) => {
const health = this.requireComponent(entity, Health);
return health.value > 50;
});
}Inherited from
getDefaultEntityDataSize()
abstractprotectedgetDefaultEntityDataSize():number
Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:264
获取实体数据大小 - 子类必须实现 返回每个实体在SharedArrayBuffer中占用的Float32数量
Returns
number
process()
protectedprocess(entities):void
Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:425
重写process方法,支持Worker并行处理
Parameters
entities
readonly Entity[]
Returns
void
Overrides
writeEntityToBuffer()
abstractprotectedwriteEntityToBuffer(entityData,offset):void
Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:607
将单个实体数据写入SharedArrayBuffer - 子类必须实现
Parameters
entityData
TEntityData
实体数据
offset
number
在SharedArrayBuffer中的偏移位置(Float32索引)
Returns
void
readEntityFromBuffer()
abstractprotectedreadEntityFromBuffer(offset):null|TEntityData
Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:684
从SharedArrayBuffer读取单个实体数据 - 子类必须实现
Parameters
offset
number
在SharedArrayBuffer中的偏移位置(Float32索引)
Returns
null | TEntityData
实体数据或null
getSharedArrayBufferProcessFunction()?
protectedoptionalgetSharedArrayBufferProcessFunction():SharedArrayBufferProcessFunction
Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:690
获取SharedArrayBuffer处理函数 - 子类可选实现 返回一个函数,该函数将被序列化到Worker中执行
Returns
SharedArrayBufferProcessFunction
extractEntityData()
abstractprotectedextractEntityData(entity):TEntityData
Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:697
提取实体数据 - 子类必须实现
将Entity转换为可序列化的数据对象
Parameters
entity
Returns
TEntityData
workerProcess()
abstractprotectedworkerProcess(entities,deltaTime,systemConfig?):TEntityData[] |Promise<TEntityData[]>
Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:707
Worker处理函数 - 子类必须实现
这个函数会被序列化并在Worker中执行,因此:
- 必须是纯函数,不能访问外部变量
- 不能使用闭包或this
- 只能使用标准JavaScript API
Parameters
entities
TEntityData[]
deltaTime
number
systemConfig?
any
Returns
TEntityData[] | Promise<TEntityData[]>
applyResult()
abstractprotectedapplyResult(entity,result):void
Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:718
应用处理结果 - 子类必须实现
将Worker处理的结果应用回Entity的组件
Parameters
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?
optionalentitiesPerWorker:number
maxSystemWorkerCount
maxSystemWorkerCount:
number
isProcessing
isProcessing:
boolean
sharedArrayBufferSupported
sharedArrayBufferSupported:
boolean
sharedArrayBufferEnabled
sharedArrayBufferEnabled:
boolean
currentMode
currentMode:
"worker"|"shared-buffer"|"sync"
onDestroy()
protectedonDestroy():void
Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:842
销毁系统时清理Worker池
Returns
void
Overrides
getLoggerName()
protectedgetLoggerName():string
Defined in: packages/core/src/ECS/Systems/WorkerEntitySystem.ts:851
获取Logger名称 默认返回类的构造函数名称, 子类可以重写此方法来自定义logger名称
Returns
string