Working with an AuraJS Project

This is the exact-reference guide for scaffolded AuraJS projects.

Use it when you need:

• the exact CLI to create scenes, screens, prefabs, enemies, cards, and other files
• the scaffold folder layout
• the ownership model for appState, sceneState, config, and content

TL;DR

npm install -g auramaxx
auramaxx create my-game
cd my-game
npm run dev
auramaxx make scene Scene1

Inside a project root, these surfaces all point at the same AuraJS project:

• auramaxx ... public wrapper
• npm run dev|play|publish|state|inspect|action generated wrapper scripts

Exact CLI

Create a project:

auramaxx create my-game
auramaxx create my-game --template 2d-adventure
auramaxx create my-game --template 3d-adventure
auramaxx create my-game --template blank

Current create behavior:

• auramaxx create my-game opens the starter prompt
• auramaxx create my-game --template ... accepts the shipped template catalog
• --template 2d and --template 3d normalize to 2d-adventure and 3d-adventure

Run the local dev loop:

cd my-game
npm run dev
auramaxx explain
auramaxx check

List available generators for the current project:

auramaxx make list
auramaxx make list --json

Core generators available in every scaffold:

auramaxx make scene Scene1
auramaxx make ui-screen PauseMenu
auramaxx make prefab EnemyShip --role enemy
auramaxx make system Combat
auramaxx make component Health
auramaxx make config enemy-table
auramaxx make content spawn-table
auramaxx make material GrassTile
auramaxx make shader RimLight

make config and make content register those new files into src/runtime/project-registry.js, so auramaxx explain and auramaxx check keep reporting the real authored surface instead of only the starter seed files.

Starter-owned generators are template-specific. Example for deckbuilder-2d:

auramaxx make card StrikePlus
auramaxx make enemy JawWorm
auramaxx make relic BurningBlood
auramaxx make encounter Act1Hallway

Interactive make flow:

auramaxx make

When run in a TTY with no arguments, AuraJS opens a selector, asks what to make, then asks for the name.

Use make list as the truthful current project surface. It reflects starter- specific kinds too, while generic help output can still lag the merged per- project catalog.

Project Structure

Every scaffold now uses the same top-level authored layout, including blank:

my-game/
  assets/
    starter/
  bin/
  config/
    balance/
    gameplay/
      game.config.json
      # template-specific config files may live here
  content/
    gameplay/
      # authored levels, waves, checkpoints, collectibles, etc.
    localization/
    registries/
      # starter-owned registries when a template needs them
  docs/
    design/
      content-map.md
      game-pillars.md
  prefabs/
    player.prefab.js
    # reusable gameplay blueprints
  scenes/
    boot.scene.js
    gameplay.scene.js
    # additional authored scenes
  src/
    main.js
    runtime/
      app.js
      app-state.js
      capabilities.js
      project-inspector.js
      project-registry.js
      scene-flow.js
      scene-registry.js
      screen-shell.js
  ui/
    hud.screen.js
  aura.capabilities.json
  aura.config.json
  package.json
  README.md
  RUNBOOK.md

Template-specific files add on top of this:

• 2d-adventure: config/gameplay/adventure.config.js, content/gameplay/world.js
• 2d-shooter: config/gameplay/shooter.config.js, content/gameplay/waves.json
• 2d-survivor: config/gameplay/survivor.config.js, content/gameplay/spawn-zones.json
• 3d-adventure: config/gameplay/adventure.config.js, content/gameplay/course.js
• 3d-platformer: content/gameplay/course.js, content/gameplay/checkpoints.json
• 3d-collectathon: content/gameplay/course.js, content/gameplay/collectibles.json
• deckbuilder-2d: config/gameplay/deckbuilder.config.js, content/cards/, content/enemies/, content/relics/, content/encounters/, content/registries/

State and Data Model

Use this ownership model:

• aura global: engine/runtime API only
• appState: shared mutable app/session state across scenes
• sceneState: mutable state local to one scene while it is running
• config/: defaults, tunables, balancing numbers
• content/: authored nouns and progression content

Short rule:

• If many scenes need it, put it in appState.
• If one scene owns it during play, keep it in sceneState.
• If it is a default or tuning value, put it in config/.
• If it is an authored thing that exists in the game, put it in content/.

Examples:

• appState
  • current profile
  • save slot
  • settings
  • current top-level route or session flags
• sceneState
  • current hp in this fight
  • bullets on screen
  • enemy instances in the current room
  • camera shake timer
• config/
  • player speed
  • dash cooldown
  • enemy spawn rate
  • damage multipliers
• content/
  • enemy definitions
  • card definitions
  • relics
  • encounters
  • waves
  • levels
  • checkpoints

Starter example for src/runtime/app-state.js:

const runFlags = context.ensureSessionState('runFlags', { DID_START: false });
if (!runFlags.DID_START) {
  runFlags.DID_START = true;
}

Where to Put Changes

Use these defaults:

• new game flow or a new room/menu/combat screen: scenes/
• reusable gameplay object blueprint: prefabs/
• HUD or screen presentation: ui/
• cross-scene shared mutable state: src/runtime/app-state.js
• project bootstrap/runtime wiring: src/runtime/
• tuning values: config/
• authored gameplay content: content/
• human-readable design notes: docs/design/

Commands Agents Should Prefer

If you are an agent working in an AuraJS project, prefer these commands:

auramaxx explain --json
auramaxx check --json
auramaxx make list --json

Then use the returned project structure and make kinds instead of inventing paths.

If a generator exists, prefer:

auramaxx make scene Scene1

over hand-creating:

scenes/scene1.scene.js
src/runtime/project-registry.js

Related Docs

• Creating a New Game
• Handling State and Content
• Examples and First-Game Recipes
• Common Failures and Fixes
• Publishing and Large Assets
• 13 CLI, Create, Build, Dev, Test, and Project Files