ECS Framework

Appearance

ECS Framework API v2.2.13

ECS Framework API / Entity

Class: Entity ​

Defined in: packages/core/src/ECS/Entity.ts:61

游戏实体类

ECS架构中的实体（Entity），作为组件的容器。 实体本身不包含游戏逻辑，所有功能都通过组件来实现。 支持父子关系，可以构建实体层次结构。

Example ​

typescript
// 创建实体
const entity = new Entity("Player", 1);

// 添加组件
const healthComponent = entity.addComponent(new HealthComponent(100));

// 获取组件
const health = entity.getComponent(HealthComponent);

// 添加位置组件
entity.addComponent(new PositionComponent(100, 200));

// 添加子实体
const weapon = new Entity("Weapon", 2);
entity.addChild(weapon);

Constructors ​

Constructor ​

new Entity(name, id): Entity

Defined in: packages/core/src/ECS/Entity.ts:138

构造函数

Parameters ​

name ​

string

实体名称

id ​

number

实体唯一标识符

Returns ​

Entity

Properties ​

entityComparer ​

static entityComparer: EntityComparer

Defined in: packages/core/src/ECS/Entity.ts:70

实体比较器实例

name ​

name: string

Defined in: packages/core/src/ECS/Entity.ts:75

实体名称

id ​

readonly id: number

Defined in: packages/core/src/ECS/Entity.ts:80

实体唯一标识符

scene ​

scene: null | IScene = null

Defined in: packages/core/src/ECS/Entity.ts:85

所属场景引用

Accessors ​

isDestroyed ​

Get Signature ​

get isDestroyed(): boolean

Defined in: packages/core/src/ECS/Entity.ts:147

获取销毁状态

Returns ​

boolean

如果实体已被销毁则返回true

components ​

Get Signature ​

get components(): readonly Component[]

Defined in: packages/core/src/ECS/Entity.ts:167

获取组件数组（懒加载）

Returns ​

readonly Component[]

只读的组件数组

parent ​

Get Signature ​

get parent(): null | Entity

Defined in: packages/core/src/ECS/Entity.ts:208

获取父实体

Returns ​

null | Entity

父实体，如果没有父实体则返回null

children ​

Get Signature ​

get children(): readonly Entity[]

Defined in: packages/core/src/ECS/Entity.ts:217

获取子实体数组的只读副本

Returns ​

readonly Entity[]

子实体数组的副本

childCount ​

Get Signature ​

get childCount(): number

Defined in: packages/core/src/ECS/Entity.ts:226

获取子实体数量

Returns ​

number

子实体的数量

active ​

Get Signature ​

get active(): boolean

Defined in: packages/core/src/ECS/Entity.ts:235

获取活跃状态

Returns ​

boolean

如果实体处于活跃状态则返回true

Set Signature ​

set active(value): void

Defined in: packages/core/src/ECS/Entity.ts:246

设置活跃状态

设置实体的活跃状态，会影响子实体的有效活跃状态。

Parameters ​
value ​

boolean

新的活跃状态

Returns ​

void

activeInHierarchy ​

Get Signature ​

get activeInHierarchy(): boolean

Defined in: packages/core/src/ECS/Entity.ts:260

获取实体的有效活跃状态

考虑父实体的活跃状态，只有当实体本身和所有父实体都处于活跃状态时才返回true。

Returns ​

boolean

有效的活跃状态

tag ​

Get Signature ​

get tag(): number

Defined in: packages/core/src/ECS/Entity.ts:271

获取实体标签

Returns ​

number

实体的数字标签

Set Signature ​

set tag(value): void

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

设置实体标签

Parameters ​
value ​

number

新的标签值

Returns ​

void

enabled ​

Get Signature ​

get enabled(): boolean

Defined in: packages/core/src/ECS/Entity.ts:289

获取启用状态

Returns ​

boolean

如果实体已启用则返回true

Set Signature ​

set enabled(value): void

Defined in: packages/core/src/ECS/Entity.ts:298

设置启用状态

Parameters ​
value ​

boolean

新的启用状态

Returns ​

void

updateOrder ​

Get Signature ​

get updateOrder(): number

Defined in: packages/core/src/ECS/Entity.ts:307

获取更新顺序

Returns ​

number

实体的更新顺序值

Set Signature ​

set updateOrder(value): void

Defined in: packages/core/src/ECS/Entity.ts:316

设置更新顺序

Parameters ​
value ​

number

新的更新顺序值

Returns ​

void

componentMask ​

Get Signature ​

get componentMask(): BitMask64Data

Defined in: packages/core/src/ECS/Entity.ts:325

