evomeme 0.1.9 → 0.1.10-beta.13

package/dist/skills/en-US/phaser-2d-game/references/engine-performance.md

@@ -0,0 +1,64 @@
+# Engine: Performance
+
+Load this when there is stutter, frame drops, or spawn spikes.
+
+## Priority Items
+
+1. **Object pools**: bullets, enemies, floating text, short-lived particle carriers — see `engine-physics.md`  
+2. **Atlases**: keep on-screen assets in the same atlas where possible to reduce texture switching  
+3. **Fewer collision pairs**: attach only needed collider/overlap pairs; disable offscreen bodies  
+4. **No allocations in update**: do not create `{}` / `new Vector2` every frame; reuse temporary vectors  
+5. **Use delta for time**: `delta/1000`; AI/pathfinding can run at a lower frequency  
+
+## Physics
+
+```ts
+// Offscreen bodies can be disabled
+enemy.body.enable = cam.worldView.contains(enemy.x, enemy.y);
+
+// Circular collision is often cheaper than a large rectangle
+sprite.body.setCircle(16);
+```
+
+With many dynamic bodies, evaluate `arcade.useTree` / `maxEntries`; consider disabling the tree only after >5000 bodies (based on measurement).
+
+## Rendering
+
+- Use `tileSprite` or a static image for backgrounds; do not redraw large images every frame  
+- Use ADD/MULTIPLY and similar blending cautiously (they can easily split batches)  
+- Set particle `maxParticles` / `frequency`  
+- Sprites outside the camera are culled by default; fixed UI with `scrollFactor 0` on Canvas must be intentional (production HUD still uses DOM)
+
+## Memory and Scene Switching
+
+```ts
+shutdown() {
+  this.enemies?.clear(true, true);
+  // this.textures.remove('only-this-level') as needed;
+}
+```
+
+When changing levels, unload only this level's large images/tilemap; shared atlases can stay.
+
+## Reduce Frequency of Expensive Logic
+
+```ts
+if (time - this.lastAiAt > 100) {
+  this.lastAiAt = time;
+  this.updateEnemyAi(); // Can also be on the System side
+}
+```
+
+Movement/camera runs every frame; AI, pathfinding, and cleanup scans can run at 5-10Hz.
+
+## Quick Check Table
+
+| Symptom | Common Cause | Handling |
+| --- | --- | --- |
+| Slower over time | Leak not destroyed | Check pools and shutdown |
+| Periodic stutter | GC | Pool, reduce update allocations |
+| Constant low FPS | Too many objects/draws | Cull, atlas, reduce particles |
+| Spawn spike | Create on the spot | Pre-pool |
+| Collision stutter | Check pair-count explosion | Reduce pairs, simplify shape |
+
+During development, you can inspect `this.game.loop.actualFps`; for release, turn off physics debug and dense FPS text (or keep only a DOM debug toggle).

package/dist/skills/en-US/phaser-2d-game/references/engine-physics.md

