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
  • auramaxx web ... for the explicit web-first create/dev/build/run umbrella
  • auramaxx web registry ... for the local-first AuraRegistry search/describe/create/validate surface
  • auramaxx web spec ... for the web-first game-spec compiler wrapper
  • 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
auramaxx web create my-web-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
auramaxx sync-content --check
npm run api
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|api|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
  • scaffolded projects ship an AGENTS.md that documents the local CLI and REST API surfaces for agents and tools

Entry Point Model

`auramaxx`

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

Current important commands:

  • auramaxx create <name> [--template ...] [--platform <web|native>] [--skip-install]
  • auramaxx web <create|dev|build|run> ...
  • auramaxx web spec <describe|lint|explain|compile> ...
  • auramaxx dev
  • auramaxx build [--target <windows|mac|linux|all|web|android|ios|mobile>]
  • auramaxx play
  • auramaxx run [--session]
  • auramaxx api serve [--port <N>]
  • auramaxx make ...
  • auramaxx vendor helpers [--force]
  • auramaxx explain
  • auramaxx check
  • auramaxx sync-content [--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.
  • in a TTY, auramaxx create asks whether you want a Web or Native project first, asks for native target hints when needed, then asks for the starter.
  • auramaxx web is the explicit browser-facing umbrella when you want the web lane directly instead of choosing a target flag on the lower-level commands.
  • auramaxx web registry is the local-first registry wrapper for AuraRegistry. It resolves the registry source in this order: --registry-url, AURAREGISTRY_URL, then aura.config.json -> registry.url. If nothing is configured, it fails with No registry set.
  • auramaxx web registry compose --template-card ... resolves one local assembly plan for a template-card, including its code-kit, asset-family, and delivery-handle dependencies.
  • auramaxx web registry install --template-card ... applies that local assembly plan to the current project. It updates aura.bundle.json, writes data/registry/assembly.json, persists the local registry URL into aura.config.json, and vendors any repo-backed delivery assets under assets/registry/.
  • auramaxx web create --compose-file <path> --registry-url <path> can scaffold and install one bounded multi-screen compose plan in a single step, leaving the created project ready for auramaxx web dev, run, and build.
  • auramaxx create and auramaxx web create can stamp validated AuraRegistry provenance into aura.bundle.json with --registry-template-card, --registry-code-kit, and repeatable --registry-asset-family when you want generated projects to record the code-kit and asset-family choices they came from.
  • auramaxx web spec is the thin product-facing wrapper over the current standalone game-spec compiler. It forwards describe, lint, explain, and compile, and reuses the same local-first registry resolution order when a spec includes registry-backed selections.
  • auramaxx web spec describe browser2d prints the current machine-readable browser-2d generation catalog and prompt corpus for registry-backed web targets.
  • 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; web-first projects use it for the browser preview lane, while native projects can add --session for 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
  • bundle-first projects can also describe sectioned contentPacks in aura.bundle.json, so story, dialogue, balance tables, and other authored nouns can live in smaller section folders instead of one giant runtime module
  • newly created projects now always include aura.bundle.json; it records the created product lane through product.platform

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.
  • web-first projects default plain auramaxx build to that same browser export lane.
  • auramaxx web build is the explicit wrapper for that same browser export lane and defaults to --target web.
  • the supported public browser export lane is 2D.
  • that supported 2D lane already covers the committed browser starters plus real examples such as auragotchi and bomberman-2d.
  • richer 2D examples can still be bounded partial browser lanes; aurasu and auramon are current public examples of that shape.
  • service-backed 2D examples can still expose a bounded local browser lane; infinitemon is the current guest/offline example of that shape, while its auth/save/discovery backend remains outside the public web contract.
  • native-first flagship examples such as sector-surge-2d remain outside the browser export contract today.
  • room-code multiplayer starters such as local-multiplayer remain outside the browser export contract today.
  • video playback and video-cutscene projects remain outside the browser export contract today.
  • current 3D web output uses a bounded three.js-backed browser runtime for a partial Aura 3D subset; Aura still owns the authored project model and build flow, so this is not a separate Three.js project type.
  • auramaxx dev --target web --serve is the local browser preview command; it rebuilds build/web and hosts a static preview server.
  • web-first projects default plain auramaxx dev to that browser preview loop.
  • auramaxx web dev is the explicit wrapper for that same browser preview loop and defaults to --target web --serve.
  • auramaxx run --target web hosts the built build/web output on a local preview server without the rebuild watcher.
  • web-first projects default plain auramaxx run to that browser preview lane.
  • auramaxx web run is the explicit wrapper for that same one-shot browser preview lane and defaults to --target web.
  • --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.

For the shorter target-by-target export map, use Exporting Your Game.

`npx `

Scaffolded and published AuraJS games ship a small wrapper CLI.

Default public commands:

  • play
  • fork
  • publish
  • api
  • session
  • state
  • inspect
  • action

Examples:

npx mygame play
npx mygame fork ./mygame-local
npx mygame api --port 3001
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. Do not hand-edit the generated wrapper script or replace the publish lane with a custom script unless you also plan to replace that verification model, because AuraMaxx checks the published wrapper/package contract during play and related published-game commands. 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> defaults to 2d-adventure
  • auramaxx create with no name opens the create prompt
  • the create prompt chooses Web or Native first, then native target hints when needed, then the starter
  • auramaxx create <name> --template ... accepts the shipped template catalog
  • auramaxx create <name> --platform web preselects a web-first project
  • --template 2d and --template 3d normalize to 2d-adventure and 3d-adventure

Generated project shape includes:

  • package.json
  • aura.config.json
  • aura.capabilities.json
  • AGENTS.md
  • 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, api, session, state, inspect, and action
  • AGENTS.md documents the local wrapper commands, /api/* REST routes, and the detected action/state surface after auramaxx build refreshes it

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
  • auramaxx sync-content rebuilds authored content registries from the files that actually exist on disk, while --check reports drift without writing
  • when aura.bundle.json declares sectioned bundle contentPacks, auramaxx sync-content also regenerates the pack's generated/*.registry.js files plus the generated pack index entry

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

Project-understanding truth for the current Stage 199 lane:

  • auramaxx explain --json and auramaxx check --json now surface optional packs with installMode, sourceMode, ownershipMode, and vendoredPaths
  • ownershipMode=vendored-game-content means the project owns those content/packs/** or other vendored roots directly
  • replay/evidence and state-slot surfaces stay separate: replay owns deterministic input proof, while state slot owns the menu-facing campaign continue boundary

`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 state slot save boss-ready --report artifacts/slot-save.json --slot-label "Boss Ready" --scene-id harbor --checkpoint-id boss-gate --progress-label "Harbor Boss Gate"
auramaxx state slot list --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

Current state-slot truth:

  • auramaxx state slot save ... can attach optional campaign summary metadata such as slot label, run id, scene id, checkpoint id, progress label, playtime, autosave, and run start time
  • auramaxx state slot list returns artifact metadata plus one campaignBoundary summary that makes the current continue versus new game menu boundary explicit
  • auramaxx state slot restore <name> preserves that slot metadata in the restore report

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