# Aura3D fighting-game template

This template demonstrates Aura3D's public game runtime APIs:

- `createGameApp(...)` for one mounted Aura game app with lifecycle evidence.
- `.runtime(game.runtimeNode("id"))` for mutable fighter and camera nodes.
- `gameApp.input` / `gameApp.inputController(...)` for runtime-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 search "animated humanoid fighting character" --profile fighting-character --json
npx @aura3d/cli@latest assets resolve "animated humanoid fighting character" --name playerFighter --profile fighting-character
npx @aura3d/cli@latest assets resolve "animated humanoid fighting character" --name rivalFighter --profile fighting-character
```

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 --profile fighting-character --json
```

If the catalog returns no production-ready fighting-character candidate, keep
the route in placeholder mode and do not invent a GLB URL. The refusal is a
valid safety result; production proof requires two distinct typed fighter
assets that pass the profile gate.

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.

## Real-asset crossfade path

The fighter `AnimationController` in `src/game/fighters.ts` is already configured for real,
crossfaded animation once typed GLB fighters are supplied:

- Required clips per fighter (`REQUIRED_FIGHTER_CLIPS`): `idle`, `walk`, `run`, `air`, `down`,
  `guard`, `light`, `heavy`, `special`, `hurt`, `hitstun`. Resolve a fighter whose embedded GLB
  clips cover these (`assets resolve ... --profile fighting-character`), then map them in
  `src/aura-assets.ts`.
- The controller uses two layers — `base` (full-body locomotion) and `upper-body` (attacks,
  `restartFromFrameZero`) — so locomotion state changes can crossfade instead of snapping. With
  real assets the controller drives those clips; with no asset it falls back to labeled capsule
  placeholders and the route proof reports `proofMode: "source-placeholders"` (vs `"typed-assets"`).
- For the deployed reference of crossfade-on-state-change driven from the engine combat world, see
  `apps/aura-clash-showcase` (`AuraClashArenaApp` `applyFighterAnimation`).