evomeme 0.1.9 → 0.1.10-beta.13

package/dist/skills/zh-CN/godot-3d-game/references/import-and-wrapper-scenes.md

@@ -0,0 +1,20 @@
+# Import and wrapper scenes
+
+Godot imports GLB as a `PackedScene`. Keep that import generated and reproducible. Put scripts, collision, navigation, interaction markers and gameplay signals in a separate authored scene.
+
+Recommended hierarchy:
+
+```text
+EntityRoot (gameplay/world transform)
+  CollisionRoot
+  VisualParent
+    <asset_id>_A3AlignmentRoot (canonical recipe)
+      ImportedGLBRoot (unchanged)
+```
+
+Do not edit the imported GLB child transform to fix orientation. Do not put the canonical recipe on `EntityRoot`, because its transform changes during gameplay. Do not wrap an inherited scene and then call the loader again inside it.
+
+When the canonical asset changes, resync and let the alignment key replace the visual root. Preserve authored gameplay nodes outside that root.
+
+For full scenes/maps with `pivot=origin`, instance under a world parent with identity transform. A level streaming offset is gameplay/world placement and belongs above the canonical root; it must not be written back as asset repair.
+

package/dist/skills/zh-CN/godot-3d-game/references/physics-colliders.md

@@ -0,0 +1,13 @@
+# Physics and colliders
+
+Collision belongs to the gameplay scene, not inside the generated canonical package unless the source contract explicitly carries collider data.
+
+- Use simple authored primitives for dynamic actors where possible.
+- Use trimesh collision only for appropriate static environment geometry.
+- Keep collision and visual roots as siblings under the entity so visual alignment does not silently scale physics twice.
+- Validate collision layers, masks, ground clearance and center of mass after every source/recipe revision.
+
+If the canonical wrapper scale is not `[1,1,1]`, size authored colliders against the accepted world dimensions. Do not copy the wrapper scale onto both the collision root and its shapes.
+
+Physics mismatch can reveal a spatial or semantic defect. If the visual object cannot align with a reasonable collider without local hacks, mark the relevant canonical condition non-ready and repair the source or recipe.
+

package/dist/skills/zh-CN/godot-3d-game/references/project-structure.md

@@ -0,0 +1,22 @@
+# Godot project structure
+
+Use a stable separation between imported assets, authored wrapper scenes and gameplay systems.
+
+```text
+res://
+  assets/canonical/<asset_id>/
+    model.glb
+    asset.json
+    canonical_loader.gd
+  scenes/assets/
+  scenes/levels/
+  scripts/gameplay/
+  scripts/presentation/
+```
+
+The synchronized package is generated input. Do not hand-edit it in the Godot project; update the workspace canonical package and sync again.
+
+Keep gameplay state on a stable parent such as `CharacterBody3D` or an entity root. Add the canonical visual root as a child. This lets control, networking and save state remain stable when the visual package revision changes.
+
+Use authored `.tscn` scenes for gameplay composition, signals and engine-specific components. Keep the imported GLB scene read-only or inherited. Never save canonical compensation transforms into multiple scene layers.
+

package/dist/skills/zh-CN/godot-3d-game/references/skeleton-animation.md

@@ -0,0 +1,16 @@
+# Skeleton and animation
+
+Keep the canonical wrapper above the imported skeleton. Never apply alignment rotation to individual bones or bake it into animation clips.
+
+After sync, verify:
+
+- Skeleton3D and skinned meshes share the expected imported hierarchy;
+- animations bind to existing node/bone paths;
+- root motion is handled by one gameplay policy, not both AnimationTree and entity movement;
+- frame zero does not snap because an animation track overwrites the wrapper;
+- sockets for weapons or effects attach to bones/markers below the imported root as intended.
+
+Retargeting, missing bones, broken weights and unusable clip naming are structural problems. Mark structural review non-ready and return to the canonical/Blender repair flow. A Godot AnimationTree state machine is not a geometry repair mechanism.
+
+When replacing a character source, repeat structural and semantic review even if the silhouette appears unchanged; bone names and clip bindings are part of the maintained state.
+

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/checklists/compose-quality.md

