Autoload: state between levels

Configure SessionState

Add SessionState.cs and SessionHud.cs at the root of a Reckfell 1.0.0 C# project and build. In Project → Project Settings → Globals → Autoload select asset://SessionState.cs and name it SessionState. The equivalent configuration section follows: add it to the existing project.reckfell without replacing the whole file or creating a second autoload section.

[autoload]
SessionState="*asset://SessionState.cs"

using Reckfell;

public partial class SessionState : Entity
{
    [Signal]
    public delegate void CoinsChangedEventHandler(int total);
    public int Coins { get; private set; }

    public bool AddCoins(int amount)
    {
        if (amount <= 0 || Coins > int.MaxValue - amount) return false;
        Coins += amount;
        EmitSignal(SignalName.CoinsChanged, Coins);
        return true;
    }

    public void ResetRun()
    {
        if (Coins == 0) return;
        Coins = 0;
        EmitSignal(SignalName.CoinsChanged, Coins);
    }
}

using Reckfell;

public partial class SessionHud : Label
{
    private SessionState? _session;

    public override void _EnterTree()
    {
        _session = GetEntityOrNull<SessionState>("/root/SessionState");
        if (_session is null)
        {
            Text = TranslationServer.GetLocale().StartsWith("ru") ? "Нет /root/SessionState" : "Missing /root/SessionState";
            return;
        }
        _session.CoinsChanged += Refresh;
        Refresh(_session.Coins);
    }

    public override void _ExitTree()
    {
        if (_session is not null && ReckfellObject.IsInstanceValid(_session)) _session.CoinsChanged -= Refresh;
        _session = null;
    }

    private void Refresh(int value) => Text = TranslationServer.GetLocale().StartsWith("ru")
        ? "Монеты: " + value + " · C: +1 · R: новый забег"
        : "Coins: " + value + " · C: +1 · R: new run";

    public override void _UnhandledKeyInput(InputEvent @event)
    {
        if (_session is null || @event is not InputEventKey { Pressed: true, Echo: false } key) return;
        if (key.Keycode == Key.C) _session.AddCoins(1);
        else if (key.Keycode == Key.R) _session.ResetRun();
        else return;
        GetViewport().SetInputAsHandled();
    }
}

Create a Label in a test level, place it visibly and attach SessionHud. Run with F6: C adds a coin and R explicitly begins a new run. An EntityTree level change retains SessionState; the new HUD reads the current snapshot and subscribes to changes.

What autoload creates

Startup configuration creates an Entity from a script or PackedEntity and adds it below the main Root before the initial level. /root/SessionState is the active-tree instance name. The C# SessionState class does not become a static object: obtain the instance as the HUD does. Do not invoke instance AddCoins through the type name.

Autoload does not prevent new SessionState or a second instance of the same prefab. It does not automatically enforce Singleton. Do not create a second service copy in each level when you intend to use the shared instance under Root.

Design autoload initialization dependencies explicitly. Do not assume every sibling has completed _Ready during another service early _EnterTree. For interdependent setup, use a composition point after service creation rather than cyclic constructor access.

Subscription and reset

The HUD refreshes immediately from Coins, then receives CoinsChanged. It disconnects in _ExitTree and rereads the snapshot on reentry. This preserves updates made while the HUD was detached. SessionState knows no HUD path and does not retain it after correct disconnection.

ResetRun is explicit. Changing a level does not by itself begin a new game or clear the shared session. Memory data does not survive process exit: disk saves need a separate schema. Autoload also does not make its methods automatically pause-safe, thread-safe or authoritative for network requests.

Configuration is verified by actual engine startup with the autoload section; Coins persistence is verified through native level replacement. Project Settings mouse actions and a finished export were not performed in this check.