ECS Framework API / Scene

Class: Scene

Defined in: packages/core/src/ECS/Scene.ts:34

游戏场景默认实现类

实现IScene接口，提供场景的基础功能。推荐使用组合而非继承的方式来构建自定义场景。

Implements

IScene

Constructors

Constructor

new Scene(config?): Scene

Defined in: packages/core/src/ECS/Scene.ts:234

创建场景实例

Parameters

config?

ISceneConfig

Returns

Scene

Properties

name

name: string = ''

Defined in: packages/core/src/ECS/Scene.ts:40

场景名称

用于标识和调试的友好名称。

Implementation of

IScene.name

sceneData

readonly sceneData: Map<string, any>

Defined in: packages/core/src/ECS/Scene.ts:48

场景自定义数据

用于存储场景级别的配置和状态数据。

Implementation of

IScene.sceneData

entities

readonly entities: EntityList

Defined in: packages/core/src/ECS/Scene.ts:55

场景中的实体集合

管理场景内所有实体的生命周期。

Implementation of

IScene.entities

identifierPool

readonly identifierPool: IdentifierPool

Defined in: packages/core/src/ECS/Scene.ts:62

实体ID池

用于分配和回收实体的唯一标识符。

Implementation of

IScene.identifierPool

componentStorageManager

readonly componentStorageManager: ComponentStorageManager

Defined in: packages/core/src/ECS/Scene.ts:69

组件存储管理器

高性能的组件存储和查询系统。

Implementation of

IScene.componentStorageManager

querySystem

readonly querySystem: QuerySystem

Defined in: packages/core/src/ECS/Scene.ts:76

查询系统

基于位掩码的高性能实体查询系统。

Implementation of

IScene.querySystem

eventSystem

readonly eventSystem: TypeSafeEventSystem

Defined in: packages/core/src/ECS/Scene.ts:83

事件系统

类型安全的事件系统。

Implementation of

IScene.eventSystem

referenceTracker

readonly referenceTracker: ReferenceTracker

Defined in: packages/core/src/ECS/Scene.ts:90

引用追踪器

追踪Component中对Entity的引用，当Entity销毁时自动清理引用。

Implementation of

IScene.referenceTracker

Accessors

systems

Get Signature

get systems(): EntitySystem[]

Defined in: packages/core/src/ECS/Scene.ts:150

获取场景中所有已注册的EntitySystem

按updateOrder排序。使用缓存机制，仅在系统变化时重新排序。

Returns

EntitySystem[]

系统列表

获取系统列表

Implementation of

IScene.systems

services

Get Signature

get services(): ServiceContainer

Defined in: packages/core/src/ECS/Scene.ts:227

获取场景的服务容器

用于注册和解析场景级别的服务（如EntitySystem）。

Example

typescript

// 注册服务
scene.services.registerSingleton(PhysicsSystem);

// 解析服务
const physics = scene.services.resolve(PhysicsSystem);

Returns

ServiceContainer

服务容器

场景级别的依赖注入容器，用于管理服务的生命周期。

Implementation of

IScene.services

performanceMonitor

Get Signature

get performanceMonitor(): PerformanceMonitor

Defined in: packages/core/src/ECS/Scene.ts:254

获取性能监控器

从 ServiceContainer 获取，如果未注册则创建默认实例（向后兼容）

Returns

PerformanceMonitor

Methods

getSystem()

getSystem<T>(systemType): null | T

Defined in: packages/core/src/ECS/Scene.ts:200

通过类型获取System实例

Type Parameters

T

T extends EntitySystem

Parameters

systemType

ServiceType<T>

System类型

Returns

null | T

System实例，如果未找到则返回null

Example

typescript

const physics = scene.getSystem(PhysicsSystem);
if (physics) {
    physics.doSomething();
}

Implementation of

IScene.getSystem

markSystemsOrderDirty()

markSystemsOrderDirty(): void

Defined in: packages/core/src/ECS/Scene.ts:209

标记系统顺序为脏

当系统列表或顺序发生变化时调用，使缓存失效

Returns

void

initialize()

initialize(): void

Defined in: packages/core/src/ECS/Scene.ts:266

初始化场景

在场景创建时调用，子类可以重写此方法来设置初始实体和组件。

Returns

void

Implementation of

IScene.initialize

onStart()

onStart(): void

Defined in: packages/core/src/ECS/Scene.ts:273

场景开始运行时的回调

在场景开始运行时调用，可以在此方法中执行场景启动逻辑。

Returns

void

Implementation of