@@ -0,0 +1,10 @@
+# Compose Quality Checklist
+
+- [ ] Camera model matches `scene_profile_id`
+- [ ] Depth layer table documented and applied
+- [ ] Parallax ratios sensible; Far slower than Play
+- [ ] Tint/vignette does not gray-out state colors
+- [ ] Shake/punch does not hide next decision
+- [ ] No CSS/transform scaling of the game canvas
+- [ ] Near occluders do not block critical telegraphs
+- [ ] Readability tests passed on mobile screenshot

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/checklists/performance-safe-visual-detail.md

@@ -0,0 +1,9 @@
+# Performance-Safe Visual Detail Checklist
+
+- [ ] Particle/emitter caps set and respected
+- [ ] Bullets/FX/enemies pooled where spammy
+- [ ] Large biome textures unload or reuse across scenes when possible
+- [ ] Parallax layer count justified (≤ strong layers, not many weak)
+- [ ] First-cut order documented (what drops on low FPS)
+- [ ] No per-frame texture generation
+- [ ] Lights Manager avoided unless budgeted

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/checklists/premium-game-quality-gate.md

@@ -0,0 +1,15 @@
+# Premium Game Quality Gate (2D)
+
+Before claiming premium / showcase / release-ready visuals:
+
+- [ ] `scene_profile_id` recorded from `scene-profiles.md`
+- [ ] Active-play screenshot compared to `assets/scorecard-anchors/` before scoring
+- [ ] Reference ledger complete (no skipped required refs without reason)
+- [ ] Asset sourcing ledger complete for hero + main background (+ primary hazards)
+- [ ] Visual scorecard filled; premium or showcase thresholds met
+- [ ] Automatic Failures = none
+- [ ] Fresh-eyes review done
+- [ ] Mobile active-play screenshot captured
+- [ ] Technical art brief + budgets noted
+- [ ] Formal HUD still DOM (unless project explicitly requires Canvas HUD)
+- [ ] Playability not regressed (controls, hitboxes fair)

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/checklists/sprite-quality.md

@@ -0,0 +1,10 @@
+# Sprite Quality Checklist
+
+- [ ] Hero facing matches movement/art brief
+- [ ] Hero readable at mobile play size without glow crutch
+- [ ] Hazards: enough silhouette variants for the genre (or documented single-threat)
+- [ ] Rewards distinct from hazards in shape and color
+- [ ] Backgrounds free of characters/UI baked into plates
+- [ ] Spritesheet frame sizes measured before loader config
+- [ ] `config.json` keys bound for all premium surfaces claimed
+- [ ] Collision proxies fair vs art overhang

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/checklists/technical-art-quality.md

@@ -0,0 +1,9 @@
+# Technical Art Quality Checklist
+
+- [ ] Technical art brief written before broad visual changes
+- [ ] Hero vs support surfaces listed
+- [ ] Texture/atlas plan noted
+- [ ] VFX language + caps noted
+- [ ] Asset strategy per high-value surface recorded
+- [ ] Mobile constraints acknowledged
+- [ ] Post-pass diagnostics reported (even if qualitative + caps)

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/checklists/visual-scorecard.md

@@ -0,0 +1,9 @@
+# Visual Scorecard Checklist (2D)
+
+- [ ] Compared active-play screenshot to `assets/scorecard-anchors/` (scene-1 / scene-2 / scene-3)
+- [ ] Scored from active-play screenshot (not title-only)
+- [ ] All 10 categories scored 0–3 with one-line evidence
+- [ ] Average computed
+- [ ] Automatic Failures checked explicitly
+- [ ] Fresh-eyes weakest-two named
+- [ ] Measured evidence cited for textures/config/screenshots where claiming ≥2 on fidelity/performance

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/compose-recipes.md

