evomeme-dev 0.1.7

package/skills/phaser-2d-game/references/file-structure.md

@@ -0,0 +1,94 @@
+# H5 游戏文件结构规范
+
+本文档定义手机 H5 游戏的标准文件结构。项目是 Vite + React + Phaser 应用：游戏画面由 Phaser 管理，DOM UI 由 React 管理。**这是本插件所有 2D 代码结构和配置文件的唯一规范来源**，`game-director`、`game-designer`、`game-art`、`game-asset-image-generator` 在涉及 2D 项目的 config 或目录结构时必须遵循本文件。3D 项目见 `../threejs-3d-game/references/file-structure.md`。
+
+## `/public/config.json` 规则
+
+`/public/config.json` 是游戏运行时外置配置文件，构建后原样输出为 `/dist/config.json`。
+
+### 存储规则
+
+1. 所有用户可调颜色、玩法参数、平衡数值和资源 URL 必须写入 `/public/config.json`，禁止硬编码在业务代码中。
+2. 游戏代码必须通过 `fetch("./config.json")`（相对路径）读取配置；禁止使用绝对路径 `/config.json`；禁止从 `src` 目录直接 `import config.json`。
+3. 不得在 React、Phaser、CSS 中重复硬编码同一份用户可调值。
+
+### 结构要求：必须严格扁平
+
+config **必须是扁平顶层对象**，每个参数都是直接顶层 key，**禁止**按 `assets`、`images`、`gameplay`、`colors`、`params` 等分组：
+
+```json
+// 正确 —— 扁平
+{ "image_background": { ... }, "gravity_scale": { ... } }
+
+// 错误 —— 禁止嵌套分组
+{ "assets": { "background": { ... } }, "gameplay": { "gravity": { ... } } }
+```
+
+每个 key 分两类：
+
+- **可见参数**（key 不以 `_` 开头）：暴露给用户编辑，必须使用下方标准 schema。
+- **不可见参数**（key 以 `_` 开头）：内部字段（如 `_game_name`、`_config_version`），原始值即可，不使用 schema。
+
+### 可见参数 schema
+
+```json
+"key_name": {
+  "value": <实际值>,
+  "type": "int" | "float" | "color" | "bool" | "string" | "audio" | "image" | "video",
+  "label": "<用户语言标签，≤10字>",
+  "min": <数字>,
+  "max": <数字>
+}
+```
+
+规则：
+
+- `type` 只能是 `int`、`float`、`color`、`bool`、`string`、`audio`、`image`、`video`。
+- `label` 使用用户语言，长度不超过 10 个字符。
+- `min`/`max` 只在 `int`/`float` 时出现，且必须同时给出。
+- `type: "color"` 使用十六进制颜色字符串。
+- `type: "image"` 必须额外声明 `"image_type": "Asset"` 和 `"size": "宽x高"`（如 `"1440x2560"`），供无法读取真实图片尺寸时判断显示尺寸。
+- `audio`/`image`/`video` 的 `value` 必须是真实可访问的外部 `http(s)` URL；禁止本地相对路径。图片由上游异步生成，URL 短暂 404 不代表素材失效，不得因此改写、替换或删除素材。
+
+### 示例
+
+```json
+{
+  "_game_name": "示例游戏",
+  "_config_version": 1,
+  "move_speed": { "value": 220, "type": "int", "label": "移动速度", "min": 50, "max": 400 },
+  "gravity_scale": { "value": 1.2, "type": "float", "label": "重力倍率", "min": 0.2, "max": 3 },
+  "theme_background_color": { "value": "#10131f", "type": "color", "label": "背景色" },
+  "enable_shake": { "value": true, "type": "bool", "label": "震屏开关" },
+  "start_button_text": { "value": "开始游戏", "type": "string", "label": "开始文案" },
+  "bgm_main": { "value": "https://example.com/bgm.mp3", "type": "audio", "label": "背景音乐" },
+  "image_background": {
+    "value": "https://example.com/background.png",
+    "type": "image",
+    "image_type": "Asset",
+    "size": "1440x2560",
+    "label": "背景图"
+  }
+}
+```
+
+## `/user_upload` 目录规则
+
+`/user_upload` 是用户上传素材的虚拟目录，其下文件不是真实素材文件，只保存素材链接或元数据。
+
+1. 需要使用用户上传素材时，先读取 `/user_upload` 下对应文件，提取真实 URL。
+2. 不要把 `/user_upload/...` 当成本地素材路径；最终代码必须引用提取出的真实 URL。
+
+## 部署与路径规则
+
+1. 最终部署产物固定为 `/dist`，以静态站点形式部署，运行时资源必须能通过浏览器直接访问。
+2. `/dist` 必须能脱离源码目录独立运行：所有运行时代码、资源、chunk、CSS、音频、图片和配置只能引用 `/dist` 内文件或外部 `http(s)` 链接，必须使用相对路径或构建产物内部路径，严禁指向源码目录的运行时引用。
+3. `vite.config.js` 必须设置 `base: './'`，使构建产物使用相对路径（`./assets/...`），保证在任意子路径部署都能运行。
+4. 所有运行时字符串路径（`fetch`、`Audio`、动态 `import`、CSS `url()`）必须使用 `./` 相对路径，禁止以 `/` 开头的绝对路径。
+
+## 项目根目录必需文件
+
+- `/project.md`：唯一游戏需求来源（策划案），后续所有开发依据此文件。
+- `/public/config.json`：运行时配置与素材绑定契约。
+- `/src`：Vite + React + Phaser 源码。
+- `/dist`：构建产物，交付物。

