evomeme-dev 0.1.7

package/skills/threejs-aaa-graphics-builder/references/shader-cookbook.md

@@ -0,0 +1,292 @@
+# Shader And Material Cookbook
+
+Concrete material, shader, and post-processing recipes. Use with `technical-art.md` (budgets, when shader work is justified) and `render-recipes.md` (render pipeline).
+
+Targets three.js `^0.184`; imports use the `three/addons/*` alias (maps to `examples/jsm`). Every entry lists **When**, **Cost** (draw calls / fill rate / compile), and **Read** (the rule: effects clarify gameplay, never hide missing geometry).
+
+## Prerequisite: Renderer And Environment Map
+
+Metals and glossy dielectrics read as flat gray without an environment map to reflect. Set this up once before PBR materials.
+
+```ts
+import * as THREE from 'three';
+import { RoomEnvironment } from 'three/addons/environments/RoomEnvironment.js';
+
+renderer.outputColorSpace = THREE.SRGBColorSpace;
+renderer.toneMapping = THREE.ACESFilmicToneMapping; // simpler tone mapping for bright arcade reads
+renderer.toneMappingExposure = 1.0;
+renderer.setPixelRatio(Math.min(devicePixelRatio, 2));
+
+// 5-line env map: neutral studio IBL, no HDR file needed.
+const pmrem = new THREE.PMREMGenerator(renderer);
+scene.environment = pmrem.fromScene(new RoomEnvironment(), 0.04).texture; // r184: RoomEnvironment() takes no args
+scene.environmentIntensity = 1.0; // r184 global multiplier over per-material envMapIntensity
+pmrem.dispose();
+```
+
+Needed by any scene with metal, ceramic, glass, or clearcoat. Cost is one PMREM bake at startup, near-zero per frame; it lights support surfaces so hero emissive/trim still wins attention.
+
+## PBR Material Recipes
+
+Copy the config; tune `color` to the palette. `envMapIntensity` values assume the env map above. Use `MeshStandardMaterial` unless a `MeshPhysicalMaterial`-only feature (clearcoat, transmission, sheen) is visible during play.
+
+```ts
+// Painted metal (car body, ship hull panel) — dielectric paint over metal read via clearcoat.
+new THREE.MeshPhysicalMaterial({ color: 0x1f6feb, metalness: 0.0, roughness: 0.5,
+  clearcoat: 0.9, clearcoatRoughness: 0.15, envMapIntensity: 1.0 });
+
+// Bare brushed metal (raw steel, gun frame) — needs the env map to look metallic.
+new THREE.MeshStandardMaterial({ color: 0xaeb4bd, metalness: 1.0, roughness: 0.4, envMapIntensity: 1.1 });
+
+// Rubber / tire — near-black, no reflection, kills the env map.
+new THREE.MeshStandardMaterial({ color: 0x0a0a0b, metalness: 0.0, roughness: 0.92, envMapIntensity: 0.35 });
+
+// Matte plastic (housings, crates) — dielectric, mid roughness, muted reflection.
+new THREE.MeshStandardMaterial({ color: 0xd23b3b, metalness: 0.0, roughness: 0.62, envMapIntensity: 0.6 });
+
+// Glossy ceramic / clean hull — sharp reflection, add clearcoat for wet-look premium.
+new THREE.MeshPhysicalMaterial({ color: 0xf5f5f5, metalness: 0.0, roughness: 0.12,
+  clearcoat: 1.0, clearcoatRoughness: 0.05, envMapIntensity: 1.0 });
+
+// Emissive signal (beacon, pickup core) — dark base so only the glow reads; >1 intensity feeds bloom.
+new THREE.MeshStandardMaterial({ color: 0x101010, emissive: 0x18e0ff, emissiveIntensity: 2.5,
+  metalness: 0.0, roughness: 0.4 });
+
+// Cloth / fabric — high roughness + sheen for the soft edge highlight.
+new THREE.MeshPhysicalMaterial({ color: 0x3a4a6b, metalness: 0.0, roughness: 0.9,
+  sheen: 1.0, sheenRoughness: 0.5, sheenColor: new THREE.Color(0x8899bb), envMapIntensity: 0.5 });
+```
+
+**Read:** separate roles by roughness/metalness contrast (matte vs glossy, metal vs plastic), not hue alone.
+
+### Glass: real vs fake
+
+```ts
+// REAL refractive glass — MeshPhysicalMaterial transmission.
+new THREE.MeshPhysicalMaterial({ metalness: 0.0, roughness: 0.05, transmission: 1.0,
+  thickness: 0.5, ior: 1.5, envMapIntensity: 1.0 });
+```
+
+- **When:** one or two hero surfaces (cockpit canopy, potion vial) at close range.
+- **Cost:** high. Each transmissive material triggers an extra scene render into a transmission buffer every frame; fill-rate heavy and multiplies with resolution. Never use on repeated/instanced props.
+- **Read:** refraction must not smear the hazard behind it into unreadability.
+
+```ts
+// CHEAP fake glass — no transmission buffer. Use for repeated windows, visors, shields.
+new THREE.MeshPhysicalMaterial({ color: 0x88ccff, metalness: 0.0, roughness: 0.1,
+  transparent: true, opacity: 0.25, clearcoat: 1.0, envMapIntensity: 1.5, depthWrite: false });
+```
+
+- **Cost:** one transparent draw call, no extra render target. Add the fresnel rim below for a readable edge.
+
+## onBeforeCompile Patterns
+
+Inject GLSL into stock materials to keep PBR lighting for free. Rules that make this safe with shared materials:
+
+- **Cache key:** any material whose `onBeforeCompile` injects code MUST set `customProgramCacheKey` returning a string unique to that injection. Without it three can hand back a cached program compiled from a different (un-injected) material of the same type, silently dropping your code.
+- **Sharing:** `onBeforeCompile` runs once per compiled program. Reuse one material instance across meshes and its uniforms update once for all. For per-object variation, use separate material instances (same cache key → program is still reused) or drive it from `instanceMatrix` / `instanceColor`.
+- **Animating uniforms:** `onBeforeCompile` fires once, so stash the shader (`material.userData.shader = shader`) and write the uniform each frame: `if (m.userData.shader) m.userData.shader.uniforms.uTime.value = t;`. The snippets below use this pattern.
+
+### (a) Fresnel rim glow
+
+`vNormal` and `vViewPosition` (both view space) exist in the Standard/Physical fragment shader; `saturate` is defined in `<common>`.
+
+```ts
+material.onBeforeCompile = (shader) => {
+  shader.uniforms.uRimColor = { value: new THREE.Color(0x33ccff) };
+  shader.uniforms.uRimPower = { value: 3.0 };
+  shader.uniforms.uRimStrength = { value: 1.5 };
+  shader.fragmentShader =
+    'uniform vec3 uRimColor;\nuniform float uRimPower;\nuniform float uRimStrength;\n' +
+    shader.fragmentShader.replace(
+      '#include <emissivemap_fragment>',
+      `#include <emissivemap_fragment>
+       float fres = pow(1.0 - saturate(dot(normalize(vNormal), normalize(vViewPosition))), uRimPower);
+       totalEmissiveRadiance += uRimColor * fres * uRimStrength;`
+    );
+};
+material.customProgramCacheKey = () => 'fresnel-rim';
+```
+
+- **When:** shields, cloak/invuln states, silhouette separation from a busy background.
+- **Cost:** a few ALU ops, no extra passes.
+- **Read:** the rim marks a state change; keep base color readable when the rim is off.
+
+### (b) Scrolling emissive panels
+
+Inject a private UV varying so it works without a map assigned.
+
+```ts
+material.onBeforeCompile = (shader) => {
+  shader.uniforms.uTime = { value: 0 };
+  shader.uniforms.uPanelColor = { value: new THREE.Color(0x18e0ff) };
+  material.userData.shader = shader;
+  shader.vertexShader = 'varying vec2 vCookUv;\n' + shader.vertexShader.replace(
+    '#include <begin_vertex>', '#include <begin_vertex>\n vCookUv = uv;');
+  shader.fragmentShader =
+    'uniform float uTime;\nuniform vec3 uPanelColor;\nvarying vec2 vCookUv;\n' +
+    shader.fragmentShader.replace(
+      '#include <emissivemap_fragment>',
+      `#include <emissivemap_fragment>
+       float scroll = fract(vCookUv.y * 6.0 - uTime * 0.5);
+       float band = smoothstep(0.46, 0.5, scroll) * smoothstep(0.54, 0.5, scroll);
+       totalEmissiveRadiance += uPanelColor * band * 2.0;`
+    );
+};
+material.customProgramCacheKey = () => 'scroll-emissive';
+```
+
+- **When:** energy conduits, reactor walls, loading/charge bars, boost lanes.
+- **Cost:** one `fract`/`smoothstep`, no textures.
+- **Read:** scroll direction/speed should encode state (charging up, draining down).
+
+### (c) Wind sway (foliage / flags)
+
+`transformed` is object space and displaced before `<project_vertex>` applies `instanceMatrix`, so read the instance translation column for per-instance phase. Assumes model origin at the base, up = +Y.
+
+```ts
+material.onBeforeCompile = (shader) => {
+  shader.uniforms.uTime = { value: 0 };
+  material.userData.shader = shader;
+  shader.vertexShader = 'uniform float uTime;\n' + shader.vertexShader.replace(
+    '#include <begin_vertex>',
+    `#include <begin_vertex>
+     #ifdef USE_INSTANCING
+       float phase = instanceMatrix[3].x + instanceMatrix[3].z; // instance world offset
+     #else
+       float phase = 0.0;
+     #endif
+     float h = max(position.y, 0.0); // base stays planted, tips move most
+     transformed.x += sin(uTime * 1.5 + phase) * 0.08 * h;
+     transformed.z += cos(uTime * 1.1 + phase) * 0.05 * h;`
+  );
+};
+material.customProgramCacheKey = () => 'wind-sway';
+```
+
+- **When:** grass cards, banners, antennae, kelp — background life, not gameplay geometry.
+- **Cost:** two trig ops per vertex; free on an `InstancedMesh`.
+- **Read:** sway is ambient motion; never move collidable/interactable geometry with it.
+
+### (d) Dissolve / spawn
+
+Threshold-discard with a glowing edge. Inject a local-position varying and a hash; drive `uProgress` 0→1 to despawn, 1→0 to spawn.
+
+```ts
+material.onBeforeCompile = (shader) => {
+  shader.uniforms.uProgress = { value: 0 };
+  shader.uniforms.uEdgeColor = { value: new THREE.Color(0xff6a00) };
+  material.userData.shader = shader;
+  shader.vertexShader = 'varying vec3 vDisPos;\n' + shader.vertexShader.replace(
+    '#include <begin_vertex>', '#include <begin_vertex>\n vDisPos = position;');
+  shader.fragmentShader =
+    `uniform float uProgress;\nuniform vec3 uEdgeColor;\nvarying vec3 vDisPos;
+     float hash13(vec3 p){ p = fract(p * 0.1031); p += dot(p, p.yzx + 33.33); return fract((p.x + p.y) * p.z); }\n` +
+    shader.fragmentShader.replace(
+      '#include <dithering_fragment>',
+      `float n = hash13(floor(vDisPos * 12.0));
+       if (n < uProgress) discard;
+       float edge = smoothstep(uProgress, uProgress + 0.08, n);
+       gl_FragColor.rgb += uEdgeColor * (1.0 - edge) * 3.0; // post-tonemap add feeds bloom
+       #include <dithering_fragment>`
+    );
+};
+material.customProgramCacheKey = () => 'dissolve';
+```
+
+- **When:** enemy death, teleport-in, pickup spawn, object streaming.
+- **Cost:** one hash + `discard` (discard disables early-Z; keep it to spawning objects, not the whole scene).
+- **Read:** the edge color/direction telegraphs the event — spawn vs destroy must look different.
+
+## Gradient Sky Dome
+
+Cheaper than a cubemap for stylized scenes: a `BackSide` sphere with a top/horizon lerp plus a sun disc and halo.
+
+```ts
+const skyUniforms = {
+  uTop:      { value: new THREE.Color(0x3a6fb0) },
+  uHorizon:  { value: new THREE.Color(0xcfe4f5) },
+  uSunColor: { value: new THREE.Color(0xfff2cc) },
+  uSunDir:   { value: new THREE.Vector3(0.4, 0.28, 0.6).normalize() },
+};
+const sky = new THREE.Mesh(
+  new THREE.SphereGeometry(500, 32, 16),
+  new THREE.ShaderMaterial({
+    side: THREE.BackSide, depthWrite: false, uniforms: skyUniforms,
+    vertexShader: `varying vec3 vDir;
+      void main(){ vDir = normalize(position); gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }`,
+    fragmentShader: `varying vec3 vDir;
+      uniform vec3 uTop, uHorizon, uSunColor, uSunDir;
+      void main(){
+        float h = clamp(vDir.y * 0.5 + 0.5, 0.0, 1.0);
+        vec3 col = mix(uHorizon, uTop, pow(h, 0.6));
+        float d = clamp(dot(normalize(vDir), normalize(uSunDir)), 0.0, 1.0);
+        col += uSunColor * (pow(d, 800.0) + pow(d, 8.0) * 0.25); // disc + halo
+        gl_FragColor = vec4(col, 1.0);
+      }`,
+  })
+);
+sky.frustumCulled = false;
+scene.add(sky);
+```
+
+- **When:** any stylized outdoor scene without a photographic backdrop.
+- **Cost:** one draw call, no cubemap textures, no mips.
+- **Read:** a raw `ShaderMaterial` bypasses tone mapping and sRGB conversion — author colors in display space; if the scene runs ACES, nudge them brighter. Keep horizon value distinct from hazards silhouetted against it.
+
+## Post-Processing Chain
+
+Finishing pass only. Move tone mapping/sRGB to `OutputPass`; keep `renderer.toneMapping` set so it reads it.
+
+```ts
+import { EffectComposer } from 'three/addons/postprocessing/EffectComposer.js';
+import { RenderPass } from 'three/addons/postprocessing/RenderPass.js';
+import { UnrealBloomPass } from 'three/addons/postprocessing/UnrealBloomPass.js';
+import { ShaderPass } from 'three/addons/postprocessing/ShaderPass.js';
+import { OutputPass } from 'three/addons/postprocessing/OutputPass.js';
+
+const composer = new EffectComposer(renderer);
+composer.addPass(new RenderPass(scene, camera));
+
+// UnrealBloomPass(resolution, strength, radius, threshold)
+const bloom = new UnrealBloomPass(new THREE.Vector2(innerWidth, innerHeight),
+  0.45,  // strength: 0.35-0.6
+  0.3,   // radius: 0.2-0.4
+  0.85); // threshold: only pixels brighter than this bloom
+composer.addPass(bloom);
+
+const VignetteShader = {
+  uniforms: { tDiffuse: { value: null }, uStrength: { value: 0.85 }, uSize: { value: 0.72 } },
+  vertexShader: `varying vec2 vUv; void main(){ vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0); }`,
+  fragmentShader: `uniform sampler2D tDiffuse; uniform float uStrength, uSize; varying vec2 vUv;
+    void main(){
+      vec4 c = texture2D(tDiffuse, vUv);
+      float d = distance(vUv, vec2(0.5));
+      c.rgb *= mix(1.0, smoothstep(uSize, uSize - 0.45, d), uStrength);
+      gl_FragColor = c;
+    }`,
+};
+composer.addPass(new ShaderPass(VignetteShader));
+composer.addPass(new OutputPass()); // ALWAYS last: tone mapping + sRGB
+
+// In R3F projects: call composer.render() inside useFrame and disable the
+// default R3F present path for that frame; do not also run a separate outer
+// renderer.render() game loop. Imperative-only demos may replace renderer.render().
+// In R3F projects: call composer.render() inside useFrame and disable the
+// default R3F present path for that frame; do not also run a separate outer
+// renderer.render() game loop. Imperative-only demos may replace renderer.render().
+// loop: composer.render() instead of renderer.render()
+// resize: composer.setSize(w, h); composer.setPixelRatio(Math.min(devicePixelRatio, 2));
+```
+
+- **Bloom rule:** bloom sells authored emissive (threshold 0.85 keeps mid-bright materials out). It must never be the main source of detail — if a shape only reads because it glows, the geometry is missing.
+- **Vignette cost:** one full-screen ShaderPass; keep `uStrength` subtle, never darken the play path.
+- **Mobile:** the composer allocates full-resolution HDR targets, so cost scales with DPR². Cap DPR before adding passes. On low-end, skip the composer (call `renderer.render`) or run bloom-only via `composer.setPixelRatio(Math.min(devicePixelRatio, 1.25))`. Compare screenshots with post on/off and profile.
+
+## Cheap Tricks
+
+- **Vertex-color AO** — bake occlusion into the mesh: `geometry.setAttribute('color', new THREE.BufferAttribute(colors, 3))`, material `{ vertexColors: true }`, darken cavities/creases. **When:** static props/terrain. **Cost:** one attribute, zero draw calls. **Read:** ground shapes with contact darkness; don't tint gameplay-critical surfaces.
+- **Polygon-offset decals** — coplanar decal mesh with `{ polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1, transparent: true }` to kill z-fighting. **When:** panel lines, numbers, faction glyphs. **Cost:** +1 draw call each — instance repeats. **Read:** decals imply function/scale, not random surface noise.
+- **Fake contact shadow** — flat `PlaneGeometry` with a radial-gradient `CanvasTexture`, `{ transparent: true, depthWrite: false }`, under the object; scale/fade alpha with height. **When:** hovering or moving props that don't warrant a shadow map. **Cost:** one draw call, no shadow pass. **Read:** anchors floating objects so position reads.
+- **Emissive LOD signals** — swap `emissiveIntensity` or material by distance so far pickups/beacons still read, add geometry detail only up close. **When:** dense repeated signals. **Cost:** a material/uniform swap. **Read:** keep the signal color constant across LOD so identity survives the transition.
+- **Matcap props** — `new THREE.MeshMatcapMaterial({ matcap })` bakes lighting into one texture; no lights or env needed. **When:** background/stylized props. **Cost:** the cheapest lit-looking material, one texture. **Read:** matcap ignores scene lights, so never use it where a dynamic light or state glow must show on the surface.

package/skills/threejs-aaa-graphics-builder/references/technical-art.md

@@ -0,0 +1,167 @@
+# Technical Art For Three.js Games
+
+Use this reference before premium/AAA/showcase graphics work, shader/material/post-processing changes, VFX systems, generated/imported asset cleanup, LOD/instancing work, or any visual pass that could affect browser performance.
+
+Technical art is the bridge between art direction and real-time constraints. The goal is not maximum detail; it is readable authored detail that survives active gameplay, mobile viewports, and WebGL budgets.
+
+Research basis: Three.js exposes renderer diagnostics through `WebGLRenderer.info`; `InstancedMesh` is designed for many objects sharing geometry/materials; `LOD` switches objects by distance; `KTX2Loader` supports Basis Universal GPU texture workflows; MDN WebGL best practices emphasize eliminating errors, understanding system limits, eager deletion, batching draw calls, per-pixel VRAM budgets, smaller back buffers, mipmaps, compressed textures, and high-DPI discipline.
+
+## Technical Art Brief
+
+Before implementation, write:
+
+- Art direction in renderable terms: shapes, materials, lighting, VFX, camera, UI/world motifs.
+- Hero surfaces: what must look authored at active-play distance.
+- Support surfaces: what can be procedural, instanced, simplified, or culled.
+- Material kit: named roles, not one-off colors.
+- VFX language: event-driven effects and state readability.
+- Lighting stack: key/fill/rim/practical/contact/depth.
+- Render budget target: draw calls, triangles, textures, materials, DPR, shadow/post cost.
+- Asset strategy: procedural / generated 2D / generated 3D / hybrid / imported.
+- Mobile constraint: what changes first if performance or readability fails.
+
+## Render Budget Starting Points
+
+These are starting contracts, not universal limits — measure on the target game, and document every deliberate overrun as a tradeoff. The canvas inspector (`pnpm exec node ../game-test/scripts/inspect-threejs-canvas.mjs` when available, or any project `inspect:canvas` script) compares live diagnostics against the same numbers and reports over-budget rows.
+
+| Metric (worst active-play view) | Desktop tier | Mobile tier |
+| --- | --- | --- |
+| Draw calls (`info.render.calls`) | <= 300 | <= 150 |
+| Triangles (`info.render.triangles`) | <= 750k | <= 300k |
+| Geometries (`info.memory.geometries`) | <= 300 | <= 200 |
+| Textures (`info.memory.textures`) | <= 60 | <= 40 |
+| Texture memory (est.) | <= 256 MB | <= 128 MB |
+| Shadow-casting lights | <= 2 | 1 |
+| Shadow map size | <= 2048 | <= 1024 |
+| DPR cap | 2 | 1.5-2 |
+| Post passes (beyond render+output) | <= 2 | 0-1 |
+
+How to spend within them:
+
+- Draw calls: repeated world/detail pieces should be instanced or merged by material.
+- Triangles: spend on silhouettes near the camera; reduce background detail through LOD, impostors, or simplified meshes.
+- Materials: share material roles aggressively. Unique material count often grows faster than geometry count.
+- Textures: keep opaque large images compressed or small; avoid unique 2K+ textures for tiny repeated props.
+- Shadows: reserve real shadows for hero objects and grounding anchors; use blob/contact meshes for small repeated props (see `shader-cookbook.md` for the cheap contact-shadow recipe).
+- Post: every pass must earn its cost and preserve gameplay clarity; concrete chain settings are in `shader-cookbook.md`.
+
+Always report actual renderer diagnostics after the graphics pass: calls, triangles, geometries, textures, material count if available, post passes, shadow settings, DPR cap, and bottlenecks.
+
+## Material And Shader System
+
+Use a material kit of named shared roles, not one-off colors. Reuse each role across every mesh that plays the same part:
+
+- `bodyPrimary`: dominant player/world shell.
+- `bodySecondary`: panel contrast.
+- `trim`: rails, bevel highlights, borders, edge highlights.
+- `hazard`: danger surfaces, damage cues, warning stripes.
+- `reward`: collectible surfaces with readable value.
+- `shieldBoost`: shield, boost, and status states.
+- `glass`: cockpit, shield, lens, visor.
+- `emissiveSignal`: authored glow strips, status lights, beacon cores.
+- `groundContact`: dark matte surfaces and shadow receivers.
+- `decalDark` and `decalLight`: panel lines, scratches, numbers, icons.
+- UI/world signal colors shared between HUD and diegetic markers.
+
+Use `MeshStandardMaterial` for most surfaces. Use `MeshPhysicalMaterial` selectively for cockpit glass, clearcoat panels, iridescent shields, or premium hero details. Share materials across repeated meshes.
+
+Shader or `onBeforeCompile` work must have a reason:
+
+- State readability: shield ripple, heat, cloak, damage pulse.
+- Surface identity: water, forcefield, hologram, scanline, energy core.
+- Performance: cheap procedural variation instead of many textures.
+- Composition: separating player/threat/reward from background.
+
+Reject shader work that only adds noise, bloom bait, or hidden cost without improving active-play decisions. When shader work is justified, use the proven recipes in `shader-cookbook.md` (material values, onBeforeCompile patterns, sky, post chain) instead of improvising GLSL.
+
+## VFX Readability
+
+Every VFX effect must answer:
+
+- What event or state triggers it?
+- What does it tell the player?
+- Does it point to player, threat, reward, objective, or impact?
+- How long does it last?
+- Is it pooled or cheap to recreate?
+- Does it obscure collision, HUD, or the next decision?
+- Is there a reduced-motion fallback for heavy shake/strobe?
+
+Use event-driven VFX over permanent particle clutter:
+
+- Pickup: ring contraction, shard burst, score trail, brief HUD echo.
+- Hit/fail: impact ring, debris, damage flash, brief hit pause, camera impulse.
+- Boost/speed: engine trail, lane streaks, FOV ease, side streaks, audio pitch.
+- Near miss/combo: side spark, line snap, badge pulse, streak counter.
+- Shield/invulnerable: refractive shell, rim pulse, absorbed-impact ripple, material swap.
+- Spawn/despawn: anticipation pulse, telegraph, dissolve or scale snap.
+
+Pool effects and reuse geometries/materials. Permanent particle fields must stay cheap and sparse.
+
+## Instancing, LOD, And Culling
+
+Use instancing for many copies with the same geometry/material and different transforms: windows, bolts, lane markers, city lights, debris, foliage-like props, stars, crowd cards, track panels, repeated pickups, background modules.
+
+Rules:
+
+- Update `instanceMatrix.needsUpdate` and `instanceColor.needsUpdate` only after batched changes.
+- Compute or update bounds for instanced groups when transforms change materially.
+- Do not instance everything blindly. Different materials or constantly changing transforms can erase the win.
+- Keep collision separate from instanced visual detail.
+
+Use LOD when:
+
+- A hero/background object spans large distance ranges.
+- The silhouette matters near camera but not far away.
+- Imported/generated models are heavier than needed for background use.
+
+Rules:
+
+- Add hysteresis or distance gaps to reduce visible popping.
+- Use impostor cards or simplified silhouettes for far layers when appropriate.
+- Verify LOD transitions during gameplay camera motion, not only static orbit.
+
+## Generated And Imported Asset Cleanup
+
+For every imported GLB/FBX hero asset:
+
+- Confirm scale, pivot, forward/up orientation, bounds, and active-play silhouette.
+- Create a simple collision proxy independent from the visual mesh.
+- Inspect file size, approximate triangles, mesh count, material count, texture count, and animation clips when available.
+- Replace or simplify excessive materials and textures.
+- Add LOD or simplified background variant when reused many times.
+- Verify PBR material readability under the game's lighting, not only in a model viewer.
+- Keep API keys and temporary URLs out of client code and checked-in files.
+
+## Decals, Trim, And Surface Detail
+
+Prefer reusable surface systems:
+
+- Canvas-generated trim sheets for panel lines, markings, arrows, numbers.
+- Thin offset decal meshes for hazard marks, faction symbols, lane glyphs, scuffs.
+- Shared small textures for noise/wear rather than unique full-size images.
+- Procedural UV-independent detail for repeated hard-surface props.
+
+Surface detail must reinforce scale, function, faction, route, or state. Do not add random lines everywhere.
+
+## Color And Readability
+
+Readability beats palette consistency:
+
+- Threats differ from rewards by shape and motion, not only hue.
+- Interactables differ from background by silhouette/value/material.
+- UI signal colors match world signal colors.
+- Bloom/fog/darkness cannot be the primary separator.
+- Colorblind-risk information has shape/icon/motion backup.
+
+## Technical Art Report
+
+Report:
+
+- Technical art brief.
+- Material kit and shader/VFX decisions.
+- Instancing/LOD/culling strategy.
+- Render budget target and actual diagnostics.
+- Imported/generated asset cleanup evidence.
+- VFX readability checks.
+- Mobile/DPR/post/shadow tradeoffs.
+- Remaining visual performance risks.

package/skills/threejs-aaa-graphics-builder/references/visual-scorecard.md

@@ -0,0 +1,147 @@
+# Visual Scorecard
+
+Score active-play screenshots, not idle title screens or isolated showroom models. Use desktop and mobile screenshots when mobile is in scope.
+
+Scores are self-assessed against the anchors below, so they drift optimistic. Two countermeasures are mandatory for premium/AAA/showcase claims: cite Measured Evidence for the categories it supports, and run the Fresh-Eyes Review before finalizing.
+
+## Calibration Anchors
+
+Reference screenshots for score calibration are packaged in `threejs-aaa-graphics-builder/assets/scorecard-anchors/`:
+
+- `scene-1.jpg` — score ~1: primitive player and pickups on a flat sparse arena, utility HUD.
+- `scene-2.jpg` — score ~2: authored track kit, imported hero asset, designed genre HUD, intentional lighting.
+- `scene-3.jpg` — score ~2.5-3: dense layered world in active play, readable hero silhouette, event VFX, cohesive HUD.
+
+Before scoring World/environment, Hero/player, Materials/textures, or Lighting/render, view the anchors and compare: if your screenshot reads closer to `scene-1.jpg` than `scene-3.jpg` for that surface, the category is at most a 1-2 regardless of how much code was written.
+
+## Scoring Scale
+
+- 0: Placeholder. Default primitives, sparse world, unreadable state, debug UI, or no evidence.
+- 1: Basic styled. Playable and themed, but still obvious prototype assets, flat composition, repeated silhouettes, or generic UI.
+- 2: Premium stylized. Authored silhouettes, material/detail systems, readable state, cohesive UI/world, measured performance.
+- 3: Showcase. Strong art direction, memorable hero and world, dense authored detail, excellent readability, polished VFX/rendering, and diagnostics.
+
+## Categories
+
+1. Art direction.
+   - 0: No clear theme.
+   - 1: Theme is mostly colors/fog.
+   - 2: Theme affects forms, materials, UI, world, and feedback.
+   - 3: Distinct identity visible in every surface.
+2. Hero/player.
+   - 0: Default primitive stack.
+   - 1: Basic object with glow or simple attachments.
+   - 2: Authored silhouette, decals/trim, state cues, collision proxy.
+   - 3: Memorable model with layered construction and expressive feedback.
+3. Obstacles/enemies.
+   - 0: Cubes/cones/spheres.
+   - 1: Recolored repeated silhouette.
+   - 2: Three readable variants with telegraphs and material cues.
+   - 3: Varied family with animation, anticipation, and gameplay clarity.
+4. Rewards/interactables.
+   - 0: Plain sphere/ring/token.
+   - 1: Repeated object with simple glow.
+   - 2: Two authored forms with idle/collect states and UI feedback.
+   - 3: Desirable, animated, and clearly valued during motion.
+5. World/environment.
+   - 0: Flat plane, empty arena, box skyline.
+   - 1: Themed but sparse repeated blocks.
+   - 2: Layered prop kit with foreground/midground/background and scale cues.
+   - 3: Dense authored world that supports gameplay readability.
+6. Materials/textures.
+   - 0: Flat colors.
+   - 1: Basic roughness/metalness or emissive color.
+   - 2: Shared material roles, procedural decals, trim, panel lines, wear/noise.
+   - 3: Rich cohesive material language with measured texture/resource use.
+7. Lighting/render.
+   - 0: Default lights or unreadable darkness.
+   - 1: Fog/bloom used as main style.
+   - 2: Intentional tone mapping, exposure, key/fill/rim, contact, depth.
+   - 3: Cinematic but readable composition with disciplined post-processing.
+8. VFX/motion.
+   - 0: None or random particles.
+   - 1: Generic particles/trails.
+   - 2: Event-driven VFX for boost, pickup, hit, fail, combo, shield, or spawn.
+   - 3: High-impact effects that clarify gameplay and remain performant.
+9. UI/HUD.
+   - 0: Debug text or missing UI.
+   - 1: Generic stat-card dashboard.
+   - 2: Genre-specific HUD states, meters/icons, responsive text fit.
+   - 3: Cohesive game interface with strong hierarchy and polished transitions.
+10. Performance evidence.
+   - 0: No metrics after visual changes.
+   - 1: Informal "seems fine".
+   - 2: Renderer counts, build/browser QA, desktop/mobile screenshots, and technical-art budget notes.
+   - 3: Baseline/post metrics, bottleneck notes, budgets, optimized asset strategy, and VFX/readability tradeoffs.
+
+## Thresholds
+
+Premium:
+
+- Every category at least 2.
+- Average at least 2.3.
+- Desktop and mobile active-play screenshots captured when mobile is in scope.
+- Renderer diagnostics reported after graphics changes.
+
+Showcase:
+
+- At least six categories score 3.
+- No category below 2.
+- Average at least 2.7.
+- Performance evidence includes before/after or budget-aware notes.
+
+## Automatic Failures
+
+Any of these prevents a premium/AAA/showcase claim:
+
+- Active screenshot is primitive-dominant.
+- Main world is mostly stretched boxes, flat planes, or a sparse arena.
+- Hero asset is mostly default primitives plus glow.
+- Obstacles or rewards are one repeated silhouette.
+- HUD is mostly rectangular stat/debug cards.
+- Fog, darkness, bloom, or particles hide missing authored geometry.
+- UI overlaps the play path, clips text, or fails mobile safe areas.
+- The game is not playable through real input.
+- No active-play screenshot was captured.
+- No renderer diagnostics were collected after major graphics work.
+- No technical-art budget or imported/generated asset diagnostics were reported for premium graphics work.
+
+## Measured Evidence
+
+Run the canvas inspector (`pnpm exec node` on `../game-test/scripts/inspect-threejs-canvas.mjs`, or a project `inspect:canvas` script) on desktop and mobile and cite its `metrics` and `renderBudget` blocks in the scorecard. The numbers are advisory signals, not gates, but they must be reported and low values must be explained rather than ignored:
+
+- `colorEntropyBits` below ~3.0 or `dominantColorShare` above ~0.6 suggests a sparse, flat scene — supporting evidence against World/environment or Materials/textures scores above 2.
+- `edgeDensity` below ~0.04 suggests primitive-dominant or empty framing — supporting evidence against World/environment and Hero/player scores above 2.
+- `luminance.contrast` below ~60 suggests fog/darkness compression — supporting evidence against Lighting/render scores above 2.
+- `renderBudget` rows over the tier budget require a documented tradeoff in the technical-art budget (see `technical-art.md`).
+- Renderer diagnostics (calls, triangles, geometries, textures) back the Performance evidence category.
+
+## Fresh-Eyes Review
+
+The builder must not be the only grader. For premium/AAA/showcase claims:
+
+- If the runner supports subagents (Task tool or equivalent), spawn a reviewer with ONLY: the screenshots, this scorecard file, and the inspector metrics JSON. No build context, no prior scores. The reviewer must receive the COMPLETE capture set — every captured state, desktop and mobile — never a hand-picked subset; a curated selection can hide weak states or miss content the builder knows exists (capture states with the inspector's `--state` flag so nothing is gated behind live play). The reviewer fills the scorecard independently; reconcile by taking the lower score per category unless concrete evidence overturns it. Report both score sets.
+- If subagents are unavailable, run an adversarial self-review before finalizing: for each category, write one sentence making the strongest case that the score is a 1, citing what is visible in the screenshot; only then assign the score. Include these sentences in the report.
+
+## Report Format
+
+```text
+Visual scorecard:
+- Art direction: before X / after Y - evidence:
+- Hero/player: before X / after Y - evidence:
+- Obstacles/enemies: before X / after Y - evidence:
+- Rewards/interactables: before X / after Y - evidence:
+- World/environment: before X / after Y - evidence:
+- Materials/textures: before X / after Y - evidence:
+- Lighting/render: before X / after Y - evidence:
+- VFX/motion: before X / after Y - evidence:
+- UI/HUD: before X / after Y - evidence:
+- Performance evidence: before X / after Y - evidence:
+Measured evidence: colorEntropyBits / edgeDensity / luminance.contrast /
+  dominantColorShare per viewport, renderer diagnostics, render budget rows
+Fresh-eyes review: subagent scores or adversarial self-review notes
+Average:
+Automatic failures remaining:
+```
+
+If any category remains below threshold, state the exact next pass instead of declaring completion.