@@ -0,0 +1,139 @@
+# Engine: Arcade Physics and Object Pools
+
+Gameplay values still belong to System / `config.json`; this file only covers Phaser physics APIs and common pitfalls.
+
+Load this when modifying collisions, platforms, bullet pools, knockback, or one-way platforms.
+
+## World Config (Excerpt)
+
+```ts
+physics: {
+  default: 'arcade',
+  arcade: {
+    gravity: { x: 0, y: 300 }, // Can be multiplied by config gravity_scale
+    debug: false,              // Turn off for release
+    fps: 60,
+    overlapBias: 4,
+    tileBias: 16,
+    useTree: true,             // Re-evaluate false only with extremely many dynamic bodies
+  },
+}
+```
+
+## Body Types
+
+- **Dynamic**: velocity, gravity, collision response (player, enemies, bullets).
+- **Static**: unmoving platforms; call `refreshBody()` / group `refresh()` after changing scale/position.
+
+```ts
+const player = this.physics.add.sprite(100, 100, 'player');
+player.body.setCollideWorldBounds(true);
+player.body.setSize(24, 40, true);
+player.body.setOffset(4, 8);
+player.body.setMaxVelocity(300, 400);
+player.body.setDrag(100, 0);
+```
+
+Circle body: `setCircle(radius, offsetX, offsetY)`. The visual mesh can be larger than the body; **do not** use an entire large image as the collision box.
+
+## Collider vs Overlap
+
+```ts
+// Physical separation
+this.physics.add.collider(player, platforms);
+this.physics.add.collider(player, enemies, onHit, processCb, this);
+
+// Detect overlap only (pickup, trigger)
+this.physics.add.overlap(player, coins, onCollect, undefined, this);
+```
+
+A `process` callback can return `false` to skip this collision (invulnerability frames, one-way platforms).
+
+### Grounded / Wall Contact
+
+```ts
+if (player.body.blocked.down) { /* grounded */ }
+if (player.body.touching.down) { /* standing on a body */ }
+if (player.body.wasTouching.down && !player.body.touching.down) { /* just left the ground */ }
+```
+
+### World Bounds
+
+```ts
+this.physics.world.setBounds(0, 0, mapWidth, mapHeight);
+this.cameras.main.setBounds(0, 0, mapWidth, mapHeight);
+this.cameras.main.startFollow(player, true, 0.08, 0.08);
+```
+
+## Object Pools (Required for High-Frequency Spawning)
+
+```ts
+this.bullets = this.physics.add.group({
+  defaultKey: 'bullet',
+  maxSize: 100,
+});
+
+function fire(x: number, y: number, vx: number, vy: number) {
+  const b = this.bullets.get(x, y);
+  if (!b) return;
+  b.setActive(true).setVisible(true);
+  b.body.enable = true;
+  b.body.reset(x, y);
+  b.setVelocity(vx, vy);
+}
+
+function kill(b: Phaser.Physics.Arcade.Sprite) {
+  b.setActive(false).setVisible(false);
+  b.body.enable = false;
+  b.body.stop();
+}
+```
+
+It is forbidden to `new` / `destroy` bullets and particle carriers every frame on hot paths.
+
+## Common Patterns
+
+### Platform Jump
+
+```ts
+if (jumpPressed && player.body.blocked.down) {
+  player.setVelocityY(-330); // Height uses config
+}
+```
+
+### Acceleration Movement
+
+```ts
+player.body.setMaxVelocity(maxSpeed);
+player.body.setDrag(drag, 0);
+player.body.setAccelerationX(left ? -accel : right ? accel : 0);
+```
+
+### One-Way Platform
+
+```ts
+function oneWay(
+  player: Phaser.Physics.Arcade.Sprite,
+  platform: Phaser.Physics.Arcade.Sprite,
+) {
+  return (
+    player.body.velocity.y > 0 &&
+    player.body.bottom <= platform.body.top + 10
+  );
+}
+this.physics.add.collider(player, platforms, undefined, oneWay, this);
+```
+
+### Knockback
+
+After changing velocity, System records invulnerability; Scene only plays feedback. The `setVelocity` direction is determined by relative position.
+
+## Layering with System
+
+- In collision callbacks: hand the event to System **first** (damage, pickup), then modify the view (white flash, disable sprite).
+- Do not scatter duplicate win/loss rules inside callbacks.
+- `debug: true` is development-only; turn it off before release and screenshots.
+
+## Matter?
+
+Only when Arcade AABB is insufficient (complex polygons, joints, ragdolls). Do not enable physics for menus/cards. For detailed requirements, consult the Phaser Matter docs; keep Arcade as the default path.

package/dist/skills/en-US/phaser-2d-game/references/engine-runtime.md

