@aura3d/engine 1.3.3 → 1.4.1

package/templates/mini-game/README.md

@@ -3,6 +3,19 @@
 Small interactive scene starter for agent-authored controls, movement, and route
 health checks.
 
+Status: playable starter, not a production game claim. This template uses a
+typed player asset, the public `game.platformer(...)` kit, runtime nodes, HUD
+evidence, keyboard input, reset, scoring, and screenshot tests. It proves the
+starter boots and responds to keyboard input through the root `@aura3d/engine`
+safe API; it does not prove production art direction, skinned animation,
+advanced PBR, WebGPU, postprocess, or commercial game polish.
+
+Before presenting a route from this template as production-quality, replace any
+placeholder art with typed primary assets from the Aura3D CLI, keep
+`model(assets.x)` for real assets, prove each claimed mechanic with keyboard
+tests, and capture desktop/mobile screenshots where the main subject is
+readable.
+
 ```bash
 npm install
 npm run dev

package/templates/mini-game/index.html

@@ -8,6 +8,6 @@
   </head>
   <body>
     <div id="app"></div>
-    <script type="module" src="/src/main.ts"></script>
+    <script type="module" src="./src/main.ts"></script>
   </body>
 </html>

package/templates/mini-game/package.json

@@ -8,7 +8,7 @@
     "typecheck": "tsc --noEmit",
     "build": "npm run typecheck && vite build",
     "preview": "vite preview --host 127.0.0.1",
-    "test": "playwright test tests/route-health.spec.ts tests/screenshot.spec.ts --workers=1"
+    "test": "playwright test tests/route-health.spec.ts tests/playable.spec.ts tests/screenshot.spec.ts --workers=1"
   },
   "dependencies": {
     "@aura3d/engine": "1.0.0"

package/templates/mini-game/src/main.ts

@@ -1,27 +1,257 @@
-import { createAuraApp, definePromptPlan, promptPlanToScene } from "@aura3d/engine";
+import {
+  camera,
+  createAuraApp,
+  game,
+  lights,
+  material,
+  model,
+  primitives,
+  scene,
+  type AuraNodeInput
+} from "@aura3d/engine";
 import { assets } from "./aura-assets";
 
-const plan = definePromptPlan({
-  sceneType: "mini-game",
-  subject: { asset: assets.playerModel, label: "player" },
-  style: "readable neon collect-and-dodge arena",
-  environment: "bounded board with rails, lane markings, coins, hazards, and portal goal",
-  camera: { preset: "game-board" },
-  lighting: { preset: "game-readable" },
-  effects: ["motion-trail", "hud", "bloom"],
-  interaction: "keyboard",
-  acceptanceCriteria: [
-    "player, coins, hazards, and portal are all visible",
-    "arena boundaries and lane direction are readable",
-    "motion trail and shield communicate active game state"
+declare global {
+  interface Window {
+    __AURA3D_MINI_GAME__?: MiniGameEvidence;
+  }
+}
+
+interface MiniGameEvidence {
+  readonly status: string;
+  readonly frame: number;
+  readonly score: number;
+  readonly deaths: number;
+  readonly checkpointId: string;
+  readonly collected: readonly string[];
+  readonly player: {
+    readonly x: number;
+    readonly y: number;
+    readonly grounded: boolean;
+  };
+  readonly events: readonly string[];
+  readonly evidence: unknown;
+}
+
+const level = {
+  start: { x: 0, y: 0.35 },
+  finish: { x: 12.4, y: 0.35 },
+  platforms: [
+    { id: "launch", x: -0.6, y: 0, width: 4.2, height: 0.35 },
+    { id: "middle", x: 3.8, y: 0.62, width: 3.2, height: 0.3 },
+    { id: "finish", x: 8.2, y: 0.18, width: 4.8, height: 0.35 }
+  ],
+  movingPlatforms: [
+    { id: "lift", x: 6.9, y: 1.05, width: 1.35, height: 0.22, axis: "y" as const, amplitude: 0.42, period: 2.4 }
+  ],
+  collectibles: [
+    { id: "coin-01", x: 1.4, y: 1.15, value: 50, radius: 0.55 },
+    { id: "coin-02", x: 4.8, y: 1.45, value: 75, radius: 0.55 },
+    { id: "coin-03", x: 9.8, y: 1.05, value: 100, radius: 0.55 }
+  ],
+  hazards: [
+    { id: "spikes", x: 7.7, y: 0.42, width: 0.85, height: 0.24 }
+  ],
+  checkpoints: [
+    { id: "mid", x: 5.2, y: 0.92, radius: 0.8 }
   ],
-  negativeCriteria: [
-    "do not accept random primitives without readable game state",
-    "do not accept a character on an empty grid as a mini-game"
-  ]
-} as const);
+  lowerBound: -2.4,
+  moveSpeed: 5.2,
+  jumpVelocity: 8,
+  dashSpeed: 9.5
+};
 
-createAuraApp("#app", {
+const input = game.input({
+  actions: {
+    left: ["KeyA", "ArrowLeft"],
+    right: ["KeyD", "ArrowRight"],
+    jump: ["Space", "KeyW", "ArrowUp"],
+    dash: ["ShiftLeft", "ShiftRight"],
+    down: ["KeyS", "ArrowDown"],
+    reset: ["KeyR"]
+  },
+  axes: {
+    moveX: { negative: "left", positive: "right" }
+  },
+  bufferMs: 140
+});
+
+const platformer = game.platformer(level);
+const routeEvents = game.eventLog({ label: "mini game route events", maxEvents: 16 });
+const hud = game.hud.bindings([
+  game.hud.score({ valuePath: "appState.score" }),
+  game.hud.lives({ valuePath: "appState.lives" }),
+  game.hud.objective({ valuePath: "appState.objective" }),
+  game.hud.checkpoint({ valuePath: "appState.checkpoint" }),
+  game.hud.eventLog({ valuePath: "appState.events" })
+]);
+
+const app = createAuraApp("#app", {
   diagnostics: { overlay: true, performancePanel: true },
-  scene: promptPlanToScene(plan)
+  scene: buildScene()
+});
+
+const player = app.nodes.require("mini-player");
+const lift = app.nodes.require("platform-lift");
+const coins = level.collectibles.map((coin) => [coin.id, app.nodes.require(`coin-${coin.id}`)] as const);
+const checkpoint = app.nodes.require("checkpoint-mid");
+const goal = app.nodes.require("goal");
+const hudRoot = createHud();
+
+let objective = "Collect coins, avoid spikes, reach the goal";
+
+app.onFrame(({ dt }: { readonly dt: number }) => {
+  input.update(dt);
+  if (input.pressed("reset")) {
+    platformer.reset();
+    routeEvents.push({ type: "reset", label: "Route reset" });
+    objective = "Collect coins, avoid spikes, reach the goal";
+  }
+
+  const state = platformer.step(dt, {
+    moveX: input.axis("moveX"),
+    jumpPressed: input.buffered("jump"),
+    jumpHeld: input.held("jump"),
+    dashPressed: input.pressed("dash"),
+    fastFall: input.held("down")
+  });
+
+  for (const event of state.events) {
+    routeEvents.push({
+      type: event.type,
+      label: event.id ? `${event.type}:${event.id}` : event.type,
+      targetId: event.id,
+      severity: event.type === "complete" || event.type === "collect" ? "success" : event.type === "hazard" || event.type === "fall" ? "warning" : "info",
+      frame: event.frame,
+      time: event.time
+    });
+    if (event.type === "checkpoint") objective = "Checkpoint reached. Finish the route.";
+    if (event.type === "complete") objective = "Finished. Press R to replay.";
+    if (event.type === "respawn") objective = "Respawned. Take the safer route.";
+  }
+
+  player.setPosition(state.player.x, state.player.y + 0.54, 0);
+  lift.setPosition(level.movingPlatforms[0].x + level.movingPlatforms[0].width / 2, movingLiftY(state.time), 0);
+  for (const [id, node] of coins) node.setVisible(!state.collected.includes(id));
+  checkpoint.setVisible(!state.activatedCheckpoints.includes("mid"));
+  goal.setScale(state.status === "completed" ? [0.28, 1.08, 0.18] : [0.22, 0.92, 0.16]);
+
+  renderHud(state);
+  publishEvidence(state);
 });
+
+publishEvidence(platformer.snapshot());
+renderHud(platformer.snapshot());
+
+function buildScene() {
+  const nodes: AuraNodeInput[] = [
+    model(assets.playerModel, { name: "typed mini-game player", castShadow: true })
+      .position(level.start.x, level.start.y + 0.54, 0)
+      .scale(0.42)
+      .runtime(game.runtimeNode("mini-player", { tags: ["player", "typed-asset", "runtime"] })),
+    ...level.platforms.map((platform) =>
+      primitives.box({ name: `${platform.id} platform`, material: material.neon({ color: "#62d8ef", emissive: "#62d8ef", emissiveIntensity: 0.18 }) })
+        .position(platform.x + platform.width / 2, platform.y + platform.height / 2, -0.05)
+        .scale([platform.width, platform.height, 0.22])
+    ),
+    primitives.box({ name: "moving lift platform", material: material.neon({ color: "#b5f77d", emissive: "#b5f77d", emissiveIntensity: 0.35 }) })
+      .position(level.movingPlatforms[0].x + level.movingPlatforms[0].width / 2, movingLiftY(0), 0)
+      .scale([level.movingPlatforms[0].width, level.movingPlatforms[0].height, 0.22])
+      .runtime(game.runtimeNode("platform-lift", { tags: ["moving-platform", "runtime"] })),
+    ...level.collectibles.map((coin) =>
+      primitives.sphere({ name: `${coin.id} collectible`, material: material.neon({ color: "#f7d76b", emissive: "#f7d76b", emissiveIntensity: 0.7 }) })
+        .position(coin.x, coin.y, 0.02)
+        .scale(0.18)
+        .runtime(game.runtimeNode(`coin-${coin.id}`, { tags: ["coin", "runtime"] }))
+    ),
+    primitives.box({ name: "hazard spikes", material: material.neon({ color: "#f06b7a", emissive: "#f06b7a", emissiveIntensity: 0.7 }) })
+      .position(level.hazards[0].x + level.hazards[0].width / 2, level.hazards[0].y + level.hazards[0].height / 2, 0.05)
+      .scale([level.hazards[0].width, level.hazards[0].height, 0.2]),
+    primitives.box({ name: "checkpoint marker", material: material.neon({ color: "#9df59e", emissive: "#9df59e", emissiveIntensity: 0.65 }) })
+      .position(level.checkpoints[0].x, level.checkpoints[0].y + 0.42, 0.08)
+      .scale([0.14, 0.85, 0.14])
+      .runtime(game.runtimeNode("checkpoint-mid", { tags: ["checkpoint", "runtime"] })),
+    primitives.box({ name: "finish portal", material: material.neon({ color: "#ffad57", emissive: "#ffad57", emissiveIntensity: 0.82 }) })
+      .position(level.finish.x, level.finish.y + 0.7, 0.08)
+      .scale([0.22, 0.92, 0.16])
+      .runtime(game.runtimeNode("goal", { tags: ["finish", "runtime"] }))
+  ];
+
+  return scene()
+    .background("#071015")
+    .addMany(nodes)
+    .add(lights.ambient({ name: "game ambient", intensity: 0.38, color: "#d9f8ff" }))
+    .add(lights.directional({ name: "game key", position: [4, 6, 5], intensity: 1.2, color: "#ffffff" }))
+    .camera(camera.perspective({ position: [5.8, 4.3, 8.5], target: [5.8, 0.9, 0], fov: 44 }));
+}
+
+function movingLiftY(time: number): number {
+  const platform = level.movingPlatforms[0];
+  return platform.y + platform.height / 2 + Math.sin((time / platform.period) * Math.PI * 2) * platform.amplitude;
+}
+
+function createHud(): HTMLElement {
+  const root = document.createElement("aside");
+  root.id = "mini-game-hud";
+  root.style.cssText = [
+    "position:absolute",
+    "left:16px",
+    "top:16px",
+    "z-index:5",
+    "min-width:260px",
+    "font:600 13px/1.35 Inter, system-ui, sans-serif",
+    "color:#f5fbff",
+    "background:rgba(3,9,14,0.78)",
+    "border:1px solid rgba(125,220,235,0.34)",
+    "border-radius:8px",
+    "padding:12px",
+    "pointer-events:none"
+  ].join(";");
+  document.body.append(root);
+  return root;
+}
+
+function renderHud(state: ReturnType<typeof platformer.snapshot>): void {
+  hudRoot.innerHTML = [
+    `<strong>Aura3D Mini Game</strong>`,
+    `<div>Score ${state.score} | Lives ${state.lives} | Deaths ${state.deaths}</div>`,
+    `<div>Checkpoint ${state.checkpointId}</div>`,
+    `<div>${objective}</div>`,
+    `<div>Move A/D or arrows. Jump Space. Dash Shift. Reset R.</div>`
+  ].join("");
+}
+
+function publishEvidence(state: ReturnType<typeof platformer.snapshot>): void {
+  const evidence = app.evidence({
+    input,
+    events: routeEvents,
+    hud,
+    appState: {
+      score: state.score,
+      lives: state.lives,
+      objective,
+      checkpoint: state.checkpointId,
+      events: routeEvents.events().map((event: { readonly label: string }) => event.label)
+    },
+    assets: {
+      typedAssets: Object.keys(assets).length,
+      missingAssets: []
+    },
+    source: { expectsGame: true }
+  });
+  window.__AURA3D_MINI_GAME__ = {
+    status: state.status,
+    frame: state.frame,
+    score: state.score,
+    deaths: state.deaths,
+    checkpointId: state.checkpointId,
+    collected: state.collected,
+    player: {
+      x: state.player.x,
+      y: state.player.y,
+      grounded: state.player.grounded
+    },
+    events: routeEvents.events().map((event: { readonly label: string }) => event.label),
+    evidence
+  };
+}

package/templates/mini-game/tests/playable.spec.ts

@@ -0,0 +1,49 @@
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+type MiniGameState = {
+  readonly score: number;
+  readonly events: readonly string[];
+  readonly player: {
+    readonly x: number;
+    readonly y: number;
+  };
+};
+
+function readMiniGameState(): MiniGameState | undefined {
+  return (window as unknown as { readonly __AURA3D_MINI_GAME__?: MiniGameState }).__AURA3D_MINI_GAME__;
+}
+
+test("Aura3D mini game responds to keyboard input, scoring, and reset", async ({ page }) => {
+  await page.goto("/");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_000 }).toBe("true");
+
+  const initial = await page.evaluate(readMiniGameState);
+  expect(initial?.player.x).toBeLessThan(0.2);
+
+  await page.keyboard.down("ArrowRight");
+  await page.waitForTimeout(650);
+  await page.keyboard.up("ArrowRight");
+
+  const moved = await page.evaluate(readMiniGameState);
+  expect(moved?.player.x ?? 0).toBeGreaterThan((initial?.player.x ?? 0) + 1.2);
+
+  await page.keyboard.press("Space");
+  await page.waitForTimeout(180);
+  const jumped = await page.evaluate(readMiniGameState);
+  expect(jumped?.player.y ?? 0).toBeGreaterThan(moved?.player.y ?? 0);
+
+  await page.keyboard.down("ArrowRight");
+  await page.waitForTimeout(1600);
+  await page.keyboard.up("ArrowRight");
+  const progressed = await page.evaluate(readMiniGameState);
+  expect(progressed?.score ?? 0).toBeGreaterThanOrEqual(50);
+  expect(progressed?.events.length ?? 0).toBeGreaterThan(0);
+
+  await page.keyboard.press("KeyR");
+  await page.waitForTimeout(120);
+  const reset = await page.evaluate(readMiniGameState);
+  expect(reset?.player.x ?? 99).toBeLessThan(0.3);
+  expect(reset?.events.some((event) => event.includes("reset"))).toBe(true);
+});

package/templates/mini-game/tests/screenshot.spec.ts

@@ -4,60 +4,65 @@ import { expect, test } from "@playwright/test";
 
 test.setTimeout(60_000);
 
-test("Aura3D mini game screenshot shows a playable collect-and-dodge scene", async ({ page }) => {
+test("Aura3D mini game screenshot shows a readable playable scene", async ({ page }) => {
   await page.goto("/");
   await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_000 }).toBe("true");
+
+  await page.keyboard.down("ArrowRight");
+  await page.waitForTimeout(550);
+  await page.keyboard.up("ArrowRight");
+
+  const state = await page.evaluate(() =>
+    (window as unknown as {
+      readonly __AURA3D_MINI_GAME__?: {
+        readonly score: number;
+        readonly player: { readonly x: number };
+      };
+    }).__AURA3D_MINI_GAME__
+  );
+  expect(state?.player.x ?? 0).toBeGreaterThan(0.8);
+
   const canvas = page.locator("canvas");
   const profile = await canvas.evaluate((element) => {
     const target = element as HTMLCanvasElement;
     const gl = target.getContext("webgl2", { preserveDrawingBuffer: true });
-    if (!gl) return { error: "missing-webgl2", robotArmorPixels: 0, robotJointPixels: 0, boostPixels: 0, coinPixels: 0, hazardPixels: 0, portalPixels: 0, cyanTrailPixels: 0, arenaPixels: 0, uniqueBuckets: 0 };
+    if (!gl) return { error: "missing-webgl2", brightPixels: 0, warmPixels: 0, cyanPixels: 0, redPixels: 0, uniqueBuckets: 0 };
     const pixels = new Uint8Array(target.width * target.height * 4);
     gl.readPixels(0, 0, target.width, target.height, gl.RGBA, gl.UNSIGNED_BYTE, pixels);
     const buckets = new Set<string>();
-    let robotArmorPixels = 0;
-    let robotJointPixels = 0;
-    let boostPixels = 0;
-    let coinPixels = 0;
-    let hazardPixels = 0;
-    let portalPixels = 0;
-    let cyanTrailPixels = 0;
-    let arenaPixels = 0;
+    let brightPixels = 0;
+    let warmPixels = 0;
+    let cyanPixels = 0;
+    let redPixels = 0;
     for (let y = 0; y < target.height; y += 4) {
       for (let x = 0; x < target.width; x += 4) {
-        if (x > target.width * 0.76 && y > target.height * 0.74) continue;
         const offset = (y * target.width + x) * 4;
         const r = pixels[offset] ?? 0;
         const g = pixels[offset + 1] ?? 0;
         const b = pixels[offset + 2] ?? 0;
         const luminance = r * 0.2126 + g * 0.7152 + b * 0.0722;
-        if (luminance > 32) buckets.add(`${r >> 5}-${g >> 5}-${b >> 5}`);
-        const inPlayerWindow = x > target.width * 0.2 && x < target.width * 0.42 && y > target.height * 0.34 && y < target.height * 0.7;
-        if (inPlayerWindow && r > 120 && g > 118 && b > 86 && Math.abs(r - g) < 70) robotArmorPixels += 1;
-        if (inPlayerWindow && r < 95 && g < 115 && b < 125 && luminance > 18) robotJointPixels += 1;
-        if (inPlayerWindow && r > 150 && g > 80 && b < 82) boostPixels += 1;
-        if (r > 170 && g > 130 && b < 110) coinPixels += 1;
-        if (r > 165 && g < 125 && b < 145) hazardPixels += 1;
-        if (r > 165 && g > 95 && b < 125) portalPixels += 1;
-        if (g > 140 && b > 150 && r < 150) cyanTrailPixels += 1;
-        if (g > 42 && b > 50 && b > r * 1.08 && luminance > 24 && luminance < 100) arenaPixels += 1;
+        if (luminance > 30) {
+          brightPixels += 1;
+          buckets.add(`${r >> 5}-${g >> 5}-${b >> 5}`);
+        }
+        if (r > 150 && g > 110 && b < 110) warmPixels += 1;
+        if (g > 120 && b > 130 && r < 150) cyanPixels += 1;
+        if (r > 145 && g < 115 && b < 140) redPixels += 1;
       }
     }
-    return { robotArmorPixels, robotJointPixels, boostPixels, coinPixels, hazardPixels, portalPixels, cyanTrailPixels, arenaPixels, uniqueBuckets: buckets.size };
+    return { brightPixels, warmPixels, cyanPixels, redPixels, uniqueBuckets: buckets.size };
   });
+
   const screenshot = await page.screenshot({ fullPage: false });
   mkdirSync(resolve("tests/reports"), { recursive: true });
   writeFileSync(resolve("tests/reports/screenshot.png"), screenshot);
-  writeFileSync(resolve("tests/reports/screenshot.json"), `${JSON.stringify({ bytes: screenshot.byteLength, profile }, null, 2)}\n`);
+  writeFileSync(resolve("tests/reports/screenshot.json"), `${JSON.stringify({ bytes: screenshot.byteLength, profile, state }, null, 2)}\n`);
+
   expect(profile.error).toBeUndefined();
-  expect(profile.robotArmorPixels).toBeGreaterThan(90);
-  expect(profile.robotJointPixels).toBeGreaterThan(18);
-  expect(profile.boostPixels).toBeGreaterThan(8);
-  expect(profile.coinPixels).toBeGreaterThan(35);
-  expect(profile.hazardPixels).toBeGreaterThan(45);
-  expect(profile.portalPixels).toBeGreaterThan(45);
-  expect(profile.cyanTrailPixels).toBeGreaterThan(90);
-  expect(profile.arenaPixels).toBeGreaterThan(600);
-  expect(profile.uniqueBuckets).toBeGreaterThan(22);
+  expect(profile.brightPixels).toBeGreaterThan(900);
+  expect(profile.cyanPixels).toBeGreaterThan(20);
+  expect(profile.warmPixels).toBeGreaterThan(10);
+  expect(profile.redPixels).toBeGreaterThan(5);
+  expect(profile.uniqueBuckets).toBeGreaterThan(10);
   expect(screenshot.byteLength).toBeGreaterThan(1000);
 });