@auraindustry/aurajs 0.0.7 → 0.1.0

package/templates/create/3d-collectathon/scenes/gameplay.scene.js

@@ -0,0 +1,200 @@
+import {
+  axisFromKeys,
+  createGoalZone,
+  distanceSquared3D,
+  isGoalReached,
+  respawnAtCheckpoint,
+  setAvatarInput3D,
+  spawnCharacterAvatar3D,
+  stepMovingPlatform3D,
+  tickCharacterAvatar3D,
+  updateCheckpointProgress,
+} from '../src/starter-utils/index.js';
+import {
+  GOAL_ZONE,
+  TARGET_COLLECTIBLES,
+  WORLD_LIMIT,
+} from '../content/gameplay/course.js';
+import { ensureUiState } from '../src/runtime/app-state.js';
+import { bindPlayerAvatarVisual, drawCollectathonActors, loadPlayerAvatarVisual } from '../prefabs/player.prefab.js';
+import { drawCollectathonCourse, syncCollectathonCharacterObstacles } from '../prefabs/world.prefab.js';
+import { createCollectathonMaterials } from '../src/runtime/materials.js';
+import { createCollectathonRunState } from '../src/runtime/state.js';
+import { drawCollectathonHud } from '../ui/hud.screen.js';
+
+function createCollectathonSessionSeed() {
+  return {
+    runsStarted: 0,
+    bestScore: 0,
+    lastOutcome: 'idle',
+    lastSceneId: 'gameplay',
+  };
+}
+
+function ensureCollectathonSession(context, appState) {
+  if (typeof context.ensureSessionState === 'function') {
+    return context.ensureSessionState('collectathon', createCollectathonSessionSeed());
+  }
+  if (!appState.session || typeof appState.session !== 'object' || Array.isArray(appState.session)) {
+    appState.session = {};
+  }
+  if (!appState.session.collectathon || typeof appState.session.collectathon !== 'object' || Array.isArray(appState.session.collectathon)) {
+    appState.session.collectathon = createCollectathonSessionSeed();
+  }
+  return appState.session.collectathon;
+}
+
+function createCollectathonUiStateSeed() {
+  return {
+    showControlsHint: true,
+  };
+}
+
+function ensureCollectathonUiState(context, appState) {
+  if (typeof context.ensureUiState === 'function') {
+    return context.ensureUiState('collectathonHud', createCollectathonUiStateSeed());
+  }
+  if (!appState.ui || typeof appState.ui !== 'object' || Array.isArray(appState.ui)) {
+    appState.ui = {};
+  }
+  if (!appState.ui.collectathonHud || typeof appState.ui.collectathonHud !== 'object' || Array.isArray(appState.ui.collectathonHud)) {
+    appState.ui.collectathonHud = createCollectathonUiStateSeed();
+  }
+  return appState.ui.collectathonHud;
+}
+
+export function createGameplayScene(context = {}) {
+  const appState = context.appState || {};
+  const collectathonSession = ensureCollectathonSession(context, appState);
+  const collectathonUiState = ensureCollectathonUiState(context, appState);
+  const projectTitle = context.projectTitle || 'AuraJS Game';
+  const goalZone = createGoalZone(GOAL_ZONE);
+  let boxMesh = null;
+  let materials = null;
+  let playerVisual = null;
+  let sceneState = createCollectathonRunState();
+
+  function syncSessionState() {
+    collectathonSession.lastSceneId = 'gameplay';
+    collectathonSession.bestScore = Math.max(Number(collectathonSession.bestScore || 0), sceneState.score);
+    collectathonSession.lastScore = sceneState.score;
+    collectathonSession.lastTimerRemaining = Number(sceneState.timerRemaining.toFixed(2));
+    collectathonSession.lastOutcome = sceneState.runComplete
+      ? 'course-cleared'
+      : (sceneState.runFailed ? 'failed' : 'running');
+  }
+
+  function resetRun() {
+    sceneState = createCollectathonRunState(sceneState?.player ?? null);
+    if (!playerVisual) return;
+    bindPlayerAvatarVisual(sceneState.player, playerVisual);
+    syncCollectathonCharacterObstacles(sceneState.movingPlatform);
+    spawnCharacterAvatar3D(aura, sceneState.player, { position: sceneState.player.position });
+    collectathonSession.runsStarted += 1;
+    syncSessionState();
+  }
+
+  function updateMovement(dt) {
+    const moveX = axisFromKeys(aura.input, ['arrowleft', 'a'], ['arrowright', 'd']);
+    const moveZ = axisFromKeys(aura.input, ['arrowup', 'w'], ['arrowdown', 's']);
+    setAvatarInput3D(sceneState.player, {
+      moveX,
+      moveZ,
+      jump: aura.input.isKeyPressed('space'),
+      run: aura.input.isKeyDown('shift') || aura.input.isKeyDown('shiftleft') || aura.input.isKeyDown('shiftright'),
+    });
+    tickCharacterAvatar3D(aura, sceneState.player, dt);
+    sceneState.player.position.x = Math.max(-WORLD_LIMIT, Math.min(WORLD_LIMIT, sceneState.player.position.x));
+    sceneState.player.position.z = Math.max(-WORLD_LIMIT, Math.min(WORLD_LIMIT, sceneState.player.position.z));
+    spawnCharacterAvatar3D(aura, sceneState.player, { position: sceneState.player.position });
+  }
+
+  function updateRespawnAndCheckpoints() {
+    if (sceneState.player.position.y < -10) {
+      if (!respawnAtCheckpoint(sceneState.checkpointSystem, sceneState.player)) {
+        resetRun();
+        return false;
+      }
+      spawnCharacterAvatar3D(aura, sceneState.player, { position: sceneState.player.position });
+    }
+
+    updateCheckpointProgress(sceneState.checkpointSystem, sceneState.player);
+    return true;
+  }
+
+  function collectNearbyPickups() {
+    for (const collectible of sceneState.collectibles) {
+      if (collectible.collected) continue;
+      if (distanceSquared3D(sceneState.player, collectible) > 0.95) continue;
+      collectible.collected = true;
+      sceneState.score += 1;
+    }
+  }
+
+  return {
+    setup() {
+      boxMesh = aura.mesh.createBox();
+      materials = createCollectathonMaterials();
+      playerVisual = loadPlayerAvatarVisual();
+
+      aura.light.ambient({ r: 1, g: 1, b: 1 }, 0.23);
+      aura.light.directional({ x: 0.55, y: -1.0, z: -0.35 }, { r: 1, g: 1, b: 1 }, 1.0);
+      aura.camera3d.perspective(62, 0.1, 150);
+
+      resetRun();
+      console.log(`${projectTitle} started (3D collectathon template)`);
+    },
+    update(dt) {
+      if (aura.input.isKeyPressed('h')) {
+        collectathonUiState.showControlsHint = collectathonUiState.showControlsHint !== true;
+      }
+      sceneState.elapsed += dt;
+      stepMovingPlatform3D(sceneState.movingPlatform, dt);
+      syncCollectathonCharacterObstacles(sceneState.movingPlatform);
+
+      if (sceneState.runFailed || sceneState.runComplete) {
+        if (aura.input.isKeyPressed('enter')) resetRun();
+        return;
+      }
+
+      sceneState.timerRemaining = Math.max(0, sceneState.timerRemaining - dt);
+      if (sceneState.timerRemaining <= 0) {
+        sceneState.runFailed = true;
+        syncSessionState();
+        return;
+      }
+
+      updateMovement(dt);
+      if (!updateRespawnAndCheckpoints()) return;
+      collectNearbyPickups();
+
+      if (sceneState.score >= TARGET_COLLECTIBLES && isGoalReached(goalZone, sceneState.player)) {
+        sceneState.runComplete = true;
+      }
+      syncSessionState();
+    },
+    draw() {
+      aura.draw3d.clear3d({ r: 0.06, g: 0.08, b: 0.12 });
+      drawCollectathonCourse({
+        mesh: boxMesh,
+        floorMaterial: materials.floor,
+        platformMaterial: materials.platform,
+        movingPlatform: sceneState.movingPlatform,
+      });
+      drawCollectathonActors({
+        mesh: boxMesh,
+        materials,
+        state: sceneState,
+        goalZone,
+      });
+      aura.scene3d.submitRenderBindings();
+      drawCollectathonHud({
+        score: sceneState.score,
+        timerRemaining: sceneState.timerRemaining,
+        runFailed: sceneState.runFailed,
+        runComplete: sceneState.runComplete,
+        showControlsHint: collectathonUiState.showControlsHint !== false,
+      });
+    },
+  };
+}

