evomeme-dev 0.1.7

package/skills/threejs-aaa-graphics-builder/references/graphics-prompt-templates.md

@@ -0,0 +1,236 @@
+# Three.js AAA Graphics Prompt Templates
+
+Reusable prompt templates packaged with this skill. Use only templates relevant to the current request, and adapt placeholders to the game/project context.
+
+---
+
+# AAA Graphics Production Pass Prompt
+
+Use `threejs-aaa-graphics-builder` to upgrade this Three.js game from basic prototype visuals to premium browser-game graphics.
+
+Current screenshot blockers:
+- 
+
+Target art direction:
+- 
+
+Required pass:
+- Score current screenshots with `visual-scorecard.md`.
+- Add or improve the graphics architecture from `implementation-blueprint.md`.
+- Add the technical art brief from `technical-art.md`: material kit, shader/VFX purpose, instancing/LOD/culling, imported asset cleanup, renderer budget, mobile tradeoffs.
+- Build material library, procedural texture/decal helpers, model factories, world prop kit, VFX system, lighting/render pipeline, and diagnostics.
+- Prefer procedural model factories or user-provided GLB/FBX for high-value hero/player, character, creature, vehicle, building, weapon, pickup, or boss forms.
+- For 2D concepts, texture references, decals, logos, icons, GUI art, skies, or backgrounds: prefer procedural/CSS/canvas; use user-supplied images or remote MCP `evomeme_generate_game_image` — local image generator skill removed.
+- Upgrade hero/player, obstacles/enemies, rewards/interactables, world kit, HUD cohesion, lighting, effects, and renderer metrics.
+
+Do not count as completion:
+- Recolored boxes/cones/spheres.
+- Glow, fog, or darkness hiding missing detail.
+- One improved object while world/obstacles/UI remain placeholders.
+- Idle/showroom screenshots only.
+- Missing renderer diagnostics after visual density changes.
+
+Verification:
+- Capture active gameplay desktop and mobile screenshots.
+- Report visual score before/after.
+- Report draw calls, triangles, geometries, textures, material count, DPR cap, shadow/post settings, and instancing/LOD/culling decisions when available.
+- Run build, browser, console/page error, nonblank canvas, interaction, and responsive checks.
+- Continue until every scorecard category is at least 2, or report exactly why the target was not reached.
+
+---
+
+# Before/After Visual Critique Prompt
+
+Use `threejs-aaa-graphics-builder` to critique this Three.js game's current screenshots with the visual scorecard and produce a prioritized graphics plan.
+
+Evidence to gather:
+- Desktop screenshot.
+- Mobile screenshot.
+- Optional before/after screenshots if a pass was already completed.
+- Renderer diagnostics if available.
+- Notes on the game genre, core verb, and target mood.
+
+Critique dimensions:
+- Gameplay readability.
+- UI hierarchy and text fit.
+- Procedural model silhouette and fidelity.
+- Material, lighting, shadows, color, and contrast.
+- Camera composition and motion clarity.
+- Mobile framing and touch/control readability.
+- Performance risk from proposed upgrades.
+
+Output:
+- Pass/fail on whether the game looks polished enough for the current milestone.
+- Top five blockers ordered by player impact.
+- Recommended next skill/phase: `threejs-aaa-graphics-builder`, `game-ui`, `game-test`, or `game-test`.
+- Concrete acceptance criteria for the next pass.
+
+---
+
+# Material, Lighting, and Render Quality Pass Prompt
+
+Use `threejs-aaa-graphics-builder` for scene-level render quality, material libraries, model materials, geometry factories, and visual scoring.
+
+Current problem:
+- 
+
+Target look:
+- 
+
+Work areas:
+- Renderer color space, tone mapping, exposure, shadow settings, DPR cap.
+- Key/fill/rim/environment lighting.
+- Material roughness, metalness, emissive accents, vertex colors, generated textures, and decals.
+- Fog, background, post-processing, and feedback effects only where they improve readability.
+- Camera composition and gameplay-distance readability.
+
+Constraints:
+- Improve lighting and materials before adding heavy post-processing.
+- Keep threats, pickups, player, and objective readable during motion.
+- Avoid excessive bloom, low-contrast fog, and particle clutter.
+- Re-measure renderer info if visual complexity changes.
+
+Verification:
+- Capture desktop and mobile screenshots.
+- Check console/page errors and nonblank canvas pixels.
+- Compare renderer calls/triangles/textures before and after when practical.
+- Play the core loop and confirm effects do not hide gameplay information.
+
+---
+
+# Technical Art Pass Prompt
+
+Use `threejs-aaa-graphics-builder` for a technical-art pass on this Three.js game.
+
+Current visual/performance risk:
+- 
+
+Target art direction:
+- 
+
+Required pass:
+- Load `technical-art.md`.
+- Write a technical art brief: hero surfaces, support surfaces, material kit, VFX language, lighting stack, render budget, asset strategy, mobile constraint.
+- Convert art direction into renderable systems: materials, decals/trim, shaders, VFX, LOD, instancing, culling, imported asset cleanup.
+- Make threats, rewards, player state, and objectives readable by shape/motion/value, not color alone.
+- Keep API/generated asset calls out of browser runtime.
+
+Verification:
+- Capture active desktop and mobile screenshots.
+- Report renderer diagnostics: calls, triangles, geometries, textures, material count when available, DPR cap, shadow/post settings.
+- Report imported/generated asset diagnostics when relevant: file size, bounds, scale, orientation, collision proxy, triangles/materials/textures/clips when available.
+- Report VFX readability: trigger, duration, player-facing meaning, and reduced-motion concern if applicable.
+- State what was optimized, what was intentionally left rich, and remaining performance risks.
+
+---
+
+# Procedural Hero Asset Pass Prompt
+
+Use `threejs-aaa-graphics-builder` to create or upgrade a high-fidelity scratch-built Three.js hero asset.
+
+Asset brief:
+- Role:
+- Silhouette:
+- Scale:
+- Camera distance:
+- Style references:
+- Performance budget:
+
+Requirements:
+- Build a reusable model factory that returns a named `THREE.Group`.
+- Establish a recognizable silhouette before adding small detail.
+- Add secondary and tertiary detail through bevels, trims, panels, ridges, tubes, decals, emissive elements, and material contrast.
+- Add visible subassemblies, not just a few primitives: shell/body, core/cockpit, trims/rails, engines/emitters, decals/surface marks, and state feedback when relevant.
+- Use shared geometries/materials where possible.
+- Use PBR-style materials, shadows, color management, and lighting intentionally.
+- Keep collision or gameplay proxies simpler than the visual mesh.
+
+Avoid:
+- Placeholder stacks of primitives.
+- Detail visible only from a showroom camera.
+- Excessive segment counts, unique materials, or draw calls without gameplay value.
+- Glow-only upgrades that leave the silhouette primitive.
+
+Verification:
+- Build and run locally.
+- Capture gameplay-camera screenshot and one inspection screenshot if useful.
+- Report renderer info before/after when available.
+- Verify the asset reads clearly at desktop and mobile gameplay distances.
+
+---
+
+# Visual Polish Prompt
+
+Use `threejs-aaa-graphics-builder` to improve the game's visual clarity and identity.
+
+Use focused prompts instead when the main problem is narrower:
+- Use `../../game-ui/references/ui-prompt-templates.md` for HUD/menu/interface quality prompts.
+- Use the procedural hero asset or world prop kit sections in this file for scratch-built model fidelity inside the AAA graphics phase.
+- Use the before/after visual critique section in this file when priorities are unclear.
+
+Target feel:
+- 
+
+Constraints:
+- Keep the game readable during motion.
+- Avoid generic purple gradients, excessive bloom, particle clutter, and static showroom composition.
+- Prefer purposeful lighting, color contrast, silhouettes, material variation, and procedural geometry that supports gameplay.
+- Hand off substantial UI craft to `game-ui`; keep model/world/render construction under `threejs-aaa-graphics-builder`.
+- Keep performance visible while polishing.
+
+Verification:
+- Capture before/after screenshots where possible.
+- Check desktop and mobile framing.
+- Confirm the game remains interactive and no console errors were introduced.
+
+---
+
+# World Prop Detail Kit Pass Prompt
+
+Use `threejs-aaa-graphics-builder` to create a reusable procedural prop/detail kit for this Three.js game's world.
+
+World role:
+- 
+
+Kit requirements:
+- Define 4-8 reusable prop factories with shared materials.
+- Include scale variants, color/material variants, and clear placement rules.
+- Use instancing or shared geometry/materials for repeated details.
+- Add visual detail that supports navigation, danger, reward, or atmosphere.
+- Keep the kit coherent with the existing game UI and world lighting.
+- For city/runner worlds, include skyline modules with setbacks/window bands/roof details, foreground speed props, track hardware, signage/cables/supports, and distant parallax layers.
+
+Performance constraints:
+- Avoid unique material explosions.
+- Keep repeated props instanced or pooled when practical.
+- Track draw calls, triangles, geometries, textures, and frame impact.
+
+Verification:
+- Capture before/after screenshots from gameplay camera.
+- Check desktop and mobile readability.
+- Report renderer diagnostics.
+- Confirm no console/page errors and no obvious collision/occlusion issues.
+- If the world is still dominated by stretched boxes, continue the prop-kit pass.
+
+---
+
+# Fresh-Eyes Scorecard Review Prompt
+
+Use for the independent review pass required by `visual-scorecard.md` for premium/AAA/showcase claims. Give the reviewer ONLY the inputs below — no build history, no prior scores, no description of the work performed.
+
+Inputs:
+- The COMPLETE screenshot capture set — every captured state, desktop and mobile, never a hand-picked subset: <paths>
+- Scorecard rubric: `visual-scorecard.md`
+- Calibration anchors: `threejs-aaa-graphics-builder/assets/scorecard-anchors/`
+- Inspector metrics JSON: <paths>
+
+Task:
+- Score all ten scorecard categories from the screenshots alone, using the 0-3 anchors and calibration images.
+- Cross-check scores against the metrics (colorEntropyBits, edgeDensity, luminance.contrast, dominantColorShare, renderBudget) and flag any score the numbers contradict.
+- List every automatic failure you can see in the screenshots.
+- Do not give benefit of the doubt: if a surface could be a 1 or a 2, score it 1 and say what visible change would earn the 2.
+
+Report:
+- Ten category scores with one-sentence visual evidence each.
+- Automatic failures observed.
+- The three highest-impact changes to raise the lowest scores.

