Handling State and Content

TL;DR

• aura is the global engine API.
• appState is shared mutable state for the whole game/session.
• sceneState is local mutable state owned by one scene.
• config/ is for defaults and tuning.
• content/ is for authored game definitions.

Use This Rule

• If many scenes need it, put it in appState.
• If only one scene needs it while running, keep it in sceneState.
• If it is a default, balance value, or tuning knob, put it in config/.
• If it is a card, enemy, item, encounter, level, registry, or localization file, put it in content/.

Examples

• appState

  • current profile
  • unlocked progression
  • audio/settings state
  • cross-scene UI/session state

• sceneState

  • current HP in this battle
  • enemies alive on screen
  • bullets, timers, cooldowns, camera shake
  • encounter-local temporary state

• config/

  • player speed
  • dash cooldown
  • hand size
  • starting health
  • scoring and spawn tuning

• content/

  • cards
  • enemies
  • relics
  • encounters
  • levels
  • checkpoints
  • localization
  • starter-owned registries

Mental Model For App-Style Projects

• appState is like app-wide store/context state.
• sceneState is like route/page-local state.
• config/ is like app config and feature tuning.
• content/ is like CMS or authored game data.

Where This Lives In A Scaffold

• src/runtime/app-state.js owns shared mutable appState for the project.
• src/runtime/project-registry.js is the authored source of truth for configFiles and contentFiles.
• scenes/ owns top-level flow and the sceneState that only one scene needs while running.
• config/ owns defaults, tuning, balance, and feature knobs.
• content/ owns authored definitions, registries, levels, encounters, cards, enemies, and localization payloads.

Quick Placement Test

• If several scenes need to read or mutate it, use appState.
• If it only matters while one scene is active, keep it in sceneState.
• If it is a default or balancing value, put it in config/.
• If it defines what exists in the game, put it in content/.

What Not To Do

• Do not put normal mutable game state on aura.
• Do not use random top-level module globals when the state belongs to one scene.
• Do not mix tuning and authored content in one catch-all folder.