IScene.onStart

unload()

unload(): void

Defined in: packages/core/src/ECS/Scene.ts:280

场景卸载时的回调

在场景被销毁时调用，可以在此方法中执行清理工作。

Returns

void

Implementation of

IScene.unload

begin()

begin(): void

Defined in: packages/core/src/ECS/Scene.ts:287

开始场景，启动实体处理器等

这个方法会启动场景。它将启动实体处理器等，并调用onStart方法。

Returns

void

Implementation of

IScene.begin

end()

end(): void

Defined in: packages/core/src/ECS/Scene.ts:308

结束场景，清除实体、实体处理器等

这个方法会结束场景。它将移除所有实体，结束实体处理器等，并调用unload方法。

执行顺序：

调用 unload() - 用户可以在此访问实体和系统进行清理
清理所有实体
清空服务容器，触发所有系统的 onDestroy()

注意：

onRemoved 回调不会在 Scene.end() 时触发，因为这是批量销毁场景
用户清理：在 Scene.unload() 中处理（可访问实体和系统）
系统清理：在 System.onDestroy() 中处理（实体已被清理）

Returns

void

Implementation of

IScene.end

update()

update(): void

Defined in: packages/core/src/ECS/Scene.ts:336

更新场景

Returns

void

Implementation of

IScene.update

createEntity()

createEntity(name): Entity

Defined in: packages/core/src/ECS/Scene.ts:394

将实体添加到此场景，并返回它

Parameters

name

string

实体名称

Returns

Entity

Implementation of

IScene.createEntity

clearSystemEntityCaches()

clearSystemEntityCaches(): void

Defined in: packages/core/src/ECS/Scene.ts:406

清除所有EntitySystem的实体缓存当实体或组件发生变化时调用

Returns

void

Implementation of

IScene.clearSystemEntityCaches

addEntity()

addEntity(entity, deferCacheClear): Entity

Defined in: packages/core/src/ECS/Scene.ts:417

在场景的实体列表中添加一个实体

Parameters

entity

Entity

要添加的实体

deferCacheClear

boolean = false

是否延迟缓存清理（用于批量操作）

Returns

Entity

Implementation of

IScene.addEntity

createEntities()

createEntities(count, namePrefix): Entity[]

Defined in: packages/core/src/ECS/Scene.ts:441

批量创建实体（高性能版本）

Parameters

count

number

要创建的实体数量

namePrefix

string = 'Entity'

实体名称前缀

Returns

Entity[]

创建的实体列表

Implementation of

IScene.createEntities

destroyEntities()

destroyEntities(entities): void

Defined in: packages/core/src/ECS/Scene.ts:468

批量销毁实体

Parameters

entities

Entity[]

Returns

void

Implementation of

IScene.destroyEntities

destroyAllEntities()

destroyAllEntities(): void

Defined in: packages/core/src/ECS/Scene.ts:491

从场景中删除所有实体

Returns

void

Implementation of

IScene.destroyAllEntities

findEntity()

findEntity(name): null | Entity

Defined in: packages/core/src/ECS/Scene.ts:501

搜索并返回第一个具有名称的实体

Parameters

name

string

实体名称

Returns

null | Entity

Implementation of

IScene.findEntity

findEntityById()

findEntityById(id): null | Entity

Defined in: packages/core/src/ECS/Scene.ts:509

根据ID查找实体

Parameters

id

number

实体ID

Returns

null | Entity

Implementation of

IScene.findEntityById

findEntitiesByTag()

findEntitiesByTag(tag): Entity[]

Defined in: packages/core/src/ECS/Scene.ts:517

根据标签查找实体

Parameters

tag

number

实体标签

Returns

Entity[]

Implementation of

IScene.findEntitiesByTag

getEntityByName()

getEntityByName(name): null | Entity

Defined in: packages/core/src/ECS/Scene.ts:533

根据名称查找实体（别名方法）

Parameters

name

string

实体名称

Returns

null | Entity

Deprecated

请使用 findEntity() 代替此方法

Implementation of

IScene.getEntityByName

getEntitiesByTag()

getEntitiesByTag(tag): Entity[]

Defined in: packages/core/src/ECS/Scene.ts:543

根据标签查找实体（别名方法）

Parameters

tag

number

实体标签

Returns

Entity[]

Deprecated

请使用 findEntitiesByTag() 代替此方法

Implementation of

IScene.getEntitiesByTag

queryAll()

queryAll(...componentTypes): object

Defined in: packages/core/src/ECS/Scene.ts:562

