Entity

Entity Management

Adding an Entity

You can click the "+" button in the hierarchy tree panel to add a new entity. Note that if an entity is currently selected, the new entity will become a child of the selected entity; otherwise, it will be a child of the scene:

You can also right-click an entity to add a child entity to it:

You can add empty entities or quickly add entities with relevant functional components attached, such as entities with camera components, light components, and 3D/2D basic rendering components.

After adding, you can edit the properties of the new entity in the Inspector Panel.

Deleting an Entity

To delete an entity, you can use the following methods:

1. Select the entity to be deleted -> Click the delete button, the shortcut key is Delete

2. Right-click an entity -> Delete

Copying an Entity

Copying an entity will duplicate the selected entity and all its child entities, along with their components.

1. Select an entity, then use Duplicated to quickly clone the entity in the same hierarchy level, or use the shortcut ⌘ + D to quickly copy the selected entity.

2. You can also choose copy and paste separately to achieve cross-hierarchy copying.

Sorting Entities

To better organize entities, you can sort them by dragging. After selecting an entity, you can change its position in the hierarchy tree by dragging with the left mouse button.

Search

There is a search box at the top of the hierarchy panel where users can enter the name of an entity to search for it in the scene. The search box supports fuzzy search, allowing you to enter part of the entity's name to find it.

Hiding Entities

Every entity has an eye button on its right side, which can be clicked to toggle the entity's display/hide state in the scene.

Shortcut Keys

The following operations take effect after selecting an entity.

Editing Entities

Clicking an entity allows you to edit it in the Inspector Panel on the right, where you can edit the following attributes:

Basic Information

Component Management

Components of entities are displayed tiled in the Inspector panel, such as the most common Transform component. For detailed usage, please refer to the Component documentation.

Script Usage

Creating New Entities

As introduced in Scenes on how to access the active scene. In a new scene, we usually start by adding a root entity:

const scene = engine.sceneManager.activeScene;
const rootEntity = scene.createRootEntity();

Typically, new entities are created by adding child entities:

const newEntity = rootEntity.createChild("firstEntity");

Of course, entities can also be created directly. However, such entities are detached and will not appear in the scene until associated with an entity hierarchy tree.

const newEntity = new Entity(engine, "firstEntity");
rootEntity.addChild(newEntity);

Deleting Entities

When an entity is no longer needed in the scene, we can delete it:

rootEntity.removeChild(newEntity);

It is worth noting that this method simply releases the object from the hierarchy tree and it will not be shown in the scene. To completely destroy it, additionally:

newEntity.destroy();

Finding Entities in the Scene

Finding Entities by Name

const entity = scene.findEntityByName("entityName");

Finding Entities by Path

const entity = scene.findEntityByPath("parent/child/grandson");

Finding Child Entities

When the parent entity is known, we typically obtain child entities through the parent entity:

const childrenEntity = newEntity.children;

If you know the specific index of the child entity within the parent, you can directly use getChild:

newEntity.getChild(0);

If the index of the child entity is unclear, findByName can be used to find by name. findByName searches not only for child entities but also for grandchild entities.

newEntity.findByName("model");

If there are entities with the same name, findByPath can be used to search step by step by inputting the path. Utilizing this API can also enhance search efficiency to some extent.

newEntity.findByPath("parent/child/grandson");

Status

When temporarily not using an entity, it can be deactivated by calling the entity's isActive, and all components under the entity will be disabled.

newEntity.isActive = false;