package/skills/phaser-2d-graphics-builder/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: phaser-2d-graphics-builder
+description: 将 Phaser 2D 游戏从基础/原型视觉升级为高品质画面。涵盖美术方向评审、2D 场景范式、精灵/世界套件、MCP 生图、摄像机/视差/构图打磨、事件特效、性能预算与视觉评分门控。在竖屏或浏览器 Phaser 游戏需要超越占位色块的可度量视觉提质时使用。
+---
+
+# Phaser 2D Graphics Builder
+
+## Purpose
+
+Own the production graphics pass for Phaser games. Convert basic screenshots into authored, layered, performance-aware visual experiences—without treating particles and glow as a substitute for real art.
+
+## Use When
+
+Screenshots still look basic, heroes/enemies are SVG placeholders or flat shapes, worlds are sparse or single flat backgrounds, UI/world art feels generic, or the user asks for premium, high-fidelity, showcase, 画面精美/高级, or less-basic 2D graphics.
+
+## Required References
+
+These references are required phase-entry gates, not optional reading:
+
+- Load `../game-art/references/scene-profiles.md` and select a `scene_profile_id` before world kit, compose polish, or any claim that World/environment is authored. Read only the **World + 2D · Compose + Entities + Reject** sections for that profile; this skill executes the production pass against it.
+- Load `../game-art/references/advanced-art-styles.md` when the user asked for 画面精美/高级/精品视觉 and a premium style has not yet been locked; otherwise keep the existing `art-styles.md` choice.
+- Load `references/visual-scorecard.md` before scoring, judging completion, or making any premium/showcase claim. **View** `assets/scorecard-anchors/scene-1.jpeg`, `scene-2.jpeg`, and `scene-3.jpg` when scoring World, Hero, Sprite fidelity, Compose, or VFX—or before any premium/showcase claim.
+- Load `references/implementation-blueprint.md` before changing graphics architecture, sprite factories, VFX, compose systems, diagnostics, or broad visual systems.
+- Load `references/sprite-recipes.md` before building or upgrading hero/player, obstacle, enemy, pickup, world-kit, or prop sprites.
+- Load `references/compose-recipes.md` before changing camera, parallax, tint/overlay, depth sorting, vignette, or screen-space compose.
+- Load `references/technical-art.md` before premium/showcase graphics work, atlas/texture strategy, particle/VFX systems, or visual changes that could affect mobile performance.
+- Load `references/vfx-recipes.md` before adding particles, trails, flashes, hitstop-linked FX, or event-driven juice.
+- Load `references/checklists/premium-game-quality-gate.md` and `references/checklists/visual-scorecard.md` before declaring a game premium, showcase, complete, release-ready, or less basic.
+- Load the relevant checklist before focused work: `references/checklists/sprite-quality.md`, `references/checklists/compose-quality.md`, `references/checklists/performance-safe-visual-detail.md`, or `references/checklists/technical-art-quality.md`.
+- Load `references/graphics-prompt-templates.md` only when the user asks for reusable prompts, a graphics-pass prompt, or a task template.
+
+For broad "still looks basic", premium, showcase, high-fidelity, or less-basic graphics work, load the scene-profiles paradigm (2D Compose rail) plus all five core references (`visual-scorecard`, `implementation-blueprint`, `sprite-recipes`, `compose-recipes`, `technical-art`) as the first action in the phase. Track them in a reference ledger with yes/no, path, and failure reason. Do not mark the graphics phase complete while any required reference is skipped.
+
+External asset sourcing gate:
+
+- For premium/showcase/high-fidelity/less-basic graphics with a hero/player, character, creature, boss, vehicle, weapon, signature prop, complex pickup, background, or parallax layer, load `../game-asset-image-generator/SKILL.md` before deciding SVG/CSS placeholders or procedural shapes are enough.
+- Prefer MCP `evomeme_generate_game_image` (and `evomeme_cutout_game_image` when needed) via `game-asset-image-generator`; bind URLs in `public/config.json` per `../phaser-2d-game/references/file-structure.md`.
+- Create an asset sourcing ledger for each high-value surface: mcp-image / hybrid / user-provided / procedural, plus outputs or skip reason.
+- `not-needed` is valid only after the relevant path was considered and the ledger explains why generation would not improve a non-hero support surface, or why an attempted MCP call shows a real blocker.
+- For premium hero surfaces and main backgrounds, procedural/SVG-only is not an allowed final answer unless there is real blocker evidence. At least one high-value surface must show an MCP `asset_url` (or user-provided path) written into `public/config.json`.
+
+## Workflow
+
+1. Capture or inspect active mobile (and desktop if in scope) screenshots of gameplay—not only the title screen.
+2. Confirm or select a `scene_profile_id` from `../game-art/references/scene-profiles.md` (World / 2D · Compose / Entities). If missing, write it before upgrading surfaces.
+3. Score visuals across art direction, hero/player, obstacles, rewards, world, sprite fidelity, compose, VFX, UI, and performance evidence—**after** comparing the active-play screenshot to `assets/scorecard-anchors/` (`scene-1` / `scene-2` / `scene-3`).
+4. Add missing graphics architecture: sprite factories / world prop kit, depth/layer contract, tint/compose helpers, VFX system, technical-art budget, diagnostics.
+5. Fill the external asset sourcing ledger per surface; generate/bind missing hero, hazard, reward, background, and parallax assets through `game-asset-image-generator`.
+6. Upgrade every weak visible surface, not only one hero sprite. World layers must match the chosen scene-profiles paradigm (Play / Near / Mid / Far / Motion).
+7. Add camera/parallax/tint/compose polish after authored sprites and backgrounds exist, following `references/compose-recipes.md`.
+8. Add event-driven VFX tied to gameplay state per `references/vfx-recipes.md`—after forms and compose are readable. Management/sim genres may use status bubbles, progress rings, and day-night cues as primary readability FX when particle bursts would hurt clarity.
+9. Re-score screenshots against the same anchors. Continue until every premium category is at least 2/3 or report exact blockers.
+10. Run the fresh-eyes review per `references/visual-scorecard.md` before finalizing premium/showcase claims.
+11. Verify Phaser/display budgets against `references/technical-art.md`, mobile screenshots, console/page errors, and playability. Engine constraints: `../phaser-2d-game/references/engine-performance.md` and `../phaser-2d-game/references/engine-spritesheets.md`.
+
+## Core Rule
+
+Do not make placeholders look premium by adding glow, bloom-like overlays, or ambient particles. First author silhouettes and layered world art, then compose (depth/parallax/tint), then event-driven effects.
+
+## Boundaries
+
+- Domains owned here: world/sprite visual production pass, compose, in-world VFX readability, graphics budgets, scorecard.
+- Not owned here: core gameplay rules (`game-designer`), DOM HUD/menu design (`game-ui`), audio binding (`game-audio`), Phaser architecture basics (`phaser-2d-game`), art-direction selection alone (`game-art`—this skill consumes its outputs and runs the upgrade pass).
+- Formal HUD remains DOM overlay; do not move dense UI into Canvas to “look fancy”.
+
+## Final Response
+
+Report the reference ledger, external asset sourcing ledger, technical art brief, score before/after (cite which anchor each weak/strong category resembled), production surfaces upgraded, files changed, screenshots/artifacts, display/texture budget notes, VFX readability tradeoffs, and remaining blockers. For premium/showcase claims, include the filled visual scorecard exactly as defined in `references/visual-scorecard.md`, including average and automatic failures remaining.

package/skills/phaser-2d-graphics-builder/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Phaser 2D Graphics Builder"
+  short_description: "全面提升二维游戏的角色、场景、构图、特效和整体画面品质"
+  default_prompt: "请使用 $phaser-2d-graphics-builder 提升这个二维游戏的整体画面品质，完善角色、场景层次、构图和特效表现。"
+
+policy:
+  allow_implicit_invocation: false

package/skills/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/skills/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/skills/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/skills/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/skills/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/skills/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/skills/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/skills/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/skills/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/skills/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/skills/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.