Entity

Editor Usage

Hierarchy Panel is located on the far left side of the editor. It displays all nodes in the current scene in a tree structure. The scene node is the parent node of all other nodes, including cameras, lights, meshes, etc. There is a search box at the top of the node panel that allows you to search for nodes in the scene to quickly locate them. Through the Hierarchy Panel, you can add or delete nodes and organize nodes better by dragging and dropping to sort them.

Adding a New Entity

To add a new entity, you can click the add button in the Hierarchy Panel or right-click an entity and select Add Child Entity. After adding, you can edit the properties of the new entity in the Inspector Panel. If you use the add entity button, you can also quickly create basic models such as cubes/spheres.

Editing an Entity

Click on an entity to edit it. In the Inspector Panel on the right, you can edit its name.

Whether it is active

Transform

And add or remove components for it

Deleting an Entity

After selecting an entity, you can click the delete button in the Hierarchy Panel or use the delete option in the right-click menu to delete the entity. Deleting an entity will delete the entity and all its child entities. Therefore, when deleting an entity, you need to be aware of whether the deleted entity will affect other entities in the scene.

Sorting Entities

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

Searching for Entities

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

Hiding Entities

Each entity has an eye button on the right side. Clicking it toggles the entity's visibility in the scene. Note that this adjustment to the entity's visibility only affects the workspace and not the isActive property in the Inspector Panel.

Script Usage

Creating a New Entity

In the Scene, we have already introduced how to get the active scene. In a new scene, we usually add a root entity first:

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

Generally, a new entity is created by adding a child entity:

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

Of course, you can also create an entity directly. However, such an entity is detached and will not appear in the scene until it is associated with the hierarchy tree.

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

Delete Entity

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

rootEntity.removeChild(newEntity);

It is worth noting that this method only releases the object from the hierarchy tree and does not display it in the scene. To completely destroy it, you need to:

newEntity.destroy();

Find Child Entity

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

const childrenEntity = newEntity.children;

If you know the child's index in the parent entity, you can directly use getChild:

newEntity.getChild(0);

If you don't know the child's index, you can use findByName to search by name. findByName will search not only child entities but also grandchild entities.

newEntity.findByName("model");

If there are entities with the same name, you can use findByPath to pass in the path for step-by-step search. Using this API will also improve search efficiency to some extent.

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

State

When an entity is temporarily not in use, you can stop activating it by calling the entity's isActive. At the same time, the components under this entity will be passively component.enabled = false

newEntity.isActive = false;