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 lineage component encodes a hierarchy.
This hierarchy is a tree — an entity can have only one parent, but multiple children.
Additionally, some entities with a scene_ref 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 mesh_ref
attached.
The plus button next to the filter input is for adding entities, not filtering. See below.
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 | camera + perspective_lens |
| Point light | point_light |
| Spot light | point_light + spot_light |
| Sun | point_light with attributes isDirectional and isSun toggled on. |
| Environment | environment |
| Primitive | mesh_ref + material - 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.
The whole primitive generation process happens on the AlgoBelt and is an asynchronous operation that can take an undefined amount of time.
The AlgoBelt is a scriptable conversion pipeline. In this case using a Python script to procedurally generate a Mesh asset.
You will see a toast appear on the bottom right of the page notifying you that the pipeline has been scheduled to run.
Once it finishes, whether successfully or with errors, a new toast will appear.
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 lineage component.
The attribute parentUUID is the UUID of the parent entity.
The persisted parent-child relationship is unidirectional, only the child knows about its parent, the parent doesn’t hold any reference to its children. They are solved at runtime.
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 icon in front of the name of an entity is the icon of its most important component. The importance of components is determined by the backend.
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.
Toggling visibility is not a persistent action.
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.
A parent entity can not be reparented under one of its children, as this would create a cycle in the hierarchy.
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.
The triangle count does not account for instancing, i.e. if a mesh having 10 triangles is reused 5 times across the scene, the triangle count will display 50 triangles (10 triangles × 5 instances).
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:
Most actions are associated with keyboard shortcuts that are displayed on the right of the menu entry when available
| Action | Number of selected entities | Required component | Description |
|---|---|---|---|
| Rename | ≥ 1 | Renames the entity, alters the debug_name 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 | lineage | 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 | mesh_ref | Create a convex collision geometry asset based on its mesh and attach it to the entity as a collision_geometry_ref component. |
| Create triangular collision geometry | ≥ 1 | mesh_ref | Create a triangular collision geometry asset based on its mesh and attach it to the entity as a collision_geometry_ref 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 scene_ref referencing the new scene. | |
| Delete | ≥ 1 | Deletes all selected entities with all their children |
To be able to cut, copy and paste entities you need to make sure that the browser allows the web page access to the clipboard:
External entities
An entity that contains a scene_ref 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.
You cannot alter the hierarchy of the referenced scene nor reparent an internal entity under an external one.
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.
The linker itself is a local entity.
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 overrider 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.
There’s no visual way to distinguish between the two types of behavior.
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.
If an overrider is set to delete its targeted entity, other behaviors have no effect.
A linker that has an overridden entity will show a small orange chip on the bottom right of its scene_ref 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.
It is possible to reparent an internal entity under a transient one, but it is a transient operation — the reparenting is not persisted.
A transient entity is recognizable with the hatched background. Note that the transient rule applies on top of external versus internal rule.
When a user opens the editor, a new camera is spawned for them. That camera is actually a transient entity.
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.
You never see your own avatar, only those of other users.
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.
