Runtime, Lifecycle, and Module Gates

This page covers the runtime model that every AuraJS game starts from.

Entry callbacks

AuraJS looks for these top-level callbacks on aura:

• aura.setup()
• aura.update(dt)
• aura.draw()
• aura.onResize(width, height)
• aura.onFocus()
• aura.onBlur()
• aura.onQuit()

Notes:

• setup() runs once during boot.
• update(dt) is the main game-step callback.
• draw() owns immediate-mode rendering.
• onResize, onFocus, and onBlur are optional lifecycle hooks.
• onQuit() can veto shutdown in native runtime by returning false.

Runtime model

AuraJS is immediate-mode first.

• You own rendering from aura.draw().
• Additive helpers like aura.scene, aura.scene3d, aura.anim2d, aura.animation, aura.tween, aura.tilemap, and aura.ecs help organize state, but they do not take over the host loop.
• aura.scene3d is a deterministic hierarchy/helper layer. It does not replace aura.draw3d.drawMesh(...) ownership.

Common namespace families

You should expect the runtime to provide these major groups:

• 2D and core: window, input, draw2d, audio, assets, storage, fs, math, timer, collision, collision3d, ecs, debug
• Additive gameplay helpers: anim2d, animation, tween, particles, tilemap, scene, state
• 3D/runtime: draw3d, camera3d, light, mesh, material, scene3d, skinnedMesh, video
• World/simulation: physics, physics3d, terrain, navmesh, character3d, compute
• Online/multiplayer: net, multiplayer

Module gating

The current optional runtime modules are:

• modules.physics = true enables aura.physics
• modules.network = true enables aura.net
• modules.multiplayer = true enables aura.multiplayer

If one of these modules is disabled, AuraJS throws deterministic guidance with a reason code such as:

• optional_module_physics_disabled
• optional_module_net_disabled
• optional_module_multiplayer_disabled

The guidance text points back to the config flag that enables the module.

Reason-coded failures

AuraJS surfaces validation failures in two main ways:

• thrown errors with embedded reason codes for some host calls
• result objects like { ok: false, reasonCode: '...' } for helper-style APIs

As a game dev or agent, you should prefer handling reason codes instead of string-matching whole error messages.

Compatibility and deprecation notes

• Legacy compatibility aliases still exist in a few places, but new code should target the canonical names documented in this handbook and the contract docs.
• aura.state is special: it is added by the CLI/runtime bootstrap layer instead of the bare host namespace installer.

Best follow-up pages

• 02 Window, Input, and 2D Camera
• 07 Scenes, State, Debug, and Test Harness
• 13 CLI, Create, Build, Dev, Test, and Project Files