@aura3d/cli 3.0.1 → 4.0.2

package/skills/aura3d-art-direction/references/look-recipes.md

@@ -0,0 +1,32 @@
+# Look recipes — 13 genre rows
+
+One row per genre. Use the row's look id verbatim, take its camera/framing/palette
+as the starting point, then iterate in the look-dev loop. Palettes: 3 base tones +
+1 accent, no pure primaries. Key = sun position `elevation°`/`azimuth°`. Subject %
+is the subject's share of frame height.
+
+| Genre | Look | Camera rig + fov | Subject % | Key | Palette | Atmosphere | Post | VFX | Reference frames |
+|---|---|---|---|---|---|---|---|---|---|
+| platformer | `outdoor-day` | `follow` (side-on), fov 50 | 18–25 | 48° / 35° (3/4 front) | saturated greens, sky blue, warm wood + coin gold | fog 0.0025 | `daylight-outdoor` | coin sparkle, land dust | `webgl_animation_skinning_blending` |
+| racing | `golden-hour` | `chase`, fov 60 | 15–25 | 12° / 35° (low sun) | warm asphalt, burnt orange, charcoal + headlight amber | fog 30–180 m | `cinematic-film` | brake glow, speed dust | `webgl_materials_car` |
+| fighting | `arena-fight` | `follow` (side-on), fov 45 | 20–30 (pair) | top spot 60° / 0° | arena dark, rope colour, crowd shadow + spotlight rim | haze cone | `arena-fight` | hit sparks, knockback flash | `webgl_animation_skinning_morph` |
+| arena shooter | `space` | `orthographic` (top-down) 60°, fov 55 | 10–15 (field) | rim 70° / 210° | deep space blue, graphite, teal + laser magenta | none (space background exception) | `space` | model muzzle flash, shield segments | `webgl_shaders_sky` |
+| sports/table | `interior-industrial` | broadcast `orthographic` (top-down) 70°, fov 40 | 25–40 (table) | flood 55° / 45° | turf green, line white, crowd dark + ball accent | indoor haze | `arena-fight` | scoreboard pulse | `webgl_materials_lightmap` |
+| product | `product-studio` | `orbit` autoframe, fov 35 | 45–70 | softbox 45° / 30° | neutral grey, white, metal + one brand accent | none | `product-studio` | sweep highlight on turn | `webgl_materials_video` |
+| character | `character-showcase` | `orbit`, fov 40 | 50–70 | 3-point 50° / 35° | costume-driven neutrals + rim pick | light room haze | `product-studio` | cloth/hair motion settle | `webgl_animation_skinning_blending` |
+| outdoor environment | `overcast` | `establishing` wide, fov 55 | vista | 50° / 40° | muted green, slate, fog blue + wildflower accent | fog 0.004 | `daylight-outdoor` | wind grass, drifting cloud | `webgl_lights_physical` |
+| interior | `interior-warm` | medium `orbit`, fov 45 | 30–50 (anchor) | window 35° / 60° | warm wood, cream wall, book spines + plant green | dust shafts | `cinematic-film` | window bounce | `webgl_lights_spotlight` |
+| night city | `night-city` | low tele, fov 35 | 20–35 (street) | neon rim 25° / 120° | sodium orange, neon sign, dark asphalt + cyan accent | fog 15–90 m, wet street | `neon-night` | sign flicker, drizzle sheen | `webgl_lights_spotlights` |
+| space | `space` | `orbit` wide, fov 60 | 30–50 (planet) | star key 30° / 180° | void blue, planet limb, star field + aurora accent | none (background exception) | `space` | engine trail, planet rotation | `webgl_shaders_sky` |
+| underwater | `underwater` | `follow`, fov 50 | 20–40 (creature) | godray 70° / 10° | deep blue, teal, kelp green + coral accent | scatter 0.03, caustics | `underwater` | bubble stream, silt drift | `webgl_water` |
+| cinematic | `polar-night` | `establishing` dolly, fov 35 | 25–40 | moon 20° / 300° | aurora green, snow blue, night + lantern amber | snow mist 0.006 | `cinematic-film` | aurora drift, breath fog | `webgl_animation_cloth` |
+
+Notes:
+
+- `orbit`/`follow`/`follow` (side-on)/`follow` (side-on)/`shoulder`/`orthographic` (top-down)/`chase`/`establishing`
+  are camera-rig names used by the template gate; wire them through the camera
+  rig spec API of the current engine version, never through evidence fields.
+- "background exception" rows skip the sky-fill hard check; the look's own
+  background supplies the void.
+- VFX rows name models/practicals; no CSS/DOM overlays and no primitive sprite
+  cards faking rain, reflections or splashes.

