evomeme 0.1.9 → 0.1.10

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.

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

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Phaser 2D Graphics Builder"
+  short_description: "Comprehensively improve a 2D game's characters, scenes, composition, effects, and overall visual quality"
+  default_prompt: "Please use $phaser-2d-graphics-builder to improve this 2D game's overall visual quality, and refine its characters, scene layering, composition, and effects presentation."
+
+policy:
+  allow_implicit_invocation: false

package/dist/skills/en-US/threejs-3d-game/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: threejs-3d-game
+description: Implement 3D browser games with Three.js, React Three Fiber, TypeScript, and Vite. Use when R3F Canvas, simulation systems, DOM HUD overlays, event-bus bridging, or 3D project file structure is needed.
+---
+
+# Three.js 3D Game Implementation
+
+## Overview
+
+This skill is for the concrete implementation phase of 3D browser games.
+
+Tech stack: **Three.js + React + R3F + TypeScript + Vite + pnpm**. R3F `<Canvas>` owns the 3D / WebGL world; React DOM (`src/ui`) owns the HUD, menus, and narrative panels. Cross-layer communication goes through the event bus, unified input actions, and serializable simulation state.
+
+## Architecture Principles
+
+1. **Separate R3F and DOM**
+   - `<Canvas>` / `game/three` owns scenes, meshes, lights, `AnimationMixer`, and camera orchestration.
+   - `src/ui` owns the formal HUD, menus, settings, inventory, quests, and narrative panels.
+   - MUST NOT use R3F `<Html>` as a replacement for the formal HUD.
+
+2. **Simulation Before Rendering**
+   - Rules, values, win/loss, and saves belong in `game/simulation`, with no Three / React dependencies. (Aligned with the System layer in the 2D skill: the rules source-of-truth layer.)
+   - `useFrame` only orchestrates: read input/simulation -> sync `Object3D` -> mixer/camera; it does not write core rules.
+
+3. **Pure Three Modules Must Be Unit-Testable**
+   - `game/three/*` MUST NOT import React; scene construction and math helpers can be verified independently.
+
+4. **Stable Asset Keys + Canonical Semantics**
+   - All game code references assets through `manifest` / `public/config.json` / canonical packages, and does not hardcode glTF / texture paths in business code.
+   - **3D meshes MUST come from** `assets/canonical/<id>/` (or from `evomeme_asset_sync_to_three` syncing to `public/assets/canonical/<id>/`).
+   - After loading, orientation/scale **MUST** be applied according to `asset.json` (see `references/engine-asset-pipeline.md`); hardcoding `rotation.y += Math.PI` inside entities is prohibited.
+   - Alignment and preview default to skill `game-asset-align` + MCP `evomeme_stage_open`.
+   - **After Blender modeling or modification, Stage MUST be opened first, and the asset may only be imported after the user views and confirms the current Three.js version.** `alignment.ready=true` or set_orientation does not replace user confirmation; do not manually copy or click on behalf of the user to bypass the gate.
+
+## Implementation Guidance
+
+- Use `gameBus` (mitt) so React UI emits `command:*`, and the game runtime emits factual events such as `game:*` / `player:*`.
+- Centralize physical input mapping in `game/input`; UI and Canvas only consume unified semantic actions.
+- Put content data (levels, encounters, items) in `game/content`, decoupled from the rendering lifecycle.
+- Centralize audio in `game/audio`, driven by bus events; MUST NOT play in-game SFX with `new Audio()` inside the HUD (see `references/engine-audio.md` for details).
+- Canvas / gl / DPR defaults and R3F loading boundaries are covered in `references/engine-runtime.md`.
+
+## Covered 3D Game Types
+
+- Third-person / top-down exploration and lightweight action
+- Endless runners and obstacle dodging
+- Vehicles, pinball, and rigid-body sketches
+- Lightweight shooting or encounter battles
+- Casual gameplay that needs spatial 3D presentation
+
+## Camera and Presentation
+
+- Decide the camera model early: follow, orbit, lock-on, over-the-shoulder.
+- Separate camera logic from game rules; shake / FOV changes serve readability.
+- Resources MUST be disposed on StrictMode remount / unmount (geometry, materials, mixer, bus subscriptions).
+- See `references/engine-input-camera.md` for details.
+
+## Engine References (Load As Needed)
+
+When writing/modifying 3D runtime code, load references by task in addition to `file-structure.md`; do not pre-read everything at once:
+
+| Task | Load |
+| --- | --- |
+| Frame loop, Canvas/gl defaults, dispose, blank screen/double loop, R3F policy, diagnostic hooks | `references/engine-runtime.md` |
+| Input intent, touch stickiness, camera follow / FOV | `references/engine-input-camera.md` |
+| Physics selection, Rapier/fixed step, collision proxies | `references/engine-physics.md` |
+| GLB/FBX import, AnimationMixer, root motion, import performance | `references/engine-asset-pipeline.md` |
+| Stutter, pooling, InstancedMesh, DPR, LOD, hot-path allocation | `references/engine-performance.md` |
+| AudioContext unlock, bus-driven audio playback, mute, restart cleanup | `references/engine-audio.md` |
+
+Directory structure and layering are governed by this skill's `file-structure.md`; **do not** create separate directories based on the unrelated `core/entities/systems` scaffold.
+
+## UI Integration
+
+- HUDs, command menus, settings, and narrative interfaces use React DOM, overlaid above Canvas (`App` composition).
+- `GameCanvas.tsx` is the WebGL <-> React DOM boundary.
+- Business UI goes in `src/ui`; shared non-business primitives go in `src/components`.
+
+## Scaffolding and Configuration
+
+New project entry points: `index.html`, `src/main.tsx`, `public/config.json`. The package manager is **pnpm**. Build artifacts go to `dist/`, which must include `dist/index.html` and `dist/config.json`.
+
+Directory layout, layering responsibilities, config schema, and deployment paths use `references/file-structure.md` as the only normative source.
+
+## Common Anti-Patterns
+
+- Writing combat/win-loss rules in `useFrame` or `Hud.tsx`
+- Piling formal menus and settings into R3F `<Html>`
+- Importing React hooks / components inside `game/three`
+- HUD directly holding an `Object3D` reference and changing `position` every frame
+- Hardcoding the same glTF / texture path in multiple places
+- Adding an extra `new WebGLRenderer` or a second rAF that competes with R3F's loop
+- Not capping DPR; aggressively creating meshes/audio sources on hot paths
+- Playing in-game SFX with `new Audio()` inside the HUD
+- Replacing this specification with a CRA / Next.js / npm-only scaffold (unless the user explicitly requests it)
+
+## References
+
+**Engine (This Skill)**
+- File structure and layering: `references/file-structure.md`
+- Runtime / Canvas / R3F policy: `references/engine-runtime.md`
+- Input and camera: `references/engine-input-camera.md`
+- Physics and collision: `references/engine-physics.md`
+- Asset loading and animation: `references/engine-asset-pipeline.md`
+- Performance: `references/engine-performance.md`
+- Audio runtime: `references/engine-audio.md`
+
+**Cross-Skill (Gameplay / Acceptance, Not Engine Implementation Details)**
+- Gameplay workflow: `../game-designer/references/gameplay-workflows.md`
+- Game-feel tuning: `../game-designer/references/game-feel.md`
+- Level design: `../game-designer/references/game-design-level-design.md`
+- Physics selection (design-side comparison): `../game-designer/references/physics-engine-selection.md`
+- Definition of done for new games: `../game-designer/references/checklists/new-game-definition-of-done.md`
+- Art style guide: `../game-art/references/art-styles.md`
+- UI style specification: `../game-ui/references/ui-styles.md`
+- Audio asset generation: `../game-audio/SKILL.md`
+- QA / performance profiling: `../game-test/SKILL.md`

package/dist/skills/en-US/threejs-3d-game/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Three.js 3D Game"
+  short_description: "Build clearly structured 3D browser games, separating gameplay simulation, scene rendering, and interface"
+  default_prompt: "Please use $threejs-3d-game to implement this 3D browser game according to my requirements, while keeping the boundaries between gameplay simulation, 3D scene, and interface clear."
+
+policy:
+  allow_implicit_invocation: true