查询拥有所有指定组件的实体

Parameters

componentTypes

...ComponentType[]

组件类型数组

Returns

object

查询结果

entities

entities: readonly Entity[]

Example

typescript

const result = scene.queryAll(Position, Velocity);
for (const entity of result.entities) {
    const pos = entity.getComponent(Position);
    const vel = entity.getComponent(Velocity);
}

Implementation of

IScene.queryAll

queryAny()

queryAny(...componentTypes): object

Defined in: packages/core/src/ECS/Scene.ts:572

查询拥有任意一个指定组件的实体

Parameters

componentTypes

...ComponentType[]

组件类型数组

Returns

object

查询结果

entities

entities: readonly Entity[]

Implementation of

IScene.queryAny

queryNone()

queryNone(...componentTypes): object

Defined in: packages/core/src/ECS/Scene.ts:582

查询不包含指定组件的实体

Parameters

componentTypes

...ComponentType[]

组件类型数组

Returns

object

查询结果

entities

entities: readonly Entity[]

Implementation of

IScene.queryNone

query()

query(): TypedQueryBuilder

Defined in: packages/core/src/ECS/Scene.ts:607

创建类型安全的查询构建器

Returns

TypedQueryBuilder

查询构建器，支持链式调用

Example

typescript

// 使用查询构建器
const matcher = scene.query()
    .withAll(Position, Velocity)
    .withNone(Disabled)
    .buildMatcher();

// 在System中使用
class MovementSystem extends EntitySystem {
    constructor() {
        super(matcher);
    }
}

Implementation of

IScene.query

addEntityProcessor()

addEntityProcessor<T>(systemTypeOrInstance): T

Defined in: packages/core/src/ECS/Scene.ts:637

在场景中添加一个EntitySystem处理器

支持两种使用方式：

传入类型（推荐）：自动使用DI创建实例，支持@Injectable和@Inject装饰器
传入实例：直接使用提供的实例

Type Parameters

T

T extends EntitySystem

Parameters

systemTypeOrInstance

系统类型或系统实例

T | ServiceType<T>

Returns

T

添加的处理器实例

Example

typescript

// 方式1：传入类型，自动DI（推荐）
@Injectable()
class PhysicsSystem extends EntitySystem {
    constructor(@Inject(CollisionSystem) private collision: CollisionSystem) {
        super(Matcher.empty().all(Transform));
    }
}
scene.addEntityProcessor(PhysicsSystem);

// 方式2：传入实例
const system = new MySystem();
scene.addEntityProcessor(system);

Implementation of

IScene.addEntityProcessor

registerSystems()

registerSystems(systemTypes): EntitySystem[]

Defined in: packages/core/src/ECS/Scene.ts:735

批量注册EntitySystem到场景（使用DI）

自动按照依赖顺序注册多个System。所有System必须使用@Injectable装饰器标记。

Parameters

systemTypes

ServiceType<EntitySystem>[]

System类型数组

Returns

EntitySystem[]

注册的System实例数组

Example

typescript

@Injectable()
@ECSSystem('Collision', { updateOrder: 5 })
class CollisionSystem extends EntitySystem implements IService {
    constructor() { super(Matcher.empty().all(Collider)); }
    dispose() {}
}

@Injectable()
@ECSSystem('Physics', { updateOrder: 10 })
class PhysicsSystem extends EntitySystem implements IService {
    constructor(@Inject(CollisionSystem) private collision: CollisionSystem) {
        super(Matcher.empty().all(Transform, RigidBody));
    }
    dispose() {}
}

// 批量注册（自动解析依赖顺序）
scene.registerSystems([
    CollisionSystem,
    PhysicsSystem,  // 自动注入CollisionSystem
    RenderSystem
]);

Implementation of

IScene.registerSystems

addSystem()

addSystem(system): EntitySystem

Defined in: packages/core/src/ECS/Scene.ts:750

添加系统到场景（addEntityProcessor的别名）

Parameters

system

EntitySystem

系统

Returns

EntitySystem

Implementation of

IScene.addSystem

removeEntityProcessor()

removeEntityProcessor(processor): void

Defined in: packages/core/src/ECS/Scene.ts:758

从场景中删除EntitySystem处理器

Parameters

processor

EntitySystem

要删除的处理器

Returns

void

Implementation of

IScene.removeEntityProcessor

removeSystem()

removeSystem(system): void

Defined in: packages/core/src/ECS/Scene.ts:775

从场景中删除系统（removeEntityProcessor的别名）

Parameters

system

EntitySystem

系统

