@auraindustry/aurajs 0.1.1 → 0.1.5

package/templates/skills/auramaxx/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: auramaxx
+description: Use when building or modifying AuraMaxx or AuraJS game projects. Helps agents infer game requirements from local project files, pick the right starter-owned edit points, and validate gameplay work with the current CLI and project wrapper commands.
+---
+
+# AuraMaxx Skill
+
+Use this skill when working inside an AuraMaxx or AuraJS game project.
+
+## Working Set
+
+Read these files in order:
+
+1. `project-requirements.md`
+2. `starter-recipes.md`
+3. `validation-checklist.md`
+4. the current project files named by those docs
+
+Use `https://www.aurajs.gg/llm.txt` only when you need broader public docs
+context than the local project and installed package sources provide.
+
+## Rules
+
+- Treat the current project files as the primary source of truth.
+- Keep `src/main.js` thin; prefer the registry-backed runtime flow already in the scaffold.
+- Put durable authored data in `config/` or `content/`, not scene-local constants.
+- Put mutable runtime state in scenes or `src/runtime/app-state.js`.
+- Extend `src/starter-utils/` before inventing one-off helpers.
+- Use `auramaxx make` instead of hand-wiring new scaffold nouns when a generator exists.
+
+## Default Loop
+
+1. Infer the current game requirements with `project-requirements.md`.
+2. Choose the starter-specific edit path in `starter-recipes.md`.
+3. Implement the smallest playable slice that changes one mechanic at a time.
+4. Run the relevant checks from `validation-checklist.md`.
+
+## Retrieval Boundary
+
+Open local project files first. If you still need package-level behavior or
+template intent, inspect:
+
+- `node_modules/@auraindustry/aurajs/src/`
+- `node_modules/@auraindustry/aurajs/templates/`
+
+Use `aurajs.gg/llm.txt` after that, not before.

package/templates/skills/auramaxx/project-requirements.md

@@ -0,0 +1,68 @@
+# AuraMaxx Project Requirements
+
+Use this checklist to understand the game before you edit it.
+
+## 1. Identity
+
+- Read `package.json` and `aura.config.json`.
+- Capture: package name, bin name, project title, version, runtime targets, and
+  whether the project is intended to be published.
+
+## 2. Template and module shape
+
+- Read `aura.capabilities.json` and `config/gameplay/game.config.json`.
+- Capture: template id, required APIs, optional modules, `startingSceneId`,
+  `gameplaySceneId`, `hudScreenId`, and `playerPrefabId`.
+
+## 3. Player promise
+
+- Read `README.md`, `RUNBOOK.md`, `docs/design/game-pillars.md`,
+  `docs/design/loop.md`, and `assets/starter/dev-notes.md`.
+- Write down:
+  - genre and player fantasy
+  - first 60-second goal
+  - controls
+  - win and lose states
+  - what “done for this task” should feel like on screen
+
+## 4. Authored owners
+
+- Read `src/runtime/project-registry.js`, `config/gameplay/*`,
+  `content/gameplay/*`, `content/registries/*`, `prefabs/*.prefab.js`,
+  `scenes/*.scene.js`, and `ui/*.screen.js`.
+- Map which files own:
+  - loop logic
+  - tuning values
+  - authored nouns and layout
+  - HUD and modal UI
+  - progression, save, dialogue, inventory, or multiplayer state
+
+## 5. Assets and starter data
+
+- Read `assets/starter/*` first, then only the `assets/**` files actually used
+  by the touched scene or prefab.
+- Capture: placeholder assets still in use, required art/audio hooks, and any
+  starter JSON or notes that define layout, waves, cards, checkpoints, or room
+  behavior.
+
+## 6. Decide where the change belongs
+
+- Stable tunable: `config/`
+- Authored noun or layout data: `content/`
+- Reusable entity or world descriptor: `prefabs/`
+- Live mechanic or per-frame flow: `scenes/`
+- HUD, overlay, or modal surface: `ui/`
+- Cross-scene mutable app state: `src/runtime/app-state.js`
+- Reusable starter helper: `src/starter-utils/`
+
+## 7. Discovery commands
+
+- `auramaxx explain`
+- `auramaxx check`
+- `auramaxx make list --json`
+- `npm run dev`
+- `npm run state -- export --compact`
+- `npm run action -- schema --compact`
+
+Use these to confirm what the project already exposes before you add new
+structure.