package/skills/threejs-aaa-graphics-builder/references/implementation-blueprint.md

@@ -0,0 +1,161 @@
+# AAA Graphics Implementation Blueprint
+
+Use this when a Three.js game reads as basic even after it is playable. The goal is a production graphics architecture that can be iterated, scored, profiled, and reused. For premium/AAA/showcase work, also load `technical-art.md` and treat the technical art brief and budget as part of the graphics architecture.
+
+## Recommended Ownership
+
+Directory layout follows `../threejs-3d-game/references/file-structure.md`. Place graphics modules under `src/game/three` (pure Three, no React) and `src/game/assets` (manifest / import registry). Wire lighting, post, and VFX from `GameCanvas` `useFrame` / R3F scene tree — do not create a parallel imperative `src/systems` game loop.
+
+```text
+src/game/assets/MaterialLibrary.ts
+src/game/assets/ProceduralTextures.ts
+src/game/assets/DecalShapes.ts
+src/game/assets/ModelDiagnostics.ts
+src/game/assets/ImportedAssetRegistry.ts
+src/game/assets/manifest.ts
+src/game/three/modelFactories/HeroFactory.ts
+src/game/three/modelFactories/ObstacleFactory.ts
+src/game/three/modelFactories/RewardFactory.ts
+src/game/three/modelFactories/WorldPropKit.ts
+src/game/three/LightingRig.ts
+src/game/three/RenderPipeline.ts
+src/game/three/VfxSystem.ts
+src/game/three/WorldArtDirector.ts
+src/game/three/QualityDiagnostics.ts
+src/ui/components/GameCanvas.tsx   # R3F mount + useFrame orchestration
+```
+
+Keep these boundaries lightweight. In small projects, a single file can contain multiple factories, but the concepts must remain separate: materials, authored geometry, repeated props, effects, render settings, and diagnostics.
+
+## Hybrid Asset Pipeline
+
+Choose the asset path per surface:
+
+- Procedural Three.js: hero forms, repeated detail, simple props, rails, track parts, decals, collision proxies, VFX geometry, debug-friendly primitives.
+- User-provided / remote MCP / procedural 2D: concept sheets, texture references, trim sheets, decals, icons, logos, skies, backgrounds, UI art; user-provided GLB/FBX for heroes when available.
+- Hybrid: 2D reference (user/remote/procedural) -> procedural 3D factory or user GLB import -> procedural collision/VFX/prop kit -> visual scorecard.
+
+Prefer procedural authorship or user-provided models.
+
+Use user-provided GLB/FBX when fidelity will materially improve the active screenshot. Keep repeated small props as instancing/procedural kits.
+
+Before finishing a premium graphics pass, note the chosen source per high-value surface (procedural / hybrid / user-provided / audio skill) and the outputs or real blocker for each surface.
+
+## Production Surfaces
+
+A premium pass must touch every weak visible surface:
+
+- Hero/player: authored silhouette, state feedback, decals/trim, readable front/up/side, collision proxy.
+- Hazards/enemies: at least three distinct silhouettes with telegraphs and material cues.
+- Rewards/interactables: at least two forms with collection states and motion/VFX hooks.
+- World kit: foreground, playable lane/arena, midground, background/parallax, set dressing, scale cues.
+- Materials/textures: shared PBR/stylized material library, procedural panel lines, noise, trim, wear, emissive masks.
+- Lighting/render: color space, tone mapping, exposure, shadows/contact, fog/depth, post-processing discipline.
+- VFX/motion: event-driven bursts, trails, impact rings, speed lines, shield/boost states, pickup/fail feedback.
+- UI/world cohesion: UI colors, icons, alerts, and meters echo gameplay materials and status colors.
+- Diagnostics: renderer counts, material/geometry/texture counts, screenshots, scorecard.
+
+For imported generated 3D assets, also require downloaded GLB/PBR output, import wrappers with scale/pivot/bounds, simple collision proxies, animation clips when relevant, and triangle/material/texture/file-size diagnostics.
+
+## Technical Art Contract
+
+Before broad implementation, write the technical art brief and render budget from `technical-art.md`: hero vs support surfaces, render budget target, material kit roles, shader/VFX purpose, instancing/LOD/culling plan, and imported asset cleanup. Treat that brief as part of this graphics architecture.
+
+Do not add costly effects until this contract exists. A technical-art pass should make the scene more authored and more measurable at the same time.
+
+## Material Library
+
+Implement the named material-role kit defined in `technical-art.md` (`bodyPrimary`, `bodySecondary`, `trim`, `hazard`, `reward`, `glass`, `emissiveSignal`, `groundContact`, `decalDark`/`decalLight`, plus shared UI/world signal colors) in `src/game/assets/MaterialLibrary.ts`. Create named roles instead of one-off colors and share materials across repeated meshes.
+
+## Procedural Texture And Decal Kit
+
+Use canvas textures, shape geometry, or thin offset meshes for detail that would otherwise require external assets:
+
+- Panel lines and access hatches.
+- Trim sheets and edge bands.
+- Window strips, city light grids, arena markings.
+- Hazard stripes, arrows, target indicators, lane glyphs.
+- Scratches, wear, noise, dirt, heat tint, scorch marks.
+- UI/world icon motifs reused in HUD and diegetic markers.
+
+Set texture filtering, mipmaps, repeat/wrap, color space, and anisotropy intentionally. Avoid unique full-size textures for tiny repeated marks.
+
+Use procedural canvas textures, user-supplied art, or remote MCP for high-value 2D source art: terrain/rock/asphalt/snow/moss texture references, sci-fi trim sheets, signs, hazard stripes, cockpit decals, sky/background plates, menu/loading art, faction logos, pickup icons, ability icons, and GUI glyphs. Use the resulting images either as actual 2D assets or as image-to-3D inputs.
+
+## Model Factories
+
+Factories should return a grouped object plus metadata:
+
+```ts
+type ModelFactoryResult = {
+  root: THREE.Group;
+  collision?: THREE.Object3D;
+  lod?: THREE.LOD;
+  bounds?: THREE.Box3;
+  diagnostics?: {
+    meshes: number;
+    materials: number;
+    geometries: number;
+    triangles?: number;
+  };
+};
+```
+
+Use named child meshes for readable debugging. Separate visual detail from collision proxies. Keep repeated detail instanced where practical.
+
+For imported generated 3D models, create an `ImportedAssetRegistry` or loader wrapper that returns similar metadata: root group, bounds, collision proxy, animation clips, and diagnostics. Never put 3D/image/audio generation API calls in browser runtime code.
+
+## World Art Director
+
+Before building layers, load `../../game-art/references/scene-profiles.md` and pick a `scene_profile_id` (read 3D · Lighting rail only). That file owns the early spatial contract; this section owns production layering.
+
+Build the world as layers (same names as `scene-profiles.md`):
+
+- Play layer: ground, lanes, rails, objective path, hazards, pickups.
+- Near layer: speed props, signs, arches, barriers, debris, foreground occluders used carefully.
+- Mid layer: buildings, cliffs, hangars, pillars, platforms, arena machinery.
+- Far layer: skyline, terrain silhouettes, nebula/cloud/fog cards, parallax planes.
+- Motion layer: speed lines, particles, trail strips, dust, sparks, screen-space UI feedback.
+
+Every layer should support gameplay readability. Do not obscure threats or the next decision. Reject sparse flat arenas and stretched-box skylines per `visual-scorecard.md` and the active paradigm's Reject if.
+
+## Render Pipeline
+
+Own renderer / R3F `Canvas` gl setup in one place (`GameCanvas` + `game/three/RenderPipeline.ts`):
+
+- `outputColorSpace = THREE.SRGBColorSpace`.
+- Tone mapping and exposure selected for the art direction.
+- DPR capped for mobile and high-density displays.
+- Shadows enabled only for objects that benefit from grounding.
+- Post-processing is limited and measured: bloom, vignette, chromatic aberration, film grain, or color grade only when they improve authored forms.
+- Prefer R3F to present the frame. If an EffectComposer is required, drive `composer.render()` from `useFrame` and disable R3F's default render for that path — do not also call a separate outer `renderer.render` game loop.
+- Resize updates canvas, renderer, camera, composer, and UI CSS variables.
+
+## VFX System
+
+Implement the event-driven VFX language from `technical-art.md` in `src/game/three/VfxSystem.ts`. Effects should be pooled, readable, and tied to state; they must clarify state instead of adding permanent particle clutter. Prefer triggering from `gameBus` / simulation facts, not from HUD components.
+
+## Diagnostics
+
+Own diagnostics in `src/game/three/QualityDiagnostics.ts` and expose snapshots on `window.__THREE_GAME_DIAGNOSTICS__` from `GameCanvas` or `game/bridge`. Report the renderer diagnostics defined in `technical-art.md` (calls, triangles, geometries, textures, material count, DPR/post/shadow settings), plus these architecture-specific counts:
+
+- Scene mesh count, instanced mesh count, unique materials/geometries/textures.
+- Approximate visible prop counts by layer.
+- Screenshot paths and visual scorecard.
+- Performance notes after post-processing, shadows, or many repeated props.
+
+## Browser Game Budgets
+
+Use the render budget starting points and instancing/LOD/culling guidance in `technical-art.md`, then measure on the target game after every major graphics pass.
+
+## Implementation Order
+
+1. Score active screenshots and identify the weakest three categories.
+2. Add material and diagnostic foundations.
+3. Decide which weak surfaces need procedural, user-provided/remote 2D, imported user GLB, or hybrid treatment.
+4. Build/import hero/player and one complete obstacle/reward family.
+5. Add world prop kit and layered composition.
+6. Add lighting/render polish.
+7. Add event-driven VFX.
+8. Re-score desktop/mobile active screenshots.
+9. Optimize measured bottlenecks.

