Session

Session is a simple key/value store that survives a scene change — the recommended way to carry a score, a checkpoint, or a settings flag from one scene into the next. See Scenes for how scene loading itself works.

It's in-memory only and cleared when you stop Play — nothing here is written to disk on its own. Supports int, long, float, bool, and string; using any other type throws an exception rather than silently doing nothing, since a save-data write that quietly does nothing is a much worse failure mode than an obvious error.

Session.Set<T>(string key, T value)

Stores value under key, overwriting anything already stored there.

Session.Set("score", 1200);
Session.Set("checkpoint", "Cave_02");
Session.Set("hasKey", true);

Session.Get<T>(string key, T defaultValue = default)

Reads key back as type T. Returns defaultValue if key was never set — or if it was last set as a different type (read as the wrong type is treated as a miss, not a crash).

int score = Session.Get("score", 0);
string checkpoint = Session.Get("checkpoint", "Start");

Session.Has(string key)

True if key currently holds a value of any supported type.

if (!Session.Has("checkpoint"))
    Session.Set("checkpoint", "Start");

Session.Remove(string key)

Removes key. Safe to call even if it was never set — not an error.

Session.Remove("temporaryPowerUp");

Example: score and checkpoint across a level

using JoystickEngine;

public class Player : GameEntity
{
    protected override void OnCreate()
    {
        // Every level's Player entity picks up where the last one left off.
        int score = Session.Get("score", 0);
        Log.Info($"Starting {Name} with score {score}");
    }

    public void CollectCoin(int value)
    {
        Session.Set("score", Session.Get("score", 0) + value);
    }

    public void ReachCheckpoint(string checkpointName)
    {
        Session.Set("checkpoint", checkpointName);
    }
}

Session vs. GameEntity.Persist()

An entity also has a Persist() method that carries the whole entity — its transform, components, and script — across a scene change, instead of just data. For a score, a flag, or anything that's just a value, prefer Session: dragging a whole entity across a scene boundary for one number is easy to leak and hard to reason about. Save Persist() for things that genuinely need to keep existing, like a music player or a network connection manager. Calling Persist() twice on entities with the same name destroys the newer one automatically and keeps the original running, so a level reload can't accidentally create a second copy of something you persisted earlier.