package/templates/skills/auramaxx/starter-recipes.md

@@ -0,0 +1,104 @@
+# AuraMaxx Starter Recipes
+
+Use the current template id from `aura.capabilities.json` or `aura.config.json`
+to pick the right recipe.
+
+## 2d-adventure
+
+- Edit first:
+  - `content/gameplay/world.js`
+  - `config/gameplay/adventure.config.js`
+  - `scenes/gameplay.scene.js`
+  - `prefabs/world.prefab.js`
+  - `prefabs/relic.prefab.js`
+  - `ui/hud.screen.js`
+- Good first tasks:
+  - tighten movement and interaction feel
+  - rewrite room nouns, relic goals, dialogue, and route beats
+  - add one strong interaction before widening scope
+- Avoid:
+  - burying route data inside the scene
+  - replacing starter-utils with duplicated local helpers
+
+## 2d-shooter and 2d-survivor
+
+- Edit first:
+  - `config/gameplay/*.config.js`
+  - `scenes/gameplay.scene.js`
+  - `prefabs/player.prefab.js`
+  - enemy or projectile prefabs
+  - `ui/*.screen.js`
+- Good first tasks:
+  - pacing, spawn pressure, weapon feel, hit feedback, restart loop
+- Avoid:
+  - mixing balance constants into render code
+  - adding many enemy types before one wave feels good
+
+## deckbuilder-2d
+
+- Edit first:
+  - starter-owned `content/registries/*`
+  - `config/gameplay/*`
+  - combat scene files
+  - HUD and card presentation screens
+- Good first tasks:
+  - one coherent card set
+  - one enemy intent loop
+  - one relic or progression rule
+- Avoid:
+  - putting card data directly in scene logic
+
+## 3d-adventure, 3d-platformer, 3d-collectathon
+
+- Edit first:
+  - `content/gameplay/course.js`
+  - `config/gameplay/*.config.js`
+  - `scenes/gameplay.scene.js`
+  - `prefabs/world.prefab.js`
+  - `prefabs/player.prefab.js`
+  - `src/starter-utils/avatar-3d.js`
+  - `src/starter-utils/platformer-3d.js`
+- Good first tasks:
+  - movement feel, camera follow, checkpoints, collectibles, route readability
+- Avoid:
+  - hardcoding course layout in the scene
+  - treating imported models as the only source of gameplay truth
+
+## local-multiplayer
+
+- Edit first:
+  - `config/gameplay/local-multiplayer.config.js`
+  - `content/gameplay/room-layout.js`
+  - `scenes/gameplay.scene.js`
+  - `ui/hud.screen.js`
+- Good first tasks:
+  - one host/join room loop
+  - one shared objective
+  - one clear disconnect or retry path
+- Avoid:
+  - breaking the local-first host flow while chasing internet features
+  - assuming headless state or action flows work unless you verify them
+
+## blank
+
+- Edit first:
+  - `src/main.js`
+  - `scenes/gameplay.scene.js`
+  - `prefabs/player.prefab.js`
+  - `ui/hud.screen.js`
+  - `config/gameplay/game.config.json`
+- Good first tasks:
+  - one visible mechanic
+  - one HUD element
+  - one authored config value
+- Avoid:
+  - recreating the whole scaffold model from scratch
+
+## Cross-starter recipe
+
+For any starter:
+
+1. make one mechanic feel good
+2. make the goal readable in HUD or world feedback
+3. move stable data into `config/` or `content/`
+4. only then add more systems

package/templates/skills/auramaxx/validation-checklist.md

