Entities and hierarchy — documentation

Entity is the base hierarchy class. Entity3D adds position, rotation and scale in 3D; Entity2D does so in 2D. Specialized classes add particular capabilities.

Parents and children

World (Entity3D)
└── Player (CharacterBody3D)
    ├── Visual (MeshInstance3D)
    ├── CollisionShape3D
    └── Camera3D

World is the parent of Player. Visual, CollisionShape3D and Camera3D are children of Player. An entity has at most one parent. Siblings must have distinct names.

For ordinary spatial children, transforms are relative to the parent. Moving Player also moves its model, collision shape and camera. The special Top Level setting changes transform inheritance; leave it disabled for the first lessons.

The tree organizes objects. Nesting alone does not establish gameplay rules: a MeshInstance3D displays a model but does not become a solid body without a physics object and collision shape.

Choosing a type

Task	Starting point
Group objects without spatial properties	`Entity`
Group objects in 3D	`Entity3D`
Display a 3D model	`MeshInstance3D` with a `Mesh` resource
Create a controllable character	`CharacterBody3D` or `CharacterBody2D`
Make a static physical floor	`StaticBody3D` with `CollisionShape3D`
Display an interface	`Control`, `Label`, `Button`

Do not automatically choose Entity3D for every task. For example, Label already provides interface element behaviour.

Names, paths and types

Visual is the chosen name of a particular object. MeshInstance3D is its type and determines its capabilities. Renaming Visual to BodyMesh does not change its type.

Paths start at the entity running the code. From a script on Player, the camera's path is Camera3D; from World, it is Player/Camera3D. Names are case-sensitive. asset:// refers to project files, not paths through the entity tree.

C#
using Reckfell;

public partial class PlayerView : Entity3D
{
    public override void _Ready()
    {
        var camera = GetEntity<Camera3D>("Camera3D");
        camera.Current = true;
    }
}

This example requires a child of type Camera3D named Camera3D. The script can attach to Player above because CharacterBody3D inherits Entity3D. Moving the camera under a Pivot changes the path to Pivot/Camera3D.

When code runs

C# method	Called when	Useful for
`_EnterTree()`	Entering the active tree; parent before children	Connecting to the application tree
`_Ready()`	After children are ready; children before parent	Finding children and setting initial values
`_Process(double delta)`	Each rendered frame	Visual rotation and interface updates
`_PhysicsProcess(double delta)`	At a fixed physics interval	Character movement and physics

delta is the elapsed time in seconds since the previous corresponding step. The C# lesson explains it with a first script.

Parents, ownership and deletion

Parent determines hierarchy. Owner determines which saved tree includes the object. For normal editor operations, the editor sets ownership for you. Calling AddChild() in code creates an object in the running game, but does not automatically make it part of the source file when packing a tree.

QueueFree() schedules the object and its children for deletion at the end of the frame, after deferred calls. Do not access a deleted entity later. Start with this method rather than immediate Free() calls while handling gameplay events.

Reference: Entity, Entity3D, EntityTree.