@auraindustry/aurajs

Alpha status: AuraJS is currently in alpha and is not safe for production use yet.

Write games in JavaScript and build native binaries for macOS, Linux, and Windows.

Current mobile build truth:

• aura build --target android|ios|mobile stages mobile package roots in v1
• build/android/android-build-manifest.json and build/ios/ios-build-manifest.json are the target-owned truth surfaces
• aura run remains desktop/web only; mobile targets hand off to the staged package lane
• shared mobile capability conformance reason-codes desktop-only assumptions instead of implying parity

Create A New Game

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

One-off bootstrap without a global install:

npx auramaxx

Scaffolded projects also expose the shorter aura alias for in-project engine commands.

Local-First Dev Loop

AuraJS currently leads with the scaffolded native loop:

cd my-game
npm run dev

When you want the live developer session surface in parallel with the native window, stay in the same project wrapper:

npm run state -- export --session <session-id> --compact
npm run inspect -- export --session <session-id> --compact
npm run action -- schema --session <session-id> --compact

Generated projects wire those commands through bin/play.js. Raw aura dev still exists as the engine command, but it is no longer the public first step for a new local project.

The same native play lane also exposes aura play / npm run play for the foreground live-session loop. Press F1 in that runtime to open the dev-only playtest HUD, jump between authored scenes, and use the compact record, screenshot, restart, pause, and minimize controls.

This wrapper-driven native lane is the current product center for aura dev. Browser rebuilds exist, but they are a secondary surface in this stage rather than the default authoring loop.

Room-Code Multiplayer

The public first stop is the single-project local-first starter:

auramaxx create my-room-game --template multiplayer
cd my-room-game
npm run dev

# second terminal
npm run join -- AURA2P

Fastest internet-backed upgrade for the same starter:

AURA_MULTIPLAYER_RELAY_HOST=relay.aurajs.gg npm run dev
AURA_MULTIPLAYER_RELAY_HOST=relay.aurajs.gg npm run join -- AURA2P

The lower-level proof path is still two native aura dev --session processes on one machine using a room code. See:

• ../../docs/local-multiplayer-dev-playbook.md
• ../../examples/README.md

Publish And Play

In a scaffolded AuraJS game:

aura publish --dry-run
npm run publish
npm run play
npx <game> fork ./mygame-local

aura publish is the canonical npm-first publish command. In generated projects, npm run publish delegates to the same engine-owned lane, which then dispatches to npm publish with scoped packages defaulting to public access. The dry-run lane validates the native build contract first and writes .aura/publish/publish-report.json before dispatch. Change package.json -> name first if you are publishing outside the @aurajs scope.

Raw npm publish remains available as an escape hatch, but it is not the engine-owned product path for this stage and does not replace the publish report/validation contract.

Published game wrappers also expose fork, which copies the installed package surface into a new local directory for editing. After npx <game> fork ./mygame-local, run npm install inside the fork before starting npm run dev.

Secondary API Surfaces

• Cutscene/media helpers: @auraindustry/aurajs/cutscene
• JS-first retained 3D scene helpers: @auraindustry/aurajs/scene-composition
• Scene prefab and serialization helpers: @auraindustry/aurajs/prefabs
• Shader kits over custom materials: @auraindustry/aurajs/shader-kits
• React embedding: @auraindustry/aurajs/react
• Web runtime helpers: @auraindustry/aurajs/web

These package surfaces stay available, but native local development is the priority path in the current stage and browser work remains secondary.

Current media truth:

• native desktop .mp4 playback is supported through aura.video and the cutscene helpers
• browser .mp4 parity is not part of the current contract
• frame sequences or sprite sheets remain the portable fallback

Docs

• Repo README: https://github.com/Aura-Industry/auramaxx
• Docs hub: https://aurajs.gg/docs
• Game Dev API handbook: https://aurajs.gg/docs/asc
• Core API: https://aurajs.gg/docs/api-contract
• 3D API: https://aurajs.gg/docs/api-contract-3d