Scene and entities

A level is made of entities. An entity is an identifier with components attached to it, such as a transform, a mesh, a physics body, or a component defined in a project's C++ module. Parent and child relationships are links between entities, not one entity containing another.

Most entities in a level are placed copies of actor classes. A placed copy stores its class, its position and any variables it overrides.

Entity identifiers

An entity identifier is made of a slot number and a version counter. When an entity is deleted, the version counter for its slot goes up, so any leftover reference to it can be detected as out of date instead of pointing to whatever reuses that slot.

This is what makes undo reliable. Undoing a delete restores the entity with its original identifier, so every reference to it keeps working. If the slot is somehow already in use, the undo reports an error instead of restoring into the wrong entity.

What is saved when an entity is deleted

An entity does not contain its components or its children: components are stored separately by type, children are separate entities, and the order among siblings is stored by the parent. Deleting an entity records all three, so undo can bring it back completely.

All changes go through undo

No editor panel changes a level directly. The hierarchy, the inspector and the viewport gizmos all make their changes through the undo system, so every change can be undone.

Levels are files

Lights, cameras, interfaces and input bindings are stored in level files rather than in code. When you stop playing, the editor restores the level by reloading its saved file, which means saving and loading are tested every time you press Play. If the level cannot be saved, Play does not start.

Each level also has a World Settings object that controls exposure, sky, clouds, weather, fog and post-processing, and post-process volumes can change these settings in specific areas. Large levels can be split into sub-levels that load and unload as the player moves around.

Asset references

Every asset has a permanent ID stored in a small file next to it, and levels refer to assets by that ID. Moving or renaming an asset in the content browser keeps its ID, so references never break. If a reference cannot be found, it stays empty rather than guessing at a different asset.

Reflection

Saving, the inspector and code reloading all need to know which fields each type has. That information is generated from the source code at build time instead of being written by hand, and it is set up so it can later be replaced by C++26's built-in reflection.