获取组件位掩码

Returns ​

BitMask64Data

实体的组件位掩码

Methods ​

setDestroyedState() ​

setDestroyedState(destroyed): void

Defined in: packages/core/src/ECS/Entity.ts:159

Internal

设置销毁状态（内部使用）

此方法供Scene和批量操作使用，以提高性能。 不应在普通业务逻辑中调用，应使用destroy()方法。

Parameters ​

destroyed ​

boolean

Returns ​

void

createComponent() ​

createComponent<T>(componentType, ...args): T

Defined in: packages/core/src/ECS/Entity.ts:342

创建并添加组件

Type Parameters ​

T ​

T extends Component

Parameters ​

componentType ​

ComponentType<T>

组件类型构造函数

args ​

...any[]

组件构造函数参数

Returns ​

T

创建的组件实例

Example ​

typescript
const position = entity.createComponent(Position, 100, 200);
const health = entity.createComponent(Health, 100);

addComponent() ​

addComponent<T>(component): T

Defined in: packages/core/src/ECS/Entity.ts:397

添加组件到实体

Type Parameters ​

T ​

T extends Component

Parameters ​

component ​

T

要添加的组件实例

Returns ​

T

添加的组件实例

Throws ​

如果实体已存在该类型的组件

Example ​

typescript
const position = new Position(100, 200);
entity.addComponent(position);

getComponent() ​

getComponent<T>(type): null | T

Defined in: packages/core/src/ECS/Entity.ts:456

获取指定类型的组件

Type Parameters ​

T ​

T extends Component

Parameters ​

type ​

ComponentType<T>

组件类型构造函数

Returns ​

null | T

组件实例，如果不存在则返回null

Example ​

typescript
const position = entity.getComponent(Position);
if (position) {
    position.x += 10;
    position.y += 20;
}

hasComponent() ​

hasComponent<T>(type): boolean

Defined in: packages/core/src/ECS/Entity.ts:485

检查实体是否拥有指定类型的组件

Type Parameters ​

T ​

T extends Component

Parameters ​

type ​

ComponentType<T>

组件类型构造函数

Returns ​

boolean

如果实体拥有该组件返回true，否则返回false

Example ​

typescript
if (entity.hasComponent(Position)) {
    const position = entity.getComponent(Position)!;
    position.x += 10;
}

getOrCreateComponent() ​

getOrCreateComponent<T>(type, ...args): T

Defined in: packages/core/src/ECS/Entity.ts:510

获取或创建指定类型的组件

如果组件已存在则返回现有组件，否则创建新组件并添加到实体

Type Parameters ​

T ​

T extends Component

Parameters ​

type ​

ComponentType<T>

组件类型构造函数

args ​

...any[]

组件构造函数参数（仅在创建新组件时使用）

Returns ​

T

组件实例

Example ​

typescript
// 确保实体拥有Position组件
const position = entity.getOrCreateComponent(Position, 0, 0);
position.x = 100;

removeComponent() ​

removeComponent(component): void

Defined in: packages/core/src/ECS/Entity.ts:527

移除指定的组件

Parameters ​

component ​

Component

要移除的组件实例

Returns ​

void

removeComponentByType() ​

removeComponentByType<T>(type): null | T

Defined in: packages/core/src/ECS/Entity.ts:578

移除指定类型的组件

Type Parameters ​

T ​

T extends Component

Parameters ​

type ​

ComponentType<T>

组件类型

Returns ​

null | T

被移除的组件实例或null

removeAllComponents() ​

removeAllComponents(): void

Defined in: packages/core/src/ECS/Entity.ts:590

移除所有组件

Returns ​

void

addComponents() ​

addComponents<T>(components): T[]

Defined in: packages/core/src/ECS/Entity.ts:618

批量添加组件

Type Parameters ​

T ​

T extends Component

Parameters ​

components ​

T[]

要添加的组件数组

Returns ​

T[]

添加的组件数组

removeComponentsByTypes() ​

removeComponentsByTypes<T>(componentTypes): (null | T)[]

Defined in: packages/core/src/ECS/Entity.ts:638

批量移除组件类型

Type Parameters ​

T ​

T extends Component

Parameters ​

componentTypes ​

ComponentType<T>[]

要移除的组件类型数组

Returns ​

(null | T)[]

被移除的组件数组

getComponents() ​

getComponents<T>(type): T[]

Defined in: packages/core/src/ECS/Entity.ts:654

获取所有指定类型的组件

Type Parameters ​

T ​

T extends Component

Parameters ​

type ​

ComponentType<T>

组件类型

Returns ​

T[]

组件实例数组

getComponentByType() ​

