auramaxx 0.1.0 → 0.1.1

package/README.md

@@ -27,15 +27,34 @@ npx auramaxx
 Inside a scaffolded game, use the shorter `auramaxx` alias or the generated
 `npm run ...` scripts for local engine commands.
 
-Play an example:
+## Play an Example
 
 ```bash
-auramaxx play aurasu
+npm install -g auramaxx
+auramaxx play auracraft
 
 # or run a published game wrapper directly
-npx aurasu play
+npx auracraft play
+```
+
+## Fork a Game
+
+```bash
+npm install -g auramaxx
+auramaxx fork auramon
 ```
 
+## Working With AI Agent
+
+Inside your codebase:
+
+```bash
+cd <your-codebase>
+npx -y skills add Aura-Industry/auramaxx
+```
+
+Then use <https://www.aurajs.gg/docs> for engine docs and API references.
+
 ## Multiplayer TL;DR
 
 ```bash
@@ -52,7 +71,7 @@ Keep that same flow and add internet-backed rooms with either:
 - `aura.config.json -> multiplayer.relay = "relay.aurajs.gg"`
 - or `AURA_MULTIPLAYER_RELAY_HOST=relay.aurajs.gg`
 
-Use [`packages/aurascript/docs/external/game-dev-api/multiplayer-quickstart.md`](./packages/aurascript/docs/external/game-dev-api/multiplayer-quickstart.md) for the short multiplayer doc, or [`packages/aurascript/examples/multiplayer-party/README.md`](./packages/aurascript/examples/multiplayer-party/README.md) for the same-project example with diagnostics and room chat.
+Use [Multiplayer Quickstart](https://www.aurajs.gg/docs/multiplayer-quickstart) for the short multiplayer doc, or [Multiplayer Party Example](./packages/aurascript/examples/multiplayer-party/README.md) for the same-project example with diagnostics and room chat.
 
 ## Feature Set
 
@@ -80,13 +99,13 @@ Use [`packages/aurascript/docs/external/game-dev-api/multiplayer-quickstart.md`]
 
 ## Docs
 
-- [`packages/aurascript/README.md`](./packages/aurascript/README.md) - AuraJS overview and public docs entrypoint
-- [`docs/external/game-dev-api/README.md`](./docs/external/game-dev-api/README.md) - game developer handbook
-- [`docs/external/game-dev-api/multiplayer-quickstart.md`](./packages/aurascript/docs/external/game-dev-api/multiplayer-quickstart.md) - shortest multiplayer setup path
-- [`docs/api-contract.md`](./docs/api-contract.md) - frozen core API contract
-- [`docs/api-contract-3d.md`](./docs/api-contract-3d.md) - frozen 3D API contract
-- [`docs/reference/README.md`](./docs/reference/README.md) - exact reference index
-- [`docs/external/api-contract-complete.md`](./docs/external/api-contract-complete.md) - combined public reference
+- [AuraJS README](https://www.aurajs.gg/docs) - AuraJS overview and public docs entrypoint
+- [Game Developer Handbook](https://www.aurajs.gg/docs/handbook) - game developer handbook
+- [Multiplayer Quickstart](https://www.aurajs.gg/docs/multiplayer-quickstart) - shortest multiplayer setup path
+- [Core API Contract](https://www.aurajs.gg/docs/api-contract) - frozen core API contract
+- [3D API Contract](https://www.aurajs.gg/docs/api-contract-3d) - frozen 3D API contract
+- [Exact Reference Index](https://www.aurajs.gg/docs/reference) - exact reference index
+- [Combined Public Reference](https://www.aurajs.gg/docs/reference) - combined public reference
 
 Live docs:
 

package/bin/auramaxx.js

@@ -48,7 +48,7 @@ const COMMANDS = {
   'shell-hook': 'Auto-load .aura env vars on cd (like direnv)',
   play: 'Play an AuraJS game from npm (auramaxx play <game>)',
   fork: 'Fork a published AuraJS game into a local editable project (auramaxx fork <game>)',
-  create: 'Scaffold a new AuraJS game (2d/3d/blank) via AuraJS CLI',
+  create: 'Scaffold a new AuraJS game (2d/3d/multiplayer) via AuraJS CLI',
   make: 'Generate authored AuraJS project files via AuraJS CLI',
   publish: 'Publish current AuraJS game package to npm with guided prompts',
   // diary: 'Append daily diary entries via authenticated CLI path', // Temporarily disabled at root CLI.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auramaxx",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "AuraJS CLI for creating, playing, and publishing JavaScript-first games.",
   "keywords": [
     "aurajs",

package/src/server/cli/commands/create.ts

@@ -6,23 +6,21 @@ import { printBanner, printSection, paint, ANSI } from '../lib/theme';
 import { promptInput, promptSelect } from '../lib/prompt';
 
 const TEMPLATE_OPTIONS = [
-  { value: '2d-shooter', label: '[2D] Shooter', aliases: ['1', '2', '2d', 'shooter', '2d shooter'] },
-  { value: '3d-platformer', label: '[3D] Platformer', aliases: ['3', '3d', 'platformer', 'platformers', '3d platformer'] },
-  { value: 'blank', label: 'Blank', aliases: ['b'] },
+  { value: '2d', label: '[2D] Adventure', aliases: ['1', '2', '2d', '2d-adventure', 'adventure-2d'] },
+  { value: '3d', label: '[3D] Adventure', aliases: ['3', '3d', '3d-adventure', 'adventure-3d'] },
+  { value: 'multiplayer', label: '[MP] Multiplayer', aliases: ['4', 'mp', 'multiplayer', 'room', 'room-code', 'local-multiplayer'] },
 ];
-
-const VALID_TEMPLATES = new Set(TEMPLATE_OPTIONS.map((option) => option.value));
 const TEMPLATE_ALIASES: Record<string, string> = {
-  '2d': '2d-shooter',
-  'shooter': '2d-shooter',
-  '2d shooter': '2d-shooter',
-  '2d-shooter': '2d-shooter',
-  '3d': '3d-platformer',
-  'platformer': '3d-platformer',
-  'platformers': '3d-platformer',
-  '3d platformer': '3d-platformer',
-  '3d-platformer': '3d-platformer',
-  'blank': 'blank',
+  '2d': '2d',
+  '2d-adventure': '2d',
+  'adventure-2d': '2d',
+  '3d': '3d',
+  '3d-adventure': '3d',
+  'adventure-3d': '3d',
+  'multiplayer': 'multiplayer',
+  'local-multiplayer': 'multiplayer',
+  'room-code': 'multiplayer',
+  'room': 'multiplayer',
 };
 const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
 const LOCAL_AURAJS_CLI = path.resolve(
@@ -98,15 +96,10 @@ async function resolveGameName(initialName: string | null): Promise<string> {
 
 async function resolveTemplate(initialTemplate: string | null): Promise<string> {
   const normalized = normalizeTemplate(initialTemplate);
-  if (normalized && VALID_TEMPLATES.has(normalized)) {
+  if (normalized) {
     return normalized;
   }
-
-  if (normalized && !VALID_TEMPLATES.has(normalized)) {
-    console.log(`  Unknown template "${normalized}"; choose one below.`);
-  }
-
-  return promptSelect('  Starter template', TEMPLATE_OPTIONS, '2d-shooter');
+  return promptSelect('  Starter template', TEMPLATE_OPTIONS, '2d');
 }
 
 async function main() {
@@ -114,10 +107,13 @@ async function main() {
 
   if (parsed.help) {
     printBanner('CREATE');
-    console.log(`  ${paint('Usage:', ANSI.bold)} auramaxx create [name] [--template <2d-shooter|3d-platformer|blank>] [--skip-install]`);
+    console.log(`  ${paint('Usage:', ANSI.bold)} auramaxx create [name] [--template <2d|3d|multiplayer>] [--skip-install]`);
     console.log('');
     console.log('  Styled wrapper around AuraJS create scaffolding.');
-    console.log(`  ${paint('Example:', ANSI.dim)} auramaxx create my-game --template 3d-platformer`);
+    console.log(`  ${paint('Examples:', ANSI.dim)}`);
+    console.log('    auramaxx create my-game --template 2d');
+    console.log('    auramaxx create my-game --template 3d');
+    console.log('    auramaxx create my-room-game --template multiplayer');
     console.log('');
     return;
   }

package/src/server/cli/commands/play.ts

@@ -3,7 +3,7 @@ import { existsSync, mkdtempSync, readFileSync, rmSync } from 'fs';
 import { homedir, tmpdir } from 'os';
 import { join, resolve } from 'path';
 import { pathToFileURL } from 'url';
-import { printBanner, printSection, paint, ANSI } from '../lib/theme';
+import { printBanner, printSection, paint, ANSI, createProgressDisplay } from '../lib/theme';
 import {
   assertPublishedGameBinIntegrity,
   buildPublishedGameLaunchEnv,
@@ -185,17 +185,21 @@ export async function installVerifiedGamePackage(
   {
     execFileSyncImpl = execFileSync,
     env = process.env,
+    onProgress,
   }: {
     execFileSyncImpl?: typeof execFileSync;
     env?: NodeJS.ProcessEnv;
+    onProgress?: (step: number, label: string, detail?: string) => void;
   } = {},
 ) {
   if (!plan.name || !plan.packageName) {
     throw new Error('installVerifiedGamePackage requires a resolved package spec.');
   }
 
+  onProgress?.(1, 'Resolving package', plan.packageName);
   const installRoot = mkdtempSync(join(tmpdir(), 'auramaxx-play-'));
   try {
+    onProgress?.(2, 'Installing verified wrapper', plan.name);
     execFileSyncImpl(resolveNpmCommand(), buildSecureInstallArgs(plan.name, installRoot), {
       stdio: ['ignore', 'pipe', 'pipe'],
       env: {
@@ -212,6 +216,7 @@ export async function installVerifiedGamePackage(
 
     const gamePackage = readInstalledPackageJson(packageRoot);
     const dependencySpec = String(gamePackage?.dependencies?.['@auraindustry/aurajs'] || '').trim();
+    onProgress?.(3, 'Verifying package integrity', dependencySpec || plan.packageName);
     const integrity = assertPublishedGameBinIntegrity({
       packageRoot,
       projectPackage: gamePackage,
@@ -296,14 +301,20 @@ export async function main(argv: string[] = process.argv.slice(2)) {
 
   printBanner(plan.name.toUpperCase());
   printSection(plan.name, describeForwardedCommand(plan.forwardedArgs[0] || 'play'));
+  const progress = createProgressDisplay(4);
 
   let install: Awaited<ReturnType<typeof installVerifiedGamePackage>> | null = null;
   try {
-    install = await installVerifiedGamePackage(plan);
+    install = await installVerifiedGamePackage(plan, {
+      onProgress(step, label, detail) {
+        progress.update(step, label, detail);
+      },
+    });
     const env = buildPublishedGameLaunchEnv(
       process.env,
       plan.forwardedArgs[0] === 'join' ? { AURA_GAME_JOIN_MODE: 'play' } : {},
     );
+    progress.update(4, 'Launching game', plan.forwardedArgs[0] || 'play');
     execFileSync(process.execPath, [install.binAbsolutePath, ...plan.forwardedArgs], {
       stdio: 'inherit',
       cwd: install.packageRoot,

package/src/server/cli/lib/theme.ts

@@ -221,6 +221,64 @@ export function printComplete(message: string): void {
   console.log('');
 }
 
+function stripAnsi(text: string): string {
+  return text.replace(/\x1b\[[0-9;]*m/g, '');
+}
+
+function formatProgressBar(current: number, total: number, width: number): string {
+  const safeTotal = Math.max(1, total);
+  const clamped = Math.max(0, Math.min(current, safeTotal));
+  const filled = Math.round((clamped / safeTotal) * width);
+  const active = paint('/'.repeat(filled), ANSI.fgAccent, ANSI.bold);
+  const pending = paint('-'.repeat(Math.max(0, width - filled)), ANSI.dim);
+  return `[${active}${pending}]`;
+}
+
+export interface ProgressDisplay {
+  update(step: number, label: string, detail?: string): void;
+  complete(label?: string, detail?: string): void;
+}
+
+export function createProgressDisplay(totalSteps: number, width = 24): ProgressDisplay {
+  const stdout = process.stdout;
+  const interactive = stdout.isTTY;
+  let renderedLineCount = 0;
+
+  function draw(step: number, label: string, detail?: string) {
+    const safeStep = Math.max(0, Math.min(step, totalSteps));
+    const titleLine = `  ${paint('//', ANSI.fgAccent, ANSI.bold)} ${paint(label, ANSI.bold)} ${paint(`${safeStep}/${totalSteps}`, ANSI.dim)} ${formatProgressBar(safeStep, totalSteps, width)}`;
+    const lines = detail ? [titleLine, `     ${paint(detail, ANSI.dim)}`] : [titleLine];
+
+    if (interactive && renderedLineCount > 0) {
+      stdout.write(`\u001b[${renderedLineCount}A`);
+      for (let index = 0; index < renderedLineCount; index += 1) {
+        stdout.write('\u001b[2K');
+        stdout.write('\u001b[1B');
+      }
+      stdout.write(`\u001b[${renderedLineCount}A`);
+    }
+
+    for (const line of lines) {
+      if (interactive) {
+        stdout.write('\u001b[2K');
+        stdout.write(`${line}\n`);
+      } else {
+        console.log(stripAnsi(line));
+      }
+    }
+    renderedLineCount = lines.length;
+  }
+
+  return {
+    update(step: number, label: string, detail?: string) {
+      draw(step, label, detail);
+    },
+    complete(label = 'Ready', detail?: string) {
+      draw(totalSteps, label, detail);
+    },
+  };
+}
+
 // ── Seed phrase box (security-critical) ──────────────────────
 
 /**