Scene Graph
A scene is an asset that represents a virtual world.
This world is made up of entities — containers for components that define their behavior and appearance.
The
component encodes a hierarchy.This hierarchy is a tree — an entity can have only one parent, but multiple children.
Additionally, some entities with a
component — called linkers — can reference external scenes, each with its own internal hierarchy.The scene graph extension is a way to visually display this hierarchy.
Basics
Filter
This section allows you to search entities by name or by attached components.
To search for entities that have a specific component attached, type c:
followed by the
component’s name, e.g. c:mesh_ref
will find all entities with a
Create entity from template
The plus button allows you to add an entity with pre-attached components to the scene.
All templates attach these components by default:
| Template name | Components attached |
|---|---|
| Blank | Nothing more than the default components |
| Camera | + |
| Point light | |
| Spot light | + |
| Sun | with attributes isDirectional and isSun toggled on. |
| Environment | |
| Primitive | + - see below |
Create a Primitive
A primitive is a procedurally generated mesh representing a simple geometric shape.
Once a primitive is selected, a menu appears with customization parameters:
One of those parameters is a mesh reference M.
Leaving the reference empty will create a new mesh named following the Name input.
Selecting an existing Mesh asset will replace its geometry with the newly generated primitive.
If the mesh generation succeeded, a new entity will appear in the 3D world as well as in the Scene Graph.
Scene Hierarchy
Entities are presented in a tree widget.
The parent/child relationship between entities is resolved using the
component. The attributeparentUUID is the UUID of the parent entity.
On loading a scene, only the root entities are resolved. When an entity containing children is unfolded, a request is sent to the backend to retrieve its children.
The other components are represented with their icons displayed following the name of the entity.
If an entity doesn’t have any component beside the default ones, it will appear with a simple square icon. If the entity has children the square is plain, otherwise it’s an outline.
Hovering over a component icon shows the component’s name.
Hovering over an entity reveals an eye icon on the right side. The eye icon is for toggling the visibility of the entity.
Double clicking on an entity entry will focus, i.e. move the camera to look at that entity.
Entity entries can be dragged and dropped to move them around, a red line appears to indicate the new position of the entity. Reparenting entities is done this way.
Scene statistics
At the bottom left, you'll find the total number of entities in the scene — including those from referenced scenes.
On the bottom right, the total number of triangles spanning all scenes.
Context Menu
Right-clicking in the Scene Graph opens a context menu.
Depending on whether you clicked on an empty space, on one entity, on multiple entities or on an entity with children, the menu displays slightly different options.
Right-clicking on empty space shows the following options:
| Action | Number of selected entities | Required component | Description |
|---|---|---|---|
| Rename | ≥ 1 | Renames the entity, alters the component. | |
| Focus on entity | = 1 | Moves the camera towards the entity so that the bounding box of the entity fits entirely on the screen. This can be triggered by double clicking on an entity as well. | |
| Toggle entity visibility | ≥ 1 | Show or hide selected entities. | |
| Group entities | > 1 | Creates a new parent entity and moves all selected entities under it. | |
| Cut | ≥ 1 | Cut selected entities. | |
| Copy | ≥ 1 | Copies the selected entities — excluding their children. | |
| Copy with its hierarchy | = 1 | Copy the entity and all its children recursively. | |
| Paste | ≥ 0 | Paste previously cut or copied entities. | |
| Duplicate | ≥ 1 | A single action copy paste. | |
| Create entity | = 0 | Creates a blank entity with only default components attached to it. | |
| Create child entity | = 1 | Creates a blank entity parented to the selected entity. | |
| Paste component | ≥ 1 | Paste the copied component inside the selected entity - see components extension | |
| Simplify hierarchy | = 1 | Scans down the selected entity children and removes any redundant entity. A redundant entity has a single child but no specific components other than the default ones. When an entity is removed its local transform is applied to its child’s. | |
| Create convex collision geometry | ≥ 1 | Create a convex collision geometry asset based on its mesh and attach it to the entity as a component. | |
| Create triangular collision geometry | ≥ 1 | Create a triangular collision geometry asset based on its mesh and attach it to the entity as a component. | |
| Create a scene from this entity | = 1 | Extracts the entity and its children and creates a new scene with a copy of those entities. It’s possible to replace the entity hierarchy with a referencing the new scene. | |
| Delete | ≥ 1 | Deletes all selected entities with all their children |
External entities
An entity that contains a
component is called a linker, i.e. a linker is a reference to another scene.Entities of the imported scene are resolved like local ones, but are marked as external — that is, they are read-only.
You can still explore the referenced scene structure and show/hide any entity, as toggling visibility is not a persistent action.
Internal entities have a dark blue background, whereas external entities have a lighter blue background.
A linker can have internal entities as children. Those will appear with a dark blue background as other internal entities.
Hovering over a linker will reveal on the right side a new option Open in a new tab
that opens the referenced scene
in a new tab.
Opening the context menu by right clicking on a linker will also show this option and two more: Open in a new window
and Open in asset browser
.
Overriders
Overriders allow you to modify external entities in the scope of the current scene, i.e. without altering the original entities.
Overriders are entities that live in the current scene, they have an
component attached to them.On the UI side the orange color is dedicated to overriders. An overrider can modify specific components of the targeted entity. This will turn the overridden component’s icon color to orange.
An overrider can delete specific components of the targeted entity. This will turn the deleted component’s icon color to orange.
An overrider can delete its target entity if its deleter attribute is set to true. In this case the targeted entity’s
name will be crossed out with an orange line.
A linker that has an overridden entity will show a small orange chip on the bottom right of its
icon. If an external entity has an overridden descendant it will also display the small orange chip in the bottom right of its icon.
Opening a context menu on an overridden entity reveals three new options:
Discard all overrides
to get rid of the overrider.
Mark as deleted
replaces
Delete
to support the point that the entity is not actually deleted.
Restore entity
appears if the entity has been marked as deleted (orange stroke).
Transient entities
A transient entity is an entity that only exists briefly during the life of the session i.e. it’s not persisted.
Transient entities can be parented to internal entities for the duration of the session.
A transient entity is recognizable with the hatched background. Note that the transient rule applies on top of external versus internal rule.
Collaboration
When several people work on the same scene, the scene graph reflects this.
When another user selects an entity, their avatar will show up next to that entity outline with their specific color.
When a user modifies an entity, the entry corresponding to that entity in the scene graph will briefly display a flash of the color of the user that made the modification.
Multiple users can select the same entity. Their avatars will appear stacked beside the entity.
If the selected entity is not revealed in the current user’s view, a small dot of the other user’s avatar color appears on the first revealed parent of that entity.
If the other user is not in the same session, their avatar will be outlined in white, and the dot will also be white.
Users are visible even if they’re working inside a referenced scene of the one you’re viewing.
