@auraindustry/aurajs 0.1.3 → 0.1.5

package/templates/create/shared/src/starter-utils/world-compositor-2d.js

@@ -0,0 +1,253 @@
+function finite(value, fallback = 0) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : fallback;
+}
+
+function positiveInteger(value, fallback = null) {
+  const numeric = Math.floor(finite(value, Number.NaN));
+  if (numeric >= 1) return numeric;
+  return fallback;
+}
+
+function normalizeText(value, fallback) {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : fallback;
+}
+
+function resolveAura(auraRef = globalThis.aura) {
+  return auraRef && typeof auraRef === 'object' ? auraRef : null;
+}
+
+function normalizeStageIds(value) {
+  if (!Array.isArray(value) || value.length === 0) {
+    return ['scene', 'light', 'final'];
+  }
+
+  const stageIds = [];
+  const seen = new Set();
+  for (const entry of value) {
+    const id = normalizeText(entry, null);
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+    stageIds.push(id);
+  }
+  return stageIds.length > 0 ? stageIds : ['scene', 'light', 'final'];
+}
+
+function createTarget(aura, width, height) {
+  if (!aura?.draw2d || typeof aura.draw2d.createRenderTarget !== 'function') return null;
+  const target = aura.draw2d.createRenderTarget(width, height);
+  return target && typeof target === 'object' && target.ok === true ? target : null;
+}
+
+function destroyTarget(aura, target) {
+  if (!target || typeof target !== 'object' || target.ok !== true) return false;
+  if (!aura?.draw2d || typeof aura.draw2d.destroyRenderTarget !== 'function') return false;
+  aura.draw2d.destroyRenderTarget(target);
+  return true;
+}
+
+function resolveDimensions(compositor, options = {}) {
+  const width = positiveInteger(
+    options.width ?? compositor.fixedWidth,
+    null,
+  );
+  const height = positiveInteger(
+    options.height ?? compositor.fixedHeight,
+    null,
+  );
+  if (width == null || height == null) return null;
+  return { width, height };
+}
+
+function getStageRecord(compositor, stageId) {
+  return Array.isArray(compositor?.stages)
+    ? compositor.stages.find((entry) => entry.id === stageId) || null
+    : null;
+}
+
+function normalizeStageDefinitions(compositor, stageDefinitions) {
+  if (Array.isArray(stageDefinitions)) {
+    return compositor.stageIds.map((stageId) => (
+      stageDefinitions.find((entry) => entry?.id === stageId) || { id: stageId }
+    ));
+  }
+
+  if (stageDefinitions && typeof stageDefinitions === 'object') {
+    return compositor.stageIds.map((stageId) => {
+      const entry = stageDefinitions[stageId];
+      if (typeof entry === 'function') {
+        return { id: stageId, draw: entry };
+      }
+      if (entry && typeof entry === 'object') {
+        return { id: stageId, ...entry };
+      }
+      return { id: stageId };
+    });
+  }
+
+  return compositor.stageIds.map((stageId) => ({ id: stageId }));
+}
+
+export function createWorldCompositor2D(options = {}) {
+  const stageIds = normalizeStageIds(options.stageIds);
+  const finalStageId = stageIds.includes(options.finalStageId)
+    ? options.finalStageId
+    : stageIds[stageIds.length - 1];
+  return {
+    graphName: normalizeText(options.graphName, 'world-compositor-2d'),
+    stageIds,
+    finalStageId,
+    fixedWidth: positiveInteger(options.width ?? options.fixedWidth, null),
+    fixedHeight: positiveInteger(options.height ?? options.fixedHeight, null),
+    width: 0,
+    height: 0,
+    targets: null,
+    stages: null,
+  };
+}
+
+export function destroyWorldCompositor2D(compositor, auraRef = globalThis.aura) {
+  const aura = resolveAura(auraRef);
+  if (!compositor || typeof compositor !== 'object') return false;
+  if (compositor.targets && typeof compositor.targets === 'object') {
+    for (const stageId of compositor.stageIds || []) {
+      destroyTarget(aura, compositor.targets[stageId]);
+    }
+  }
+  compositor.width = 0;
+  compositor.height = 0;
+  compositor.targets = null;
+  compositor.stages = null;
+  return true;
+}
+
+export function ensureWorldCompositorTargets2D(compositor, options = {}, auraRef = globalThis.aura) {
+  const aura = resolveAura(auraRef);
+  if (!compositor || typeof compositor !== 'object') {
+    throw new Error('world compositor state is required.');
+  }
+
+  const dimensions = resolveDimensions(compositor, options);
+  if (!dimensions) return null;
+  if (
+    compositor.targets
+    && compositor.width === dimensions.width
+    && compositor.height === dimensions.height
+  ) {
+    return compositor.targets;
+  }
+
+  destroyWorldCompositor2D(compositor, aura);
+
+  const targets = {};
+  for (const stageId of compositor.stageIds) {
+    const target = createTarget(aura, dimensions.width, dimensions.height);
+    if (!target) {
+      for (const created of Object.values(targets)) {
+        destroyTarget(aura, created);
+      }
+      return null;
+    }
+    targets[stageId] = target;
+  }
+
+  compositor.width = dimensions.width;
+  compositor.height = dimensions.height;
+  compositor.targets = targets;
+  return targets;
+}
+
+export function runWorldCompositor2D(
+  compositor,
+  stageDefinitions,
+  options = {},
+  auraRef = globalThis.aura,
+) {
+  const aura = resolveAura(auraRef);
+  if (!compositor || typeof compositor !== 'object') {
+    throw new Error('world compositor state is required.');
+  }
+
+  const dimensions = resolveDimensions(compositor, options);
+  const fallbackDraw = typeof options.fallbackDraw === 'function' ? options.fallbackDraw : null;
+  if (!dimensions) {
+    if (fallbackDraw) fallbackDraw({ reasonCode: 'invalid_world_compositor_size' });
+    return {
+      ok: false,
+      reasonCode: 'invalid_world_compositor_size',
+      graph: null,
+      targets: null,
+      finalStage: null,
+      width: 0,
+      height: 0,
+    };
+  }
+
+  const targets = ensureWorldCompositorTargets2D(compositor, dimensions, aura);
+  if (!targets) {
+    if (fallbackDraw) fallbackDraw({ reasonCode: 'draw2d_render_target_unavailable' });
+    return {
+      ok: false,
+      reasonCode: 'draw2d_render_target_unavailable',
+      graph: null,
+      targets: null,
+      finalStage: null,
+      width: dimensions.width,
+      height: dimensions.height,
+    };
+  }
+
+  const definitions = normalizeStageDefinitions(compositor, stageDefinitions);
+  compositor.stages = definitions;
+  if (!aura?.draw2d || typeof aura.draw2d.runCompositorGraph !== 'function') {
+    if (fallbackDraw) {
+      fallbackDraw({
+        reasonCode: 'draw2d_compositor_unavailable',
+        width: dimensions.width,
+        height: dimensions.height,
+        targets,
+      });
+    }
+    return {
+      ok: false,
+      reasonCode: 'draw2d_compositor_unavailable',
+      graph: null,
+      targets,
+      finalStage: targets[compositor.finalStageId] || null,
+      width: dimensions.width,
+      height: dimensions.height,
+    };
+  }
+
+  const graph = aura.draw2d.runCompositorGraph(
+    compositor.graphName,
+    definitions.map((entry) => ({
+      id: entry.id,
+      target: targets[entry.id],
+      draw: () => {
+        if (typeof entry.draw !== 'function') return;
+        entry.draw({
+          id: entry.id,
+          width: dimensions.width,
+          height: dimensions.height,
+          graphName: compositor.graphName,
+          targets,
+          aura,
+          stage: getStageRecord(compositor, entry.id),
+          finalStageId: compositor.finalStageId,
+        });
+      },
+    })),
+  );
+
+  const finalStageIndex = compositor.stageIds.indexOf(compositor.finalStageId);
+  return {
+    ok: graph?.ok === true,
+    reasonCode: graph?.reasonCode || null,
+    graph,
+    targets,
+    finalStage: graph?.stages?.[finalStageIndex] || targets[compositor.finalStageId] || null,
+    width: dimensions.width,
+    height: dimensions.height,
+  };
+}