Returns

void

Implementation of

IScene.removeSystem

getEntityProcessor()

getEntityProcessor<T>(type): null | T

Defined in: packages/core/src/ECS/Scene.ts:797

获取指定类型的EntitySystem处理器

Type Parameters

T

T extends EntitySystem

Parameters

type

(...args) => T

处理器类型

Returns

null | T

处理器实例，如果未找到则返回null

Deprecated

推荐使用依赖注入代替此方法。使用 scene.services.resolve(SystemType) 或在System构造函数中使用 @Inject(SystemType) 装饰器。

Example

typescript

@Injectable()
class MySystem extends EntitySystem {
    constructor(@Inject(PhysicsSystem) private physics: PhysicsSystem) {
        super();
    }
}

Implementation of

IScene.getEntityProcessor

getStats()

getStats(): object

Defined in: packages/core/src/ECS/Scene.ts:804

获取场景统计信息

Returns

object

entityCount

entityCount: number

processorCount

processorCount: number

componentStorageStats

componentStorageStats: Map<string, { totalSlots: number; usedSlots: number; freeSlots: number; fragmentation: number; }>

Implementation of

IScene.getStats

getDebugInfo()

getDebugInfo(): object

Defined in: packages/core/src/ECS/Scene.ts:819

获取场景的调试信息

Returns

object

name

name: string

entityCount

entityCount: number

processorCount

processorCount: number

isRunning

isRunning: boolean

entities

entities: object[]

processors

processors: object[]

componentStats

componentStats: Map<string, { totalSlots: number; usedSlots: number; freeSlots: number; fragmentation: number; }>

Implementation of

IScene.getDebugInfo

serialize()

serialize(options?): string | Uint8Array<ArrayBufferLike>

Defined in: packages/core/src/ECS/Scene.ts:880

序列化场景

将场景及其所有实体、组件序列化为JSON字符串或二进制Uint8Array

Parameters

options?

SceneSerializationOptions

序列化选项

Returns

string | Uint8Array<ArrayBufferLike>

序列化后的数据（JSON字符串或二进制Uint8Array）

Example

typescript

// JSON格式
const jsonData = scene.serialize({
    format: 'json',
    pretty: true
});

// 二进制格式（更小、更快）
const binaryData = scene.serialize({
    format: 'binary'
});

Implementation of

IScene.serialize

deserialize()

deserialize(saveData, options?): void

Defined in: packages/core/src/ECS/Scene.ts:905

反序列化场景

从序列化数据恢复场景状态

Parameters

saveData

序列化的数据（JSON字符串或二进制Uint8Array）

string | Uint8Array<ArrayBufferLike>

options?

SceneDeserializationOptions

反序列化选项

Returns

void

Example

typescript

// 从JSON恢复（自动从ComponentRegistry获取组件类型）
scene.deserialize(jsonData, {
    strategy: 'replace'
});

// 从二进制恢复
scene.deserialize(binaryData, {
    strategy: 'replace'
});

Implementation of

IScene.deserialize

createIncrementalSnapshot()

createIncrementalSnapshot(options?): void

Defined in: packages/core/src/ECS/Scene.ts:933

创建增量序列化的基础快照

在需要进行增量序列化前，先调用此方法创建基础快照

Parameters

options?

IncrementalSerializationOptions

序列化选项

Returns

void

Example

typescript

// 创建基础快照
scene.createIncrementalSnapshot();

// 进行一些修改...
entity.addComponent(new PositionComponent(100, 200));

// 计算增量变更
const incremental = scene.serializeIncremental();

Implementation of

IScene.createIncrementalSnapshot

serializeIncremental()

serializeIncremental(options?): IncrementalSnapshot

Defined in: packages/core/src/ECS/Scene.ts:962

增量序列化场景

只序列化相对于基础快照的变更部分

Parameters

options?

IncrementalSerializationOptions

序列化选项

Returns

IncrementalSnapshot

增量快照对象

Example

typescript

// 创建基础快照
scene.createIncrementalSnapshot();

// 修改场景
const entity = scene.createEntity('NewEntity');
entity.addComponent(new PositionComponent(50, 100));

// 获取增量变更
const incremental = scene.serializeIncremental();
console.log(`变更数量: ${incremental.entityChanges.length}`);

// 序列化为JSON
const json = IncrementalSerializer.serializeIncremental(incremental);

Implementation of

IScene.serializeIncremental

applyIncremental()

applyIncremental(incremental, componentRegistry?): void

Defined in: packages/core/src/ECS/Scene.ts:990

