AURA

JSGG

AuraJS
DOCSEXAMPLESGITHUB
CLI, Create, Build, Dev, Test, and Project Files
Public CLI entrypoints, scaffolded project loops, session model, and current project file shape.
docs/external/game-dev-api/13-cli-create-build-dev-test-and-project-files.md

CLI, Create, Build, Dev, Test, and Project Files

AuraJS currently exposes three related public entrypoints:

  • auramaxx ... for global install, first-run bootstrap, project creation, project-local authoring commands, and auramaxx play <game> ... from any directory
  • npm run ... for the generated project-local wrapper scripts inside a scaffolded game
  • npx <game> ... for scaffolded or published game wrappers

TL;DR

Bootstrap loop:

npm install -g auramaxx
auramaxx create my-game
cd my-game
npm run dev

# or run the interactive bootstrap once
npx auramaxx

Local developer loop:

cd my-game
npm run dev
auramaxx make scene Scene1
auramaxx vendor helpers
auramaxx explain
auramaxx check
npm run state -- export --compact
npm run action -- schema --compact

Published game loop:

npx <game> play
npx <game> session start
npx <game> state export --compact

auramaxx play <game> play
auramaxx play <game> session start
auramaxx play <game> state export --compact

Important truth:

  • public docs lead with auramaxx, not aura
  • inside a scaffolded repo, auramaxx resolves the current AuraJS project for authoring and publish commands
  • generated npm run dev|play|session|state|inspect|action scripts remain the shortest local wrapper path
  • session controls an AuraMaxx-launched project process; it is not a generic attach API for arbitrary foreign processes

Entry Point Model

`auramaxx`

Use auramaxx for the public AuraJS surface both outside and inside a project.

Current important commands:

  • auramaxx create <name> [--template ...] [--skip-install]
  • auramaxx dev
  • auramaxx build [--target <windows|mac|linux|all|web|android|ios|mobile>]
  • auramaxx play
  • auramaxx run [--session]
  • auramaxx make ...
  • auramaxx vendor helpers [--force]
  • auramaxx explain
  • auramaxx check
  • auramaxx publish [--dry-run]
  • auramaxx external-assets generate --public-base-url <url>
  • auramaxx clean
  • auramaxx test [file] [options]
  • auramaxx conformance [--mode shim|native|both] [--json]
  • auramaxx state <export|diff|patch|apply|step|slot|checkpoint> ...
  • auramaxx inspect export ...
  • auramaxx action <schema|run> ...
  • auramaxx session <start|list|attach|detach|close|state|inspect|action> ...
  • auramaxx play <game> ...
  • auramaxx publish
  • npx auramaxx

Important notes:

  • auramaxx create is the public create path used in onboarding and docs.
  • npx auramaxx runs the same first-run flow without requiring a global install.
  • inside a project root, auramaxx delegates to the AuraJS project you are standing in
  • auramaxx play is the fastest local path for a visible native game plus a live developer session
  • auramaxx run is the lower-level launcher; add --session when you want explicit live session registration
  • auramaxx session start defaults to native; use --headless when you explicitly want a detached non-windowed runtime
  • auramaxx explain and auramaxx check describe and validate the authored registry, scenes, screens, prefabs, data files, and runtime bootstrap files for the current project

Build Target Truth

Current output lanes are intentionally split by platform truth:

  • --target web emits browser artifacts under build/web for the current browser-backed subset.
  • --target android|ios|mobile produces host artifacts, stages mobile package roots, and runs Gradle/Xcode export when prerequisites are present; otherwise manifests stay reason-coded and staged.
  • Mobile targets require --asset-mode embed in v1.

`npx `

Scaffolded and published AuraJS games ship a small wrapper CLI.

Default public commands:

  • play
  • fork
  • publish
  • session

The wrapper also forwards:

  • state
  • inspect
  • action

The wrapper keeps default help intentionally small. Use --help --all when you want the full forwarded surface.

Examples:

npx mygame play
npx mygame fork ./mygame-local
npx mygame session start
npx mygame state export --compact
npx mygame action schema --compact

npx <game> fork [destination] copies the installed package surface into a new local directory for editing. When you omit destination, the wrapper suggests a default ./<game>-fork target (or a sibling path when you launch from inside an existing project root). The copy intentionally skips transient runtime artifacts such as .logs/, .aura/, build/, .git/, and node_modules/. Run npm install inside the fork after the copy completes.

`auramaxx play `

AuraMaxx can launch the published game wrapper directly.

Examples:

auramaxx play mygame
auramaxx play mygame fork ./mygame-local
auramaxx play mygame session start
auramaxx play mygame state export --compact
auramaxx play mygame action schema --compact

auramaxx play <game> now preserves forwarded game verbs instead of treating everything after the package name as an opaque play-only tail.

Published game launches through auramaxx play <game> preserve the local shell environment before handing off to the installed game wrapper. .env remains a project-root convenience for project-owned runs; for published wrapper runs, export the vars you want in the local shell before launch.

When a project-root .env exists, auramaxx publish generates a blank .env.example from its keys and excludes the real .env from the npm package surface.

auramaxx publish now emits a signed package integrity manifest into the published package surface. AuraMaxx verifies that manifest before launch, including exact file hashes plus published metadata such as npm name/version/description, authored identity/window metadata, and publish-time icon/build identity records. Packages published outside auramaxx publish will not carry that manifest and are not treated as safe by auramaxx play <game>. AuraMaxx also pins the signer fingerprint on first successful launch and refuses later signer changes for the same published package name. For the trust model and remaining limits, see docs/published-game-security.md.