@@ -0,0 +1,129 @@
+# Engine Runtime (Phaser 3)
+
+**System holds rules truth, Scene only handles the view, and production HUD uses DOM**. Directories and config follow `file-structure.md`.
+
+Load this file when writing/modifying scene lifecycle, scaling, frame loops, or scene switching.
+
+## Mapping to This Project's Layers
+
+| Phaser Concept | Location in This Project |
+| --- | --- |
+| Boot / preload | Boot Scene: read `config.json`, preload according to manifest |
+| Gameplay Scene | Read System state -> sprites/camera/effects; send input intents back to System |
+| Production HUD / menu | React DOM overlay (not dense Canvas text UI) |
+| Optional parallel Scene | Debug only / extremely lightweight in-world indicators; does not replace production HUD |
+| Adjustable values | `public/config.json`; scattered magic numbers are forbidden |
+
+## Scene Structure (Recommended)
+
+```text
+scenes/
+├── BootScene.ts       # Config and asset preloading, progress
+├── MenuScene.ts       # Shell layer (can be very thin; complex menus can still use DOM)
+├── GameScene.ts       # Main-loop view
+└── (optional)DebugScene  # Parallel debugging; do not stuff production HUD into it
+```
+
+Switching:
+
+```ts
+this.scene.start('GameScene', { level: 1 }); // Stop current, start new
+this.scene.launch('DebugScene');             // Parallel
+this.scene.pause('GameScene');
+this.scene.stop('DebugScene');
+```
+
+Use **init data / registry / System facade** for state between scenes; it is forbidden to attach mutable globals to `window`.
+
+## Scene Lifecycle
+
+```ts
+class GameScene extends Phaser.Scene {
+  init(data: unknown) {}           // Receive data from the previous scene
+  preload() {}                     // Load only; production projects should prefer centralized Boot loading
+  create() {}                      // Objects, physics, input binding; connect to System
+  update(time: number, delta: number) {} // delta unit is ms
+}
+```
+
+Rules:
+
+- Assets belong in `preload` / Boot; do not start `load` only in `create` and then immediately reference the asset.
+- `update` **maps** System results and samples input; core rules belong in System, avoiding a "giant Scene god class."
+- Animation/sprite state is derived from System; do not use random sprite flags as truth.
+
+## Frame-Rate-Independent Movement
+
+Phaser `update` `delta` is **milliseconds**:
+
+```ts
+// Correct
+this.viewX += speedPxPerSec * (delta / 1000);
+
+// Wrong: tied to frame rate
+this.viewX += speedPxPerSec;
+```
+
+Physics bodies should prefer Arcade `setVelocity` / acceleration; manual displacement must multiply by `delta/1000`.
+
+## Viewport Scaling (Scale Manager Is the Only Correct Path)
+
+**You must use Phaser Scale Manager**; using CSS/`transform`/hand-written `resize` to scale the canvas is forbidden (it breaks coordinates, input, and physics).
+
+```ts
+const config: Phaser.Types.Core.GameConfig = {
+  type: Phaser.AUTO,
+  width: 720,
+  height: 1280,
+  scale: {
+    mode: Phaser.Scale.FIT,
+    autoCenter: Phaser.Scale.CENTER_BOTH,
+    parent: 'game-container',
+    width: 720,
+    height: 1280,
+  },
+  // physics / scene ...
+};
+```
+
+| Mode | When to Use |
+| --- | --- |
+| `FIT` | Default: preserve aspect ratio; may have margins |
+| `ENVELOP` | Fill and crop (cropped edges must be acceptable) |
+| `RESIZE` | Layout changes with viewport (you must relayout world/UI yourself) |
+| `NONE` | Fixed desktop size |
+
+Response:
+
+```ts
+this.scale.on('resize', (gameSize: Phaser.Structs.Size) => {
+  // Adjust camera / world bounds as needed; production HUD is responsive through DOM itself
+});
+```
+
+### Anti-Pattern (Forbidden)
+
+```ts
+// Forbidden
+canvas.style.width = '75%';
+canvas.style.transform = 'scale(0.75)';
+window.addEventListener('resize', () => { /* Hand-edit container pixels to "simulate" scaling */ });
+```
+
+## Physics System Selection (Decide Early)
+
+Default to **Arcade**; Matter is only for rigid-body/joint scenarios; menus/cards can avoid enabling physics. See `engine-physics.md` for selection, collisions, and object pools.
+
+## Engine Anti-Patterns
+
+| Anti-Pattern | Problem | Practice |
+| --- | --- | --- |
+| Hand-written CSS scaling for Canvas | Input/physics mismatch | Scale Manager |
+| All rules written in `update` | Hard to test, hard to reuse | System + Scene mapping |
+| `window` global state | Breaks scene switching | registry / System |
+| Load in `create` and use immediately | Asset not ready | Boot / preload |
+| Count frames as time | Speed changes when frames drop | `delta/1000` |
+| Matter for simple collisions | Too heavy | Arcade |
+| Stuff production HUD into Scene dense text | Hard to adapt to portrait/safe areas | DOM overlay |
+| Magic numbers | Hard to tune balance | `config.json` |
+| Bullets/enemies constantly create/destroy | GC stutter | Object pools (see physics / performance) |

package/dist/skills/en-US/phaser-2d-game/references/engine-spritesheets.md