package/skills/aura3d-art-direction/references/quality-bar.md

@@ -0,0 +1,103 @@
+# Quality bar — the 12-category look rubric
+
+Score every captured PNG per category 0-10 in 0.5 steps. Anchors are written as
+what you observe, not what the code does. A score < 7 needs an `observations`
+entry naming the concrete thing seen on screen.
+
+## lighting
+
+- 2: one flat light everywhere; faces and props read equally bright
+- 5: a key direction exists but the fill flattens it; mood is generic daylight
+- 7: clear key + fill + rim separation; the mood matches the look brief
+- 9: light feels motivated by the world (sun, sign, lamp); bounce and colour temperature vary by area
+
+## shadows
+
+- 2: no visible shadow; objects float
+- 5: a shadow exists but is grey/soft with no contact darkening
+- 7: dark contact shadows ground every object, soft falloff
+- 9: cascaded and stable; contact + ambient occlusion match the reference
+
+## ibl_reflections
+
+- 2: surfaces uniform, no environment response
+- 5: metals look like plastic; reflections faint or absent
+- 7: environment visible in glossy surfaces; roughness varies by material
+- 9: reflections pick up the actual sky/studio setup and track correctly
+
+## environment_world
+
+- 2: solid void background
+- 5: a sky/ground exist but read as a backdrop, not a place
+- 7: horizon, ground and props compose a believable space
+- 9: parallax layers (far, mid, near) plus weather or time-of-day cues
+
+## atmospheric_effects
+
+- 2: air is empty; no depth between near and far
+- 5: a fog exists but mismatches the light (wrong colour or distance)
+- 7: fog/haze ties to the horizon colour and lifts the far field
+- 9: volumetric cues (shafts, mist, drizzle) read at a glance
+
+## material_quality
+
+- 2: one flat colour per object, everything the same
+- 5: some materials differ but most read as untextured plastic
+- 7: wood/metal/fabric/skin read distinctly; normal/roughness respond to light
+- 9: materials carry wear, edge highlights and texture at read distance
+
+## modeling_assets
+
+- 2: hero subject is a box/sphere primitive
+- 5: typed models but scale mismatches or obvious gaps
+- 7: real models at real scale, fitted to the world
+- 9: asset variety, dressing and silhouette richness like the reference
+
+## composition
+
+- 2: subject centred and tiny, or clipping the frame edge
+- 5: subject visible but dead-centre symmetry with wasted space
+- 7: clear focal hierarchy; rule-of-thirds or genre framing used
+- 9: leading lines and depth layers direct the eye through the shot
+
+## camera
+
+- 2: default angle; horizon level but arbitrary
+- 5: a deliberate angle exists but fov/height flattens the subject
+- 7: rig matches the genre row; subject inside its framing band
+- 9: camera reads as a choice (dolly, chase, orbit) and moves with intent
+
+## postprocessing
+
+- 2: raw output; clipped brights or crushed blacks
+- 5: a grade exists but fights the palette (muddy or oversaturated)
+- 7: tone/grade holds the palette; AO grounds the mid-tones
+- 9: grade + bloom + AO are tuned as one image pipeline
+
+## animation_quality
+
+- 2: hero subject static or sliding
+- 5: animation exists but feet slide or loops stutter
+- 7: locomotion matches travel direction; idle vs action states read
+- 9: secondary motion and timing give the subject weight
+
+## ui_hud
+
+- 2: debug overlay or dev counters in the shipped frame
+- 5: HUD exists but overlaps the subject or sits off-layout
+- 7: HUD in DOM, readable, out of the subject's way
+- 9: HUD styled to the game's palette and responsive at mobile width
+
+## Hard checks (lint codes that must be clean)
+
+`aura3d look lint` plus `app.diagnostics().look.lint` must report no
+`error`-severity finding for:
+
+- `look/no-lights`, `look/no-ibl` — the scene lights and reflects nothing
+- `look/ambient-kills-ibl`, `look/ambient-flattens` — ambient used as the only fill
+- `look/solid-void` — void background without a declared exception
+- `look/low-dpr`, `look/double-aa` — renderer overrides or doubled AA
+- `look/fake-effect-names`, `look/capture-branch` — fake effect primitives or
+  capture-only branches (except where the flagged lane allows capture branches)
+- `look/primitive-subject`, `look/debug-overlay` — primitive hero or shipped debug HUD
+- `look/multiple-looks`, `look/expansion-mismatch` — look conflicts