Large Self-Hosted Assets

auramaxx publish also measures the built asset payload before it asks npm to carry the package. The default npm-first threshold is 50 MiB, and operators can override it with AURA_PUBLISH_ASSET_THRESHOLD_BYTES when they need a different release policy.

When the payload is too large for the normal npm-first lane, the current public answer is self-hosting on infrastructure you control:

  1. keep npm as the code/bootstrap transport
  2. host the heavy assets yourself on a public HTTPS origin such as Cloudflare R2, S3, or an equivalent object/static host
  3. run auramaxx external-assets generate --public-base-url <url> to write aura.external-assets.json and stage manifests plus upload records
  4. publish the slim npm package after that config exists
  5. let packaged npx <game> play or join hydrate and cache the hosted assets before launch

Live Session Model

There are two honest developer-session shapes today:

  1. native-default session
  2. explicit headless session

Native-default session:

  • auramaxx play
  • auramaxx run --session
  • auramaxx session start

These flows launch one Aura-owned native process and register it as the current developer session for the project. Other terminals can then use:

  • auramaxx session state export
  • auramaxx session inspect export
  • auramaxx session action schema
  • auramaxx session action run
  • auramaxx session close

Explicit headless session:

auramaxx session start --headless --name ci-loop --compact

Use this when a visible native window is not wanted.

Still not claimed:

  • arbitrary attach to an already-running foreign process
  • generic keyboard/mouse/gamepad injection for every genre

`auramaxx create`

auramaxx create is the public scaffold command.

Current templates:

  • 2d-adventure
  • 2d-shooter
  • 2d-survivor
  • deckbuilder-2d
  • 3d-adventure
  • 3d-platformer
  • 3d-collectathon
  • blank
  • local-multiplayer

Current create note:

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

Generated project shape includes:

  • package.json
  • aura.config.json
  • aura.capabilities.json
  • README.md
  • RUNBOOK.md
  • src/
  • src/starter-utils/ for non-blank templates
  • src/runtime/project-registry.js for registry-backed authored projects
  • src/runtime/scene-registry.js for registry-backed authored projects
  • src/runtime/project-inspector.js for registry-backed authored projects
  • src/runtime/scene-flow.js for registry-backed authored projects
  • src/runtime/screen-shell.js for registry-backed authored projects
  • scenes/, ui/, prefabs/, config/, and content/ for scaffolded authored starters
  • assets/
  • skills/
  • .logs/
  • bin/play.js

Scaffold notes:

  • projects are npm-ready
  • capabilities metadata is generated from template metadata
  • starter asset packs are generated per template
  • non-blank templates seed local helper copies into src/starter-utils/
  • the published @auraindustry/aurajs/helpers lane owns the shared helper implementation, while scaffolded gameplay code can keep local copies
  • non-blank 2D templates include copied helper modules such as src/starter-utils/animation-2d.js, tween-2d.js, and combat-feedback-2d.js
  • non-blank starters also include copied trigger helpers in src/starter-utils/triggers.js
  • adventure starters also include copied progression helpers in src/starter-utils/adventure-objectives.js
  • logs are streamed into .logs/ during wrapper and dev flows
  • the generated wrapper is the user-facing CLI for play, publish, and session

Registry-backed authored projects now also scaffold an app-shell runtime:

  • scene-flow.js owns scene-stack flow for replace/push/pop cases
  • screen-shell.js owns mounted HUD, overlay, and modal screen state
  • project-registry.js remains the authored inventory and source of truth
  • auramaxx make scene|ui-screen|prefab self-wires those authored files into the project registry

In practice, that means starters can mount HUD and pause/settings screens through one explicit runtime model instead of only starter-local booleans.

`aura.config.json`

The main config file controls identity, window/build settings, and module gates.

Common module flags:

  • modules.physics
  • modules.network
  • modules.multiplayer

Important naming detail:

  • the config flag is modules.network
  • the runtime namespace is aura.net

State, Inspect, and Action Flows

The CLI exposes three related developer surfaces:

  • auramaxx state ... for canonical state export/apply/diff/restore
  • auramaxx inspect export for engine/runtime telemetry snapshots
  • auramaxx action ... for optional gameplay-semantic commands defined by the game
  • auramaxx replay run ... for deterministic headless input replay with checkpoints and divergence reports
  • auramaxx evidence for one combined headless manifest plus state.json, inspect.json, perf.json, and optional replay artifacts

Examples:

auramaxx state export --compact
auramaxx inspect export --compact
auramaxx action schema --compact
auramaxx action run request.json --export-state --compact
auramaxx replay run replay.json --compact
auramaxx evidence --compact
auramaxx evidence --replay replay.json --compact

For development restore loops:

  • auramaxx dev --restore-slot <name>
  • auramaxx dev --restore-checkpoint <name>

Test and Conformance Workflows

Testing surfaces:

  • auramaxx test runs a headless game-logic harness
  • auramaxx conformance runs API-level conformance in shim/native/both modes

These are useful for:

  • agent-generated regression checks
  • deterministic gameplay assertions
  • API truthfulness audits after runtime changes

Package-Level Exports

The published package currently exports:

  • ./cutscene
  • ./helpers
  • ./helpers/2d
  • ./scene-composition
  • ./prefabs
  • ./shader-kits
  • ./react
  • ./web
  • CLI binaries auramaxx and aura
DOCUMENT REFERENCE
docs/external/game-dev-api/13-cli-create-build-dev-test-and-project-files.md
AURAJS
Cmd/Ctrl+K
aurajsgg