Scenes, State, Debug, and Test Harness

This page groups the runtime management helpers that sit above raw draw/update code.

`aura.scene`

Deterministic scene lifecycle helper:

• define(sceneKey, definition)
• register(sceneKey, definition)
• start(sceneKey)
• switchTo(sceneKey)
• update(dt)
• getState()
• schedule(delay, callback, options?)
• pauseEvent(eventId)
• resumeEvent(eventId)
• cancelEvent(eventId)
• getEventState(eventId)

Use cases:

• scene boot/create/update/shutdown sequencing
• scene-local timed events without adding a separate scheduler
• menu/gameplay/cutscene scene switching

Important boundary:

• aura.scene is still the low-level lifecycle helper.
• Registry-backed AuraJS projects now also scaffold a higher-level authored app shell on top of it for stacked scene flow, mounted screens, and gameplay triggers.

Authored App Shell

Registry-backed starters and authored projects now ship three JS-first helpers:

• src/runtime/scene-flow.js
• src/runtime/screen-shell.js
• src/starter-utils/triggers.js

These are scaffold/runtime surfaces, not new aura.* namespaces.

Scene flow

Use scene-flow.js when you want app-style scene handoff instead of only manual switchTo(...) orchestration.

Committed surface:

• replace(sceneId, data?)
• push(sceneId, data?)
• pop(result?)
• current()
• canPop()
• getState()

This covers the common authored flow cases:

• title -> gameplay
• gameplay -> game-over
• temporary briefing scenes
• return flow after a pushed scene

State snapshots use schema aurajs.scene-flow.v1.

Screen shell

Use screen-shell.js when you want mounted authored screens instead of starter-local booleans for HUD, overlays, and pause/settings menus.

Committed surface:

• setHud(screenId, data?)
• clearHud()
• showOverlay(screenId, data?)
• clearOverlay()
• pushModal(screenId, data?)
• popModal(result?)
• getState()

This gives one explicit runtime model for:

• always-on HUD
• prompt/objective overlays
• pause/settings modal stacks

State snapshots use schema aurajs.screen-shell.v1.

Trigger helpers

Use src/starter-utils/triggers.js when you want reusable entered/stayed/left tracking and prompt readiness without hand-rolling previous-frame overlap bookkeeping.

Committed helper families:

• createRectTrigger2D(...)
• createProximityTrigger3D(...)
• createVolumeTrigger3D(...)
• createTriggerTracker(...)
• stepTriggerTracker(...)
• createInteractionPromptState(...)
• updateInteractionPromptState(...)

State snapshots use schemas:

• aurajs.trigger-tracker.v1
• aurajs.interaction-prompt.v1

Common use cases:

• checkpoints
• pickups
• objective zones
• press-key interaction prompts

For one complete authored proof, see examples/scene-flow-frontier.

`aura.state`

Structured state export/apply helper installed by the CLI/runtime bootstrap layer.

Canonical surface:

• export(options?)
• apply(payload, options?)
• diff(before, after, options?)
• patch(state, patchPayload, options?)

Compatibility aliases:

• exportState(...)
• applyState(...)
• diffState(...)
• patchState(...)

Important notes:

• aura.state is not a core Rust-host namespace install like aura.window or aura.draw2d.
• Native and headless flows install it through the JS runtime bootstrap.

Use cases:

• deterministic export/apply workflows
• save snapshots, patching, diffing
• tooling/agent loops and hot-reload restore flows

`aura.debug`

Runtime diagnostics and overlay helpers:

• log(...)
• drawRect(...)
• drawCircle(...)
• drawText(...)
• showScene3dWireframe(enabled)
• showPhysics3dColliders(enabled)
• cacheStats()
• resetCaches()
• enableInspector(enabled)
• inspectorStats()

Use cases:

• quick gameplay overlays
• cache and renderer diagnostics
• scene3d/physics inspection during development

`aura.test`

Headless/conformance-only assertion helper:

• assert(condition, message?)
• equal(actual, expected, message?)

Important note:

• Treat aura.test as a test harness surface, not as a shipping gameplay runtime API.
• It is primarily available in auramaxx test and conformance flows.

Related CLI flows

These runtime helpers connect directly to CLI tooling:

• auramaxx play
• auramaxx state export
• auramaxx state diff
• auramaxx state patch
• auramaxx state apply
• auramaxx inspect export
• auramaxx action schema
• auramaxx action run
• auramaxx session state export
• auramaxx session inspect export
• auramaxx session action schema
• auramaxx session action run
• auramaxx state slot save|restore|list
• auramaxx state checkpoint save|restore|list
• auramaxx dev --restore-slot <name>
• auramaxx dev --restore-checkpoint <name>

For operator-level details, see:

• docs/game-state-cli-contract-v1.md
• docs/state-cli-playbook.md