@@ -0,0 +1,71 @@
+# Compose Recipes (Phaser 2D)
+
+Use before changing camera, parallax, global tint, vignette, depth sorting, or screen-space overlays. Compose supports readability; it is not a replacement for authored sprites.
+
+## Camera
+
+| Model | When | Notes |
+| --- | --- | --- |
+| Lock | `portrait_stage`, `board_table`, `fixed_arena` | Punch zoom on big events only |
+| Follow + deadzone | `side_scroll_lane`, `topdown_map`, `runner_lane` | Deadzone avoids jitter |
+| Room snap | Metroidvania-like | Bounds = room; no lerp fight |
+
+Rules:
+
+- Camera logic stays out of gameplay Systems when possible.
+- Shake intensity scales with event severity; never obscure the next hazard.
+- Prefer Phaser camera effects over CSS transforms on the canvas.
+- World bounds and physics bounds stay aligned (`phaser-2d-game`).
+
+## Parallax
+
+1. Place Far → Mid → Play → Near per `DepthLayers`.
+2. Set `scrollFactorX/Y` (or parent container motion) so Far moves slowest.
+3. Near may move slightly faster than Play for depth, but must not cover telegraphs.
+4. Disable strong parallax on `topdown_map` / `board_table` unless subtle.
+
+Reject: background scrolling faster than player decision reading; mismatched tile seams while scrolling.
+
+## Tint / Overlay / Vignette
+
+Use a single full-screen Image/Graphics or Camera fade for:
+
+- Biome mood (cool night, warm dusk).
+- Pressure (arena wave)—keep center Play clearer than edges.
+- Damage flash (≤100–150ms).
+
+Do **not**:
+
+- Stack multiple multiply overlays until art is gray mush.
+- Use permanent heavy vignette to hide empty Far layers.
+- Recolor every sprite differently so the palette collapses.
+
+Signal colors (hazard / reward / safe) stay consistent with HUD tokens.
+
+## Depth Sorting
+
+- Static world: fixed depths from the layer table.
+- Mobile actors: Y-sort within Play band, or explicit depth = `base + y`.
+- VFX above the actor that owns them, below Near occluders unless the FX is screen-space.
+
+## Screen FX vs World FX
+
+| Kind | Placement | Examples |
+| --- | --- | --- |
+| World FX | At entity position, Play/Motion depth | Impact burst, dash dust |
+| Screen FX | Camera-fixed container | Hit flash, edge warning |
+
+Prefer world FX for spatial clarity; screen FX for global state only.
+
+## Readability Tests
+
+After compose changes, verify on mobile:
+
+1. Hero silhouette still finds the eye in <1s.
+2. Next hazard/reward in the decision window is unobscured.
+3. Parallax does not cause mis-taps on touch targets (DOM HUD separate).
+4. No CSS scaling of the game canvas.
+
+## Checklist Hook
+
+Run `checklists/compose-quality.md` before scoring the Compose category.

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/graphics-prompt-templates.md

@@ -0,0 +1,33 @@
+# Graphics Pass Prompt Templates (Phaser 2D)
+
+Use only when the user asks for reusable prompts or a templated graphics pass.
+
+## Full premium pass
+
+```text
+Load phaser-2d-graphics-builder. Select or confirm scene_profile_id from game-art/references/scene-profiles.md (2D Compose rail only).
+Fill reference ledger (visual-scorecard, implementation-blueprint, sprite-recipes, compose-recipes, technical-art).
+Score current mobile active-play screenshot. Build asset sourcing ledger; generate missing hero/bg/parallax via game-asset-image-generator.
+Upgrade all weak surfaces; then compose; then event VFX. Re-score to premium thresholds or list blockers.
+```
+
+## Hero + background only
+
+```text
+Graphics pass scoped to hero silhouette and Far/Mid backgrounds for profile <id>.
+MCP-generate and bind config keys; do not redesign HUD. Report scorecard categories 2, 5, 6 only plus blockers.
+```
+
+## Compose-only
+
+```text
+Do not regenerate art. Fix camera/parallax/depth/tint per compose-recipes for profile <id>.
+Verify readability tests; update technical-art notes if layer count changed.
+```
+
+## VFX-only
+
+```text
+Sprites/world already premium. Add event-driven FX from vfx-recipes for: <events>.
+Pool emitters; respect technical-art caps; no ambient filler.
+```

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/implementation-blueprint.md