package/skills/threejs-aaa-graphics-builder/references/model-recipes.md

@@ -0,0 +1,146 @@
+# Procedural Model Recipes
+
+These recipes are for scratch-built Three.js models when external art assets are unavailable. The goal is not photorealism; it is authored, layered, readable, premium browser-game art.
+
+## Modeling Principles
+
+- Start with silhouette. A model should be recognizable as a dark shape before materials or glow.
+- Combine primitive bases with authored geometry: extrusions, bevels, curves, tubes, lathes, custom buffers, decals, trim, and instanced micro-detail.
+- Use asymmetry and functional parts: hinges, fins, vents, handles, rails, brackets, sensors, cables, panels, bolts.
+- Put detail where the camera sees it. Spend triangles on player-facing surfaces, not hidden undersides.
+- Create state variants through material swaps, animated child parts, emissive strips, and VFX sockets.
+- Keep a simple collision proxy separate from the detailed visual group.
+- Use shared geometries/materials and instancing for repeated bolts, panels, lights, windows, spikes, rocks, or rail segments.
+- Name important child meshes: `cockpitGlass`, `leftEngine`, `hazardTeeth`, `pickupCore`, `collisionProxy`.
+
+## Minimum Premium Asset Pass
+
+For a game that asks for premium/AAA/showcase quality, build at least:
+
+- One hero/player model with readable front/up/side and three state cues.
+- Three obstacle/enemy variants with unique silhouettes and telegraphs.
+- Two reward/interactable variants with idle and collect states.
+- One world prop kit with at least eight reusable parts.
+- One material kit with trim, decals, panel lines, and emissive masks.
+- Collision proxies and renderer diagnostics for the above.
+
+## Hero Vehicle Recipe
+
+Use for runners, racers, hovercraft, spaceships, drones, or arcade vehicles.
+
+- Core hull: `ExtrudeGeometry` or custom tapered `BufferGeometry`, not just a box.
+- Nose/front: wedge, intake, sensor strip, bumper, or blade shape.
+- Cockpit/core: glass dome from sphere/lathe segments, beveled capsule, or faceted canopy.
+- Engines: cylinders/cones/tubes with nozzle rings, inner emissive discs, heat fins, and trail sockets.
+- Wings/fins: extruded triangular or curved plates with bevel/trim lines.
+- Undercarriage: skids, landing pads, rail clamps, suspension arms, or thruster pods.
+- Decals: panel lines, numeric marks, faction glyph, hazard ticks, small bolts.
+- State cues: boost flares, shield shell, damage scorch, pickup glow, overheat red.
+- Collision proxy: one capsule/box/sphere group matching gameplay footprint.
+
+Reject if the hero is mostly a box with two cylinders and a glow.
+
+## Hero Character Recipe
+
+Use for arena fighters, brawlers, platformers, or stylized third-person games.
+
+- Body mass: torso, pelvis, head/helmet, limbs with tapered capsule/cylinder custom scales.
+- Rig illusion: separate shoulders, elbows, knees, wrists, ankles, belt, backpack, armor plates.
+- Face/identity: visor, mask, hair/helmet crest, color-blocked silhouette, weapon/tool.
+- Animation-ready pivots: group limbs under named joints even if animation is procedural.
+- Material zones: skin/fabric/armor/metal/glass/emissive accents.
+- State cues: hit flash material, shield ring, attack trail socket, stamina/charge glow.
+- Collision proxy: capsule or cylinder independent of mesh detail.
+
+Reject if the character reads as stacked spheres/cylinders with no costume, joints, or silhouette.
+
+## Obstacle And Enemy Families
+
+Build distinct gameplay reads:
+
+- Low barrier: ground-hugging slab, spikes, rails, caution panels, animated warning light.
+- Gate/arch: overhead frame, side posts, pulsing pass/avoid lane, moving shutters.
+- Moving hazard: rotating arm, sweeper beam, drone, crusher, sliding block, orbiting mines.
+- Trap/zone: laser grid, electric puddle, collapsing tile, gravity well, proximity mine.
+- Enemy: body core, sensor/head, weapon, shield, locomotion/hover base, attack telegraph.
+
+Each variant needs:
+
+- Unique silhouette.
+- Material cue for danger.
+- Telegraph from distance.
+- Animation or state change.
+- Collision proxy.
+- Low-cost repeated detail.
+
+Reject if all hazards are recolored cubes/cones.
+
+## Reward And Interactable Recipes
+
+Rewards should be readable and desirable during motion.
+
+- Token: outer ring, inner core, value icon, shimmer cards, collect burst socket.
+- Shard: faceted crystal, metal bracket, orbiting chips, emissive seam.
+- Capsule: glass shell, suspended item, end caps, rotating label strip.
+- Power-up: icon silhouette matched to effect, color and shape differ from score pickups.
+- Objective item: larger scale, unique motion, UI echo, stronger lighting/VFX.
+
+States:
+
+- Idle: slow rotation, pulse, bob, or orbit.
+- Attract: line/trail toward player.
+- Collect: vanish, burst, score trail, HUD meter update.
+
+Reject if rewards are plain spheres or torus rings without state feedback.
+
+## World Prop Kit
+
+Build modular props that can be instanced and recombined:
+
+- Track/road: lane plates, seams, arrows, side rails, guard segments, repair panels.
+- Arena: boundary rings, floor tiles, spawn pads, cover blocks, goal markers.
+- City/sci-fi: window strips, antennas, rooftop units, bridge trusses, pylons, billboards.
+- Nature: rocks from custom faceted buffers, cliffs, roots, crystals, grasses as cards.
+- Industrial: pipes, vents, cables, tanks, crates, gantries, lights, warning signs.
+- Space/air: debris panels, satellites, buoys, asteroid chunks, parallax dust.
+
+Layer the kit:
+
+- Near props create speed and scale.
+- Mid props define the playable corridor.
+- Far props create depth without stealing draw calls.
+
+Reject if the world is mostly stretched boxes or a flat plane.
+
+## Procedural Geometry Techniques
+
+- `ExtrudeGeometry`: panels, fins, wings, badges, UI/world glyphs, signs.
+- `LatheGeometry`: capsules, domes, engines, pipes, bottles, turret bases.
+- `TubeGeometry`: cables, rails, trails, conduits, curved weapons.
+- Custom `BufferGeometry`: tapered hulls, rocks, shards, wedges, low-poly terrain.
+- `ShapeGeometry`: decals, flat icons, trim strips, hazard markers.
+- `InstancedMesh`: windows, bolts, lane markers, debris, grass, lights, small props.
+- `LOD`: hero/background variants and dense prop reductions.
+
+Use bevel-like layering when real bevel geometry is too expensive: duplicate thin trim meshes, edge strips, or slightly offset darker panels.
+
+## Material And Detail Rules
+
+- Use roughness/metalness contrast, not only hue contrast.
+- Use emissive for authored signals, not entire objects.
+- Use glass/clearcoat sparingly on hero details.
+- Add darker contact material under important objects.
+- Use decals to imply scale and function.
+- Reuse UI icon shapes as world decals for cohesion.
+
+## Diagnostics Checklist
+
+After a model pass, report:
+
+- Mesh count.
+- Instanced mesh count.
+- Unique geometries/materials/textures.
+- Approximate triangle count if available.
+- Collision proxies included.
+- LOD or culling strategy for repeated/background props.
+- Active-play screenshots, not only showroom renders.

