@auraindustry/aurajs 0.0.2 → 0.0.4

package/src/web-api.mjs

@@ -0,0 +1,454 @@
+function isPlainObject(value) {
+  return value != null && typeof value === 'object' && Object.prototype.toString.call(value) === '[object Object]';
+}
+
+function cloneLifecycle(value) {
+  const source = isPlainObject(value) ? value : {};
+  return {
+    running: source.running === true,
+    setupCalls: toNonNegativeInt(source.setupCalls),
+    updateCalls: toNonNegativeInt(source.updateCalls),
+    drawCalls: toNonNegativeInt(source.drawCalls),
+    frameCount: toNonNegativeInt(source.frameCount),
+    lastDeltaSeconds: toNonNegativeNumber(source.lastDeltaSeconds),
+  };
+}
+
+function toNonNegativeInt(value) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric < 0) return 0;
+  return Math.floor(numeric);
+}
+
+function toNonNegativeNumber(value) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric) || numeric < 0) return 0;
+  return Number(numeric.toFixed(6));
+}
+
+function sanitizeState(value) {
+  const source = isPlainObject(value) ? value : {};
+  const lastError = isPlainObject(source.lastError)
+    ? {
+      reasonCode: typeof source.lastError.reasonCode === 'string' ? source.lastError.reasonCode : null,
+      layer: typeof source.lastError.layer === 'string' ? source.lastError.layer : null,
+      retryable: source.lastError.retryable === true,
+      details: isPlainObject(source.lastError.details) ? { ...source.lastError.details } : {},
+    }
+    : null;
+  return {
+    phase: typeof source.phase === 'string' ? source.phase : 'idle',
+    reasonCode: typeof source.reasonCode === 'string' ? source.reasonCode : null,
+    lifecycle: cloneLifecycle(source.lifecycle),
+    lastError,
+  };
+}
+
+function normalizeConfig(value) {
+  if (value == null) {
+    return {
+      rootUrl: '.',
+      mount: null,
+    };
+  }
+  if (!isPlainObject(value)) {
+    throw createApiError(
+      'web_api_invalid_config',
+      'Configuration must be a plain object.',
+      'api',
+      false,
+      { expectedType: 'object' },
+    );
+  }
+
+  const normalized = {
+    rootUrl: '.',
+    mount: null,
+  };
+
+  if (Object.prototype.hasOwnProperty.call(value, 'rootUrl')) {
+    if (typeof value.rootUrl !== 'string' || value.rootUrl.trim().length === 0) {
+      throw createApiError(
+        'web_api_invalid_config',
+        'Config rootUrl must be a non-empty string.',
+        'api',
+        false,
+        { field: 'rootUrl' },
+      );
+    }
+    normalized.rootUrl = value.rootUrl.trim();
+  }
+
+  if (Object.prototype.hasOwnProperty.call(value, 'mount')) {
+    const mount = value.mount;
+    const mountIsSelector = typeof mount === 'string' && mount.trim().length > 0;
+    const mountIsNodeLike = mount != null && typeof mount === 'object' && typeof mount.appendChild === 'function';
+    if (mount == null) {
+      normalized.mount = null;
+    } else if (mountIsSelector || mountIsNodeLike) {
+      normalized.mount = mount;
+    } else {
+      throw createApiError(
+        'web_api_invalid_config',
+        'Config mount must be a selector string or HTMLElement-like node.',
+        'api',
+        false,
+        { field: 'mount' },
+      );
+    }
+  }
+
+  return normalized;
+}
+
+function mergeConfig(baseConfig, patch) {
+  const base = normalizeConfig(baseConfig);
+  if (patch == null) return base;
+  if (!isPlainObject(patch)) {
+    throw createApiError(
+      'web_api_invalid_config',
+      'Configuration must be a plain object.',
+      'api',
+      false,
+      { expectedType: 'object' },
+    );
+  }
+
+  const next = {
+    rootUrl: base.rootUrl,
+    mount: base.mount,
+  };
+
+  if (Object.prototype.hasOwnProperty.call(patch, 'rootUrl')) {
+    if (typeof patch.rootUrl !== 'string' || patch.rootUrl.trim().length === 0) {
+      throw createApiError(
+        'web_api_invalid_config',
+        'Config rootUrl must be a non-empty string.',
+        'api',
+        false,
+        { field: 'rootUrl' },
+      );
+    }
+    next.rootUrl = patch.rootUrl.trim();
+  }
+
+  if (Object.prototype.hasOwnProperty.call(patch, 'mount')) {
+    const mount = patch.mount;
+    const mountIsSelector = typeof mount === 'string' && mount.trim().length > 0;
+    const mountIsNodeLike = mount != null && typeof mount === 'object' && typeof mount.appendChild === 'function';
+    if (mount == null) {
+      next.mount = null;
+    } else if (mountIsSelector || mountIsNodeLike) {
+      next.mount = mount;
+    } else {
+      throw createApiError(
+        'web_api_invalid_config',
+        'Config mount must be a selector string or HTMLElement-like node.',
+        'api',
+        false,
+        { field: 'mount' },
+      );
+    }
+  }
+
+  return next;
+}
+
+function normalizeCallbacks(options = {}) {
+  const source = isPlainObject(options) ? options : {};
+  const callbacks = {
+    onPhaseChange: typeof source.onPhaseChange === 'function' ? source.onPhaseChange : null,
+    onLifecycle: typeof source.onLifecycle === 'function' ? source.onLifecycle : null,
+    onError: typeof source.onError === 'function' ? source.onError : null,
+  };
+  return callbacks;
+}
+
+function createApiError(reasonCode, message, layer, retryable, details) {
+  const error = new Error(message);
+  error.ok = false;
+  error.reasonCode = reasonCode;
+  error.layer = layer;
+  error.retryable = retryable === true;
+  error.details = isPlainObject(details) ? { ...details } : {};
+  return error;
+}
+
+function normalizeApiError(error, fallback) {
+  if (error && typeof error === 'object' && typeof error.reasonCode === 'string') {
+    return error;
+  }
+
+  return createApiError(
+    fallback.reasonCode,
+    fallback.message,
+    fallback.layer,
+    fallback.retryable,
+    {
+      cause: String(error && error.message ? error.message : error),
+    },
+  );
+}
+
+function snapshotError(error) {
+  if (!error || typeof error !== 'object') {
+    return null;
+  }
+  return {
+    reasonCode: typeof error.reasonCode === 'string' ? error.reasonCode : null,
+    layer: typeof error.layer === 'string' ? error.layer : null,
+    retryable: error.retryable === true,
+    details: isPlainObject(error.details) ? { ...error.details } : {},
+  };
+}
+
+function resolveLoader(injectedLoader) {
+  if (injectedLoader && typeof injectedLoader === 'object') {
+    return injectedLoader;
+  }
+  if (typeof globalThis !== 'undefined' && globalThis && typeof globalThis.AuraWebLoader === 'object') {
+    return globalThis.AuraWebLoader;
+  }
+  return null;
+}
+
+function stableLifecycleKey(lifecycle) {
+  const source = cloneLifecycle(lifecycle);
+  return JSON.stringify(source);
+}
+
+function stableErrorKey(error) {
+  if (!error) return null;
+  return JSON.stringify({
+    reasonCode: error.reasonCode || null,
+    layer: error.layer || null,
+    retryable: error.retryable === true,
+    details: isPlainObject(error.details) ? error.details : {},
+  });
+}
+
+export function createAuraGame(options = {}) {
+  const opts = isPlainObject(options) ? options : {};
+  let loader = resolveLoader(opts.loader);
+  let config = normalizeConfig(opts.config || null);
+  const callbacks = normalizeCallbacks(opts);
+  let state = sanitizeState(loader && typeof loader.getState === 'function' ? loader.getState() : null);
+  let lastPhase = state.phase;
+  let lastLifecycle = stableLifecycleKey(state.lifecycle);
+  let lastError = stableErrorKey(state.lastError);
+
+  function readLoaderState() {
+    if (!loader || typeof loader.getState !== 'function') {
+      return null;
+    }
+    try {
+      return sanitizeState(loader.getState());
+    } catch (_) {
+      return null;
+    }
+  }
+
+  function currentState() {
+    if (state.phase === 'error') {
+      return sanitizeState(state);
+    }
+
+    const loaderState = readLoaderState();
+    const merged = loaderState
+      ? sanitizeState({
+        phase: loaderState.phase,
+        reasonCode: loaderState.reasonCode,
+        lifecycle: loaderState.lifecycle,
+        lastError: loaderState.lastError || state.lastError,
+      })
+      : sanitizeState(state);
+    state = merged;
+    return merged;
+  }
+
+  function emitFromState(nextState, force = false) {
+    const phase = nextState.phase;
+    const lifecycle = cloneLifecycle(nextState.lifecycle);
+    const error = snapshotError(nextState.lastError);
+
+    const phaseChanged = phase !== lastPhase;
+    const lifecycleKey = stableLifecycleKey(lifecycle);
+    const lifecycleChanged = lifecycleKey !== lastLifecycle;
+    const errorKey = stableErrorKey(error);
+    const errorChanged = errorKey !== lastError && error != null;
+
+    if ((phaseChanged || force) && callbacks.onPhaseChange) {
+      callbacks.onPhaseChange(phase, {
+        phase,
+        reasonCode: nextState.reasonCode,
+        lifecycle,
+        lastError: error,
+      });
+    }
+    if ((lifecycleChanged || force) && callbacks.onLifecycle) {
+      callbacks.onLifecycle(lifecycle, {
+        phase,
+        reasonCode: nextState.reasonCode,
+        lifecycle,
+        lastError: error,
+      });
+    }
+    if (errorChanged && callbacks.onError) {
+      callbacks.onError(error, {
+        phase,
+        reasonCode: nextState.reasonCode,
+        lifecycle,
+        lastError: error,
+      });
+    }
+
+    lastPhase = phase;
+    lastLifecycle = lifecycleKey;
+    lastError = errorKey;
+    state = sanitizeState({
+      phase,
+      reasonCode: nextState.reasonCode,
+      lifecycle,
+      lastError: error,
+    });
+  }
+
+  function ensureLoader() {
+    if (!loader) {
+      loader = resolveLoader(null);
+    }
+    if (!loader || typeof loader !== 'object') {
+      throw createApiError(
+        'web_api_loader_missing',
+        'AuraWebLoader is not available. Ensure build/web/js/aura-web-loader.js is loaded or inject a loader.',
+        'api',
+        false,
+        {},
+      );
+    }
+    const required = ['load', 'mount', 'unmount', 'getState'];
+    for (const name of required) {
+      if (typeof loader[name] !== 'function') {
+        throw createApiError(
+          'web_api_loader_invalid',
+          'AuraWebLoader is missing required method: ' + name,
+          'api',
+          false,
+          { method: name },
+        );
+      }
+    }
+    return loader;
+  }
+
+  async function mount(target, runtimeConfig) {
+    const resolvedLoader = ensureLoader();
+    const mergedConfig = mergeConfig(config, runtimeConfig || null);
+
+    try {
+      await resolvedLoader.load({
+        rootUrl: mergedConfig.rootUrl,
+        mount: mergedConfig.mount,
+      });
+      await resolvedLoader.mount(target != null ? target : mergedConfig.mount, {
+        rootUrl: mergedConfig.rootUrl,
+        mount: mergedConfig.mount,
+      });
+      const loaderState = currentState();
+      emitFromState({
+        ...loaderState,
+        phase: loaderState.phase === 'idle' ? 'mounted' : loaderState.phase,
+        reasonCode: loaderState.phase === 'idle' ? null : loaderState.reasonCode,
+      }, true);
+      return currentState();
+    } catch (error) {
+      const normalized = normalizeApiError(error, {
+        reasonCode: 'web_api_mount_failed',
+        message: 'Failed to mount Aura runtime.',
+        layer: 'api',
+        retryable: true,
+      });
+      emitFromState({
+        ...currentState(),
+        phase: 'error',
+        reasonCode: normalized.reasonCode,
+        lastError: snapshotError(normalized),
+      }, true);
+      throw normalized;
+    }
+  }
+
+  async function unmount() {
+    const resolvedLoader = ensureLoader();
+    try {
+      await resolvedLoader.unmount();
+      const loaderState = currentState();
+      emitFromState({
+        ...loaderState,
+        phase: loaderState.phase === 'idle' ? 'unmounted' : loaderState.phase,
+        reasonCode: loaderState.phase === 'idle' ? null : loaderState.reasonCode,
+      }, true);
+      return currentState();
+    } catch (error) {
+      const normalized = normalizeApiError(error, {
+        reasonCode: 'web_api_unmount_failed',
+        message: 'Failed to unmount Aura runtime.',
+        layer: 'api',
+        retryable: true,
+      });
+      emitFromState({
+        ...currentState(),
+        phase: 'error',
+        reasonCode: normalized.reasonCode,
+        lastError: snapshotError(normalized),
+      }, true);
+      throw normalized;
+    }
+  }
+
+  function setConfig(nextConfig) {
+    config = mergeConfig(config, nextConfig);
+    return getConfig();
+  }
+
+  function getConfig() {
+    return {
+      rootUrl: config.rootUrl,
+      mount: config.mount,
+    };
+  }
+
+  function getState() {
+    return currentState();
+  }
+
+  return {
+    mount,
+    unmount,
+    setConfig,
+    getConfig,
+    getState,
+  };
+}
+
+const defaultGame = createAuraGame();
+
+export function mount(target, options) {
+  return defaultGame.mount(target, options);
+}
+
+export function unmount() {
+  return defaultGame.unmount();
+}
+
+export function setConfig(nextConfig) {
+  return defaultGame.setConfig(nextConfig);
+}
+
+export function getState() {
+  return defaultGame.getState();
+}
+
+export function getConfig() {
+  return defaultGame.getConfig();
+}