@@ -0,0 +1,82 @@
+# Phaser 2D Graphics Implementation Blueprint
+
+Use when a Phaser game reads as basic even after it is playable. Goal: a production graphics architecture that can be iterated, scored, and budgeted. For premium/showcase work, also load `technical-art.md`.
+
+## Recommended Ownership
+
+Directory layout follows `../phaser-2d-game/references/file-structure.md`. Keep **rules in Systems**, **sprites/FX in Scene or view helpers**. Suggested modules (names can merge in small games; concepts must stay separate):
+
+```text
+src/game/assets/manifest.ts          # or public/config.json bindings
+src/game/view/SpriteFactory.ts       # hero / hazard / reward creators
+src/game/view/WorldPropKit.ts        # repeated props, tileside dressing
+src/game/view/DepthLayers.ts         # Play/Near/Mid/Far/Motion constants
+src/game/view/ComposeRig.ts          # camera helpers, parallax, vignette/tint
+src/game/view/VfxSystem.ts           # event-driven FX (pooled)
+src/game/view/QualityDiagnostics.ts  # optional counters / debug overlays
+src/scenes/GameplayScene.ts          # wires systems → view; no rule ownership
+```
+
+Asset files live under `assets/` (`characters/`, `environment/`, `fx/`, …) with stable keys in `public/config.json`.
+
+## Hybrid Asset Pipeline
+
+Choose the asset path per surface:
+
+- **MCP image** (`game-asset-image-generator`): hero, enemies, signature props, backgrounds, parallax layers, tileset sheets when art quality matters.
+- **User-provided**: local/remote URLs the user supplies; still bind via `config.json`.
+- **Procedural / Phaser Graphics / shapes**: collision debug, temporary stubs, repeated micro-detail, telegraph shapes that must stay code-driven.
+- **Hybrid**: MCP base sprite + code tint/flash/outline for states; or tileset + prop kit overlays.
+
+For premium hero, main background, and primary hazard family: do not finish with procedural-only unless a real MCP/user blocker is recorded.
+
+## Production Surfaces
+
+A premium pass must touch every weak visible surface:
+
+- Hero/player: authored silhouette, facing aligned with art brief, hurt/invuln/boost cues.
+- Hazards/enemies: ≥3 distinct silhouettes when the genre has multiple threat types; telegraphs readable.
+- Rewards/interactables: ≥2 forms; idle + collect states.
+- World kit: Play / Near / Mid / Far / Motion matching `scene-profiles` profile; parallax ratios documented.
+- Sprite fidelity: consistent pixel density; spritesheets measured before `load.spritesheet` (`engine-spritesheets.md`).
+- Compose: camera model, depth sort, tint/overlay discipline (`compose-recipes.md`).
+- VFX: event-driven only (`vfx-recipes.md`); pooled.
+- UI/world cohesion: DOM HUD colors echo hazard/reward/safe signals—do not redesign HUD here beyond color token alignment; full HUD work is `game-ui`.
+- Diagnostics: budget notes, screenshots, scorecard.
+
+## Technical Art Contract
+
+Before broad implementation, write the brief from `technical-art.md`: hero vs support surfaces, texture/display/particle budgets, atlas plan, VFX caps, mobile first cuts.
+
+## Depth Layer Contract
+
+Map `scene-profiles` layers to Phaser depth (example—adjust per game, keep gaps):
+
+| Layer | Role | Typical depth |
+| --- | --- | --- |
+| Far | Background / sky | 0–100 |
+| Mid | Stage / buildings | 100–300 |
+| Play | Actors, hazards, rewards | 500–800 |
+| Near | Foreground occluders | 900–1000 |
+| Motion / VFX | Muzzle, impact, dashes | 1100–1200 |
+| Screen FX | Flash/vignette containers | 2000+ |
+
+Document the chosen map in `DepthLayers.ts`. Actors that need Y-sort stay within Play band.
+
+## State Feedback Without Fake AAA
+
+Prefer, in order:
+
+1. Swap frame / anim / attachment sprite.
+2. Controlled tint / flash (short).
+3. Scale squash-stretch tied to gameplay events.
+4. Camera punch / hitstop (from `game-feel`, scaled for readability).
+5. Particles/trails last.
+
+Never use permanent bloom-like overlays to hide missing art.
+
+## Wiring Rules
+
+- Scene reads System state and spawns/updates view objects; Systems do not import Phaser GameObjects if avoidable.
+- All runtime image URLs come from `config.json` / manifest—no scattered hardcoded CDN strings in multiple files.
+- Scale only via Phaser Scale Manager (`engine-runtime.md`).

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/sprite-recipes.md

