Entities, levels and prefabs
Parents, Owner, instantiation, event order, and deletion.
An Entity is an object in the game hierarchy with a name, properties, a parent, and children. It can have a C# script. Entity2D adds a 2D transform and Entity3D a 3D transform; cameras, physics bodies, and UI controls use specialized types.
This is an object hierarchy, not ECS. The Entity name alone does not imply component tables or automatic processing by systems.
Assemble an object by responsibility
A controlled 3D character commonly has this structure:
Player (CharacterBody3D)
├── CollisionShape3D
├── MeshInstance3D
└── Camera3DThe body provides physical movement, the shape defines collision, the mesh supplies appearance, and the camera provides a viewpoint. One component does not replace the others. Complete movement example: 3D character.
Spatial children normally inherit their parent's transform. Position is local; GlobalPosition is global. In the executed example, the parent is at (10, 0, 0), the child locally at (1, 2, 3), and its global position is (11, 2, 3). Do not use simple addition for rotated or scaled parents.
Level, prefab, and instance
| Item | Purpose |
|---|---|
.rscene | Hierarchy file used as a project level. |
.rprefab | Reusable hierarchy file: character, prop, UI, or environment object. |
PackedEntity | Loaded hierarchy resource used to instantiate either format. |
| Instance | Created in-memory Entities that can be attached to the tree. |
The extension expresses a file's role; these are not different resource classes or a hard restriction preventing a prefab from being loaded through the level-change API. Keep roles distinct in your own code: a level replaces the current game space, while a prefab creates an object within it.
Creation order: load a PackedEntity, create its root with Instantiate(), set initial properties, and attach it with AddChild(). Instantiate() alone does not add an object to the game. The complete prefab example checks root type, initial position, and an unsuitable resource.
Two instances have separate Entities, but some resources can be shared. Moving one does not change the prefab file; editing a shared material can affect both. See resources and independent copies.
When scripts run
| Event | Order and use |
|---|---|
_EnterTree() | Parent enters before children. Repeats on reentry. |
_Ready() | Children become ready before their parent. Typically obtains required child references. Does not automatically repeat for the same instance. |
_PhysicsProcess(double delta) | Physics ticks: body control and physics queries. |
_Process(double delta) | Frame updates: tasks that do not need a physics tick. |
_ExitTree() | Children exit before the parent. Exiting alone does not delete an object. |
If the parent is already in the active tree, AddChild() can run entry and _Ready() before returning. Set properties needed by _Ready() beforehand. You can assign local position before attachment; global position depends on the future spatial parent.
The checked first attachment produced enter:Parent, enter:Child, ready:Child, ready:Parent. Reattachment produced entry without another _Ready(). RequestReady() requests preparation for that Entity's next entry, not immediately and not recursively for every child. See lifecycle details.
Parent, Owner, and deletion
AddChild()assigns a parent. A new object cannot belong to two parents simultaneously.RemoveChild()detaches the object but leaves it in memory. Retain a reference for reuse or free it.QueueFree()queues deletion of the object and its child hierarchy. The native object can still exist until the queue is processed; stop treating it as an active gameplay object.Owneridentifies membership in a saved hierarchy, not lifetime.AddChild()does not assign it automatically. For programmatic saving, set ownership after attachment; the owner must be an ancestor.
The detached parent remained valid in the check; after queued deletion, both parent and child were gone. A C# reference alone does not keep a freed native Entity alive. For saving a composite object, see Owner and packing.
Diagnose a failure
Created but not updating: check attachment to the active tree. Wrong position: distinguish local and global coordinates. _Ready() does not repeat: this is the same instance rather than a fresh load. A child is absent from the saved file: check Owner. Object counts rise after RemoveChild(): detachment does not free memory.
Executed checks cover event order, reentry, queued deletion, instantiation, initial transform, and a shared resource. Editor mouse operations and exports to other platforms were not evaluated here.