package/templates/create/shared/src/starter-utils/world-persistence-2d.js

@@ -0,0 +1,180 @@
+import { syncStreamedWorldFocus2D } from './streamed-world-2d.js';
+
+function cloneSnapshot(value) {
+  if (value == null) return value;
+  return JSON.parse(JSON.stringify(value));
+}
+
+function resolveStorage(auraRef = globalThis.aura) {
+  const storage = auraRef?.storage;
+  if (!storage || typeof storage !== 'object') return null;
+  return storage;
+}
+
+function storageSave(storage, key, value) {
+  if (!storage || typeof key !== 'string' || key.length === 0) return false;
+  if (typeof storage.save === 'function') {
+    storage.save(key, value);
+    return true;
+  }
+  if (typeof storage.set === 'function') {
+    storage.set(key, value);
+    return true;
+  }
+  return false;
+}
+
+function storageLoad(storage, key, fallback = null) {
+  if (!storage || typeof key !== 'string' || key.length === 0) return fallback;
+  if (typeof storage.load === 'function') {
+    return storage.load(key, fallback);
+  }
+  if (typeof storage.get === 'function') {
+    return storage.get(key, fallback);
+  }
+  return fallback;
+}
+
+function storageDelete(storage, key) {
+  if (!storage || typeof key !== 'string' || key.length === 0) return false;
+  if (typeof storage.delete === 'function') {
+    storage.delete(key);
+    return true;
+  }
+  return false;
+}
+
+function normalizeSnapshot(snapshot) {
+  if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) return null;
+  return {
+    version: Number.isFinite(Number(snapshot.version)) ? Number(snapshot.version) : 1,
+    scope: typeof snapshot.scope === 'string' ? snapshot.scope : 'streamed-world-2d',
+    activeRegionId: typeof snapshot.activeRegionId === 'string' ? snapshot.activeRegionId : null,
+    focus: snapshot.focus && typeof snapshot.focus === 'object'
+      ? {
+        x: Number(snapshot.focus.x) || 0,
+        y: Number(snapshot.focus.y) || 0,
+      }
+      : null,
+    world: snapshot.world == null ? null : cloneSnapshot(snapshot.world),
+    regions: Array.isArray(snapshot.regions)
+      ? snapshot.regions
+        .filter((entry) => entry && typeof entry === 'object' && typeof entry.id === 'string')
+        .map((entry) => ({
+          id: entry.id,
+          data: cloneSnapshot(entry.data),
+        }))
+      : [],
+  };
+}
+
+export function captureStreamedWorldSnapshot2D(stream, options = {}) {
+  if (!stream || !(stream.regionById instanceof Map)) {
+    return null;
+  }
+  const captureRegion = typeof options.captureRegion === 'function' ? options.captureRegion : null;
+  const captureWorld = typeof options.captureWorld === 'function' ? options.captureWorld : null;
+  const regionIds = Array.isArray(options.regionIds)
+    ? options.regionIds.filter((entry) => typeof entry === 'string')
+    : stream.regions.map((entry) => entry.id);
+  const regions = [];
+
+  regionIds.forEach((regionId) => {
+    const descriptor = stream.regionById.get(regionId) || null;
+    if (!descriptor || !captureRegion) return;
+    const record = stream.loaded?.get(regionId) || null;
+    const data = captureRegion(descriptor, record, stream, options);
+    if (data == null) return;
+    regions.push({
+      id: regionId,
+      data: cloneSnapshot(data),
+    });
+  });
+
+  return {
+    version: 1,
+    scope: options.scope ?? 'streamed-world-2d',
+    activeRegionId: stream.activeRegionId ?? null,
+    focus: stream.focus ? { x: Number(stream.focus.x) || 0, y: Number(stream.focus.y) || 0 } : null,
+    world: captureWorld ? cloneSnapshot(captureWorld(stream, options)) : null,
+    regions,
+  };
+}
+
+export function applyStreamedWorldSnapshot2D(stream, snapshot, options = {}) {
+  if (!stream || !(stream.regionById instanceof Map)) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_stream',
+      appliedRegionIds: [],
+    };
+  }
+  const normalized = normalizeSnapshot(snapshot);
+  if (!normalized) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_snapshot',
+      appliedRegionIds: [],
+    };
+  }
+  const applyRegion = typeof options.applyRegion === 'function' ? options.applyRegion : null;
+  const applyWorld = typeof options.applyWorld === 'function' ? options.applyWorld : null;
+  const appliedRegionIds = [];
+
+  if (applyWorld && normalized.world != null) {
+    applyWorld(cloneSnapshot(normalized.world), stream, options);
+  }
+
+  normalized.regions.forEach((entry) => {
+    const descriptor = stream.regionById.get(entry.id) || null;
+    if (!descriptor || !applyRegion) return;
+    const record = stream.loaded?.get(entry.id) || null;
+    applyRegion(descriptor, record, cloneSnapshot(entry.data), stream, options);
+    appliedRegionIds.push(entry.id);
+  });
+
+  if (options.restoreFocus === true && normalized.focus) {
+    syncStreamedWorldFocus2D(stream, options.auraRef, normalized.focus);
+  }
+
+  return {
+    ok: true,
+    reasonCode: null,
+    appliedRegionIds,
+    restoredFocus: options.restoreFocus === true && normalized.focus != null,
+  };
+}
+
+export function saveStreamedWorldSnapshot2D(key, stream, auraRef = globalThis.aura, options = {}) {
+  const storage = resolveStorage(auraRef);
+  const snapshot = captureStreamedWorldSnapshot2D(stream, options);
+  if (!snapshot) {
+    return {
+      ok: false,
+      reasonCode: 'invalid_stream',
+      snapshot: null,
+    };
+  }
+  if (!storageSave(storage, key, snapshot)) {
+    return {
+      ok: false,
+      reasonCode: 'storage_unavailable',
+      snapshot,
+    };
+  }
+  return {
+    ok: true,
+    reasonCode: null,
+    snapshot,
+  };
+}
+
+export function loadStreamedWorldSnapshot2D(key, auraRef = globalThis.aura, fallback = null) {
+  const storage = resolveStorage(auraRef);
+  const snapshot = storageLoad(storage, key, fallback);
+  return normalizeSnapshot(snapshot);
+}
+
+export function deleteStreamedWorldSnapshot2D(key, auraRef = globalThis.aura) {
+  return storageDelete(resolveStorage(auraRef), key);
+}