@@ -0,0 +1,90 @@
+# Sprite Recipes (Phaser 2D)
+
+Use before upgrading hero, hazard, reward, or world prop visuals. Recipes describe **readable silhouettes and production intent**, not full illustration briefs. Generation details stay in `../game-asset-image-generator/`.
+
+## Shared Rules
+
+- One subject per asset key; facing must match gameplay (right-facing runners stay right-facing in art).
+- Keep a **collision proxy** simpler than the art (rectangle/circle); art can overhang slightly if the hitbox stays fair.
+- Family variants share a motif (helmet shape, horn, stripe) so players learn the cast.
+- Pixel density: characters readable at mobile play size; do not upscale tiny icons into heroes.
+- Prefer transparent Assets for actors; opaque Background for Far plates; Parallax layers with alpha for Mid/Near dressing.
+
+## Hero / Player
+
+**Must have**
+
+- Clear silhouette at thumbnail size.
+- Readable front/facing (or top-down orientation for `topdown_map` / `board_table`).
+- At least one state cue path: idle vs hurt vs power (frame, overlay, or tint—documented).
+
+**Avoid**
+
+- Symmetric blobs with no facing.
+- Oversized weapon that hides the body.
+- Relying on outline glow as the only identity.
+
+**Upgrade path**
+
+1. Lock style from `game-art` (+ advanced style if requested).
+2. MCP generate `asset_player` (and optional `asset_player_hurt` / atlas frames).
+3. Wire anim keys; verify facing vs movement code.
+4. Add attach points later (dust, muzzle) without reskinning the whole hero.
+
+## Hazards / Enemies
+
+**Must have**
+
+- ≥3 variants when the design has multiple threat roles (blocker / chaser / ranged)—or document why the genre is single-threat.
+- Telegraph: wind-up pose, color flash, or warning glyph **before** damage frames.
+- Shape language distinct from rewards.
+
+**Avoid**
+
+- One square, three hues.
+- Camouflage against Mid/Far that makes hits feel unfair.
+
+## Rewards / Interactables
+
+**Must have**
+
+- High contrast vs Play floor.
+- Idle motion subtle (bob/pulse ≤ subtle); collect burst is event FX.
+- Two forms when economy has tiers (coin vs gem, weapon vs heal).
+
+**Avoid**
+
+- Same shape as hazards.
+- Permanent screen-covering sparkle.
+
+## World Prop Kit
+
+Build a small kit, not one-off decorations:
+
+| Kit piece | Use |
+| --- | --- |
+| Edge marker | Lane/arena boundary readability |
+| Mid module | Repeatable building/cliff/hedge segment |
+| Far plate | Single strong skyline or stage back |
+| Near fringe | Grass, railing, table lip—occludes lightly |
+| Hazard stripe / safe glyph | Gameplay-readable floor language |
+
+Repeat with tint variants; do not MCP-generate 50 unique bushes.
+
+## Tilesets
+
+When using tilemaps (`engine-tilemaps.md`):
+
+- One visual language per biome.
+- Collision layer ≠ decorated layer.
+- Autotile/seam care: avoid noisy tiles that hide pickups.
+
+## Backgrounds & Parallax
+
+- Far: full-bleed Background, no characters/UI in the plate.
+- Mid/Near parallax: fewer focal subjects; leave Play cone clean per `scene-profiles`.
+- Scroll factors: Far `0.1–0.3`, Mid `0.4–0.7`, Near `1.0–1.15` (tune per game; document).
+
+## Checklist Hook
+
+Before scoring Sprite fidelity / Hero / Obstacles / Rewards, run `checklists/sprite-quality.md`.

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/technical-art.md