@@ -0,0 +1,99 @@
+# Engine: Spritesheets and Atlases
+
+**Read this file before loading any spritesheet.** Frame dimensions that are off by a few pixels will silently misalign, and everything after that breaks.
+
+Production HUD defaults to DOM (`game-ui`); nine-slice Canvas panels are used only when truly needed for in-world / pixel-art panels.
+
+## Mandatory: Measure Before Writing the Loader
+
+1. Open the image and note the total width and height  
+2. Count rows and columns clearly  
+3. Measure the true width and height of one cell (pixel ruler)  
+4. Check whether there is a gap between cells -> `spacing`  
+5. Check whether there is padding around the outer edge of the whole image -> `margin`  
+6. Verify divisibility with the formula  
+
+```text
+imageWidth  = frameWidth  × cols + spacing × (cols - 1) + margin × 2
+imageHeight = frameHeight × rows + spacing × (rows - 1) + margin × 2
+```
+
+### Try Square Character Frames First
+
+After calculating `frameWidth`, **try `frameHeight = frameWidth` first**, then check whether the height divides evenly. Do not blindly divide by "same row/column count" from the start.
+
+### Different Animations May Have Different Frame Sizes
+
+A single character's idle / run / attack animations often each have **their own sheet and their own frame size** (running poses are wider, slashes are wider). **Measure each sheet independently**; copying idle fw/fh to attack is forbidden.
+
+## Loader Example
+
+```ts
+this.load.spritesheet('player-idle', urlFromManifest, {
+  frameWidth: 64,
+  frameHeight: 64,
+});
+
+this.load.spritesheet('ui-wood', url, {
+  frameWidth: 144,
+  frameHeight: 144,
+  spacing: 8,
+});
+
+this.load.spritesheet('icons', url, {
+  frameWidth: 32,
+  frameHeight: 32,
+  margin: 4,
+  spacing: 2,
+});
+```
+
+Asset URLs go through the manifest / `config.json`; do not hardcode scattered paths in business code.
+
+## Red Flags
+
+- Width or height cannot be divided evenly by the frame count / produces a fractional result  
+- A visible gap exists but `spacing` is not set (the first frame is correct, all later frames drift)  
+- Character animation forces non-square frames without verification  
+- Assumes row and column counts are the same  
+
+## Debug: Lay Out Frames First
+
+```ts
+for (let i = 0; i < frameCount; i++) {
+  const col = i % 3;
+  const row = Math.floor(i / 3);
+  this.add.image(100 + col * 120, 100 + row * 120, key, i);
+  this.add.text(100 + col * 120, 150 + row * 120, String(i)).setOrigin(0.5);
+}
+```
+
+If a single frame is already wrong -> fix the loader before entering gameplay. For multi-animation characters, use a temporary AnimTest Scene / `?debug=anims` and switch with left/right keys to verify.
+
+## Texture Atlas
+
+Merge multiple sprites into an atlas to reduce draw calls and requests:
+
+```ts
+this.load.atlas('sprites', atlasPngUrl, atlasJsonUrl);
+this.add.sprite(x, y, 'sprites', 'player-idle-1');
+this.anims.create({
+  key: 'walk',
+  frames: this.anims.generateFrameNames('sprites', {
+    prefix: 'player-walk-',
+    start: 1,
+    end: 8,
+    zeroPad: 2,
+  }),
+  frameRate: 10,
+  repeat: -1,
+});
+```
+
+## Nine-Slice / Three-Segment Strips (Only When Canvas UI Needs Them)
+
+- 3x3: corners do not stretch, edges stretch on one axis, center stretches on both axes; transparent edges need a base color and overlap to prevent seams.  
+- Ribbons/banners are often **left cap + middle segment + right cap**; do not stretch the whole image.  
+- Configure parameters per asset; do not hardcode one set.  
+
+In-world decoration may use this; **main menus/settings/complex HUDs still prefer DOM**.

package/dist/skills/en-US/phaser-2d-game/references/engine-tilemaps.md