package/templates/create/2d/aura.config.json

@@ -0,0 +1,28 @@
+{
+  "identity": {
+    "name": "{{PROJECT_TITLE}}",
+    "version": "{{PROJECT_VERSION}}",
+    "executable": "{{PROJECT_BIN_NAME}}",
+    "icon": null
+  },
+  "window": {
+    "title": "{{PROJECT_TITLE}}",
+    "width": 1280,
+    "height": 720,
+    "resizable": true,
+    "fullscreen": false,
+    "vsync": true,
+    "hidpi": true
+  },
+  "build": {
+    "entry": "src/main.js",
+    "outDir": "build",
+    "assetDir": "assets",
+    "assetMode": "embed"
+  },
+  "modules": {
+    "physics": false,
+    "network": true,
+    "steam": false
+  }
+}

package/templates/create/2d/src/main.js

@@ -0,0 +1,196 @@
+// {{PROJECT_TITLE}} — AuraJS 2D shooter starter
+
+import { axisFromKeys, centeredRect, clamp, consumeCooldown, createCooldown, createWaveDirector, pickEnemyArchetypeForWave2D, rectsOverlap, removeWhere, spawnEnemy2D, stepWaveDirector, tickCooldown } from './starter-utils/index.js';
+
+const PLAYER_W = 34;
+const PLAYER_H = 26;
+const PLAYER_SPEED = 420;
+const BULLET_W = 6;
+const BULLET_H = 14;
+const BULLET_SPEED = 640;
+const SHOOT_COOLDOWN = 0.14;
+
+const WAVE_CONFIG = [
+  { maxSpawns: 9, spawnEvery: 0.62, archetype: 'scout', speedScale: 1.0 },
+  { maxSpawns: 10, spawnEvery: 0.56, archetype: 'striker', speedScale: 1.06 },
+  { maxSpawns: 8, spawnEvery: 0.74, archetype: 'tank', speedScale: 1.02 },
+  { maxSpawns: 12, spawnEvery: 0.48, archetype: null, speedScale: 1.12 },
+];
+
+let player = { x: 0, y: 0 };
+let bullets = [];
+let enemies = [];
+let lives = 3;
+let score = 0;
+let shootCooldown = createCooldown(SHOOT_COOLDOWN);
+let waveDirector = createWaveDirector({ waves: WAVE_CONFIG, loop: true, betweenWaveDelay: 1.0 });
+let gameOver = false;
+
+function hasMethod(obj, method) {
+  return Boolean(obj) && typeof obj[method] === 'function';
+}
+
+function failWithReason(reasonCode, message) {
+  throw new Error(`[2d-shooter-template] ${message} [reason:${reasonCode}]`);
+}
+
+function assertRuntimeCapabilities() {
+  const missing = [];
+  if (!hasMethod(aura.window, 'getSize')) missing.push('aura.window.getSize');
+  if (!hasMethod(aura.window, 'getFPS')) missing.push('aura.window.getFPS');
+  if (!hasMethod(aura.input, 'isKeyDown')) missing.push('aura.input.isKeyDown');
+  if (!hasMethod(aura.input, 'isKeyPressed')) missing.push('aura.input.isKeyPressed');
+  if (!hasMethod(aura.draw2d, 'clear')) missing.push('aura.draw2d.clear');
+  if (!hasMethod(aura.draw2d, 'rect')) missing.push('aura.draw2d.rect');
+  if (!hasMethod(aura.draw2d, 'text')) missing.push('aura.draw2d.text');
+  if (!hasMethod(aura.draw2d, 'measureText')) missing.push('aura.draw2d.measureText');
+  if (typeof aura.rgb !== 'function') missing.push('aura.rgb');
+  if (typeof aura.rgba !== 'function') missing.push('aura.rgba');
+  if (!aura.Color || !aura.Color.WHITE) missing.push('aura.Color.WHITE');
+
+  if (missing.length > 0) {
+    failWithReason('missing_runtime_api', `runtime missing required APIs: ${missing.join(', ')}`);
+  }
+
+  const small = aura.draw2d.measureText('Probe', { size: 8 });
+  const large = aura.draw2d.measureText('Probe', { size: 24 });
+  if (!Number.isFinite(Number(small?.width)) || !Number.isFinite(Number(large?.width)) || Number(large.width) <= Number(small.width)) {
+    failWithReason(
+      'placeholder_runtime_behavior',
+      'draw2d.measureText appears to be placeholder behavior (size does not affect width).',
+    );
+  }
+}
+
+function resetRun() {
+  const size = aura.window.getSize();
+  player.x = size.width * 0.5;
+  player.y = size.height - 70;
+  bullets = [];
+  enemies = [];
+  lives = 3;
+  score = 0;
+  shootCooldown = createCooldown(SHOOT_COOLDOWN);
+  waveDirector = createWaveDirector({ waves: WAVE_CONFIG, loop: true, betweenWaveDelay: 1.0 });
+  gameOver = false;
+}
+
+function spawnBullet() {
+  bullets.push({
+    x: player.x - (BULLET_W * 0.5),
+    y: player.y - PLAYER_H,
+  });
+}
+
+function spawnEnemy(width, waveState) {
+  const wave = waveState?.wave || null;
+  const archetype = wave?.archetype || pickEnemyArchetypeForWave2D(waveState?.waveIndex || 0).id;
+  const enemy = spawnEnemy2D({
+    x: 24 + (Math.random() * Math.max(1, width - 48)),
+    y: -22,
+    waveIndex: waveState?.waveIndex || 0,
+    archetypeId: archetype,
+  });
+
+  const speedScale = Number.isFinite(Number(wave?.speedScale))
+    ? Number(wave.speedScale)
+    : 1.0;
+  enemy.speed *= Math.max(0.4, speedScale);
+  enemies.push(enemy);
+}
+
+aura.setup = function () {
+  assertRuntimeCapabilities();
+  resetRun();
+  console.log('{{PROJECT_TITLE}} started (2D shooter template)');
+};
+
+aura.update = function (dt) {
+  const size = aura.window.getSize();
+
+  if (gameOver) {
+    if (aura.input.isKeyPressed('enter')) resetRun();
+    return;
+  }
+
+  const moveX = axisFromKeys(aura.input, ['arrowleft', 'a'], ['arrowright', 'd']);
+  const moveY = axisFromKeys(aura.input, ['arrowup', 'w'], ['arrowdown', 's']);
+
+  player.x += moveX * PLAYER_SPEED * dt;
+  player.y += moveY * PLAYER_SPEED * dt;
+  player.x = clamp(player.x, PLAYER_W * 0.5, size.width - (PLAYER_W * 0.5));
+  player.y = clamp(player.y, PLAYER_H * 0.5, size.height - (PLAYER_H * 0.5));
+
+  tickCooldown(shootCooldown, dt);
+  if ((aura.input.isKeyDown('space') || aura.input.isKeyDown('z')) && consumeCooldown(shootCooldown)) {
+    spawnBullet();
+  }
+
+  stepWaveDirector(waveDirector, dt, (waveState) => {
+    spawnEnemy(size.width, waveState);
+  });
+
+  for (const bullet of bullets) {
+    bullet.y -= BULLET_SPEED * dt;
+  }
+  removeWhere(bullets, (bullet) => bullet.y + BULLET_H <= 0);
+
+  for (const enemy of enemies) {
+    enemy.y += enemy.speed * dt;
+  }
+
+  const survivors = [];
+  for (const enemy of enemies) {
+    const enemyBox = centeredRect(enemy.x, enemy.y, enemy.size, enemy.size);
+    let hit = false;
+
+    for (let i = bullets.length - 1; i >= 0; i -= 1) {
+      const bullet = bullets[i];
+      const bulletBox = { x: bullet.x, y: bullet.y, w: BULLET_W, h: BULLET_H };
+      if (!rectsOverlap(enemyBox, bulletBox)) continue;
+      bullets.splice(i, 1);
+      hit = true;
+      score += enemy.scoreValue;
+      break;
+    }
+
+    if (hit) continue;
+    if (enemy.y - (enemy.size * 0.5) > size.height) {
+      lives -= 1;
+      if (lives <= 0) gameOver = true;
+      continue;
+    }
+    survivors.push(enemy);
+  }
+  enemies = survivors;
+};
+
+aura.draw = function () {
+  const fps = aura.window.getFPS().toFixed(0);
+  aura.draw2d.clear(aura.rgba(0.05, 0.06, 0.1, 1.0));
+
+  for (const bullet of bullets) {
+    aura.draw2d.rect(bullet.x, bullet.y, BULLET_W, BULLET_H, aura.rgb(1.0, 0.95, 0.72));
+  }
+
+  for (const enemy of enemies) {
+    aura.draw2d.rect(
+      enemy.x - (enemy.size * 0.5),
+      enemy.y - (enemy.size * 0.5),
+      enemy.size,
+      enemy.size,
+      aura.rgb(enemy.color.r, enemy.color.g, enemy.color.b),
+    );
+  }
+
+  aura.draw2d.rect(player.x - (PLAYER_W * 0.5), player.y - (PLAYER_H * 0.5), PLAYER_W, PLAYER_H, aura.rgb(0.28, 0.78, 1.0));
+
+  const waveLabel = waveDirector.completed ? 'Done' : String(waveDirector.waveIndex + 1);
+  aura.draw2d.text('Move: Arrows/WASD  Fire: Space/Z', 12, 12, { color: aura.Color.WHITE, size: 15, align: 'left' });
+  aura.draw2d.text(`Wave ${waveLabel}   Score ${score}   Lives ${lives}   FPS ${fps}`, 12, 34, { color: aura.Color.WHITE, size: 14, align: 'left' });
+
+  if (gameOver) {
+    aura.draw2d.text('GAME OVER', 12, 64, { color: aura.rgb(1.0, 0.42, 0.42), size: 24, align: 'left' });
+    aura.draw2d.text('Press Enter to restart', 12, 92, { color: aura.Color.WHITE, size: 16, align: 'left' });
+  }
+};

package/templates/create/3d/aura.config.json

@@ -0,0 +1,28 @@
+{
+  "identity": {
+    "name": "{{PROJECT_TITLE}}",
+    "version": "{{PROJECT_VERSION}}",
+    "executable": "{{PROJECT_BIN_NAME}}",
+    "icon": null
+  },
+  "window": {
+    "title": "{{PROJECT_TITLE}}",
+    "width": 1280,
+    "height": 720,
+    "resizable": true,
+    "fullscreen": false,
+    "vsync": true,
+    "hidpi": true
+  },
+  "build": {
+    "entry": "src/main.js",
+    "outDir": "build",
+    "assetDir": "assets",
+    "assetMode": "embed"
+  },
+  "modules": {
+    "physics": false,
+    "network": true,
+    "steam": false
+  }
+}