Introduction

AuraJS is a JavaScript-first game runtime with a native host underneath it.

The working model is simple:

• keep game state in plain JavaScript objects
• load content in aura.setup
• advance simulation in aura.update(dt)
• submit draw calls in aura.draw()
• treat aura.* as the full runtime surface

If you are starting a new project, read these pages in order:

1. Start Here
2. Creating a New Game
3. Getting Started 2D or Getting Started 3D
4. Working with an AuraJS Project
5. Game Dev API Handbook

The AuraJS mental model

AuraJS is not a retained scene editor or class-heavy engine API. The normal pattern is:

1. define some top-level state
2. initialize assets and runtime handles in setup
3. update state from input and time in update
4. draw the current frame in draw

That means:

• your gameplay code stays close to the main loop
• your state is easy to inspect, save, sync, and replay
• AI agents can work with the engine without loading a deep object model

The core loop

The committed lifecycle is:

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

Most games can ignore the extra callbacks until they need resize handling, pause behavior, or cleanup.

How to think about the runtime surface

Use the namespaces like this:

• aura.window, aura.input, aura.draw2d, aura.audio, aura.assets, aura.storage, aura.fs for the normal 2D/native game loop
• aura.draw3d, aura.camera3d, aura.light, aura.mesh, aura.material, aura.scene3d for 3D rendering
• aura.physics, aura.physics3d, aura.terrain, aura.navmesh, aura.character3d when your game actually needs simulation-heavy systems
• aura.video when you need native desktop .mp4 playback or the frame/spritesheet fallback

Keep the optional-module mindset:

• 2D window/input/assets/draw is the safest baseline
• 3D is native-only today
• some namespaces are module-gated and should be treated as optional

Recommended development path

If you want the shortest route to a working game:

1. start with one screen and one input loop
2. load only the assets you need for that screen
3. keep the first version asset-light and state-light
4. make the game feel correct before adding more systems
5. add audio, UI text, saves, and effects after the loop is stable

For 3D specifically:

1. start with one camera, one light, one mesh, one material
2. get that scene rendering correctly
3. add imported content, scene nodes, and animation after the base scene is stable
4. add physics, terrain, or navmesh only when the game truly needs them

Where exact truth lives

Use these guides for the golden path. When exact signatures or validation behavior matter, use the contract docs:

• docs/api-contract.md
• docs/api-contract-3d.md
• docs/video-cutscene-contract-v1.md
• docs/native-mp4-video-contract-v1.md

For machine-readable consumption, AuraJS also ships a generated JSON artifact:

• https://www.aurajs.gg/aurajs-public-api-schema-v1.json

Use the grouped handbook when you need a namespace-by-namespace map:

• Game Dev API Handbook

Use the narrower exact-reference pages when you know the subsystem and want to avoid searching the full contracts:

• AuraJS Reference Docs
• Runtime and 2D Exact Reference
• 3D Rendering and Content Exact Reference

One important rule

Do not guess at unsupported parity.

The safest AuraJS workflow is:

• native first
• 2D first unless the project is clearly 3D
• explicit asset formats
• explicit capability checks for optional systems