@@ -0,0 +1,80 @@
+# Engine: Tilemap (Tiled -> Phaser)
+
+Load this when side-scrolling/top-down maps, collision layers, or object-layer enemy spawning are used.
+
+## Suggested Tiled Layers (Top to Bottom)
+
+```text
+Foreground   # Decoration that covers the player
+Objects      # Spawn points, enemies, pickups, triggers (Object Layer)
+Ground       # Main collision Tile Layer
+Background   # Non-collision decoration / parallax
+```
+
+Export **JSON** (recommended). For Tilesets, pay attention to `margin` / `spacing`; extruded tilesets can prevent color bleeding.
+
+## Loading and Creation
+
+```ts
+// preload / Boot
+this.load.tilemapTiledJSON('level1', mapUrl);
+this.load.image('tiles', tilesetUrl);
+
+// create
+const map = this.make.tilemap({ key: 'level1' });
+const tileset = map.addTilesetImage('terrain', 'tiles'); // Name matches Tiled
+const ground = map.createLayer('Ground', tileset, 0, 0);
+const fg = map.createLayer('Foreground', tileset, 0, 0);
+
+ground?.setCollisionByProperty({ collides: true });
+// Or setCollisionByExclusion([-1]) / by index
+
+this.physics.add.collider(player, ground!);
+this.cameras.main.setBounds(0, 0, map.widthInPixels, map.heightInPixels);
+this.physics.world.setBounds(0, 0, map.widthInPixels, map.heightInPixels);
+```
+
+Multiple tilesets: call `addTilesetImage` for each one, and pass an array to `createLayer`.
+
+## GID Essentials
+
+- `0` = empty  
+- Multiple tilesets rely on `firstgid`; local id = `gid - firstgid`  
+- Flips exist as high-bit flags; clear `0xF0000000` first when parsing manually  
+
+Generally prefer Phaser API and hand-parse GID less.
+
+## Spawning Entities from Object Layers
+
+```ts
+const objs = map.getObjectLayer('Objects');
+objs?.objects.forEach((obj) => {
+  if (obj.type === 'spawn' || obj.name === 'player') {
+    // Hand logical position to System; Scene only creates the view
+  }
+  if (obj.type === 'coin') {
+    // overlap group / pool
+  }
+});
+```
+
+Map Tiled custom properties to config / content data and avoid hardcoding level values in Scene.
+
+## Parallax
+
+Set `parallaxx` / `parallaxy` on layers in Tiled, or use `setScrollFactor` on the Phaser side. Distant-view factor < 1.
+
+## Common Pitfalls
+
+| Symptom | Handling |
+| --- | --- |
+| Seam color bleeding | tileset extrude; check spacing/margin |
+| Collision mismatch | Confirm layer name, tileset name, and `setCollision*` after scaling |
+| Object coordinates offset | Pay attention to Tiled origin and Phaser origin; tile object vs point |
+| CSV map | Must declare tileWidth/Height in `make.tilemap`; prefer JSON |
+
+## With This Specification
+
+- Map JSON / tile URLs go into manifest or config; do not hardcode paths in multiple places.  
+- Collision results -> System events; Scene does not hold level-progress truth.  
+- For large maps, ensure camera bounds and world bounds match.

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