@@ -0,0 +1,67 @@
+# Technical Art For Phaser 2D Games
+
+Use before premium/showcase graphics work, atlas/texture strategy, particle/VFX systems, or any visual pass that could affect mobile performance.
+
+Technical art bridges art direction and real-time constraints. Goal: readable authored detail that survives active play on mid-tier phones—not maximum particle counts.
+
+## Technical Art Brief
+
+Before implementation, write:
+
+- Art direction in renderable terms: silhouettes, layers, compose, VFX language, camera.
+- Hero surfaces vs support surfaces.
+- Texture/atlas plan: max page size, shared atlases vs discrete images.
+- VFX caps: max concurrent emitters, particle lifespans, pool sizes.
+- Display list budget target (rough): dynamic objects in Play band.
+- Asset strategy per surface: mcp-image / user / procedural / hybrid.
+- Mobile first cuts: what to disable first if frame time slips (screen FX → Near props → Mid parallax detail → particle rate).
+
+## Budget Starting Points
+
+Starting contracts—not universal limits. Measure on device; document overruns.
+
+| Metric (worst active-play) | Mobile portrait target | Notes |
+| --- | --- | --- |
+| Unique textures (approx.) | ≤ 40–60 | Prefer atlases; huge unique BGs count heavy |
+| Max single texture edge | ≤ 2048 | Prefer 1024–2048 backgrounds; split if needed |
+| Concurrent particle emitters | ≤ 8 | Pool; hard-cap on spam events |
+| Particles alive (sum) | ≤ 300–500 | Lower on low-end; kill on scene sleep |
+| Dynamic GameObjects (Play) | keep pooled | No per-frame `new` for bullets/FX |
+| Camera shake stacking | 1 active profile | Don’t stack 3 shakes |
+| DPR / resolution | Scale Manager FIT/SHOW_ALL | Never CSS-scale canvas |
+
+Also follow `../phaser-2d-game/references/engine-performance.md` (pooling, culling, update budgets).
+
+## Texture And Atlas Discipline
+
+- Measure spritesheet frame size before loader config (`engine-spritesheets.md`).
+- Don’t pack unrelated PPI into one sheet if it forces wasteful padding—but do atlas frequent FX/UI icons when possible.
+- Prefer WebP/PNG with real alpha; avoid huge uncompressed photo BGs when a painted 1080×1920 plate suffices.
+- Destroy/unload textures on scene shutdown when switching biomes with large unique plates.
+
+## Particles And FX Cost
+
+- Event-driven only; no permanent full-screen ambient snow unless genre-critical and budgeted.
+- Pre-create emitters; `explode`/`quantity` bursts over long-running drip when possible.
+- Additive blending sparingly on mobile.
+- Tie FX lifetime to gameplay feedback windows (100–400ms for hits; longer only for celebrations).
+
+## Compose Cost
+
+- Parallax layers are textures too—3 strong layers beat 8 weak ones.
+- Full-screen overlay Images are cheap vs thousands of nodes; don’t simulate vignette with 200 sprites.
+- Lights (Phaser Lights Manager) are optional and costly—default to tint/overlay recipes first.
+
+## Diagnostics To Report
+
+After a graphics pass, report:
+
+- Which surfaces used MCP vs procedural.
+- Texture strategy (atlases / largest BG size).
+- Particle/emitter caps chosen.
+- Any deliberate budget overrun + why.
+- Mobile screenshot path(s).
+
+## Checklist Hook
+
+Run `checklists/technical-art-quality.md` and `checklists/performance-safe-visual-detail.md` before claiming Performance evidence ≥ 2.