package/templates/create-bin/play.js

@@ -62,18 +62,47 @@ function resolveAuraMaxxBinary() {
   return process.platform === 'win32' ? 'auramaxx.cmd' : 'auramaxx';
 }
 
+function resolveAuraAliasBinary() {
+  return process.platform === 'win32' ? 'aura.cmd' : 'aura';
+}
+
 function resolveNpmBinary() {
   return process.platform === 'win32' ? 'npm.cmd' : 'npm';
 }
 
-function isAuraMaxxInstalled() {
-  const probe = spawnSync(resolveAuraMaxxBinary(), ['--version'], {
+function resolveInvocationCwd() {
+  const forwardedCwd = process.env.AURA_INVOKE_CWD;
+  if (forwardedCwd && isAbsolute(forwardedCwd)) {
+    return resolve(forwardedCwd);
+  }
+
+  const shellPwd = process.env.PWD;
+  if (shellPwd && isAbsolute(shellPwd)) {
+    return resolve(shellPwd);
+  }
+
+  return resolve(process.cwd());
+}
+
+function canProbeBinary(binary) {
+  const probe = spawnSync(binary, ['--help'], {
     stdio: 'ignore',
     env: process.env,
   });
   return !probe.error && probe.status === 0;
 }
 
+function isAuraMaxxInstalled() {
+  if (process.env.AURAMAXX_CLI_AVAILABLE === '1') {
+    return true;
+  }
+  if (localAuraCli) {
+    return true;
+  }
+  const candidates = [resolveAuraMaxxBinary(), resolveAuraAliasBinary()];
+  return candidates.some((binary, index) => candidates.indexOf(binary) === index && canProbeBinary(binary));
+}
+
 async function installAuraMaxxGlobally() {
   return new Promise((resolveInstall) => {
     const child = spawn(
@@ -373,7 +402,7 @@ async function promptSelect(message, options, defaultValue) {
 
 function normalizeDisplayPath(targetPath) {
   const resolvedPath = resolve(targetPath);
-  const relativePath = relative(process.cwd(), resolvedPath).replaceAll('\\', '/');
+  const relativePath = relative(resolveInvocationCwd(), resolvedPath).replaceAll('\\', '/');
   if (!relativePath) return '.';
   if (!relativePath.startsWith('.') && !relativePath.startsWith('/')) {
     return `./${relativePath}`;
@@ -402,10 +431,10 @@ function resolveUniqueDestination(preferredPath) {
 
 function resolveDefaultForkDestination() {
   const defaultBaseName = `${toPackageShortName(packageName)}-fork`;
-  const cwd = resolve(process.cwd());
-  const baseDir = isSubpath(projectRoot, cwd)
+  const invocationCwd = resolveInvocationCwd();
+  const baseDir = isSubpath(projectRoot, invocationCwd)
     ? dirname(projectRoot)
-    : cwd;
+    : invocationCwd;
   return resolveUniqueDestination(resolve(baseDir, defaultBaseName));
 }
 
@@ -454,7 +483,7 @@ function parseForkArgs(args) {
 async function resolveForkDestination(args) {
   const parsed = parseForkArgs(args);
   if (parsed.destination) {
-    return resolve(process.cwd(), parsed.destination);
+    return resolve(resolveInvocationCwd(), parsed.destination);
   }
 
   const suggestedDestination = resolveDefaultForkDestination();

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.