mirror of
https://github.com/galacean/engine.git
synced 2026-05-07 23:37:11 +08:00
189 lines
6.8 KiB
Plaintext
189 lines
6.8 KiB
Plaintext
---
|
||
order: 3
|
||
title: 实体
|
||
type: 核心
|
||
label: Core
|
||
---
|
||
|
||
## 实体的管理
|
||
|
||
### 新增实体
|
||
|
||
你可以点击层级树面板中的「+」按钮新增实体。需要注意的是，若您此时正选中了某个实体，那么添加的实体将会成为**选中实体的子实体**，否则将默认为场景的子实体：
|
||
|
||
<Image
|
||
src="https://gw.alipayobjects.com/zos/OasisHub/3d808a9c-429c-4c45-91c4-5d7cb12a2fee/image-20250515120040706.png" style={{zoom:"50%"}} />
|
||
|
||
也可以右键点击某个实体，为它添加子实体：
|
||
|
||
<Image
|
||
src="https://gw.alipayobjects.com/zos/OasisHub/f4bfef7e-cff3-4fe7-a4d5-2dc253501206/image-20250515120159840.png" style={{zoom:"50%"}} />
|
||
|
||
你既可以添加空实体，也可以快速添加挂载相应功能组件的实体，如挂载相机组件的实体，挂载光源组件实体，以及挂载 3D/2D 基础渲染组件的实体。
|
||
|
||
添加完毕后，你可以在 **[检查器面板](/docs/interface/inspector)** 中对新实体的属性进行编辑。
|
||
|
||
### 删除实体
|
||
|
||
想要删除实体，可以通过以下几种方式：
|
||
|
||
1. 选中待删实体 -> 点击删除按钮，快捷键是 <Kbd>Delete</Kbd>
|
||
|
||
2. 右键某个实体 -> Delete
|
||
|
||
<Image
|
||
src="https://gw.alipayobjects.com/zos/OasisHub/1e46a6d6-3591-4e16-88b6-e1adbaa38712/image-20250515113606200.png" style={{zoom:"50%"}} />
|
||
|
||
<Callout type="warning">
|
||
删除实体会删除实体及其所有的子实体。所以在删除实体时，你需要注意所删除的实体是否会影响场景中其他实体。
|
||
</Callout>
|
||
|
||
### 拷贝实体
|
||
|
||
拷贝实体会拷贝选中实体及其所有的子实体，实体所带的组件都会被拷贝。
|
||
|
||
1. 选中某实体后，通过 `Duplicated` 在同层级下快速克隆该实体，通过快捷键 <Kbd>⌘ + D</Kbd> 快速复制选中的实体。
|
||
|
||
2. 也可以分别选择 `copy` 与 `paste` ，从而实现跨层级拷贝。
|
||
|
||
<Image
|
||
src="https://gw.alipayobjects.com/zos/OasisHub/7be3ac6a-2b4e-44c5-b8cc-fbeba7794830/image-20250515113457918.png" style={{zoom:"50%"}} />
|
||
|
||
### 实体排序
|
||
|
||
为了更好的组织实体，你可以通过拖拽的方式来排序实体。选中一个实体后，可以通过鼠标左键拖拽来改变实体在层级树中的位置。
|
||
|
||
### 搜索
|
||
|
||
层级面板上方有一个搜索框，用户可以输入实体的名称来搜索场景中的实体。搜索框支持模糊搜索，你可以输入实体名称的部分字符来查找实体。
|
||
|
||
### 隐藏实体
|
||
|
||
每个实体右侧都有一个眼睛按钮，点击可以切换实体在场景中的显示/隐藏状态。
|
||
|
||
<Callout type="info">
|
||
需要注意的是, 此处对实体显示状态的调整仅是工作区的修改, 而非在 **[检查器面板](/docs/interface/inspector)** 中的 `isActive` 的属性。
|
||
</Callout>
|
||
|
||
### 快捷键
|
||
|
||
以下操作在选中实体后方可生效。
|
||
|
||
| 操作 | 快捷键 |
|
||
| :--------------- | :---------------------------------------- |
|
||
| `删除实体` | <Kbd>Backspace</Kbd> 或 <Kbd>Delete</Kbd> |
|
||
| `复制实体` | <Kbd>⌘ + D</Kbd> |
|
||
| `选中上一个实体` | <Kbd>↑</Kbd> |
|
||
| `选中下一个实体` | <Kbd>↓</Kbd> |
|
||
| `展开实体` | <Kbd>→</Kbd> |
|
||
| `折叠实体` | <Kbd>←</Kbd> |
|
||
|
||
## 实体的编辑
|
||
|
||
点击实体，你就可以对它进行编辑，在右侧的 **[检查器面板](/docs/interface/inspector)** 中你可以编辑它的以下内容：
|
||
|
||
### 基本信息
|
||
|
||
<Image
|
||
src="https://gw.alipayobjects.com/zos/OasisHub/12d4148a-f670-443b-8eb2-12c9a837eaea/image-20250515114745494.png" style={{zoom:"50%"}} />
|
||
|
||
| 编号 | 名称 | 说明 |
|
||
| ---- | -------- | ------------------------------------------------------------ |
|
||
| 1 | 名字 | 实体的名称，脚本可以通过 `scene.findEntityByName("entityName")` 获取实体 |
|
||
| 2 | 是否激活 | 实体在场景中是否被激活 |
|
||
| 3 | 所属层 | 分层管理实体，它可以用于 [裁剪遮罩](/docs/graphics/camera/component/#裁剪遮罩)（用于控制哪些层在渲染过程中被剔除）、 [射线检测](docs/physics/query/raycast)（用于控制哪些层的实体可以被射线检测到）等场景。支持多选。 |
|
||
|
||
### 组件管理
|
||
|
||
实体的组件通过平铺的方式展示在检查器面板中，比如最常见的 **Transform** 组件，详细使用请查看[组件](/docs/core/component)文档。
|
||
|
||
<Image
|
||
src="https://gw.alipayobjects.com/zos/OasisHub/2a670e89-a8de-44b9-b978-5a25e9689fd0/image-20250515153549864.png"
|
||
style={{zoom:"50%"}}
|
||
/>
|
||
|
||
## 脚本使用
|
||
|
||
### 创建新实体
|
||
|
||
在[场景](/docs/core/scene)中已经介绍了如何获取激活场景。在新场景中，我们通常会先添加根实体：
|
||
|
||
```typescript
|
||
const scene = engine.sceneManager.activeScene;
|
||
const rootEntity = scene.createRootEntity();
|
||
```
|
||
|
||
一般以添加子实体的方式创建新实体：
|
||
|
||
```typescript
|
||
const newEntity = rootEntity.createChild("firstEntity");
|
||
```
|
||
|
||
当然，也可以直接创建实体。但这种实体是游离的，在关联层级树上的实体之前不显示在场景中。
|
||
|
||
```typescript
|
||
const newEntity = new Entity(engine, "firstEntity");
|
||
rootEntity.addChild(newEntity);
|
||
```
|
||
|
||
### 删除实体
|
||
|
||
某个实体在场景中不再需要时，我们可以删除它:
|
||
|
||
```typescript
|
||
rootEntity.removeChild(newEntity);
|
||
```
|
||
|
||
值得注意的是，这种方式仅仅是将物体从层级树上释放出来，不在场景中显示。如果彻底销毁还需要：
|
||
|
||
```typescript
|
||
newEntity.destroy();
|
||
```
|
||
### 场景中查找实体
|
||
|
||
#### 根据名字查找实体
|
||
|
||
```typescript
|
||
const entity = scene.findEntityByName("entityName");
|
||
```
|
||
#### 根据路径查找实体
|
||
|
||
```typescript
|
||
const entity = scene.findEntityByPath("parent/child/grandson");
|
||
```
|
||
|
||
|
||
### 查找子实体
|
||
|
||
在已知父实体的情况下，通常我们通过父实体来获得子实体：
|
||
|
||
```typescript
|
||
const childrenEntity = newEntity.children;
|
||
```
|
||
|
||
如果明确知道子实体在父实体中的 _index_ 可以直接使用 [getChild](/apis/core/#Entity-getChild)：
|
||
|
||
```typescript
|
||
newEntity.getChild(0);
|
||
```
|
||
|
||
如果不清楚子实体的 index，可以使用 [findByName](/apis/core/#Entity-findByName) 通过名字查找。`findByName` 不仅会查找子实体，还会查找孙子实体。
|
||
|
||
```typescript
|
||
newEntity.findByName("model");
|
||
```
|
||
|
||
如果有同名的实体可以使用 [findByPath](/apis/core/#Entity-findByPath) 传入路径进行逐级查找，使用此 API 也会一定程度上提高查找效率。
|
||
|
||
```typescript
|
||
newEntity.findByPath("parent/child/grandson");
|
||
```
|
||
|
||
### 状态
|
||
|
||
暂时不使用某实体时，可以通过调用实体的 [isActive](/apis/core/#Entity-isActive) 停止激活，同时该实体下的所有组件都会被**禁用**。
|
||
|
||
```typescript
|
||
newEntity.isActive = false;
|
||
```
|