# 实体

实体（Entity）自身不具备任何渲染和逻辑控制功能，这些功能需要通过添加组件（Component）来实现。使用组合代替继承，降低程序耦合度提升代码复用率。

# 创建实体

使用引擎（Engine）的createEntity接口创建组件。

// 创建一个空实体
const entity = engine.createEntity();

1
2

提示

实体创建参数，详见EntityParameters。
此时的实体不具备任何渲染和逻辑控制功能。

# 销毁实体

使用实体（Entity）的destroy接口销毁实体。

// 销毁实体
entity.destroy();

1
2

提示

该方法会同时销毁实体的所有子实体。

# 查找实体

1️⃣ 使用引擎（Engine）的getEntity接口查找实体。

// 查找指定GUID的实体（仅查找当前激活的场景）
const entity = engine.getEntity( 'xxxx-xxxx-xxxx-xxxx' );

// 查找指定GUID的实体（查找所有场景）
const entity = engine.getEntity( 'xxxx-xxxx-xxxx-xxxx', false );

1
2
3
4
5

2️⃣ 使用实体（Entity）的findByGUID静态接口查找实体。

import { Entity } from '@tx3d/core';

// 以当前激活场景为根查找指定GUID的实体
const entity = Entity.findByGUID( engine.sceneRenderer.activeScene, 'xxxx-xxxx-xxxx-xxxx' );

1
2
3
4

3️⃣ 使用实体（Entity）的findByName静态接口查找实体。

import { Entity } from '@tx3d/core';

// 以当前激活场景为根查找名为“car”的实体
const entities = Entity.findByName( engine.sceneRender.activeScene, 'car' );

1
2
3
4

提示

实体名称不是唯一的，所以该方法返回一个实体数组。

4️⃣ 使用实体（Entity）的findByComponent静态接口查找实体。

import { Entity, Model } from '@tx3d/core';

// 以当前激活场景为根查找包含“Model”组件的实体
const entities = Entity.findByComponent( engine.sceneRenderer.activeScene, Model );

1
2
3
4

5️⃣ 使用实体（Entity）的findByCondition静态接口查找实体。

import { Entity } from '@tx3d/core';

// 以当前激活场景为根查找属于矢量图层的实体
const entities = Entity.findByCondition( engine.sceneRenderer.activeScene, ( entity ) => {

    return entity.layer === '矢量图层';

} );

1
2
3
4
5
6
7
8
9

提示

查询条件是返回类型为boolean的闭包函数。

# 遍历实体

使用实体（Entity）的traverse静态接口遍历实体。

import { Entity } from '@tx3d/core';

// 以当前激活场景为根遍历隐藏矢量图层实体
Entity.traverse( engine.sceneRenderer.activeScene, ( entity ) => {

    if ( entity.layer === '矢量图层' ) {

        entity.transform.visible = false;

    }

} );

1
2
3
4
5
6
7
8
9
10
11
12

# 添加组件

使用实体（Entity）的addComponent接口添加组件。

import { AmbientLight } from '@tx3d/core';

// 添加一个环境光组件
const ambientLight = entity.addComponent( AmbientLight, { color: '#ffffff', intensity: 0.5 } );

1
2
3
4

注意

不允许重复添加相同类型的组件。

# 获取组件

使用实体（Entity）的getComponent接口获取组件。

import { AmbientLight } from '@tx3d/core';

// 获取环境光组件
const ambientLight = entity.getComponent( AmbientLight );

1
2
3
4

# 获取所有组件

使用实体（Entity）的getAllComponents接口获取所有组件。

// 获取实体上的所有组件
const components = entity.getAllComponents();

1
2

# 组件是否存在

使用实体（Entity）的hasComponent接口判断指定类型组件是否存在。

import { AmbientLight } from '@tx3d/core';

// 判断是否存在环境光组件
if ( entity.hasComponent( AmbientLight ) ) {

    // TODO

}

1
2
3
4
5
6
7
8

# 移除组件

使用实体（Entity）的removeComponent接口移除指定类型组件。

import { AmbientLight } from '@tx3d/core';

// 移除环境光组件
entity.removeComponent( AmbientLight );

1
2
3
4

# 实体属性

🌏 guid 唯一标识，只读。

// 获取实体GUID
const guid = entity.guid;

1
2

🌏 type 类型，只读。

// 获取实体类型
const type = entity.type;

1
2

🌏 layer 图层

// 获取实体图层
const layer = entity.layer;

// 设置实体图层
entity.layer = '巷道';

1
2
3
4
5

🌏 name 名称

// 获取实体名称
const name = entity.name;

// 设置实体名称
entity.name = '机房';

1
2
3
4
5

🌏 tag 标签

// 获取实体标签
const tag = entity.tag;

// 设置实体标签
entity.tag = "movable";

1
2
3
4
5

🌏 userData 用户数据

// 获取用户数据
const userData = entity.userData;

// 设置用户数据，方式一
entity.userData.operator = 'run'

// 设置用户数据，方式二
entity.userData = {

    state: 'fail',
    warning: true

};

1
2
3
4
5
6
7
8
9
10
11
12
13

提示

userData的默认值为{}。

🌏 transform 实体对应的Transform组件，只读。

// 获取Transform组件
const transform = entity.transform;

1
2

注意

相机实体的transform属性为null！！！

🌏 isCamera 标识是否是相机实体，只读。

// 获取是否相机实体
const isCamera = entity.isCamera;

1
2

🌏 camera 实体对应的Camera组件，只读。

// 获取Camera组件
const camera = entity.camera;

1
2

注意

相机实体的特有属性！！！

← 事件组件 →