@@ -0,0 +1,49 @@
+# AuraMaxx Validation Checklist
+
+Pick the smallest set that matches the task.
+
+## Always
+
+- Run `auramaxx explain` after structure changes.
+- Run `auramaxx check` before and after edits.
+- If you add new scaffold nouns, run `auramaxx make list --json` first and use
+  `auramaxx make ...` where possible.
+
+## Gameplay slice
+
+- Run `npm run dev`.
+- Confirm:
+  - the game boots
+  - the first objective is readable
+  - controls match the intended loop
+  - HUD or world feedback reflects the new mechanic
+  - there are no obvious stuck states or soft-locks
+
+## State and action tooling
+
+- Run `npm run state -- export --compact` when the project claims state export.
+- Run `npm run action -- schema --compact` when the project claims action
+  tooling.
+- If these fail, record the exact reason instead of pretending the flow works.
+
+## Session and headless flows
+
+- Use `auramaxx session start --headless --name ci-loop --compact` only after
+  verifying the starter and runtime actually support that lane.
+- If the project is multiplayer or starter-heavy, verify headless flows
+  explicitly instead of assuming parity with visible `npm run dev`.
+
+## Publish and package surface
+
+- Run `auramaxx publish --dry-run` for package-surface and build validation.
+- Run `auramaxx external-assets generate --public-base-url <url>` only after the
+  build artifacts exist and the project actually needs self-hosted assets.
+
+## What to report
+
+When you finish, report:
+
+- which commands passed
+- which commands failed
+- whether failures are task regressions or pre-existing runtime gaps
+- what the player-visible outcome is

package/templates/starter/src/main.js

@@ -3,6 +3,7 @@
 // - modules.physics: enables aura.physics.*
 // - modules.network: enables aura.net.*
 // - modules.steam: enables aura.steam.*
+import { initSplash, updateSplash, drawSplash, isSplashActive } from './runtime/splash.js';
 
 let x = 400;
 let y = 300;
