C#: builds, properties and engine objects

Project requirements

The Reckfell distribution includes .NET 10 and Reckfell.NET.Sdk/1.0.0. Generate a C# solution through the editor; its .csproj appears in the project directory. For a manual build, run the supplied dotnet.exe build there with the local NuGet feed configured. An arbitrary system SDK or different package does not replace the engine SDK.

Build after editing code; saving a .cs file does not guarantee that the game runs the new version. Read build errors first, then Output and the debugger. Running an older successful build does not validate new edits.

Script and base class

An attachable class matches its file name, is partial and inherits Entity or a suitable specialized type. Inherit CharacterBody3D when you need Velocity and MoveAndSlide(); an Entity3D script does not have those methods.

Do not require custom arguments in the constructor the engine uses. Resolve child entities in _Ready(), not a field initializer or constructor. For subscriptions that must survive removal and reinsertion into the tree, use a matched _EnterTree() / _ExitTree() pair.

C# API names

Examples use exact C# identifiers: GetEntity<T>(), AddChild(), QueueFree(), _PhysicsProcess(double delta) and ReckfellApi.Print(). Search those names in the reference, including the type and overload. Paths and Input Map names depend on exact spelling.

[Export] exposes a supported field or property in the inspector. Saved document values can override initial values in code. Adding an attribute alone does not make a static or read-only property an ordinary editable field.

Deletion and references

An entity has a native object and a C# wrapper. entity != null does not prove that the native object still exists. For a reference that may outlive deletion, use ReckfellObject.IsInstanceValid(entity); consider IsQueuedForDeletion() before scheduling another operation.

QueueFree() defers deletion of an entity and its children. RemoveChild() only detaches it; your code remains responsible for its lifetime. The .NET garbage collector does not replace deleting an unused entity. RefCounted resources have different lifetime rules; do not apply tree ownership rules to them automatically.

After await and on worker threads

After await, a level or object may already have been deleted. Check that the operation is still relevant and its recipients remain valid. Do not mutate the game tree from a background task: return results to the main thread and check they are still needed.

Use _PhysicsProcess() for physics movement and _Process() for ordinary per-frame behavior. delta is in seconds. Its double parameter does not imply that all vectors use doubles: this build's ordinary Vector2 and Vector3 use float.

Working examples: rotation, character movement, signals and saving.