getComponentByType<T>(baseType): null | T

Defined in: packages/core/src/ECS/Entity.ts:684

获取指定基类的组件（支持继承查找）

与 getComponent() 不同，此方法使用 instanceof 检查，支持子类查找。 性能比位掩码查询稍慢，但支持继承层次结构。

Type Parameters ​

T ​

T extends Component

Parameters ​

baseType ​

ComponentType<T>

组件基类类型

Returns ​

null | T

第一个匹配的组件实例，如果不存在则返回 null

Example ​

typescript
// 查找 CompositeNodeComponent 或其子类
const composite = entity.getComponentByType(CompositeNodeComponent);
if (composite) {
    // composite 可能是 SequenceNode, SelectorNode 等
}

addChild() ​

addChild(child): Entity

Defined in: packages/core/src/ECS/Entity.ts:699

添加子实体

Parameters ​

child ​

Entity

要添加的子实体

Returns ​

Entity

添加的子实体

removeChild() ​

removeChild(child): boolean

Defined in: packages/core/src/ECS/Entity.ts:729

移除子实体

Parameters ​

child ​

Entity

要移除的子实体

Returns ​

boolean

是否成功移除

removeAllChildren() ​

removeAllChildren(): void

Defined in: packages/core/src/ECS/Entity.ts:744

移除所有子实体

Returns ​

void

findChild() ​

findChild(name, recursive): null | Entity

Defined in: packages/core/src/ECS/Entity.ts:759

根据名称查找子实体

Parameters ​

name ​

string

子实体名称

recursive ​

boolean = false

是否递归查找

Returns ​

null | Entity

找到的子实体或null

findChildrenByTag() ​

findChildrenByTag(tag, recursive): Entity[]

Defined in: packages/core/src/ECS/Entity.ts:785

根据标签查找子实体

Parameters ​

tag ​

number

标签

recursive ​

boolean = false

是否递归查找

Returns ​

Entity[]

找到的子实体数组

getRoot() ​

getRoot(): Entity

Defined in: packages/core/src/ECS/Entity.ts:808

获取根实体

Returns ​

Entity

层次结构的根实体

isAncestorOf() ​

isAncestorOf(entity): boolean

Defined in: packages/core/src/ECS/Entity.ts:821

检查是否是指定实体的祖先

Parameters ​

entity ​

Entity

要检查的实体

Returns ​

boolean

如果是祖先则返回true

isDescendantOf() ​

isDescendantOf(entity): boolean

Defined in: packages/core/src/ECS/Entity.ts:838

检查是否是指定实体的后代

Parameters ​

entity ​

Entity

要检查的实体

Returns ​

boolean

如果是后代则返回true

getDepth() ​

getDepth(): number

Defined in: packages/core/src/ECS/Entity.ts:847

获取层次深度

Returns ​

number

在层次结构中的深度（根实体为0）

forEachChild() ​

forEachChild(callback, recursive): void

Defined in: packages/core/src/ECS/Entity.ts:863

遍历所有子实体（深度优先）

Parameters ​

callback ​

(child, index) => void

对每个子实体执行的回调函数

recursive ​

boolean = false

是否递归遍历

Returns ​

void

destroy() ​

destroy(): void

Defined in: packages/core/src/ECS/Entity.ts:896

销毁实体

移除所有组件、子实体并标记为已销毁

Returns ​

void

destroyAllChildren() ​

destroyAllChildren(): void

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

批量销毁所有子实体

Returns ​

void

compareTo() ​

compareTo(other): number

Defined in: packages/core/src/ECS/Entity.ts:973

比较实体

Parameters ​

other ​

Entity

另一个实体

Returns ​

number

比较结果

toString() ​

toString(): string

Defined in: packages/core/src/ECS/Entity.ts:982

获取实体的字符串表示

Returns ​

string

实体的字符串描述

getDebugInfo() ​

getDebugInfo(): object

Defined in: packages/core/src/ECS/Entity.ts:991

获取实体的调试信息（包含组件缓存信息）

Returns ​

object

包含实体详细信息的对象

name ​

name: string

id ​

id: number

enabled ​

enabled: boolean

active ​

active: boolean

activeInHierarchy ​

activeInHierarchy: boolean

destroyed ​

destroyed: boolean

componentCount ​

componentCount: number

componentTypes ​

componentTypes: string[]

componentMask ​

componentMask: string

parentId ​

parentId: null | number

childCount ​

childCount: number

childIds ​

childIds: number[]

depth ​

depth: number

cacheBuilt ​

cacheBuilt: boolean

Released under the MIT License.

Copyright © 2025 ECS Framework