package/skills/aura3d-art-direction/references/reference-frames.md

@@ -0,0 +1,82 @@
+# Reference frames
+
+Named three.js r185 examples (https://threejs.org/examples/) — the day-0 frame
+set. When the C-30 v2 reference scenes and the licensed stills in
+`benchmarks/quality-rebuild/refs/` land on main, they replace rows here. Every
+frame carries "what you should see" so the file is complete without images.
+
+## webgl_animation_skinning_blending
+
+https://threejs.org/examples/#webgl_animation_skinning_blending
+
+What you should see: a rigged character blending between locomotion clips under
+a real key light with shadows that track the feet. Use for: platformer,
+character — how a typed GLB hero should sit in a lit world.
+
+## webgl_animation_skinning_morph
+
+https://threejs.org/examples/#webgl_animation_skinning_morph
+
+What you should see: a creature head deforming through morph targets with skin
+and eye materials responding to environment light. Use for: fighting — facial
+and secondary motion quality on real materials.
+
+## webgl_animation_cloth
+
+https://threejs.org/examples/#webgl_animation_cloth
+
+What you should see: draped cloth catching directional light with soft,
+contact-darkened shadows on the floor. Use for: cinematic — fabric motion plus
+moody lighting discipline.
+
+## webgl_materials_car
+
+https://threejs.org/examples/#webgl_materials_car
+
+What you should see: a car body with clearcoat reflections pulling the
+environment into the paint, grounded by contact shadow. Use for: racing — how
+glossy materials and IBL should look on a vehicle.
+
+## webgl_materials_video
+
+https://threejs.org/examples/#webgl_materials_video
+
+What you should see: a product-like object under studio lighting with clean
+softboxes and a controlled backdrop. Use for: product — framing and soft studio
+key.
+
+## webgl_materials_lightmap
+
+https://threejs.org/examples/#webgl_materials_lightmap
+
+What you should see: baked light/detail on an architectural interior with warm
+bounce in corners. Use for: sports/table and interior — indoor light richness
+without dynamic lights.
+
+## webgl_lights_physical
+
+https://threejs.org/examples/#webgl_lights_physical
+
+What you should see: physically-motivated lamps in a simple room, falloff that
+reads as real. Use for: outdoor environment, interior — key/fill discipline.
+
+## webgl_lights_spotlights
+
+https://threejs.org/examples/#webgl_lights_spotlights
+
+What you should see: spot cones with visible falloff on a dark floor, haze
+inside the beam. Use for: night city — motivated practical lighting after dark.
+
+## webgl_shaders_sky
+
+https://threejs.org/examples/#webgl_shaders_sky
+
+What you should see: a full-bleed sky dome with sun, horizon gradient and haze —
+never a void. Use for: space, arena shooter, outdoor — background treatment.
+
+## webgl_water
+
+https://threejs.org/examples/#webgl_water
+
+What you should see: an animated water surface with normals, reflections and
+shore interaction. Use for: underwater — surface/caustic atmosphere cues.

package/skills/aura3d-assets/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: aura3d-assets
+description: Finds, admits, inspects, validates, and types GLB/glTF, texture, environment, and audio assets through the Aura3D CLI so scenes use `model(assets.x)`. Use when a prompt names a real object, the user brings a GLB, or the task touches `assets search`, `assets resolve`, `assets add`, `assets inspect`, `assets validate`, `assets typegen`, `aura.assets.json`, or `src/aura-assets.ts`.
+---
+
+# Aura3D assets
+
+The CLI is the only path from a file or catalog hit to a typed `assets.<key>`.
+Shared rules (catalog-first, typed assets, paid generation) are in
+[boundaries](../aura3d-core/references/boundaries.md).
+
+## Look target
+
+Preview candidates under the target look, not a neutral stage: a GLB that
+reads clean under `product-studio` softboxes can disappear into `night-city`
+shadow pools or bloom out under `neon-arcade`. The route's recipe row sets the
+lighting you evaluate materials and silhouettes against.
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help` and `npx @aura3d/cli@latest assets add
+   --help`. Use only the flags they print; `--profile` values for search and
+   resolve come from the usage line, not memory.
+2. Read `aura.assets.json` and `src/aura-assets.ts`. Reuse an existing key
+   before adding a duplicate.
+3. Note each asset's role: `character`, `vehicle`, `world`, `environment`,
+   `track`, `product`, `weapon`, `prop`, `set-dressing`, `debug`, `abstract`,
+   or `unknown`. Role decides the evidence you need later.
+
+## Procedure
+
+1. User supplied a file: skip search and admit it with provenance.
+
+   ```bash
+   npx @aura3d/cli@latest assets add ./assets/robot.glb --name robot \
+     --type model --role character --quality candidate \
+     --license CC0-1.0 --license-url <url> --source-page <url> \
+     --author "<name>" --retrieved-at <ISO-8601>
+   ```
+
+   Use `--type texture|environment|audio|navigation` for non-model files, and
+   `--public-path /cdn/aura-assets/` when assets are served from a CDN.
+2. Prompt names a real object: search with a descriptive phrase.
+
+   ```bash
+   npx @aura3d/cli@latest assets search "battle-worn knight helmet" --json
+   npx @aura3d/cli@latest assets search "animated humanoid fighting character" \
+     --profile fighting-character --json
+   ```
+
+   Narrow with `--license cc0|cc-by`, `--max-tris N`, or `--animated`.
+3. Read the result. Only auto-pullable candidates may be pulled. Marketplace
+   deep-links and `manual license check required` rows are user-handled: hand
+   the link to the user and admit their download with `assets add`.
+4. Pull the chosen candidate into a typed key.
+
+   ```bash
+   npx @aura3d/cli@latest assets resolve "battle-worn knight helmet" --name helmet
+   ```
+
+   Pick a non-top candidate with `--index N` or `--candidate-id ID`, and repeat
+   the same `--profile` you searched with.
+5. Inspect before naming clips, joints, morphs, or materials in code.
+
+   ```bash
+   npx @aura3d/cli@latest assets inspect public/aura-assets/<file>.glb \
+     --animation --humanoid --skeleton --morphs --license
+   ```
+
+   Treat `"ok": false` warnings (for example missing orientation metadata) as
+   facts to record, not noise.
+6. Regenerate types and validate the shipping set.
+
+   ```bash
+   npx @aura3d/cli@latest assets typegen
+   npx @aura3d/cli@latest assets validate --asset helmet --source
+   ```
+
+   `--source` scans `src` for raw ids, URLs, and loader code, and lists
+   `typedAssetUsages`. Add `--no-placeholders --require-license` for anything
+   public. Refresh stale manifest bounds by re-adding the file. Ensure every
+   admitted entry in `aura.assets.json` and `src/aura-assets.ts` carries a valid
+   64-character `sha256-...` `hash` and `public/aura-assets/...` path for clean
+   look and silhouette so `createAssetProvenance(node.asset).source === "typed-aura-assets-manifest"`
+   preserves PBR lighting, palette, contrast, and reflection in the production
+   glTF bridge. Never omit `hash` in custom `defineAuraAssets(...)` /
+   `defineAssets` declarations (keeps look and shadow intact) and never place
+   unhashed duplicate GLBs in route-local `apps/<route>/public/aura-assets/`
+   that collide with root `public/aura-assets/` (keeps composition readable).
+7. Use the key as generated. Every character, athlete, enemy, vehicle, weapon,
+   tree, and landmark must mount a real 3D GLB via `model(assets.<name>,
+   { targetMaxDimension, role })` for a readable silhouette — use `targetHeight`
+   only for upright humanoids and `targetMaxDimension` for vehicles, rackets,
+   paddles, weapons, and wide props so aspect ratios never stretch vertically;
+   drive rigged characters (`skins > 0`) with `handle.setAnimation({ clip,
+   loop: true, speed })` so limbs articulate under the key light and shadow; and
+   never build stick-figure humans or box cars from primitives.
+
+   ```ts
+   import { createAuraApp, groundedRenderedAssetPlacement, looks, model, scene } from "@aura3d/engine";
+   import { assets } from "./aura-assets";
+
+   const place = groundedRenderedAssetPlacement(assets.helmet, { targetMaxDimension: 1.2, floorY: 0 });
+   createAuraApp("#app", {
+     scene: scene()
+       .add(looks.preset("product-studio"))
+       .add(model(assets.helmet).position(...place.position).scale(place.scale)),
+     ...looks.appOptions("product-studio")
+   });
+   ```
+
+8. Hand off: fighters and games to `aura3d-browser-game`
+   (`assets validate-game`), rigs and clips to `aura3d-character-animation`
+   (`assets validate-animation`), release checks to `aura3d-evidence-review`.
+
+## Reject a candidate when
+
+- license, source page, author, or acquisition time is missing or temp-only;
+- no material or texture evidence exists where the role expects texture;
+- a character route claims animation but inspection shows `skins === 0` or no
+  usable clips for skeletal look and silhouette motion;
+- bounds are extreme, pivot is bad, or orientation is unknown and public APIs
+  cannot correct it;
+- the hash duplicates another asset without an explanation;
+- a generated Meshy GLB has not been decimated and compressed before admission
+  (`> 20,000` vertices, `> 2 MB`, 32-bit indices instead of 16-bit `Uint16Array`
+  with `byteStride === 0`, or `> 1024x1024` textures that stall glTF parsing and
+  exhaust GPU memory across the scene's look, lighting, and atmosphere);
+- it is placeholder-like, or only a generated thumbnail proves it is readable.
+
+## Stop and report
+
+- Search returns no auto-pullable candidate, or every candidate fails the
+  reject list: stop, list the query, profile, and rejection reasons, and offer
+  two options: a user-supplied licensed file, or Meshy generation (load
+  `meshy-cli`, dry run first). Do not model the subject from primitives.
+- Search prints a catalog fetch warning (for example an HTTP 404 from the
+  index): report it verbatim, label asset-dependent work `blocked`, and do not
+  treat fallback deep-links as auto-pullable.
+- `assets validate --release` fails on provenance: keep the route `prototype`
+  until durable evidence is added; never weaken the check.
+- A needed key is absent from `src/aura-assets.ts` after typegen: stop and fix
+  the admission.
+
+## References
+
+- [Boundaries](../aura3d-core/references/boundaries.md)
+- [Asset workflow](https://github.com/auraoneai/aura3d/blob/main/docs/agents/asset-workflow.md)
+- [Asset selection](https://github.com/auraoneai/aura3d/blob/main/docs/agents/asset-selection.md)
+- [Assets docs](https://aura3d.auraone.ai/docs/assets.html)
+- [Previewing assets under a look](references/preview-under-look.md)

package/skills/aura3d-assets/references/preview-under-look.md

@@ -0,0 +1,26 @@
+# Previewing assets under a look
+
+A GLB that survives a neutral viewer can still fail the real scene's lighting.
+Evaluate candidates under the route's look preset.
+
+| Look | What it exposes | Reject signal |
+| --- | --- | --- |
+| `product-studio` | material honesty, silhouette edge quality | faceted normals, muddy PBR, bad pivot on plinth |
+| `golden-hour` | warm key + teal shadow separation | specular wash, albedo too dark to read at dusk |
+| `night-city` | neon rim, wet reflections, dark pools | silhouette disappears into shadow, emissive bloom-out |
+| `outdoor-day` | full daylight exposure, horizon fog | washed-out albedo, no AO at contact points |
+| `interior-warm` | warm pools, wood/fabric pairing | cold grey materials fight the grade |
+| `space` | single hard key, black void | anything mid-grey vanishes; no fill light forgiving |
+| `underwater` | teal volume, caustic shimmer | high-contrast speculars shimmer to noise |
+| `arena-fight` | top spot + rim, dark crowd | midtones crush to black outside the pool |
+
+## Checks at preview time
+
+1. Spin the model `orbit` once under the look — a silhouette that dies at
+   three-quarter back is a bad candidate.
+2. Contact: feet/wheels/anchor inside the look's ground shadow, not beside it.
+3. Emissive parts bloom only where the grade expects glow (pickups, signage);
+   an unbounded emissive channel reads as a bug.
+4. Palette: the asset's dominant hue must sit inside the genre palette or be
+   the declared accent — clashing saturation reads as wrong-asset even when
+   the mesh is fine.

package/skills/aura3d-browser-game/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: aura3d-browser-game
+description: Builds a playable Aura3D browser game route on the public genre kits with typed assets, deterministic input, reset, an objective, and a genre look recipe driven through the look-dev loop. Use when working in the `mini-game`, `racing-starter`, `falling-blocks-starter`, `fighting-game`, or `character-controller` templates, calling `game.platformer`, `game.racing`, `game.fallingBlocks`, `game.fighting`, or `game.evidence`, or running `assets validate-game` or `assets certify-game-geometry`.
+---
+
+# Aura3D browser game
+
+A route with a scene and a key listener is not a game — and a playable scene
+with flat lighting is not a finished game. A public game proves input, reset,
+an objective and a progression loop in the browser AND looks like its genre.
+Shared rules (claim labels, forbidden patterns, typed assets, benchmark mode)
+are in [boundaries](../aura3d-core/references/boundaries.md).
+
+## Look target
+
+Genre → recipe row (full table: `../aura3d-art-direction/references/look-recipes.md`):
+
+| Template | Look | Camera | Frame mood |
+| --- | --- | --- | --- |
+| `mini-game` | `outdoor-day` | `follow` (side-on) fov 50 | saturated greens, sky blue, warm wood + coin gold; fog 0.0025; `daylight-outdoor` post; coin sparkle + land dust |
+| `racing-starter` | `golden-hour` | `chase` fov 60 | warm asphalt, burnt orange, charcoal + headlight amber; low sun haze; `cinematic-film` post; brake glow |
+| `falling-blocks-starter` | `neon-arcade` | `orthographic` (top-down) fov 45 | neon palette per piece colour, dark glossy board + accent rim; `neon-night` post; line-clear flash |
+| `fighting-game` | `arena-fight` | `follow` (side-on) fov 45 | arena dark, rope colour, crowd shadow + spotlight rim; haze cone; `arena-fight` post; hit sparks |
+| `character-controller` | `outdoor-day` | `shoulder` fov 55 | open world greens + cloth accent; fog to horizon; `daylight-outdoor` post |
+
+## Establish the contract
+
+1. Run `npx @aura3d/cli@latest --help`. Use only the commands and flags it
+   prints; `--category` accepts only `racing` or `platformer`.
+2. Read `src/aura-assets.ts` and `aura.assets.json`. Player, vehicle, track,
+   and world must be typed keys with a role (`character`, `vehicle`, `track`,
+   `world`). Missing keys: load `aura3d-assets` first.
+3. Read the template `package.json` so you know what `npm run test` runs.
+4. Decide the mode. Benchmark mode: if `aura3d look capture` is available, run
+   the look-dev loop; otherwise build and stop, label `prototype`.
+
+## Procedure
+
+1. Scaffold the matching template, then add the genre look before any props:
+
+   ```ts
+   import { createAuraApp, game, looks, model, scene } from "@aura3d/engine";
+   import { assets } from "./aura-assets";
+
+   const app = createAuraApp("#app", {
+     scene: scene()
+       .add(looks.preset("outdoor-day"))
+       .add(model(assets.hero).runtime(game.runtimeNode("player", { tags: ["player"] }))),
+     ...looks.appOptions("outdoor-day")
+   });
+   const player = app.nodes.require("player");
+   const input = app.input({
+     actions: { left: ["KeyA", "ArrowLeft"], right: ["KeyD", "ArrowRight"], jump: ["Space"], restart: ["KeyR"] },
+     axes: { moveX: { negative: "left", positive: "right" } },
+     bufferMs: 120
+   });
+   const level = game.platformer({
+     start: { x: 0, y: 0.35 },
+     finish: { x: 12, y: 0.35 },
+     platforms: [{ id: "ground", x: -1, y: 0, width: 14, height: 0.35 }]
+   });
+
+   app.onFrame(({ dt }) => {
+     input.update(dt);
+     const state = level.step(dt, { moveX: input.axis("moveX"), jumpPressed: input.buffered("jump") });
+     player.setPosition(state.player.x, state.player.y, 0);
+   });
+   ```
+
+2. The look supplies sky light, key shadow, fog, and grade — never stack extra
+   `lights.studio()` / `lights.directional()` on top, pass `{ fogDensityScale: 0,
+   exposureEv: -0.1 }` to `looks.preset(...)` and
+   `qualityRebuild: { flags: ["game", "-compiler", "-post", "-vfxFog"] }` on fast
+   arcade routes so contrast and frame pacing stay crisp, and never set
+   `emissive: "#ffffff"` on instanced pool materials (`instanceColors` multiply
+   `u_baseColor`, not `u_emissiveColor`).
+3. Mount typed 3D GLBs for every character, athlete, enemy, vehicle, weapon,
+   tree, and landmark (`model(assets.<name>, { targetMaxDimension, role })`,
+   emissive 3–5 on pickups, and explicit `material: material.pbr({ color })` on
+   untextured preview GLBs); use `targetHeight` only for upright humanoids and
+   `targetMaxDimension` for vehicles, rackets, paddles, weapons, and wide props
+   so silhouettes never stretch vertically. Drive rigged characters (`skins > 0`)
+   with `handle.setAnimation({ clip, loop: true, speed })` synced to locomotion
+   (`idle`, `walk`, `run`, `attack`) for real pixel motion under the key shadow
+   instead of sliding rigid statues. Never build stick-figure humans or box cars
+   from primitives; ground `model()` actors (`minY = 0`) at `y + sy / 2` of
+   centered platforms; wind custom `primitives.mesh` triangles CCW from `+Y`; and
+   decimate/compress Meshy GLBs (`<= 20,000` vertices, `<= 2 MB`, 16-bit indices,
+   `<= 1024x1024` textures, valid 64-char `sha256-...` `hash` for clean look).
+4. Camera state drives `app.camera` every frame — size `html, body, #app, canvas`
+   to `100vw × 100vh` (`position: fixed; inset: 0`), extend the 3D ground apron
+   deep in `+Z`/`-Z` so the bottom frame is never a black void, disable
+   `collision: true` on `camera.rigs.shoulder` when the hero has child nodes, and
+   enforce `>= 1.4m` fighter pushbox separation (`|x| >= 1.8m` at spawn).
+5. Gate Frame 1 on `await app.ready()` before fading `#boot-gate` (`opacity: 0;
+   pointer-events: none` then remove) and starting simulation so lighting,
+   shadow, and GLB silhouettes never pop in. Default `autopilot` to `false`
+   (immediate manual control on Frame 1) unless `?autoplay=1` or `?demo=1` is in
+   the URL or the user clicks the HUD `Auto` toggle button (`button.blur()` so
+   `Space`/`Enter` never re-trigger focused HUD controls), and wire HUD/events
+   through `game.eventLog` and `game.hud.*` in a compact top bar.
+6. Reset without tearing down the scene: mutate runtime node handles
+   (`app.nodes.require(...)`) instead of calling `app.setScene()` on same-stage
+   (`stageId` / `worldId`) restarts so shadow and postprocess grade never drop.
+7. Genre gates (plan for 60 seconds of meaningful play):
+
+   | Genre | Must have |
+   | --- | --- |
+   | racing | throttle, brake, steer, ordered checkpoints, lap or finish, penalty or timeout |
+   | platformer | move, jump, fall, collision matching visible ledges, collectibles, hazards, camera keeps player visible |
+   | falling blocks | move, rotate, soft + hard drop, lock, line clear, scoring, levels, game over |
+   | fighting | strikes/blocks, hit reactions, round + KO state, both fighters readable |
+   | character controller | walk/run/jump clips playing, camera shoulder follow, locomotion direction matches travel |
+
+8. `npx @aura3d/cli@latest assets validate --no-placeholders --require-license`
+   and `assets validate-game`; racing/platformer also
+   `assets certify-game-geometry --asset track --category racing`.
+9. Runtime evidence: pause, step one frame, then `game.evidence` over input,
+   bodies, events, HUD, and look state — see `aura3d-evidence-review` (one link).
+
+## Look-dev loop
+
+Run the `aura3d look capture` → judge → iterate loop from
+`aura3d-art-direction`: lint first (`aura3d look lint`), then the weakest
+rubric category; one change per round until every category reads 7+, 6
+rounds, or 2 flat rounds.
+
+## Stop and report
+
+- `assets certify-game-geometry` returns `"ok": false` or a blocker such as
+  `racing-road-mesh-not-found`: label `prototype`; never hide the gap with
+  primitive ledges or road strips.
+- Manual input cannot complete the route while a proof replay can: `prototype`.
+- The primary player, vehicle, or world is a primitive stand-in: `prototype`.
+- `assets validate-game` crashes or fails: report the exact message, label
+  `blocked` for public claims.
+- A kit is missing a needed rule (fail state, collision semantics, path
+  alignment): write it route-local, say so, file a library gap.
+- Benchmark mode without `look capture`: build, stop, label `prototype`.
+
+## References
+
+- [Shared boundaries](../aura3d-core/references/boundaries.md)
+- [Look recipes](../aura3d-art-direction/references/look-recipes.md)
+- [Quality bar](../aura3d-art-direction/references/quality-bar.md)
+- [Build a browser game](https://github.com/auraoneai/aura3d/blob/main/docs/guides/build-a-browser-game.md)
+- [Game example standards](https://github.com/auraoneai/aura3d/blob/main/docs/agents/game-example-standards.md)
+- [Game runtime API](https://github.com/auraoneai/aura3d/blob/main/docs/api/game-runtime.md)
+- [Genre looks in the frame](references/genre-looks.md)

package/skills/aura3d-browser-game/references/genre-looks.md

@@ -0,0 +1,52 @@
+# Genre looks in the frame
+
+What each genre's look must visibly deliver, at capture time.
+
+| Genre | The frame must show | Kills the look |
+| --- | --- | --- |
+| platformer | blue sky with depth fog, long grass-edge shadows, warm key on the hero, gold pickups glowing | void background, ambient-only light, floating platforms |
+| racing | low warm sun, orange rim on the car silhouette, asphalt reflection, fog band at the horizon | noon-flat light, grey void, no specular on bodywork |
+| falling blocks | saturated piece hues against a dark glossy board, bloom on line-clear, rim on the stack edge | washed-out palette, flat board, no glow on clears |
+| fighting | top spotlight cones, rim on both fighters, crowd silhouettes in shadow | both fighters evenly lit, empty void arena |
+| character showcase | 3/4-front key, rim separating hair/shoulder from backdrop, ground contact shadow | flat fill, floating feet, void |
+| night city | neon signage, wet-street reflections, sodium pools, window glow | pure black background, one uniform dark |
+
+## Per-genre VFX palette
+
+| Genre | Accents (emissive 3–5× bg) | Motion cue |
+| --- | --- | --- |
+| platformer | coin gold, spring green, hazard red | land dust puff, jump trail |
+| racing | brake amber, exhaust white, dial cyan | speed lines, tire smoke |
+| falling blocks | per-piece neon hue, clear flash white | line-clear flash, lock click glow |
+| fighting | impact spark orange, meter cyan | hit sparks, knockback flash |
+| character | cloth accent, eye catchlight | footstep dust, hair/cloth sway |
+| night city | sign neon, puddle rim | steam wisps, window flicker |
+| sports/table | felt green, chalk white, spot warm | ball trail, score flash |
+| interior | warm pool amber, accent object hue | dust motes, lamp flicker |
+| underwater | caustic teal, biolume cyan | bubbles, particle drift |
+| space | laser magenta, engine white | debris drift, shield ripple |
+
+## HUD style
+
+DOM HUD only. Type color follows the look: warm cream on golden-hour, neon
+cyan on night-city, high-contrast white on product-studio. Pause/menu layers
+inherit the grade (a blur + dark grade band reads as one scene, a raw solid
+overlay reads as a bug).
+
+## Lighting story per template
+
+| Template | Key story | Shadow story | Depth cue |
+| --- | --- | --- | --- |
+| `mini-game` | warm afternoon key 40° | grass-edge shadows toward camera | fog band at far platforms |
+| `racing-starter` | low sun behind the car | long streaks across asphalt | haze silhouettes the horizon |
+| `falling-blocks-starter` | soft top key | piece self-shadow on stack | board gloss reflection |
+| `fighting-game` | overhead spot cones | rim shadows under both fighters | crowd fades to black |
+| `character-controller` | daylight key 3/4 front | contact shadow under feet | fog to horizon on the run |
+
+## Mood one-liners
+
+- platformer: cheerful daylight, saturated palette, motion reads as play.
+- racing: speed sells through low sun, glare, and horizon haze.
+- fighting: drama lives in the dark crowd and the spot's hard edge.
+- blocks: rhythm is the palette — every piece hue distinct at a glance.
+- character: the silhouette is the gameplay; rim keeps it readable.