Skip to main content

Session and transitions

These native services are available in editor Play Mode and PS1 builds. The Last Exit example composes them with ordinary Lua behaviours; the engine contains no demo-specific game rules.

Run-owned data​

Session.Read(key) returns a string or nil. Session.Write(key, value) and Session.Delete(key) return booleans. There are 32 entries, keys hold 1-31 bytes, values 0-63 bytes. Embedded NULs are rejected. Writing a new entry to a full table fails without mutation; updating an existing entry still works. Delete also succeeds when a valid key is absent.

Data survives scene replacement, including the scene's Lua VM. A new Play session, application exit or console reset clears it. It never writes a Memory Card. Use namespaces and stable item IDs; scene object IDs are not persistent. Check write results and use SaveData explicitly when permanent saves are needed.

For a practical workflow, see reusing a scene with its HUD and scripts and the HUD progress example.

Queued scene changes​

SceneManager.LoadScene accepts a scene name/path and an optional table with EntryPoint (a name up to 63 bytes) and Presentation (Black or Default). It returns whether the request was accepted, not whether loading finished. Missing destinations or an already pending request are rejected. Include all PS1 destinations in Build Settings. Without options, ordinary loading is retained.

SceneManager.GetEntryPoint returns the requested marker name before destination Start, or an empty string on initial boot. It is a string handoff; Lua decides which player to position and how to resolve a marker.

Black presentation suppresses the normal loading UI. Fade out before queuing the load; fade in from destination Start. The engine replaces scenes sequentially. It does not keep two scenes resident or play Lua animations during disc loading. On native load failure, black presentation is removed to expose diagnostics.

Screen fades​

ScreenFade.ToBlack(seconds) and ScreenFade.FromBlack(seconds) return booleans. The default duration is 0.2 s; finite durations from 0 through 30 are accepted. Zero applies immediately. Invalid durations leave the current fade unchanged. A new request starts from current opacity. ScreenFade.IsPlaying returns whether the fade is progressing.

Fades advance with unscaled time and survive scene replacement. PS1 uses subtractive GPU blending for partial black and an opaque endpoint; Play Mode uses an overlay. The overlay covers game UI while error diagnostics stay visible.

UI.SetSubmitButton(name) accepts a button or input action and returns boolean. An unknown binding is rejected. Until configured, the legacy default accepts Cross or Circle. Last Exit maps Confirm to Cross and handles Circle as cancel.

Canvas.SetModal(id) restricts native navigation/submission to an enabled canvas; -1 releases it. Invalid or disabled canvas IDs return false. This does not hide other canvases. UI.SetInputEnabled(false) blocks native UI input, not rendering. Neither function blocks custom Input calls or player scripts; gate those in Lua.

UI.SetSelectionColor(r, g, b) accepts integers 0-255 for the selected-button fill. Native focus borders are retained. These UI settings reset at scene activation; configure them again in Start. Use Selectable.Select after enabling a panel. Disabled buttons are skipped even when an explicit navigation link names one.

Reusable door recipe​

Keep a world root and a disabled, isolated door stage. Lock gameplay, fade black, hide the world, show the stage, position the camera and play an ordinary Animation. Use unscaled Update time to move the camera and trigger sounds. Fade black again, then queue the next scene once. The destination restores gameplay and fades in.

The transition's duration and animation key times must agree. Handle a rejected request by restoring the previous world and camera. Keep collision on logical interaction roots and visual hinges on children. Rooms/Portals control visibility and do not replace this scene-loading sequence.