package/skills/threejs-aaa-graphics-builder/references/render-recipes.md

@@ -0,0 +1,90 @@
+# Render, Lighting, And VFX Recipes
+
+Use this after authored forms exist. Rendering polish cannot compensate for missing models, props, or readable gameplay silhouettes.
+
+## Renderer Setup
+
+- Set `renderer.outputColorSpace = THREE.SRGBColorSpace`.
+- Choose tone mapping deliberately. `ACESFilmicToneMapping` often works for cinematic stylized scenes; simpler tone mapping can be better for bright arcade readability.
+- Tune exposure against active gameplay, not a static title view.
+- Cap DPR, especially on mobile. Start around `Math.min(devicePixelRatio, 1.5 or 2)` and profile.
+- Update renderer, camera, composer, and CSS UI dimensions on resize.
+- Use a transparent or explicit background only when composition requires it.
+
+## Camera Composition
+
+- Keep the next decision visible. The camera should show player, immediate threat/reward, and route.
+- Add depth layers: foreground speed elements, playable midground, background scale cues.
+- Use FOV and camera distance to communicate speed without hiding hazards.
+- Use camera shake sparingly and clamp intensity.
+- Add camera impulses for hits/near misses/boosts, then ease back quickly.
+- Check mobile framing separately; vertical and narrow layouts often need different offsets.
+
+## Lighting Stack
+
+Use a small readable stack:
+
+- Key light: defines form and direction.
+- Fill light: keeps gameplay objects legible.
+- Rim/back light: separates player and hazards from background.
+- Practical/emissive lights: authored beacons, engines, pickups, arena markers.
+- Contact shadows or shadow blobs: ground important objects.
+
+Avoid many unmeasured dynamic lights. Prefer baked-looking material/emissive cues, light cards, or small unlit decals for repeated signals.
+
+## Shadows And Contact
+
+- Use shadows for hero/player, major hazards, and large world anchors.
+- Use smaller shadow maps and limited shadow casters when profiling shows cost.
+- Add cheap contact discs or transparent planes for pickups/hovering objects.
+- Tune bias to avoid acne and peter-panning.
+- Do not let shadows hide collision reads.
+
+## Materials
+
+Define material roles with the material kit in `technical-art.md` (`MeshStandardMaterial` for most surfaces, `MeshPhysicalMaterial` only where the premium feature is visible). At render time:
+
+- Prefer material contrast before post effects: matte vs glossy, metal vs plastic, transparent vs opaque, bright trim vs dark contact.
+- Use emissive maps or small emissive parts for signals instead of making entire objects glow.
+- Keep material roles matched across UI and world: danger, reward, shield, boost, objective.
+
+## Fog, Background, And Depth
+
+- Fog should reveal depth and mood, not hide empty worlds.
+- Layer background silhouettes at varied scales and heights.
+- Add parallax or slow-moving far layers for motion-heavy games.
+- Avoid single flat sky colors when the world needs scale; use gradients only as support, not the whole art direction.
+- Keep hazards/rewards readable against fog and background values.
+
+## Post-Processing
+
+Use post as a finishing pass:
+
+- Bloom: only authored emissive elements, not all bright materials.
+- Vignette: subtle focus, never heavy darkness.
+- Film grain/noise: low opacity; avoid compression-like artifacts.
+- Chromatic aberration: only brief event-driven impacts or very subtle style.
+- Motion blur/trails: prefer geometry trails or particles that preserve gameplay clarity.
+
+Always compare screenshots with post enabled/disabled and profile the cost.
+
+## Event-Driven VFX
+
+Tie effects to state using the event-driven VFX language in `technical-art.md` (pickup, hit/fail, boost/speed, near miss/combo, shield/invulnerable, spawn/despawn). Pool effects, reuse geometries/materials, and keep permanent particle fields cheap and sparse.
+
+## Readability Checks
+
+During active play, confirm:
+
+- Player orientation is clear.
+- Threats differ from rewards by both shape and material.
+- Important pickups are visible before reaction time expires.
+- UI feedback does not cover the play path.
+- VFX clarifies state instead of obscuring collisions.
+- Background contrast does not swallow dark objects.
+
+## Performance Checks
+
+After render changes, report the renderer diagnostics from `technical-art.md` (calls, triangles, geometries, textures, materials, DPR/post/shadow settings), plus FPS/frame time and composer/post pass count when available.
+
+If performance drops, reduce post/shadow cost first, then cull/LOD/instance, then reduce asset density only where it is least visible.