create-aura3d 1.3.2 → 1.4.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 > 130 && g > 105 && b < 155 && r >= g * 0.9) warmPixels += 1;
+        if (g > 115 && b > 105 && r < 190 && b >= r * 0.78) cyanPixels += 1;
+        if (r > 120 && g < 150 && b < 180 && r > g * 1.03) 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);
 });

package/templates/product-viewer/package.json

@@ -11,7 +11,7 @@
     "test": "playwright test tests/route-health.spec.ts tests/screenshot.spec.ts --workers=1"
   },
   "dependencies": {
-    "@aura3d/engine": "1.3.2"
+    "@aura3d/engine": "1.3.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.52.0",

package/templates/product-viewer/tests/screenshot.spec.ts

@@ -31,8 +31,8 @@ test("Aura3D product viewer screenshot shows a prompt-aligned studio product", a
         if (luminance > 32) buckets.add(`${r >> 5}-${g >> 5}-${b >> 5}`);
         const inProductWindow = x > target.width * 0.34 && x < target.width * 0.68 && y > target.height * 0.24 && y < target.height * 0.78;
         if (inProductWindow && r > 145 && g > 145 && b > 138 && Math.abs(r - g) < 32 && Math.abs(g - b) < 40) metalPixels += 1;
-        if (r > 95 && g > 62 && b < 78 && r > g * 1.12) warmAccentPixels += 1;
-        if (Math.max(r, g, b) - Math.min(r, g, b) > 45 && luminance > 42) saturatedStudioPixels += 1;
+        if (r > 70 && g > 45 && b < 120 && r >= g && g >= b * 0.75) warmAccentPixels += 1;
+        if (Math.max(r, g, b) - Math.min(r, g, b) > 32 && luminance > 38) saturatedStudioPixels += 1;
         if (inProductWindow && luminance > 32) centerObjectPixels += 1;
       }
     }
@@ -44,9 +44,9 @@ test("Aura3D product viewer screenshot shows a prompt-aligned studio product", a
   writeFileSync(resolve("tests/reports/screenshot.json"), `${JSON.stringify({ bytes: screenshot.byteLength, profile }, null, 2)}\n`);
   expect(profile.error).toBeUndefined();
   expect(profile.metalPixels).toBeGreaterThan(5);
-  expect(profile.warmAccentPixels).toBeGreaterThan(20);
+  expect(profile.warmAccentPixels).toBeGreaterThan(8);
   expect(profile.centerObjectPixels).toBeGreaterThan(650);
-  expect(profile.saturatedStudioPixels).toBeGreaterThan(900);
+  expect(profile.saturatedStudioPixels).toBeGreaterThan(800);
   expect(profile.uniqueBuckets).toBeGreaterThan(18);
   expect(screenshot.byteLength).toBeGreaterThan(1000);
 });

package/templates/prompt-animation-channel/package.json

