Assets, Audio, Persistence, and Runtime FS

This page covers loading content, audio playback, simple save persistence, and the runtime file API.

`aura.assets`

Core loading surface:

• load(path)
• exists(path)
• loadJson(path)
• loadText(path)
• loadFont(path)
• loadBitmapFont(path)
• getFormatSupport(path)

Streaming/cache helpers:

• getState(path)
• getStateHistory(path)
• evict(path)
• getCachePolicy()
• setCachePolicy(policy)
• preload2d(paths)
• preload3d(paths)

Use cases:

• deterministic asset preloading
• text/json/font ingestion
• cache lifecycle introspection for large projects

Notes:

• The canonical game-dev surface is the load* family above.
• Some shims/test harnesses expose convenience getters, but the contract-backed API is load, loadJson, loadText, and the preload/cache methods listed here.

`aura.audio`

Core playback and global control:

• play(...)
• stop(handle)
• pause(handle)
• resume(handle)
• getState(handle)
• setVolume(handle, volume)
• setMasterVolume(volume)
• pauseAll()
• resumeAll()
• stopAll()

Spatial audio and listener/emitter helpers:

• setHRTF(enabled)
• setListener(options)
• playSpatial(pathOrSpec, options)
• setEmitterPosition(handle, position)
• setOcclusion(handle, value)
• addReverbZone(zone)
• removeReverbZone(zoneId)
• clearReverbZones()

Mixer/bus/envelope helpers:

• setBusVolume(bus, volume)
• assignBus(handle, bus)
• fadeTrack(handle, options)
• fadeBus(bus, options)
• crossfade(fromHandle, toHandle, options)
• update(dt)
• clearEnvelopes()
• getMixerState()

Use cases:

• SFX/music routing
• spatial emitters attached to world objects
• dynamic bus control and cinematic crossfades
• explicit pause-menu and cutscene audio ownership
• live handle-state checks without bespoke per-game registries

Truth boundary:

• getState(handle) returns null for unknown or inactive handles
• mixer-backed voices expose live playback state, volume/pitch, and timing fields
• resumeAll() only resumes handles paused by pauseAll(), not handles gameplay paused explicitly earlier
• external fallback playback still reports active/paused/volume truth, but timing fields stay null because that runtime path does not own sample position

Scaffolded 2D Scene Audio Helper

Generated 2D projects can also use src/starter-utils/scene-audio-2d.js when you want one explicit scene-level ownership lane on top of aura.audio.

The helper owns a deliberately small contract:

• createSceneAudio2D(aura, options?)
• ensureSceneMusic2D(sceneAudio, path, options?)
• playSceneStinger2D(sceneAudio, path, options?)
• pauseSceneAudio2D(sceneAudio, options?)
• resumeSceneAudio2D(sceneAudio, options?)
• syncSceneAudio2D(sceneAudio, dt, options?)
• stopSceneAudio2D(sceneAudio, options?)

Truth boundary:

• it is a shared music/stinger/duck/pause/resume helper for medium 2D games
• it still runs on the existing aura.audio mixer/bus surface
• it does not claim audio middleware, authoring tools, or packaged asset resolution beyond the paths you provide
• the accepted packaged/native path is a project-relative asset path such as assets/title-loop.wav
• when you need explicit runtime gating before playback, probe the path with aura.assets.exists(path) first

`aura.storage`

Persistence surface:

• save(key, value)
• load(key, fallback?)
• delete(key)
• keys()

Legacy aliases:

• set(key, value)
• get(key, fallback?)

Use cases:

• simple preferences
• small save metadata
• local high scores and unlocked flags

For larger authored 2D worlds, the scaffolded helper lane now includes world-persistence-2d.js for explicit streamed-world snapshot and rehydrate ownership over aura.storage.

Keep that boundary honest:

• it captures only the region/world adapters you provide
• it is a continuity helper for fresh-run restore, not a universal mid-frame save-state system
• off-screen simulation and richer object continuity remain downstream of the first persistence slice

For authored 2D adventure starters, the shared helper lane also includes adventure-save-2d.js for explicit route-progression save composition and checkpoint restore ownership over aura.storage.

Accepted helper surface:

• captureAdventureSaveState2D(...)
• captureAdventureCheckpoint2D(...)
• captureAdventureCampaignSaveSummary2D(...)
• composeAdventureCheckpointState2D(...)
• applyAdventureSaveState2D(...)
• saveAdventureSaveState2D(...)
• saveAdventureCampaignSaveSlot2D(...)
• loadAdventureSaveState2D(...)
• loadAdventureCampaignSaveSlot2D(...)
• deleteAdventureSaveState2D(...)

Truth boundary:

• it restores only the authored inventory, journal, progression, player, and world slices you provide or customize
• it is a bounded starter-owned save and checkpoint lane, not a universal rollback or mid-frame sim snapshot system
• richer cross-scene campaign persistence still belongs to later game-specific save ownership

For a menu-facing campaign slot layer above those snapshots, the shared helper lane now also includes campaign-save-2d.js.

Accepted helper surface:

• createCampaignSaveSummary2D(...)
• createCampaignSaveRecord2D(...)
• resolveContinueCampaignSaveSlot2D(...)
• resolveCampaignSaveBoundary2D(...)
• listCampaignSaveSlots2D(...)
• saveCampaignSaveSlot2D(...)
• loadCampaignSaveSlot2D(...)
• deleteCampaignSaveSlot2D(...)

Truth boundary:

• it owns slot labels, run identity, continue/new-game menu boundaries, and small progress summaries
• it composes over starter-owned snapshots stored through aura.storage
• it does not claim a universal persistence framework, editor UI, or arbitrary genre save graphs

Vendored pack JSON/text ownership:

• content/packs/** is an accepted game-owned path once a project vendors a pack payload there
• you can load those files through aura.assets.loadJson(...), aura.assets.loadText(...), or import them as authored JSON modules when the project structure supports it
• the canonical proof is examples/sector-surge-2d, which imports vendored HUD and scene-audio JSON from content/packs/... directly

`aura.fs`

Runtime-safe file helpers:

• exists(path)
• readText(path)
• writeText(path, value)
• readJson(path)
• writeJson(path, value)
• mkdir(path)
• list(path)
• remove(path)

Important notes:

• paths are validated to stay inside the runtime/project root
• absolute paths and .. traversal are rejected
• this is useful for runtime notes, exported data, local tools, and generated content

For richer save/export/apply flows, see 07 Scenes, State, Debug, and Test Harness and the auramaxx state CLI docs.