@@ -153,6 +154,7 @@ function clearScreen(color) {
 
 aura.setup = function () {
   assertRuntimeCapabilities();
+  initSplash();
   console.log("{{PROJECT_NAME}} started");
   if (!hasAsset(PLAYER_SPRITE_PATH)) {
     console.log(`Tip: add assets/${PLAYER_SPRITE_PATH} to preview sprite draw2d options.`);
@@ -163,6 +165,7 @@ aura.setup = function () {
 };
 
 aura.update = function (dt) {
+  if (isSplashActive()) { updateSplash(dt); return; }
   if (keyDown("arrowright")) x += speed * dt;
   if (keyDown("arrowleft"))  x -= speed * dt;
   if (keyDown("arrowup"))    y -= speed * dt;
@@ -186,6 +189,7 @@ aura.update = function (dt) {
 };
 
 aura.draw = function () {
+  if (isSplashActive()) { drawSplash(); return; }
   const bg = rgba(0.08, 0.08, 0.12, 1.0);
   clearScreen(bg);
 

package/templates/starter/src/runtime/splash.js

@@ -0,0 +1,305 @@
+// AuraJS Splash — unified retro paper-card boot screen.
+// Auto-wired by createApp(). Shows once on launch, then hands off to the game.
+
+const FADE_IN = 0.7;
+const HOLD = 1.8;
+const FADE_OUT = 0.7;
+const TOTAL = FADE_IN + HOLD + FADE_OUT;
+
+const PAPER = [0.89, 0.89, 0.89];
+const PAPER_SHADOW = [0.80, 0.80, 0.80];
+const PAPER_EDGE = [0.41, 0.41, 0.41];
+const INK = [0.1, 0.1, 0.1];
+const INK_MUTED = [0.42, 0.42, 0.42];
+const MASCOT_FRAME_W = 64;
+const MASCOT_FRAME_H = 84;
+const MASCOT_SEQUENCE = Object.freeze([0, 1, 2, 1]);
+const SPLASH_STING_PATH = 'splash/boot-sting.wav';
+const SPLASH_LOOP_PATH = 'splash/boot-loop.wav';
+const SPLASH_BUS = 'splash';
+const QUIET_BUSES = Object.freeze(['default', 'music', 'sfx']);
+
+let state = null;
+
+function has(obj, method) {
+  return Boolean(obj) && typeof obj[method] === 'function';
+}
+
+function color(rgb, alpha = 1) {
+  return aura.rgba(rgb[0], rgb[1], rgb[2], alpha);
+}
+
+function drawShadowText(text, x, y, options = {}) {
+  const {
+    shadowOffset = 2,
+    shadowColor = color(INK_MUTED, 0.3),
+    ...rest
+  } = options;
+  aura.draw2d.text(text, x + shadowOffset, y + shadowOffset, {
+    ...rest,
+    color: shadowColor,
+  });
+  aura.draw2d.text(text, x, y, rest);
+}
+
+export function initSplash() {
+  state = {
+    t: 0,
+    logo: null,
+    mascot: null,
+    wordmark: null,
+    font: null,
+    stingHandle: null,
+    loopHandle: null,
+    busVolumes: null,
+    pausedHandles: [],
+  };
+  try { if (has(aura.assets, 'load')) state.logo = aura.assets.load('splash/logoholo.webp'); } catch (_) {}
+  try { if (has(aura.assets, 'load')) state.mascot = aura.assets.load('splash/logo-mascot-sheet.webp'); } catch (_) {}
+  try { if (has(aura.assets, 'load')) state.wordmark = aura.assets.load('splash/aurajs-gg-wordmark.webp'); } catch (_) {}
+  try {
+    if (has(aura.assets, 'loadBitmapFont')) {
+      const result = aura.assets.loadBitmapFont();
+      if (result && result.ok && result.font) state.font = result.font;
+    }
+  } catch (_) {}
+  captureBusVolumes();
+  applySplashBusIsolation();
+  try {
+    if (aura.audio && aura.audio.supported !== false && typeof aura.audio.play === 'function') {
+      state.loopHandle = aura.audio.play(SPLASH_LOOP_PATH, {
+        loop: true,
+        volume: 0.22,
+        bus: SPLASH_BUS,
+      });
+      state.stingHandle = aura.audio.play(SPLASH_STING_PATH, {
+        loop: false,
+        volume: 0.54,
+        bus: SPLASH_BUS,
+      });
+    }
+  } catch (_) {}
+}
+
+export function isSplashActive() {
+  return state !== null;
+}
+
+export function updateSplash(dt) {
+  if (!state) return;
+  syncPausedTracks();
+  try {
+    if (aura.audio && typeof aura.audio.update === 'function') {
+      aura.audio.update(Number(dt) > 0 ? Number(dt) : (1 / 60));
+    }
+  } catch (_) {}
+  state.t += dt;
+  if (state.t >= TOTAL) {
+    stopSplashAudio();
+    state = null;
+  }
+}
+
+export function drawSplash() {
+  if (!state) return;
+  const { width: w, height: h } = has(aura.window, 'getSize')
+    ? aura.window.getSize()
+    : { width: 640, height: 480 };
+  const t = state.t;
+  const cx = w / 2;
+  const cy = h / 2;
+
+  let a = 1;
+  if (t < FADE_IN) a = easeOut(t / FADE_IN);
+  else if (t > FADE_IN + HOLD) a = 1 - easeIn((t - FADE_IN - HOLD) / FADE_OUT);
+
+  aura.draw2d.clear(color(PAPER));
+
+  const panelW = Math.min(Math.floor(w * 0.48), 580);
+  const panelH = Math.min(Math.floor(h * 0.72), 620);
+  const panelX = Math.floor(cx - (panelW * 0.5));
+  const panelY = Math.floor(cy - (panelH * 0.5));
+
+  aura.draw2d.rectFill(panelX + 6, panelY + 6, panelW, panelH, color(INK, 0.08 * a));
+  aura.draw2d.rectFill(panelX, panelY, panelW, panelH, color(PAPER_EDGE, a));
+  aura.draw2d.rectFill(panelX + 6, panelY + 6, panelW - 12, panelH - 12, color(PAPER, a));
+  aura.draw2d.rectFill(panelX + 12, panelY + 12, panelW - 24, panelH - 24, color(PAPER, a * 0.96));
+
+  const floatY = Math.sin(t * 1.4 * Math.PI * 2) * 2;
+  const breathe = 0.985 + 0.015 * (0.5 + 0.5 * Math.sin(t * Math.PI * 2));
+  const mascotScale = Math.max(1, Math.min(Math.floor(Math.min(w, h) / 260), 2));
+  const mascotW = Math.floor(MASCOT_FRAME_W * mascotScale * breathe);
+  const mascotH = Math.floor(MASCOT_FRAME_H * mascotScale * breathe);
+  const mascotX = Math.floor(cx - (mascotW * 0.5));
+  const mascotY = Math.floor(panelY + panelH * 0.40 + floatY);
+  const mascotFrame = MASCOT_SEQUENCE[Math.floor(t * 7.5) % MASCOT_SEQUENCE.length] || 0;
+
+  aura.draw2d.rectFill(
+    mascotX + Math.floor(mascotW * 0.18),
+    mascotY + mascotH - 8,
+    Math.floor(mascotW * 0.64),
+    6,
+    color(INK, a * 0.08),
+  );
+
+  if (state.mascot) {
+    aura.draw2d.sprite(state.mascot, mascotX, mascotY, {
+      width: mascotW,
+      height: mascotH,
+      frameX: mascotFrame * MASCOT_FRAME_W,
+      frameY: 0,
+      frameW: MASCOT_FRAME_W,
+      frameH: MASCOT_FRAME_H,
+      alpha: a,
+    });
+  } else if (state.logo) {
+    const sz = Math.min(Math.floor(panelW * 0.24), Math.floor(h * 0.14)) * breathe;
+    aura.draw2d.sprite(state.logo, Math.floor(cx - sz / 2), Math.floor(mascotY + 6), {
+      width: sz,
+      height: sz,
+      alpha: a,
+    });
+  }
+
+  const ta = clamp(a * easeOut(clamp((t - 0.2) / (FADE_IN * 0.6))));
+  const sa = clamp(a * easeOut(clamp((t - 0.4) / (FADE_IN * 0.6))));
+  const scale = Math.min(w, h) / 480;
+  const tsz = Math.max(24, Math.round(scale * 28));
+  const ssz = Math.max(11, Math.round(scale * 12));
+  const wordmarkW = Math.min(Math.floor(panelW * 0.52), 290);
+  const wordmarkH = Math.floor(wordmarkW * (768 / 1408));
+  const wordmarkX = Math.floor(cx - (wordmarkW * 0.5));
+  const wordmarkY = Math.floor(panelY + 36);
+  const sY = Math.floor(panelY + panelH - 108);
+  const fo = state.font ? { font: state.font } : {};
+
+  if (state.wordmark) {
+    aura.draw2d.sprite(state.wordmark, wordmarkX, wordmarkY, {
+      width: wordmarkW,
+      height: wordmarkH,
+      alpha: ta,
+      tint: color(INK, ta),
+    });
+  } else {
+    drawShadowText('AuraJS.gg', cx, wordmarkY + Math.floor(wordmarkH * 0.55), {
+      ...fo,
+      size: tsz,
+      color: color(INK, ta),
+      shadowColor: color(INK_MUTED, ta * 0.28),
+      align: 'center',
+    });
+  }
+
+  drawShadowText('Open-Source. MIT.', cx, sY, {
+    ...fo,
+    size: ssz,
+    color: color(INK_MUTED, sa),
+    shadowColor: color(PAPER_EDGE, sa * 0.18),
+    shadowOffset: 1,
+    align: 'center',
+  });
+  drawShadowText('Who needs publishers?', cx, sY + Math.max(16, Math.round(ssz * 1.45)), {
+    ...fo,
+    size: ssz,
+    color: color(INK_MUTED, sa),
+    shadowColor: color(PAPER_EDGE, sa * 0.18),
+    shadowOffset: 1,
+    align: 'center',
+  });
+
+  const rw = Math.min(panelW - 140, 240);
+  aura.draw2d.rectFill(Math.floor(cx - rw / 2), Math.floor(sY + Math.max(34, ssz * 3.2)), rw, 2, color(PAPER_EDGE, sa * 0.38));
+}
+
+function easeOut(t) {
+  const u = 1 - clamp(t);
+  return 1 - (u * u * u);
+}
+
+function easeIn(t) {
+  const c = clamp(t);
+  return c * c * c;
+}
+
+function clamp(v) {
+  return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+
+function stopSplashAudio() {
+  if (!state || !aura.audio || typeof aura.audio.stop !== 'function') return;
+  try {
+    if (state.stingHandle != null) aura.audio.stop(state.stingHandle);
+  } catch (_) {}
+  try {
+    if (state.loopHandle != null) aura.audio.stop(state.loopHandle);
+  } catch (_) {}
+  restoreAudioState();
+  state.stingHandle = null;
+  state.loopHandle = null;
+}
+
+function captureBusVolumes() {
+  if (!state || !aura.audio || typeof aura.audio.getMixerState !== 'function') return;
+  try {
+    const mixer = aura.audio.getMixerState();
+    const buses = Array.isArray(mixer?.buses) ? mixer.buses : [];
+    state.busVolumes = buses.reduce((acc, entry) => {
+      const bus = String(entry?.bus || '').trim();
+      if (!bus) return acc;
+      acc[bus] = Number(entry?.volume);
+      return acc;
+    }, {});
+  } catch (_) {}
+}
+
+function applySplashBusIsolation() {
+  if (!state || !aura.audio || typeof aura.audio.setBusVolume !== 'function') return;
+  try { aura.audio.setBusVolume(SPLASH_BUS, 1); } catch (_) {}
+  for (const bus of QUIET_BUSES) {
+    try { aura.audio.setBusVolume(bus, 0); } catch (_) {}
+  }
+}
+
+function syncPausedTracks() {
+  if (!state || !aura.audio || typeof aura.audio.getMixerState !== 'function' || typeof aura.audio.pause !== 'function') return;
+  try {
+    const mixer = aura.audio.getMixerState();
+    const tracks = Array.isArray(mixer?.tracks) ? mixer.tracks : [];
+    const splashHandles = [state.stingHandle, state.loopHandle].filter((handle) => handle != null);
+    const pausedHandles = new Set(Array.isArray(state.pausedHandles) ? state.pausedHandles : []);
+    for (const track of tracks) {
+      const handle = Number(track?.handle);
+      if (!Number.isInteger(handle) || handle <= 0) continue;
+      if (splashHandles.includes(handle)) continue;
+      if (track?.paused === true || pausedHandles.has(handle)) continue;
+      try {
+        aura.audio.pause(handle);
+        pausedHandles.add(handle);
+      } catch (_) {}
+    }
+    state.pausedHandles = Array.from(pausedHandles);
+  } catch (_) {}
+}
+
+function restoreAudioState() {
+  if (!state || !aura.audio) return;
+  if (typeof aura.audio.setBusVolume === 'function') {
+    const snapshot = state.busVolumes && typeof state.busVolumes === 'object' ? state.busVolumes : null;
+    if (snapshot) {
+      for (const [bus, volume] of Object.entries(snapshot)) {
+        try { aura.audio.setBusVolume(bus, Number(volume)); } catch (_) {}
+      }
+    } else {
+      for (const bus of QUIET_BUSES) {
+        try { aura.audio.setBusVolume(bus, 1); } catch (_) {}
+      }
+    }
+    try { aura.audio.setBusVolume(SPLASH_BUS, 1); } catch (_) {}
+  }
+  if (typeof aura.audio.resume === 'function') {
+    for (const handle of Array.isArray(state.pausedHandles) ? state.pausedHandles : []) {
+      try { aura.audio.resume(handle); } catch (_) {}
+    }
+  }
+  state.pausedHandles = [];
+}