AURA

JSGG

AuraJS
DOCSEXAMPLESGITHUB
Working with an AuraJS Project
Exact-reference guide for scaffold layout, generated project files, make commands, and authored state ownership.
docs/external/game-dev-api/working-with-an-aurajs-project.md

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 defaults to 2d-adventure
  • auramaxx create with no name 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 level intro-route
auramaxx make dialogue archive-brief
auramaxx make encounter opening-skirmish
auramaxx make entity signal-orb
auramaxx make spawn-table enemy-spawns
auramaxx make cinematic opening-reveal
auramaxx make content spawn-table
auramaxx make material GrassTile
auramaxx make shader RimLight

make config, make content, and the content-family generators 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.

The content-family generators also maintain registry modules under content/registries/ for levels, dialogue, encounters, entities, spawns, and cinematics so authored content can stay indexed instead of turning into folder sprawl.

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/
    dialogue/
      # authored conversations and branching text
    encounters/
      # wave plans and encounter payloads
    entities/
      # placed collectibles and entity payloads
    gameplay/
      # catch-all gameplay payloads when no narrower family fits
    levels/
      # tilemaps, routes, room layouts, and course data
    localization/
    registries/
      # starter-owned registries when a template needs them
    spawns/
      # spawn zones, checkpoints, and placement payloads
  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/levels/moon-archive.level.js, content/dialogue/archive.dialogue.js
  • 2d-shooter: config/gameplay/shooter.config.js, content/encounters/wave-plan.json
  • 2d-survivor: config/gameplay/survivor.config.js, content/spawns/spawn-zones.json
  • 3d-adventure: config/gameplay/adventure.config.js, content/levels/signal-route.course.js, content/spawns/signal-route.spawns.js
  • 3d-platformer: content/levels/checkpoint-climb.course.js, content/spawns/checkpoints.json
  • 3d-collectathon: content/levels/relic-run.course.js, content/entities/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
DOCUMENT REFERENCE
docs/external/game-dev-api/working-with-an-aurajs-project.md
AURAJS
Cmd/Ctrl+K
aurajsgg