ECS Framework API / PassiveSystem

Abstract Class: PassiveSystem

Defined in: packages/core/src/ECS/Systems/PassiveSystem.ts:10

被动实体系统定义一个被动的实体系统，继承自EntitySystem类被动的实体系统不会对实体进行任何修改，只会被动地接收实体的变化事件

Extends

EntitySystem

Constructors

Constructor

new PassiveSystem(matcher?): PassiveSystem

Defined in: packages/core/src/ECS/Systems/PassiveSystem.ts:12

Parameters

matcher?

Matcher

Returns

PassiveSystem

Overrides

EntitySystem.constructor

Properties

logger

protected logger: ILogger

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

Inherited from

EntitySystem.logger

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

getLoggerName()

protected getLoggerName(): string

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

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

Returns

string

Inherited from

EntitySystem.getLoggerName

onDestroy()

protected onDestroy(): void

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

用户销毁回调

当系统从场景中移除时调用，子类可以重写此方法进行清理操作。注意：事件监听器会被框架自动清理，无需手动处理。

Returns

void

Inherited from

EntitySystem.onDestroy

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

process()

protected process(_entities): void

Defined in: packages/core/src/ECS/Systems/PassiveSystem.ts:20

不进行任何处理

Parameters

_entities

Entity[]

Returns

void

Overrides

EntitySystem.process

Abstract Class: PassiveSystem ​

Extends ​

Constructors ​

Constructor ​

Parameters ​

matcher? ​

Returns ​

Overrides ​

Properties ​

logger ​

Inherited from ​

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 ​

setPerformanceMonitor() ​

Parameters ​

monitor ​

Returns ​

Inherited from ​

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() ​

Returns ​

Inherited from ​

onBegin() ​

Returns ​

Inherited from ​

Abstract Class: PassiveSystem

Extends

Constructors

Constructor

Parameters

matcher?

Returns

Overrides

Properties

logger

Inherited from

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

setPerformanceMonitor()

Parameters

monitor

Returns

Inherited from

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()

Returns

Inherited from

onBegin()

Returns

Inherited from