package/templates/create/3d-collectathon/src/main.js

@@ -1,367 +1,17 @@
 // {{PROJECT_TITLE}} - AuraJS 3D collectathon starter
 
-import { activeCheckpoint, axisFromKeys, clamp, createCheckpointSystem, createGoalZone, createMovingPlatform3D, distanceSquared3D, isGoalReached, respawnAtCheckpoint, stepMovingPlatform3D, stepVerticalMotion, tryJump, updateCheckpointProgress } from './starter-utils/index.js';
+import { createApp } from './runtime/app.js';
 
-const PLAYER_HALF = { x: 0.45, y: 0.55, z: 0.45 };
-const MOVE_SPEED = 5.6;
-const JUMP_SPEED = 8.4;
-const GRAVITY = 20.0;
-const WORLD_LIMIT = 9.2;
-const TARGET_COLLECTIBLES = 5;
-const START_TIMER_SECONDS = 95;
-
-const WORLD_PLATFORMS = [
-  { x: -3.2, y: 1.2, z: 2.6, sx: 3.0, sy: 0.5, sz: 2.3 },
-  { x: 2.5, y: 2.2, z: 1.2, sx: 2.8, sy: 0.5, sz: 2.1 },
-  { x: 4.9, y: 3.3, z: -1.8, sx: 2.8, sy: 0.5, sz: 2.0 },
-  { x: -1.0, y: 3.7, z: -3.3, sx: 3.0, sy: 0.5, sz: 2.2 },
-  { x: 3.8, y: 4.8, z: -5.1, sx: 2.8, sy: 0.5, sz: 2.0 },
-];
-
-const CHECKPOINTS = [
-  { x: 0.0, y: 1.1, z: 5.8, radius: 1.4 },
-  { x: -3.2, y: 2.0, z: 2.6, radius: 1.2 },
-  { x: 2.5, y: 3.0, z: 1.2, radius: 1.2 },
-  { x: -1.0, y: 4.5, z: -3.3, radius: 1.25 },
-  { x: 3.8, y: 5.7, z: -5.1, radius: 1.3 },
-];
-
-const COLLECTIBLE_SPAWNS = [
-  { x: -3.2, y: 2.0, z: 2.6 },
-  { x: 2.5, y: 3.0, z: 1.2 },
-  { x: 4.9, y: 4.1, z: -1.8 },
-  { x: -1.0, y: 4.5, z: -3.3 },
-  { x: 3.8, y: 5.7, z: -5.1 },
-  { x: 0.2, y: 2.8, z: -0.8 },
-];
-
-let boxMesh;
-let floorMat;
-let platformMat;
-let playerMat;
-let collectibleMat;
-let checkpointMat;
-let goalMat;
-
-let player = { x: 0, y: 1.1, z: 5.8, vy: 0, onGround: false };
-let collectibles = [];
-let score = 0;
-let elapsed = 0;
-let timerRemaining = START_TIMER_SECONDS;
-let runFailed = false;
-let runComplete = false;
-let checkpointSystem = createCheckpointSystem({ checkpoints: CHECKPOINTS });
-let movingPlatform = createMovingPlatform3D({
-  from: { x: 0.7, y: 2.1, z: -0.5 },
-  to: { x: 3.2, y: 3.1, z: -2.1 },
-  size: { x: 2.2, y: 0.4, z: 1.8 },
-  periodSeconds: 3.0,
-});
-const goalZone = createGoalZone({ x: 3.8, y: 5.9, z: -5.1, radius: 1.15 });
-
-function hasMethod(obj, method) {
-  return Boolean(obj) && typeof obj[method] === 'function';
-}
-
-function failWithReason(reasonCode, message) {
-  throw new Error(`[3d-collectathon-template] ${message} [reason:${reasonCode}]`);
-}
-
-function assertRuntimeCapabilities() {
-  const missing = [];
-  if (!hasMethod(aura.mesh, 'createBox')) missing.push('aura.mesh.createBox');
-  if (!hasMethod(aura.material, 'create')) missing.push('aura.material.create');
-  if (!hasMethod(aura.light, 'ambient')) missing.push('aura.light.ambient');
-  if (!hasMethod(aura.light, 'directional')) missing.push('aura.light.directional');
-  if (!hasMethod(aura.camera3d, 'perspective')) missing.push('aura.camera3d.perspective');
-  if (!hasMethod(aura.camera3d, 'setPosition')) missing.push('aura.camera3d.setPosition');
-  if (!hasMethod(aura.camera3d, 'lookAt')) missing.push('aura.camera3d.lookAt');
-  if (!hasMethod(aura.input, 'isKeyDown')) missing.push('aura.input.isKeyDown');
-  if (!hasMethod(aura.input, 'isKeyPressed')) missing.push('aura.input.isKeyPressed');
-  if (!hasMethod(aura.draw3d, 'clear3d')) missing.push('aura.draw3d.clear3d');
-  if (!hasMethod(aura.draw3d, 'drawMesh')) missing.push('aura.draw3d.drawMesh');
-  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 (!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 buildCollectibles() {
-  return COLLECTIBLE_SPAWNS.map((entry, index) => ({
-    id: `c-${index + 1}`,
-    x: entry.x,
-    y: entry.y,
-    z: entry.z,
-    collected: false,
-  }));
-}
-
-function resetRun() {
-  player = { x: 0, y: 1.1, z: 5.8, vy: 0, onGround: false };
-  collectibles = buildCollectibles();
-  score = 0;
-  elapsed = 0;
-  timerRemaining = START_TIMER_SECONDS;
-  runFailed = false;
-  runComplete = false;
-  checkpointSystem = createCheckpointSystem({ checkpoints: CHECKPOINTS });
-  movingPlatform = createMovingPlatform3D({
-    from: { x: 0.7, y: 2.1, z: -0.5 },
-    to: { x: 3.2, y: 3.1, z: -2.1 },
-    size: { x: 2.2, y: 0.4, z: 1.8 },
-    periodSeconds: 3.0,
-  });
-}
-
-function findSupportTop(x, z) {
-  let top = 0;
-
-  const includePlatform = (platform) => {
-    const halfX = platform.sx * 0.5;
-    const halfZ = platform.sz * 0.5;
-    if (Math.abs(x - platform.x) > halfX || Math.abs(z - platform.z) > halfZ) return;
-    top = Math.max(top, platform.y + (platform.sy * 0.5));
-  };
-
-  for (const platform of WORLD_PLATFORMS) {
-    includePlatform(platform);
-  }
-
-  includePlatform({
-    x: movingPlatform.position.x,
-    y: movingPlatform.position.y,
-    z: movingPlatform.position.z,
-    sx: movingPlatform.size.x,
-    sy: movingPlatform.size.y,
-    sz: movingPlatform.size.z,
-  });
-
-  return top;
-}
-
-function collectNearbyPickups() {
-  for (const collectible of collectibles) {
-    if (collectible.collected) continue;
-    const pickupDistanceSq = distanceSquared3D(player, collectible);
-    if (pickupDistanceSq > 0.95) continue;
-    collectible.collected = true;
-    score += 1;
-  }
-}
+const app = createApp();
 
 aura.setup = function () {
-  assertRuntimeCapabilities();
-  boxMesh = aura.mesh.createBox();
-
-  floorMat = aura.material.create({
-    color: { r: 0.16, g: 0.25, b: 0.2, a: 1.0 },
-    metallic: 0.06,
-    roughness: 0.92,
-  });
-
-  platformMat = aura.material.create({
-    color: { r: 0.42, g: 0.54, b: 0.74, a: 1.0 },
-    metallic: 0.1,
-    roughness: 0.6,
-  });
-
-  playerMat = aura.material.create({
-    color: { r: 0.98, g: 0.55, b: 0.26, a: 1.0 },
-    metallic: 0.28,
-    roughness: 0.32,
-  });
-
-  collectibleMat = aura.material.create({
-    color: { r: 0.98, g: 0.92, b: 0.38, a: 1.0 },
-    metallic: 0.7,
-    roughness: 0.25,
-  });
-
-  checkpointMat = aura.material.create({
-    color: { r: 0.34, g: 0.9, b: 1.0, a: 1.0 },
-    metallic: 0.45,
-    roughness: 0.3,
-  });
-
-  goalMat = aura.material.create({
-    color: { r: 0.54, g: 1.0, b: 0.7, a: 1.0 },
-    metallic: 0.38,
-    roughness: 0.32,
-  });
-
-  aura.light.ambient({ r: 1, g: 1, b: 1 }, 0.23);
-  aura.light.directional({ x: 0.55, y: -1.0, z: -0.35 }, { r: 1, g: 1, b: 1 }, 1.0);
-  aura.camera3d.perspective(62, 0.1, 150);
-
-  resetRun();
-  console.log('{{PROJECT_TITLE}} started (3D collectathon template)');
+  app.setup();
 };
 
 aura.update = function (dt) {
-  elapsed += dt;
-  stepMovingPlatform3D(movingPlatform, dt);
-
-  if (runFailed || runComplete) {
-    if (aura.input.isKeyPressed('enter')) resetRun();
-    return;
-  }
-
-  timerRemaining = Math.max(0, timerRemaining - dt);
-  if (timerRemaining <= 0) {
-    runFailed = true;
-    return;
-  }
-
-  const moveX = axisFromKeys(aura.input, ['arrowleft', 'a'], ['arrowright', 'd']);
-  const moveZ = axisFromKeys(aura.input, ['arrowup', 'w'], ['arrowdown', 's']);
-
-  player.x += moveX * MOVE_SPEED * dt;
-  player.z += moveZ * MOVE_SPEED * dt;
-  player.x = clamp(player.x, -WORLD_LIMIT, WORLD_LIMIT);
-  player.z = clamp(player.z, -WORLD_LIMIT, WORLD_LIMIT);
-
-  if (aura.input.isKeyPressed('space')) {
-    tryJump(player, JUMP_SPEED);
-  }
-
-  const supportTop = findSupportTop(player.x, player.z);
-  const floorY = supportTop + PLAYER_HALF.y;
-  stepVerticalMotion(player, dt, GRAVITY, floorY);
-
-  if (player.y < -10) {
-    if (!respawnAtCheckpoint(checkpointSystem, player)) {
-      resetRun();
-      return;
-    }
-  }
-
-  updateCheckpointProgress(checkpointSystem, player);
-  collectNearbyPickups();
-
-  if (score >= TARGET_COLLECTIBLES && isGoalReached(goalZone, player)) {
-    runComplete = true;
-  }
-
-  aura.camera3d.setPosition(player.x + 7.8, player.y + 6.2, player.z + 8.5);
-  aura.camera3d.lookAt(player.x, player.y + 0.2, player.z);
+  app.update(dt);
 };
 
 aura.draw = function () {
-  aura.draw3d.clear3d({ r: 0.06, g: 0.08, b: 0.12 });
-
-  aura.draw3d.drawMesh(boxMesh, floorMat, {
-    position: { x: 0, y: -0.5, z: 0 },
-    rotation: { x: 0, y: 0, z: 0 },
-    scale: { x: 26, y: 1, z: 26 },
-  });
-
-  for (const platform of WORLD_PLATFORMS) {
-    aura.draw3d.drawMesh(boxMesh, platformMat, {
-      position: { x: platform.x, y: platform.y, z: platform.z },
-      rotation: { x: 0, y: 0, z: 0 },
-      scale: { x: platform.sx, y: platform.sy, z: platform.sz },
-    });
-  }
-
-  aura.draw3d.drawMesh(boxMesh, platformMat, {
-    position: { x: movingPlatform.position.x, y: movingPlatform.position.y, z: movingPlatform.position.z },
-    rotation: { x: 0, y: elapsed * 0.5, z: 0 },
-    scale: { x: movingPlatform.size.x, y: movingPlatform.size.y, z: movingPlatform.size.z },
-  });
-
-  aura.draw3d.drawMesh(boxMesh, playerMat, {
-    position: { x: player.x, y: player.y, z: player.z },
-    rotation: { x: 0, y: elapsed * 1.1, z: 0 },
-    scale: { x: PLAYER_HALF.x * 2, y: PLAYER_HALF.y * 2, z: PLAYER_HALF.z * 2 },
-  });
-
-  for (const collectible of collectibles) {
-    if (collectible.collected) continue;
-    aura.draw3d.drawMesh(boxMesh, collectibleMat, {
-      position: {
-        x: collectible.x,
-        y: collectible.y + (Math.sin((elapsed * 2.2) + collectible.x) * 0.16),
-        z: collectible.z,
-      },
-      rotation: { x: elapsed * 0.5, y: elapsed * 1.7, z: elapsed * 0.3 },
-      scale: { x: 0.45, y: 0.45, z: 0.45 },
-    });
-  }
-
-  const checkpoint = activeCheckpoint(checkpointSystem);
-  if (checkpoint) {
-    aura.draw3d.drawMesh(boxMesh, checkpointMat, {
-      position: { x: checkpoint.x, y: checkpoint.y - 0.35, z: checkpoint.z },
-      rotation: { x: 0, y: elapsed, z: 0 },
-      scale: { x: 0.4, y: 0.4, z: 0.4 },
-    });
-  }
-
-  aura.draw3d.drawMesh(boxMesh, goalMat, {
-    position: { x: goalZone.x, y: goalZone.y, z: goalZone.z },
-    rotation: { x: 0, y: elapsed * 0.9, z: 0 },
-    scale: {
-      x: goalZone.radius * 1.25,
-      y: goalZone.radius * 1.25,
-      z: goalZone.radius * 1.25,
-    },
-  });
-
-  aura.draw2d.text('Move: Arrows/WASD  Jump: Space', 12, 12, {
-    color: aura.Color.WHITE,
-    size: 14,
-    align: 'left',
-  });
-  aura.draw2d.text(`Collectibles ${score}/${TARGET_COLLECTIBLES}`, 12, 34, {
-    color: aura.Color.WHITE,
-    size: 14,
-    align: 'left',
-  });
-  aura.draw2d.text(`Timer ${timerRemaining.toFixed(1)}s`, 12, 56, {
-    color: aura.Color.WHITE,
-    size: 14,
-    align: 'left',
-  });
-  aura.draw2d.text('Reach checkpoints, collect orbs, then hit the goal.', 12, 78, {
-    color: aura.Color.WHITE,
-    size: 13,
-    align: 'left',
-  });
-
-  if (runComplete) {
-    aura.draw2d.text('COURSE CLEARED', 12, 108, {
-      color: aura.rgb(0.54, 1.0, 0.7),
-      size: 24,
-      align: 'left',
-    });
-    aura.draw2d.text('Press Enter to restart', 12, 136, {
-      color: aura.Color.WHITE,
-      size: 16,
-      align: 'left',
-    });
-  } else if (runFailed) {
-    aura.draw2d.text('TIME UP', 12, 108, {
-      color: aura.rgb(1.0, 0.46, 0.46),
-      size: 24,
-      align: 'left',
-    });
-    aura.draw2d.text('Press Enter to retry', 12, 136, {
-      color: aura.Color.WHITE,
-      size: 16,
-      align: 'left',
-    });
-  }
+  app.draw();
 };

package/templates/create/3d-collectathon/src/runtime/app.js

@@ -0,0 +1,49 @@
+import { createSceneRegistry } from './scene-registry.js';
+import { createProjectInspector } from './project-inspector.js';
+import { assertRuntimeCapabilities } from './capabilities.js';
+
+export function createApp() {
+  const sceneRegistry = createSceneRegistry({
+    projectTitle: '{{PROJECT_TITLE}}',
+  });
+  const projectInspector = createProjectInspector();
+  let activeSceneId = sceneRegistry.defaultSceneId || Object.keys(sceneRegistry.scenes)[0] || null;
+
+  const activeScene = () => (activeSceneId ? sceneRegistry.scenes[activeSceneId] || null : null);
+
+  return {
+    get activeSceneId() {
+      return activeSceneId;
+    },
+    get sceneRegistry() {
+      return sceneRegistry;
+    },
+    get projectInspectorEnabled() {
+      return projectInspector.enabled;
+    },
+    getProjectInspectorState() {
+      return projectInspector.snapshot({ activeSceneId });
+    },
+    setup() {
+      assertRuntimeCapabilities();
+      activeScene()?.setup?.();
+    },
+    update(dt) {
+      projectInspector.syncInput(globalThis.aura?.input || null);
+      activeScene()?.update?.(dt);
+    },
+    draw() {
+      activeScene()?.draw?.();
+      projectInspector.draw({ activeSceneId });
+    },
+    toggleProjectInspector(nextEnabled) {
+      return projectInspector.toggle(nextEnabled);
+    },
+    swapScene(nextSceneId) {
+      if (!sceneRegistry.scenes[nextSceneId]) {
+        throw new Error(`Unknown scene "${nextSceneId}".`);
+      }
+      activeSceneId = nextSceneId;
+    },
+  };
+}

package/templates/create/3d-collectathon/src/runtime/capabilities.js

@@ -0,0 +1,53 @@
+function hasMethod(obj, method) {
+  return Boolean(obj) && typeof obj[method] === 'function';
+}
+
+function failWithReason(reasonCode, message) {
+  throw new Error(`[3d-collectathon-template] ${message} [reason:${reasonCode}]`);
+}
+
+export function assertRuntimeCapabilities() {
+  const missing = [];
+  if (!hasMethod(aura.mesh, 'createBox')) missing.push('aura.mesh.createBox');
+  if (!hasMethod(aura.material, 'create')) missing.push('aura.material.create');
+  if (!hasMethod(aura.light, 'ambient')) missing.push('aura.light.ambient');
+  if (!hasMethod(aura.light, 'directional')) missing.push('aura.light.directional');
+  if (!hasMethod(aura.camera3d, 'perspective')) missing.push('aura.camera3d.perspective');
+  if (!hasMethod(aura.camera3d, 'setPosition')) missing.push('aura.camera3d.setPosition');
+  if (!hasMethod(aura.camera3d, 'lookAt')) missing.push('aura.camera3d.lookAt');
+  if (!hasMethod(aura.character3d, 'create')) missing.push('aura.character3d.create');
+  if (!hasMethod(aura.character3d, 'move')) missing.push('aura.character3d.move');
+  if (!hasMethod(aura.character3d, 'jump')) missing.push('aura.character3d.jump');
+  if (!hasMethod(aura.character3d, 'update')) missing.push('aura.character3d.update');
+  if (!hasMethod(aura.character3d, 'getState')) missing.push('aura.character3d.getState');
+  if (!hasMethod(aura.character3d, 'setPosition')) missing.push('aura.character3d.setPosition');
+  if (!hasMethod(aura.character3d, 'addObstacle')) missing.push('aura.character3d.addObstacle');
+  if (!hasMethod(aura.character3d, 'clearObstacles')) missing.push('aura.character3d.clearObstacles');
+  if (!hasMethod(aura.input, 'isKeyDown')) missing.push('aura.input.isKeyDown');
+  if (!hasMethod(aura.input, 'isKeyPressed')) missing.push('aura.input.isKeyPressed');
+  if (!hasMethod(aura.scene3d, 'loadGltfScene')) missing.push('aura.scene3d.loadGltfScene');
+  if (!hasMethod(aura.scene3d, 'getImportedScene')) missing.push('aura.scene3d.getImportedScene');
+  if (!hasMethod(aura.scene3d, 'playImportedAnimation')) missing.push('aura.scene3d.playImportedAnimation');
+  if (!hasMethod(aura.scene3d, 'setLocalTransform')) missing.push('aura.scene3d.setLocalTransform');
+  if (!hasMethod(aura.scene3d, 'updateClips')) missing.push('aura.scene3d.updateClips');
+  if (!hasMethod(aura.scene3d, 'submitRenderBindings')) missing.push('aura.scene3d.submitRenderBindings');
+  if (!hasMethod(aura.draw3d, 'clear3d')) missing.push('aura.draw3d.clear3d');
+  if (!hasMethod(aura.draw3d, 'drawMesh')) missing.push('aura.draw3d.drawMesh');
+  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 (!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).',
+    );
+  }
+}