应用增量变更到场景

Parameters

incremental

增量快照数据（IncrementalSnapshot对象、JSON字符串或二进制Uint8Array）

string | Uint8Array<ArrayBufferLike> | IncrementalSnapshot

componentRegistry?

Map<string, ComponentType>

组件类型注册表（可选，默认使用全局注册表）

Returns

void

Example

typescript

// 应用增量变更对象
scene.applyIncremental(incrementalSnapshot);

// 从JSON字符串应用
const jsonData = IncrementalSerializer.serializeIncremental(snapshot, { format: 'json' });
scene.applyIncremental(jsonData);

// 从二进制Uint8Array应用
const binaryData = IncrementalSerializer.serializeIncremental(snapshot, { format: 'binary' });
scene.applyIncremental(binaryData);

Implementation of

IScene.applyIncremental

updateIncrementalSnapshot()

updateIncrementalSnapshot(options?): void

Defined in: packages/core/src/ECS/Scene.ts:1027

更新增量快照基准

将当前场景状态设为新的增量序列化基准

Parameters

options?

IncrementalSerializationOptions

序列化选项

Returns

void

Example

typescript

// 创建初始快照
scene.createIncrementalSnapshot();

// 进行一些修改并序列化
const incremental1 = scene.serializeIncremental();

// 更新基准，之后的增量将基于当前状态
scene.updateIncrementalSnapshot();

// 继续修改
const incremental2 = scene.serializeIncremental();

Implementation of

IScene.updateIncrementalSnapshot

clearIncrementalSnapshot()

clearIncrementalSnapshot(): void

Defined in: packages/core/src/ECS/Scene.ts:1036

清除增量快照

释放快照占用的内存

Returns

void

Implementation of

IScene.clearIncrementalSnapshot

hasIncrementalSnapshot()

hasIncrementalSnapshot(): boolean

Defined in: packages/core/src/ECS/Scene.ts:1045

检查是否有增量快照

Returns

boolean

如果已创建增量快照返回true

Implementation of

IScene.hasIncrementalSnapshot

Class: Scene ​

Implements ​

Constructors ​

Constructor ​

Parameters ​

config? ​

Returns ​

Properties ​

name ​

Implementation of ​

sceneData ​

Implementation of ​

entities ​

Implementation of ​

identifierPool ​

Implementation of ​

componentStorageManager ​

Implementation of ​

querySystem ​

Implementation of ​

eventSystem ​

Implementation of ​

referenceTracker ​

Implementation of ​

Accessors ​

systems ​

Get Signature ​

Returns ​

Implementation of ​

services ​

Get Signature ​

Example ​

Returns ​

Implementation of ​

performanceMonitor ​

Get Signature ​

Returns ​

Methods ​

getSystem() ​

Type Parameters ​

T ​

Parameters ​

systemType ​

Returns ​

Example ​

Implementation of ​

markSystemsOrderDirty() ​

Returns ​

initialize() ​

Returns ​

Implementation of ​

onStart() ​

Returns ​

Implementation of ​

unload() ​

Returns ​

Implementation of ​

begin() ​

Returns ​

Implementation of ​

end() ​

Returns ​

Implementation of ​

update() ​

Returns ​

Implementation of ​

createEntity() ​

Parameters ​

name ​

Returns ​

Implementation of ​

clearSystemEntityCaches() ​

Returns ​

Implementation of ​

addEntity() ​

Parameters ​

entity ​

deferCacheClear ​

Returns ​

Implementation of ​

Class: Scene

Implements

Constructors

Constructor

Parameters

config?

Returns

Properties

name

Implementation of

sceneData

Implementation of

entities

Implementation of

identifierPool

Implementation of

componentStorageManager

Implementation of

querySystem

Implementation of

eventSystem

Implementation of

referenceTracker

Implementation of

Accessors

systems

Get Signature

Returns

Implementation of

services

Get Signature

Example

Returns

Implementation of

performanceMonitor

Get Signature

Returns

Methods

getSystem()

Type Parameters

T

Parameters

systemType

Returns

Example

Implementation of

markSystemsOrderDirty()

Returns

initialize()

Returns

Implementation of

onStart()

Returns

Implementation of

unload()

Returns

Implementation of

begin()

Returns

Implementation of

end()

Returns

Implementation of

update()

Returns

Implementation of

createEntity()

Parameters

name

Returns

Implementation of

clearSystemEntityCaches()

Returns

Implementation of

addEntity()

Parameters

entity

deferCacheClear

Returns

Implementation of