create-aura3d 1.0.5

package/templates/cinematic-scene/tests/screenshot.spec.ts

@@ -0,0 +1,56 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { expect, test } from "@playwright/test";
+
+test.setTimeout(60_000);
+
+test("Aura3D cinematic scene screenshot shows the rainy neon hero prompt", async ({ page }) => {
+  await page.goto("/");
+  await expect.poll(() => page.locator("body").getAttribute("data-aura3d-ready"), { timeout: 45_000 }).toBe("true");
+  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", cyanPixels: 0, amberPixels: 0, rainPixels: 0, wetReflectionPixels: 0, centerHeroPixels: 0, darkAlleyPixels: 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 cyanPixels = 0;
+    let amberPixels = 0;
+    let rainPixels = 0;
+    let wetReflectionPixels = 0;
+    let centerHeroPixels = 0;
+    let darkAlleyPixels = 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 > 30) buckets.add(`${r >> 5}-${g >> 5}-${b >> 5}`);
+        if (b > 110 && g > 90 && b > r * 1.22) cyanPixels += 1;
+        if (r > 160 && g > 105 && b < 125) amberPixels += 1;
+        if (r > 165 && g > 185 && b > 205) rainPixels += 1;
+        if (y < target.height * 0.36 && ((b > 95 && g > 65 && b > r * 1.12) || (r > 105 && g > 62 && b < 95))) wetReflectionPixels += 1;
+        if (x > target.width * 0.32 && x < target.width * 0.68 && y > target.height * 0.26 && y < target.height * 0.78 && luminance > 75) centerHeroPixels += 1;
+        if (luminance > 8 && luminance < 36 && b >= r && x > target.width * 0.08 && x < target.width * 0.92) darkAlleyPixels += 1;
+      }
+    }
+    return { cyanPixels, amberPixels, rainPixels, wetReflectionPixels, centerHeroPixels, darkAlleyPixels, 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`);
+  expect(profile.error).toBeUndefined();
+  expect(profile.cyanPixels).toBeGreaterThan(320);
+  expect(profile.amberPixels).toBeGreaterThan(20);
+  expect(profile.rainPixels).toBeGreaterThan(90);
+  expect(profile.wetReflectionPixels).toBeGreaterThan(60);
+  expect(profile.centerHeroPixels).toBeGreaterThan(600);
+  expect(profile.darkAlleyPixels).toBeGreaterThan(180);
+  expect(profile.uniqueBuckets).toBeGreaterThan(22);
+  expect(screenshot.byteLength).toBeGreaterThan(1000);
+});

package/templates/cinematic-scene/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true,
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "strict": true
+  },
+  "include": ["src", "tests", "playwright.config.ts"]
+}

package/templates/fighting-game/README.md

@@ -0,0 +1,64 @@
+# Aura3D fighting-game template
+
+This template demonstrates Aura3D's public game runtime APIs:
+
+- `createAuraApp(...)` for one mounted Aura app.
+- `.runtime(game.runtimeNode("id"))` for mutable fighter and camera nodes.
+- `app.input(...)` for app-owned keyboard/gamepad input.
+- `game.inputReplay(...)` and `game.inputReplayDriver(...)` for deterministic replay smoke paths.
+- `game.kinematicBody(...)` and `game.jumpAssist(...)` for 2.5D movement, gravity, coyote time, jump buffering, dash, and knockback.
+- `game.combatWorld(...)` for hitboxes, hurtboxes, guard, hit-stop, stun, recovery, and typed combat events.
+- `AnimationController` bound to runtime nodes for public animation clip switching and pose-baked fallback declarations.
+- `game.effects(...)`, `game.cameraDirector(...)`, and `game.debug.overlay(...)` for hit sparks, impact shake, zoom, colliders, and runtime evidence.
+- `games.fighting.stagePreset(...)` and `games.fighting.validateStage(...)` for fighting-stage source, safe zones, combat bounds, and readiness warnings.
+- `game.hud.*`, `game.accessibility.*`, and `ui.*` helpers for HUD, controls, and a11y evidence.
+- `game.evidence(app, ...)` for proving the route is using runtime systems instead of a static scene.
+
+## Source layout
+
+- `src/main.ts` mounts the route, owns frame updates, and publishes `window.__AURA3D_GAME_*` evidence objects.
+- `src/game/fighters.ts` owns typed fighter asset resolution, runtime fighter nodes, and animation controller setup.
+- `src/game/moves.ts` owns combat move declarations and hitbox source.
+- `src/game/stage.ts` owns `games.fighting` stage helpers, touch controls, debug colliders, and route/build readiness declarations.
+- `src/aura-assets.ts` is the typed asset manifest generated by the Aura3D CLI.
+
+The scaffold does not ship invented fighter GLBs or raw model URLs. It starts
+with Aura3D runtime-node source placeholders so the route is playable and the
+combat systems are inspectable. Add real fighter assets through the Aura3D CLI
+to switch the placeholders to typed `model(assets.playerFighter)` and
+`model(assets.rivalFighter)` nodes automatically.
+
+Controls:
+
+- Move: `A/D` or arrow keys.
+- Jump: `W`, `ArrowUp`, or `Space`.
+- Guard: `Q`.
+- Dash: `Shift`.
+- Light: `J`.
+- Heavy: `K`.
+- Special: `L`.
+- Pause: `Escape` or the HUD pause button.
+- Replay: HUD replay button.
+
+Add fighter assets:
+
+```bash
+npx @aura3d/cli@latest assets add ./assets/player-fighter.glb --name playerFighter
+npx @aura3d/cli@latest assets add ./assets/rival-fighter.glb --name rivalFighter
+```
+
+The CLI writes typed definitions to `src/aura-assets.ts`. The starter imports
+`assets` from `./aura-assets` and only calls `model(...)` with those typed asset
+refs. Do not use string asset ids, three.js loaders, `GLTFLoader`, raw GLB URLs,
+or `unsafeModelUrl(...)`.
+
+Before claiming the route is asset-ready, run:
+
+```bash
+npx @aura3d/cli@latest assets validate-game
+```
+
+The source-level readiness declaration in `src/game/stage.ts` is not launch
+evidence. Before claiming build, package, visual, accessibility, or launch
+readiness, archive the matching command output, runtime evidence JSON,
+browser screenshot, and review result.

package/templates/fighting-game/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Aura3D Fighting Game Runtime</title>
+  </head>
+  <body>
+    <div id="app" aria-label="Aura3D fighting game viewport"></div>
+    <div id="hud" class="hud" role="region" aria-label="Fighting game status and controls" aria-live="polite"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/fighting-game/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "aura3d-fighting-game",
+  "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/route-health.spec.ts tests/gameplay-smoke.spec.ts --workers=1"
+  },
+  "dependencies": {
+    "@aura3d/engine": "1.0.5"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.52.0",
+    "typescript": "^5.8.3",
+    "vite": "^7.3.2"
+  }
+}

package/templates/fighting-game/playwright.config.ts

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

package/templates/fighting-game/src/aura-assets.ts

@@ -0,0 +1,11 @@
+import { defineAuraAssets } from "@aura3d/engine";
+
+export const assets = defineAuraAssets({
+  /*
+   * Add your own fighter GLBs with the Aura3D CLI, then keep these generated
+   * keys so src/main.ts can switch from source placeholders to typed models:
+   *
+   * npx @aura3d/cli@latest assets add ./assets/player-fighter.glb --name playerFighter
+   * npx @aura3d/cli@latest assets add ./assets/rival-fighter.glb --name rivalFighter
+   */
+});

package/templates/fighting-game/src/game/fighters.ts

@@ -0,0 +1,152 @@
+import {
+  AnimationController,
+  type AuraAssetRef,
+  type AuraNamedAnimationClipDefinition,
+  game,
+  material,
+  model,
+  primitives
+} from "@aura3d/engine";
+
+export type FighterId = "player" | "rival";
+export type FighterAssetKey = "playerFighter" | "rivalFighter";
+export type FighterClip = "idle" | "walk" | "jump" | "dash" | "guard" | "light" | "heavy" | "special" | "hitstun";
+
+export type TypedFighterAssets = Partial<Record<FighterAssetKey, AuraAssetRef<"model">>>;
+
+export interface ResolvedFighterAssets {
+  readonly typedFighterAssets: TypedFighterAssets;
+  readonly missingFighterAssets: readonly FighterAssetKey[];
+  readonly typedFighterAssetCount: number;
+}
+
+export const REQUIRED_FIGHTER_ASSETS: readonly FighterAssetKey[] = ["playerFighter", "rivalFighter"];
+export const REQUIRED_FIGHTER_CLIPS: readonly FighterClip[] = [
+  "idle",
+  "walk",
+  "jump",
+  "dash",
+  "guard",
+  "light",
+  "heavy",
+  "special",
+  "hitstun"
+];
+
+export const publicAssetInstructions = [
+  "npx @aura3d/cli@latest assets add ./assets/player-fighter.glb --name playerFighter",
+  "npx @aura3d/cli@latest assets add ./assets/rival-fighter.glb --name rivalFighter",
+  "npx @aura3d/cli@latest assets validate-game"
+] as const;
+
+export const fighterAnimationClips: readonly AuraNamedAnimationClipDefinition<FighterClip>[] = REQUIRED_FIGHTER_CLIPS.map((id) => ({
+  id,
+  duration: animationDuration(id),
+  frameRate: 60,
+  loop: id === "idle" || id === "walk" || id === "guard" || id === "jump",
+  layer: animationLayer(id),
+  layerMetadata: {
+    id: animationLayer(id),
+    role: id === "light" || id === "heavy" || id === "special" ? "attack" : "base",
+    bodyMask: id === "light" || id === "heavy" || id === "special" ? "upper-body" : "full-body",
+    restartFromFrameZero: id === "light" || id === "heavy" || id === "special" || id === "dash"
+  },
+  restartFromFrameZero: id === "light" || id === "heavy" || id === "special" || id === "dash",
+  suppressRootMotion: true,
+  attack: id === "light" || id === "heavy" || id === "special",
+  tracks: [],
+  metadata: {
+    source: "fighting-game-template-pose-fallback",
+    poseBakedFallback: true,
+    suppressRootMotion: true,
+    templateReadiness: "source-only"
+  }
+}));
+
+export function resolveTypedFighterAssets(assetManifest: TypedFighterAssets): ResolvedFighterAssets {
+  const typedFighterAssets: TypedFighterAssets = {
+    playerFighter: assetManifest.playerFighter,
+    rivalFighter: assetManifest.rivalFighter
+  };
+  const missingFighterAssets = REQUIRED_FIGHTER_ASSETS.filter((key) => !typedFighterAssets[key]);
+  return {
+    typedFighterAssets,
+    missingFighterAssets,
+    typedFighterAssetCount: REQUIRED_FIGHTER_ASSETS.length - missingFighterAssets.length
+  };
+}
+
+export function createFighterAnimationController(
+  id: FighterId,
+  asset?: AuraAssetRef<"model">
+): AnimationController<FighterClip> {
+  return new AnimationController<FighterClip>({
+    id: `${id}-animation-controller`,
+    ...(asset ? { clipRegistry: asset } : {}),
+    clips: fighterAnimationClips,
+    requiredClips: REQUIRED_FIGHTER_CLIPS,
+    suppressRootMotion: true,
+    layers: [
+      { id: "base", role: "base", bodyMask: "full-body" },
+      { id: "upper-body", role: "attack", bodyMask: "upper-body", restartFromFrameZero: true }
+    ]
+  });
+}
+
+export function createFighterNode(
+  id: FighterId,
+  assetKey: FighterAssetKey,
+  label: string,
+  position: readonly [number, number, number],
+  facing: 1 | -1,
+  color: string,
+  typedFighterAssets: TypedFighterAssets
+) {
+  const asset = typedFighterAssets[assetKey];
+  const runtime = game.runtimeNode(id, {
+    tags: ["fighter", id, asset ? "typed-asset" : "source-placeholder"]
+  });
+
+  if (asset) {
+    return model(asset, { name: label })
+      .position(position[0], position[1], position[2])
+      .rotate(0, facing < 0 ? Math.PI : 0, 0)
+      .scale(0.72)
+      .runtime(runtime);
+  }
+
+  return primitives
+    .capsule({
+      name: `${label} source placeholder - add ${assetKey} with the Aura3D CLI`,
+      material: material.pbr({ color, roughness: 0.62 })
+    })
+    .position(position[0], position[1] + 0.82, position[2])
+    .rotate(0, facing < 0 ? Math.PI : 0, 0)
+    .scale([0.34, 0.74, 0.34])
+    .runtime(runtime);
+}
+
+export function isLoopingFighterClip(clip: FighterClip): boolean {
+  return clip === "idle" || clip === "walk" || clip === "guard" || clip === "jump";
+}
+
+export function animationLayer(clip: FighterClip): "base" | "upper-body" {
+  return clip === "light" || clip === "heavy" || clip === "special" ? "upper-body" : "base";
+}
+
+function animationDuration(clip: FighterClip): number {
+  switch (clip) {
+    case "light":
+      return 0.28;
+    case "heavy":
+      return 0.46;
+    case "special":
+      return 0.72;
+    case "dash":
+      return 0.22;
+    case "hitstun":
+      return 0.34;
+    default:
+      return 1;
+  }
+}

package/templates/fighting-game/src/game/moves.ts

@@ -0,0 +1,70 @@
+export type FighterFacing = 1 | -1;
+
+export function lightMove(id: string, facing: FighterFacing) {
+  return {
+    id,
+    name: "Template Light Strike",
+    damage: 7,
+    guardDamage: 3,
+    hitStop: 0.08,
+    hitStun: 0.22,
+    blockStun: 0.12,
+    recovery: 0.18,
+    activeFrames: [2, 8] as const,
+    durationFrames: 18,
+    knockback: [facing * 1.8, 0.5, 0] as const,
+    hitboxes: [
+      {
+        id: "jab",
+        offset: [facing * 0.68, 0.82, 0] as const,
+        size: [0.86, 0.45, 0.45] as const
+      }
+    ]
+  };
+}
+
+export function heavyMove(id: string, facing: FighterFacing) {
+  return {
+    id,
+    name: "Template Heavy Breaker",
+    damage: 13,
+    guardDamage: 8,
+    hitStop: 0.12,
+    hitStun: 0.34,
+    blockStun: 0.18,
+    recovery: 0.32,
+    activeFrames: [4, 12] as const,
+    durationFrames: 28,
+    knockback: [facing * 2.5, 0.8, 0] as const,
+    hitboxes: [
+      {
+        id: "heavy",
+        offset: [facing * 0.78, 0.92, 0] as const,
+        size: [1.08, 0.6, 0.52] as const
+      }
+    ]
+  };
+}
+
+export function specialMove(id: string, facing: FighterFacing) {
+  return {
+    id,
+    name: "Template Aura Burst",
+    damage: 18,
+    guardDamage: 12,
+    hitStop: 0.16,
+    hitStun: 0.42,
+    blockStun: 0.24,
+    recovery: 0.46,
+    activeFrames: [3, 18] as const,
+    durationFrames: 42,
+    knockback: [facing * 3.2, 1.1, 0] as const,
+    hitboxes: [
+      {
+        id: "aura-burst",
+        offset: [facing * 0.86, 0.95, 0] as const,
+        size: [1.8, 0.85, 0.65] as const
+      }
+    ]
+  };
+}

package/templates/fighting-game/src/game/stage.ts

@@ -0,0 +1,98 @@
+import { game, games } from "@aura3d/engine";
+import { publicAssetInstructions, REQUIRED_FIGHTER_ASSETS, REQUIRED_FIGHTER_CLIPS } from "./fighters";
+
+type GameVec3 = readonly [number, number, number];
+
+export const fightingControls = games.fighting.controls();
+export const fightingStage = games.fighting.stagePreset("neon-dojo", {
+  id: "fighting-template-arena",
+  width: 7.6,
+  depth: 2.5,
+  safeInset: 0.48
+});
+export const fightingStageIssues = games.fighting.validateStage(fightingStage);
+
+export const fightingStageBounds = {
+  minX: fightingStage.combatBounds.minX,
+  maxX: fightingStage.combatBounds.maxX,
+  minY: fightingStage.combatBounds.minY,
+  maxY: fightingStage.combatBounds.maxY,
+  minZ: fightingStage.combatBounds.minZ,
+  maxZ: fightingStage.combatBounds.maxZ
+};
+
+export const fightingRouteReadiness = {
+  kind: "aura3d-fighting-game-route-readiness",
+  sourceOnly: true,
+  template: "fighting-game",
+  route: "/",
+  packageName: "aura3d-fighting-game",
+  entry: "src/main.ts",
+  sourceFiles: ["src/main.ts", "src/aura-assets.ts", "src/game/fighters.ts", "src/game/moves.ts", "src/game/stage.ts"],
+  publicEngineApis: [
+    "createAuraApp",
+    "scene",
+    "model(typed AuraAssetRef)",
+    "game.runtimeNode",
+    "app.onFrame",
+    "app.input",
+    "game.evidence",
+    "game.kinematicBody",
+    "game.jumpAssist",
+    "game.combatWorld",
+    "AnimationController",
+    "game.effects",
+    "game.cameraDirector",
+    "games.fighting.stagePreset",
+    "games.fighting.validateStage",
+    "game.hud",
+    "game.accessibility",
+    "game.debug.overlay"
+  ],
+  requiredTypedAssets: REQUIRED_FIGHTER_ASSETS,
+  requiredAnimationClips: REQUIRED_FIGHTER_CLIPS,
+  assetCommands: publicAssetInstructions,
+  buildDeclarations: {
+    routeHealthSpec: "tests/route-health.spec.ts",
+    gameplaySmokeSpec: "tests/gameplay-smoke.spec.ts",
+    localCommandsNotRunByTemplate: ["npm run typecheck", "npm run build", "npm run test"],
+    evidenceRequiredBeforeLaunchReady: [
+      "npx @aura3d/cli@latest assets validate-game output",
+      "npm run test scaffold output proving route load and replay hit",
+      "browser screenshot showing a typed GLB fighter moved by runtime node mutation",
+      "archived collectGameRuntimeEvidence/app.evidence JSON under tests/reports/game-runtime/",
+      "human or automated visual/accessibility approval"
+    ]
+  },
+  stage: {
+    id: fightingStage.id,
+    safeZone: fightingStage.safeZone,
+    combatBounds: fightingStage.combatBounds,
+    validationIssues: fightingStageIssues.map((issue) => ({
+      severity: issue.severity,
+      code: issue.code,
+      message: issue.message
+    }))
+  }
+} as const;
+
+export function createFighterColliders(playerPosition: GameVec3, rivalPosition: GameVec3) {
+  return [
+    game.collider.capsule({ id: "player-body", center: playerPosition, radius: 0.34, height: 1.7, tags: ["fighter", "player"] }),
+    game.collider.capsule({ id: "rival-body", center: rivalPosition, radius: 0.34, height: 1.7, tags: ["fighter", "rival"] })
+  ];
+}
+
+export function createTouchLayout(width: number, height: number) {
+  return game.touchControls({
+    width,
+    height,
+    buttons: [
+      { action: "jump", label: "Jump", binding: "TouchJump" },
+      { action: "guard", label: "Guard", binding: "TouchGuard" },
+      { action: "light", label: "Light", binding: "TouchLight" },
+      { action: "heavy", label: "Heavy", binding: "TouchHeavy" },
+      { action: "special", label: "Special", binding: "TouchSpecial" }
+    ]
+  });
+}