@@ -11,7 +11,7 @@
     "test": "playwright test tests/route-health.spec.ts tests/storyboard-playback.spec.ts --workers=1"
   },
   "dependencies": {
-    "@aura3d/engine": "1.3.2"
+    "@aura3d/engine": "1.3.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.52.0",

package/templates/prompt-animation-channel/tests/screenshot.spec.ts

@@ -0,0 +1,15 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+test("Aura3D prompt animation channel screenshot shows content", async ({ page }) => {
+  await page.goto("/");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_000 }).toBe("true");
+  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 }, null, 2)}\n`);
+  expect(screenshot.byteLength).toBeGreaterThan(1000);
+});

package/templates/racing-starter/README.md

@@ -0,0 +1,27 @@
+# Aura3D Racing Starter
+
+Keyboard-playable racing starter using only the public `@aura3d/engine` API.
+
+Status: source-level prototype starter, not a public-quality racing game claim.
+It proves input, route progress, checkpoints, lap/reset state, and deployable
+source structure. It does not prove that an arbitrary track GLB has certified
+road topology, car-to-road binding, camera-safe race composition, or public
+visual quality.
+
+- Typed vehicle and track assets are defined in `src/aura-assets.ts`.
+- `game.racing(...)` owns route progress, throttle, steering, drift, checkpoint,
+  lap, reset, and camera proof state.
+- `tests/playable.spec.ts` drives keyboard input and verifies checkpoint/lap
+  progression.
+
+Run:
+
+```bash
+npm install
+npm run dev
+npm test
+```
+
+Before presenting a generated racing route as a public example, add retained
+racing topology evidence, prove the car is visibly bound to the road surface,
+capture a readable public screenshot, and pass visual review.

package/templates/racing-starter/index.html

@@ -0,0 +1,23 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Aura3D Racing Starter</title>
+    <style>
+      html,
+      body,
+      #app {
+        width: 100%;
+        height: 100%;
+        margin: 0;
+        overflow: hidden;
+        background: #05090c;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./src/main.ts"></script>
+  </body>
+</html>

package/templates/racing-starter/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "aura3d-racing-starter",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1",
+    "typecheck": "tsc --noEmit",
+    "build": "npm run typecheck && vite build",
+    "preview": "vite preview --host 127.0.0.1",
+    "test": "playwright test tests/playable.spec.ts --workers=1"
+  },
+  "dependencies": {
+    "@aura3d/engine": "1.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.52.0",
+    "typescript": "^5.8.3",
+    "vite": "^7.3.2"
+  }
+}

package/templates/racing-starter/playwright.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  webServer: {
+    command: "npm run dev -- --port 5178",
+    url: "http://127.0.0.1:5178",
+    reuseExistingServer: !process.env.CI
+  },
+  use: {
+    baseURL: "http://127.0.0.1:5178"
+  }
+});

package/templates/racing-starter/public/aura-assets/showcaseCleanSportsCar.thumb.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 180"><rect width="320" height="180" fill="#101720"/><path d="M80 126 160 46l80 80-80 28z" fill="#77a7ff"/><text x="160" y="160" text-anchor="middle" font-family="Arial" font-size="18" fill="#f4f7fb">showcaseCleanSportsCar 3.455x3.428x2.206</text></svg>

package/templates/racing-starter/public/aura-assets/showcaseReadableKartCircuit.thumb.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 180"><rect width="320" height="180" fill="#101720"/><path d="M80 126 160 46l80 80-80 28z" fill="#77a7ff"/><text x="160" y="160" text-anchor="middle" font-family="Arial" font-size="18" fill="#f4f7fb">showcaseReadableKartCircuit 24.651x24.647x2.073</text></svg>

package/templates/racing-starter/src/aura-assets.ts

@@ -0,0 +1,36 @@
+import { defineAuraAssets } from "@aura3d/engine";
+
+export const assets = defineAuraAssets({
+  carModel: {
+    type: "model",
+    format: "glb",
+    url: "/aura-assets/showcaseCleanSportsCar.1c69283f.glb",
+    bounds: [3.455, 3.428, 2.206],
+    hash: "sha256-1c69283fa2b3fb96b3dc3418f2d0dede842e6984f1776a8ca00b099836fc9c14",
+    metadata: {
+      materials: ["Material.001", "Material.002", "Material.003", "Material.004"],
+      animations: [],
+      textures: [],
+      license: "CC-BY-4.0",
+      author: "JUFF",
+      sourcePage: "https://huggingface.co/datasets/allenai/objaverse/blob/main/glbs/000-008/23dfdeb55dc24970b36065afaab7a8a5.glb",
+      thumbnailUrl: "/aura-assets/showcaseCleanSportsCar.thumb.svg"
+    }
+  },
+  trackModel: {
+    type: "model",
+    format: "glb",
+    url: "/aura-assets/showcaseReadableKartCircuit.5cbb912e.glb",
+    bounds: [24.651, 24.647, 2.073],
+    hash: "sha256-5cbb912e511e5e82363c347210096d59dd3007db12c363fd0c9f07919f5ebbd0",
+    metadata: {
+      materials: ["LINEAS", "gris", "verde", "rojo", "azul", "amarillo"],
+      animations: [],
+      textures: [],
+      license: "CC-BY-4.0",
+      author: "Puendiz",
+      sourcePage: "https://huggingface.co/datasets/allenai/objaverse/blob/main/glbs/000-034/2fc89fcd8c034bc9ba05eac24c9bf537.glb",
+      thumbnailUrl: "/aura-assets/showcaseReadableKartCircuit.thumb.svg"
+    }
+  }
+} as const);