package/dist/skills/zh-CN/phaser-2d-graphics-builder/references/vfx-recipes.md

@@ -0,0 +1,67 @@
+# VFX Recipes (Phaser 2D)
+
+Event-driven visual effects that clarify game state. Load only after sprites and compose are readable. Core rule still applies: FX never substitutes for authored art.
+
+Cross-link: hand-feel timing principles in `../game-designer/references/game-feel.md`; UI motion in `../game-art/references/animation-specs.md`. This file is **in-world / camera FX** for Phaser.
+
+## Principles
+
+1. **One trigger → one readable beat.** Prefer a single strong burst over layered noise.
+2. **Severity scale.** Pickup < hit < kill < fail/clear. Strongest events must still leave the next decision visible.
+3. **Pool everything.** No allocating emitters per bullet in `update`.
+4. **Sync with audio when present.** Same frame as SFX when `game-audio` is wired.
+5. **No ambient filler** to hide empty Far layers.
+
+## Recipe Table
+
+| Event | Primary FX | Duration | Notes |
+| --- | --- | --- | --- |
+| Light confirm (UI-adjacent in world) | Small scale pop + brief spark | 100–200ms | Keep off HUD DOM |
+| Pickup / coin | Radial burst (8–16 particles) + optional arc to HUD anchor | 200–350ms | High contrast; don’t blanket Play |
+| Hit (player) | White/red flash on sprite + tiny camera shake | 80–120ms | Invuln blink separate from flash |
+| Hit (enemy) | Impact ring or directional sparks + hitstop 1–2 frames | 100–180ms | Direction from attack vector |
+| Block / parry | Sharp spark + short freeze | 80–150ms | Distinct from hurt |
+| Dash / boost | Motion streaks or afterimage (2–3 ghosts) | During dash | Cap ghosts; fade quick |
+| Death / explode | Larger burst + brief screen flash ≤30% alpha | 300–500ms | Then remove clutter |
+| Spawn | Poof / ring expand | 200–300ms | Telegraph if hostile |
+| Charge telegraph | Pulse outline / growing warning glyph | Wind-up length | Must be readable before damage |
+| Zone warning | Edge vignette or floor decal pulse | While zone active | Center Play stays clear |
+| Combo / milestone | Short celebratory burst + optional zoom punch | 250–400ms | Don’t stack with death FX |
+| Fail / soft lock | Gray flash or desat pulse | 200ms | Not seizure-level strobe |
+
+## Implementation Notes (Phaser)
+
+- Prefer `this.add.particles` with preconfigured `ParticleEmitter` reused via pools, or a small `VfxSystem.burst(kind, x, y, dir?)` API.
+- Sprite flash: tween `setTintFill` / short `setAlpha` blink; clear tint on complete.
+- Afterimages: spawn faded copies at depth just below hero; auto-destroy.
+- Screen flash: camera-fixed Rectangle or Image at Screen FX depth; fade out; ignore input blocking.
+- Respect `technical-art.md` emitter and particle caps; on spam (machine-gun hits), coalesce to rate-limited bursts.
+
+## Anti-Patterns
+
+- Permanent floating dust as “atmosphere” when Far art is missing.
+- Full-screen rainbow particles on every tap.
+- Shake so strong platforms/hazards can’t be aimed at.
+- Additive glow soup that blows out silhouette edges.
+- FX that spawn without a gameplay event (pure decoration loops).
+
+## Severity Ladder (default)
+
+```text
+0  none
+1  sprite-only (tint/scale)
+2  local particles
+3  local particles + camera punch
+4  screen flash + particles + punch
+```
+
+Map events to ≤ one ladder step above the previous severity so players learn intensity.
+
+## Checklist
+
+Before scoring VFX/motion ≥ 2:
+
+- [ ] Every FX kind maps to a gameplay event
+- [ ] Caps documented in technical art brief
+- [ ] Mobile screenshot shows FX without hiding hazards
+- [ ] No ambient-only particle layer required for “premium”