@@ -0,0 +1,94 @@
+# H5 Game File Structure Specification
+
+This document defines the standard file structure for mobile H5 games. The project is a Vite + React + Phaser application: the game view is managed by Phaser, and DOM UI is managed by React. **This is the only normative source for all 2D code structure and configuration files in this plugin**; `game-director`, `game-designer`, `game-art`, and `game-asset-image-generator` must follow this file when dealing with config or directory structure for 2D projects. For 3D projects, see `../threejs-3d-game/references/file-structure.md`.
+
+## `/public/config.json` Rules
+
+`/public/config.json` is an external configuration file for game runtime and is output unchanged as `/dist/config.json` after build.
+
+### Storage Rules
+
+1. All user-adjustable colors, gameplay parameters, balance values, and resource URLs must be written to `/public/config.json`; hardcoding them in business code is forbidden.
+2. Game code must read config through `fetch("./config.json")` (relative path); using the absolute path `/config.json` is forbidden; directly `import config.json` from the `src` directory is forbidden.
+3. The same user-adjustable value must not be hardcoded repeatedly in React, Phaser, or CSS.
+
+### Structure Requirement: Must Be Strictly Flat
+
+config **must be a flat top-level object**, with every parameter as a direct top-level key; grouping by `assets`, `images`, `gameplay`, `colors`, `params`, and similar keys is **forbidden**:
+
+```json
+// Correct -- flat
+{ "image_background": { ... }, "gravity_scale": { ... } }
+
+// Wrong -- nested grouping is forbidden
+{ "assets": { "background": { ... } }, "gameplay": { "gravity": { ... } } }
+```
+
+Each key is one of two types:
+
+- **Visible parameter** (key does not start with `_`): exposed for user editing and must use the standard schema below.
+- **Invisible parameter** (key starts with `_`): internal field (such as `_game_name`, `_config_version`), raw value is enough, and the schema is not used.
+
+### Visible Parameter Schema
+
+```json
+"key_name": {
+  "value": <actual value>,
+  "type": "int" | "float" | "color" | "bool" | "string" | "audio" | "image" | "video",
+  "label": "<user-language label, <=10 characters>",
+  "min": <number>,
+  "max": <number>
+}
+```
+
+Rules:
+
+- `type` can only be `int`, `float`, `color`, `bool`, `string`, `audio`, `image`, or `video`.
+- `label` uses the user's language and must be no longer than 10 characters.
+- `min`/`max` appear only for `int`/`float`, and both must be provided together.
+- `type: "color"` uses a hexadecimal color string.
+- `type: "image"` must additionally declare `"image_type": "Asset"` and `"size": "widthxheight"` (such as `"1440x2560"`), to judge display size when the true image dimensions cannot be read.
+- The `value` of `audio`/`image`/`video` must be a real accessible external `http(s)` URL; local relative paths are forbidden. Images are generated asynchronously upstream; a brief 404 for the URL does not mean the asset is invalid, and the asset must not be rewritten, replaced, or deleted because of that.
+
+### Example
+
+```json
+{
+  "_game_name": "Example Game",
+  "_config_version": 1,
+  "move_speed": { "value": 220, "type": "int", "label": "Move Speed", "min": 50, "max": 400 },
+  "gravity_scale": { "value": 1.2, "type": "float", "label": "Gravity", "min": 0.2, "max": 3 },
+  "theme_background_color": { "value": "#10131f", "type": "color", "label": "Bg Color" },
+  "enable_shake": { "value": true, "type": "bool", "label": "Shake" },
+  "start_button_text": { "value": "Start Game", "type": "string", "label": "Start Text" },
+  "bgm_main": { "value": "https://example.com/bgm.mp3", "type": "audio", "label": "BGM" },
+  "image_background": {
+    "value": "https://example.com/background.png",
+    "type": "image",
+    "image_type": "Asset",
+    "size": "1440x2560",
+    "label": "Bg Image"
+  }
+}
+```
+
+## `/user_upload` Directory Rules
+
+`/user_upload` is a virtual directory for user-uploaded assets; files under it are not real asset files and only store asset links or metadata.
+
+1. When user-uploaded assets need to be used, first read the corresponding file under `/user_upload` and extract the real URL.
+2. Do not treat `/user_upload/...` as a local asset path; the final code must reference the extracted real URL.
+
+## Deployment and Path Rules
+
+1. The final deployment artifact is fixed as `/dist`, deployed as a static site, and runtime resources must be directly accessible through the browser.
+2. `/dist` must be able to run independently from the source directory: all runtime code, resources, chunks, CSS, audio, images, and config can only reference files inside `/dist` or external `http(s)` links, must use relative paths or build-output internal paths, and runtime references pointing to the source directory are strictly forbidden.
+3. `vite.config.js` must set `base: './'`, making build output use relative paths (`./assets/...`) and ensuring it can run when deployed under any subpath.
+4. All runtime string paths (`fetch`, `Audio`, dynamic `import`, CSS `url()`) must use `./` relative paths; absolute paths beginning with `/` are forbidden.
+
+## Required Files at the Project Root
+
+- `/project.md`: the only source of game requirements (design document); all subsequent development is based on this file.
+- `/public/config.json`: runtime configuration and asset binding contract.
+- `/src`: Vite + React + Phaser source code.
+- `/dist`: build output, deliverable.

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

@@ -0,0 +1,68 @@
+---
+name: phaser-2d-graphics-builder
+description: Upgrade Phaser 2D games from basic/prototype visuals to high-quality graphics. Covers art direction review, 2D scene paradigms, sprite/world kits, MCP image generation, camera/parallax/composition polish, event effects, performance budgets, and visual-score gating. Use when portrait or browser Phaser games need measurable visual quality improvement beyond placeholder color blocks.
+---
+
+# 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, exquisite/high-end visuals, 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 exquisite/high-end/premium visuals 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.