evomeme 0.1.9 → 0.1.10-beta.13

package/dist/skills/en-US/game-image-splitter/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: game-image-splitter
+description: Must be used whenever an image needs splitting. Guides evomeme_smart_split_image for independent foreground regions and evomeme_manual_split_image for row/column grids, producing separate PNGs. Applies to existing asset sheets, UI component sheets, tilesets, character views and frame sheets. Explains actual processing, outputs, transparent padding, alignment, crop boxes and output order, distinguishing cropping from cutout and AI layer decomposition.
+---
+
+# Image Splitting
+
+**Whenever an image needs splitting, use this skill.** Inspect the source and actual layout, choose independent-subject splitting or a fixed grid, then check files and coordinates. Both tools process existing images and accept no generation prompt.
+
+## Choosing a tool
+
+| Image or need | Choice and reason |
+| --- | --- |
+| Scattered objects without fixed cells, with clear gaps between subjects | `evomeme_smart_split_image`: determines crop boxes from foreground regions. Transparent backgrounds usually help detection. |
+| Regular rows and columns of tiles, character views or animation frames | `evomeme_manual_split_image`: uses confirmed grid dimensions and preserves every cell and its order. |
+| Equal output dimensions | Use `pad_to_same_size=true` for smart splitting. For grid splitting, source width/height must be divisible by columns/rows respectively to ensure equal cell sizes. |
+| Preserve blank cells or exact grid indices | Use grid splitting. Smart splitting returns detected subjects and does not preserve empty-cell indices. |
+| Margins, cell spacing, irregular partitions or a specific crop rectangle | Neither tool accepts margins, spacing, coordinates or partial cell selection. Handle the actual layout separately first; do not invent these tool parameters. |
+| Background removal only | Use cutout or color key through the [image and background processing skill](../game-asset-image-generator/SKILL.md). Splitting does not remove backgrounds automatically. |
+| Separate backgrounds, characters and foregrounds that occlude each other | Use the [layer decomposition skill](../game-image-layer-decomposer/SKILL.md); this requires AI content decomposition. |
+
+The tools share the canvas `smart_split` / `manual_split` tasks. Existing `splitImageAsset` / `manualSplitImageAsset` call the processing functions in `imageSplit.ts`. Both read images, detect or calculate crop regions, write files and register task results locally. They use no AI, do not upload automatically and preserve the source. MCP does not call other MCP tools, and integration does not modify task/image algorithms or built-in prompts.
+
+## What smart splitting actually does
+
+1. Read image dimensions and pixels. Detection limits the analysis image's longest side to 1600 pixels; final crops still use the source image without reducing subject size to the analysis resolution.
+2. With sufficient transparent regions, detect foreground by alpha; otherwise sample background color at edge locations and detect foreground by color difference. Apply small repairs and fragment merging, identify independent regions and map boxes back to source coordinates.
+3. Crop each subject. By default, pad with transparent pixels to the largest crop width × largest crop height, aligned by `anchor`, without scaling subjects. Disabling padding preserves individual crop sizes.
+4. Save **N independent PNGs, with N at least 2 on success**. Count depends on detection. Outputs run roughly top-to-bottom and left-to-right for nearby rows, not by semantic category or animation time.
+
+“Smart” means local pixel analysis, not model understanding of object categories. Touching objects may merge; disconnected decorations of one object may split apart; tiny elements may be ignored. Complex backgrounds, objects touching image edges and narrow gaps affect detection. Transparent images may receive a small safety margin around detected bounds; boxes do not promise exact contour fitting.
+
+**Background color is used only for detection and is not erased automatically.** Crops from a white-background source may still contain white. Transparent padding only makes newly added borders transparent. When removal is needed, use an available cutout/color-key tool first, then split its output image ID.
+
+| Parameter | Meaning |
+| --- | --- |
+| `id` | Required asset ID of one existing image inside workspace `assets/`, such as `assets/props.png`. |
+| `pad_to_same_size` | Optional, default `true`: pad with transparent pixels to equal dimensions. `false` preserves individual crop dimensions. |
+| `anchor` | Optional, default `center`: `top-left`, `top`, `top-right`, `left`, `center`, `right`, `bottom-left`, `bottom`, `bottom-right`. Affects placement only when padding is enabled. |
+| `workspace_dir` | Optional absolute workspace root. Set explicitly when possible; otherwise uses the MCP working directory. |
+
+For example, crop props and align them bottom-center on equal transparent canvases for later placement:
+
+```json
+{
+  "workspace_dir": "D:/my-game",
+  "id": "assets/props.png",
+  "pad_to_same_size": true,
+  "anchor": "bottom"
+}
+```
+
+Pass these arguments to `evomeme_smart_split_image`. For individual unpadded crops, set `pad_to_same_size=false`; `anchor` can then be omitted. There are no subject count, detection threshold, model or prompt parameters.
+
+## What grid splitting actually does
+
+1. Read source dimensions and validate integer row/column counts from 1 to 64, a product of at least 2, rows no greater than pixel height and columns no greater than pixel width.
+2. Partition the entire image by the specified grid. Boundaries are `floor(column index × source width / columns)` and `floor(row index × source height / rows)`, with zero-based indices; subtract adjacent boundaries for cell dimensions.
+3. Crop and save **rows × columns PNGs**, including transparent or blank cells. Return top-to-bottom, left-to-right within each row. There is no subject detection, automatic margin removal, dropped remainder edge, resizing or transparent padding.
+
+Non-divisible dimensions can produce cells differing by one pixel along an axis. For a width of 10 split into 3 columns, boundaries are 0, 3, 6, 10 and widths are 3, 3, 4. Do not assume equal cell sizes or discard the remainder.
+
+| Parameter | Meaning |
+| --- | --- |
+| `id` | Required existing workspace image asset ID, such as `assets/tileset.png`. |
+| `rows` | Required number of rows down the image, integer 1–64. |
+| `columns` | Required number of columns across the image, integer 1–64. The product of rows and columns must be at least 2. |
+| `workspace_dir` | Optional absolute workspace root; set explicitly when possible. |
+
+For example, split a confirmed 4×4 tileset into 16 images:
+
+```json
+{
+  "workspace_dir": "D:/my-game",
+  "id": "assets/tileset.png",
+  "rows": 4,
+  "columns": 4
+}
+```
+
+Pass these arguments to `evomeme_manual_split_image`. Confirm the actual layout of four-view, eight-direction and frame sheets first; “eight directions” does not imply eight columns. A 3×3 eight-direction sheet with an empty center produces 9 cells; explicitly exclude the center when using the results, as the tool does not skip it. Splitting a frame sheet preserves cell positions, while playback order and durations need separate configuration; it does not generate new animation.
+
+## Terminology and result fields
+
+- **Sheet / atlas**: Multiple assets stored in one image. Regular atlases have defined rows and columns; freely arranged asset sheets may have no grid. A frame sheet stores multiple time frames in one image, with order determined by its original design.
+- **Foreground, alpha and connected regions**: Foreground is the region detection aims to keep. Alpha stores pixel opacity. Connected regions are groups of neighboring pixels. Current detection uses eight-neighbor connectivity, including horizontal, vertical and diagonal neighbors, so diagonal contact can merge regions.
+- **Crop box**: A source-image rectangle `{x,y,width,height}` in pixels, with origin at the top-left, x increasing right and y increasing down. It covers `[x,x+width)` and `[y,y+height)`. Unlike AI layer decomposition's `bounding_box`, this contract defines the coordinates.
+- **Transparent padding**: Adds transparent pixels outside a crop to equalize output dimensions. It neither enlarges smaller subjects nor removes the source background inside a crop.
+- **Alignment anchor / engine pivot**: Anchor determines where a crop sits inside its padded canvas. A pivot determines the reference point for positioning, rotation and scaling in a game. `bottom` aligns crop bounds bottom-center; it does not recognize feet or configure an engine pivot.
+- **Row-major order**: Output every cell in the first row left-to-right before starting the second row. Zero-based row r and column c correspond to index `r × columns + c`.
+
+MCP returns text metadata with arrays represented as JSON text, without embedded images or Base64:
+
+| Field | Meaning |
+| --- | --- |
+| `images` (both) | All results with `id` / `asset_id`, `local_path`, `mime_type=image/png`, `name`, `source`, `kind` and `url`. `url=/files/...` is a canvas local-service path, not a public address. |
+| Top-level `asset_id`, `local_path`, `mime_type` | Summary of the first result, not the source or complete set. |
+| `source_id`, `operation_id`, `status` | Input asset ID, local task operation ID and success status. There is no remote AI `job_id`. |
+| `boxes` (both) | Actual source crop rectangles corresponding one-to-one by index with `images`, useful for recording or reconstructing source placement. |
+| `subject_boxes` (smart) | Detected regions mapped back to source coordinates, possibly including safety margins. Currently identical in content to `boxes`, not contour masks. |
+| `output_sizes` (smart) | Actual `{width,height}` for each result in `images` order, including transparent padding. |
+| `target_width`, `target_height` (smart) | Largest detected crop width and height. Equal output dimensions when padding is enabled; otherwise only maxima, not every image's size. |
+| `anchor`, `pad_to_same_size` (smart) | Actual alignment and padding settings. |
+| `rows`, `columns`, `source_width`, `source_height` (grid) | Grid settings and source pixel dimensions. Each output's size is the width/height of its corresponding `boxes` entry. |
+
+## Delivery and use
+
+The source must exist inside the workspace's `assets/`; `id` accepts no URL, absolute path or Base64. For earlier tool outputs, use their returned `asset_id` rather than guessing filenames. Results are written to `assets/` with batch identifiers and suffixes such as `_split_01.png` or `_grid_rowsxcolumns_01.png`, not semantic object names.
+
+Check count, order, crop edges, transparency and merged/missed subjects, then build a file → purpose/cell → source crop box list. Smart splitting fails when fewer than two valid subjects are detected. Inspect spacing and background and choose suitable preprocessing or a known grid; do not substitute newly generated artwork for cropping the requested source.
+
+To reconstruct source placement, position unpadded crops at `boxes[i].x/y`. Padded results also require subtracting the padding offset: `padX=floor((target_width-box.width)×ax)` and `padY=floor((target_height-box.height)×ay)`, where left/center/right ax is 0/0.5/1 and top/center/bottom ay is 0/0.5/1. Place at `box.x-padX, box.y-padY` to retain source position; do not simply align a padded image to the crop box's top-left.
+
+Use each result's `local_path` in the game and configure pivots, cells or frame order from actual content. Image bounds are not automatically colliders. When public URLs are needed, upload the corresponding results with `evomeme_upload_game_asset`; do not substitute the source sheet's URL for cropped files. On failure, inspect the error, task records and any files already written; the shared workflow does not guarantee a complete result list on failure.

package/dist/skills/en-US/game-image-splitter/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Image Splitting"
+  short_description: "Required guidance for smart and grid image splitting"
+  default_prompt: "Use $game-image-splitter to inspect this image, choose smart or grid splitting, and explain output files, dimensions and order."
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/en-US/game-maker/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: game-maker
+description: Organize the development goals of a game or game Demo into a progressively refinable task dependency graph. At the beginning, create only a rough task skeleton composed of main goals, key decisions, the core Demo, and necessary dependencies, then gradually refine relevant branches as development decisions are made and other Skills deliver their results. Use when the developer wants to create, prototype, expand, or systematically rework a game from scratch, or needs to establish and continuously maintain a game development task list.
+---
+
+# Game Maker
+
+## Goal
+Organize the developer's game idea into a rough task dependency graph that can start development, and progressively fill in task details as the project advances. Plan the next step based on currently confirmed information, let the corresponding Skill take over the concrete work, and return its results to the task graph.
+
+The core output of this Skill is a continuously updated game development task list. The initial list expresses the main work and necessary dependencies; later lists expand according to actual decisions and delivered results.
+
+## Core Principles
+1. The developer decides the game direction and concrete details, including gameplay direction, art style, UI style, and key parameters.
+2. The initial plan expresses only main goals, milestones, key decisions, and necessary dependencies, keeping tasks that have not entered execution at a coarse granularity.
+3. Create tasks and dependencies only from already confirmed information so the plan can start executing immediately.
+4. Use stable and unique task IDs to identify each task node.
+5. Refine the corresponding branch when a task is about to be executed, dependencies have been satisfied, or new delivery results appear.
+6. When refining tasks, keep the original task ID as a milestone, add concrete work using new task IDs, and update the milestone's prerequisites.
+7. Keep the core Demo as an early task node; within the same task, advance image generation and code construction in parallel, provide SVG fallbacks for all images, and show it to the developer as soon as the code can run.
+8. Hand concrete design and implementation to the corresponding Skill, and update the design document, task status, and dependencies based on its delivered results.
+
+## Progressive Planning
+
+### Establish The Initial Task Skeleton
+
+Read the developer's game idea, existing design document, and current project state. Confirm a small amount of key information that affects the overall direction, then create a rough task list containing the main decisions, core Demo, later main work, and final acceptance.
+
+An initial task may represent a complete milestone. Task names should let the developer understand what needs to be completed, and tasks should connect only to direct dependencies that are already clear.
+
+### Refine The Current Branch
+
+When a task becomes the next piece of work, judge whether it needs to be split based on the outputs of its prerequisite tasks. Tasks that can be directly handed to the corresponding Skill remain unchanged; tasks that need multiple independent results are expanded using new task IDs.
+
+After expansion, keep the original task as a milestone and make it depend on the newly added concrete tasks. Other branches that have not entered execution remain coarse-grained.
+
+### Update The Plan Based On Results
+
+After the developer makes a decision or another Skill returns delivered results:
+
+1. Update the corresponding task status;
+2. Add new tasks made clear by the result;
+3. Update dependencies that are directly affected;
+4. Select the next task whose dependencies have already been satisfied;
+5. Continue refining the corresponding branch before entering that task.
+
+## Game Development Points
+
+### Clarify Developer Requirements
+First, the Agent should accurately understand the game the developer wants to create. This stage focuses on the game's overall direction and core gameplay; concrete details are unfolded gradually in later planning. When the developer's description is relatively vague, ask follow-up questions about key information that affects the overall direction.
+
+### Every Game Starts With A Demo
+Treat building the Demo as the first main stage of the game plan. Keep the Demo minimal, implementing only the complete flow, project structure, and system architecture required to validate the core gameplay. Code safety and first-delivery success have higher priority than feature count, visual completeness, and extensibility design.
+
+Usually only one of the Demo and game concept art is delivered; both are used to let the developer quickly see the game effect. After Demo development begins, the playable Demo carries the effect presentation, and the Demo plan does not include a game concept art drawing task; add a concept art task only when the developer explicitly needs to confirm the art direction separately.
+
+The task list uses one "Create a playable Demo" node to uniformly carry core-loop confirmation, minimum playable system, project structure, code construction, image generation, SVG fallbacks, asset integration, and browser acceptance.
+
+When executing the Demo task, prioritize starting generation for the required image assets, and complete project and code construction at the same time. Prepare a corresponding SVG fallback image for each image asset and connect it into the game through a unified asset interface. Replace them one by one after generated images return; images that have not finished yet continue using SVG and do not affect core gameplay operation.
+
+After the code build is complete and the core loop can run, immediately start a static service and open the game webpage for developer acceptance. Remaining images continue to be generated and integrated after the first presentation; image-generation progress does not delay delivery of the playable Demo. Demo acceptance is completed by the developer in the browser, and no Agent-side automated test task is arranged.
+
+### Continuously Maintain The Overall Game Design Document
+As the core game loop and core game systems gradually become clear, the Agent and developer continuously refine the complete play path. Use `/project.md` to record gameplay, the core loop, game systems, and their details in detail.
+
+Whenever gameplay is adjusted, update `/project.md` at the same time. All changes to gameplay direction should be discussed with the developer, and the developer makes the final decision.
+
+### Keep Code Modular, Functional, And Parameterized
+While building the Demo and later optimizing gameplay, split different game systems into independent code modules, and reuse common functions and logic for similar systems. Keep code paths valid, structure clear, and maintenance easy, improving the project's usability and robustness.
+
+To make it easy for the developer to fully take over later game development, parameterize all configuration and centralize variables in locations the developer can easily find and modify. When image assets are involved, establish a unified SVG fallback and asset-loading flow for each asset, and connect generated images within the same Demo production process.
+
+### Art And Game Code Can Advance In Parallel
+The developer can advance art and code work in two separate conversations. Art creation starts with concept art and an art setting collection, used to unify and control the game's overall art style.
+
+First, create concept art that represents the direction of the final game product based on information provided by the developer. Then create corresponding setting images for each type of element in the game systems, uniformly using pure white background three-view images.
+
+Continuously adjust concept art and the setting collection based on developer feedback. After the art direction is complete and confirmed, generate the in-game asset images needed according to the corresponding concept art and setting images.
+
+### Split Complex Tasks Into Four Types Of Subtasks
+Any complex task can be split into the following four types of subtasks, and each type can contain multiple concrete tasks:
+
+1. Generation task: The Agent is responsible for generating the images, code, models, and text needed by the game.
+2. Automation task: The Agent is responsible for automated processing of assets and text, such as cutout, formatting, and Photoshop operations.
+3. Decision task: The developer is responsible for judgments and choices about the game development direction.
+4. Detail adjustment task: The developer is responsible for determining concrete in-game parameters, including the spatial positions of game elements, game system parameters, and in-game colors.
+
+## Special Requirements For evomeme Platform Game Development
+When the target platform is evomeme, the initial plan may first establish a platform adaptation milestone. After entering that branch, split the following requirements into task nodes and establish dependencies:
+
+1. Create a mobile portrait, touch-first web game task.
+2. Create an evomeme cloud upload task for binary assets such as images, audio, videos, fonts, and models.
+3. Create a `public/config.json` resource configuration task, dependent on asset links returned by the cloud upload task.
+4. Create a production build task, using `npm run build` to output the final webpage to `dist/`, and dependent on game functionality and resource configuration tasks.
+5. Create a `dist/` build output inspection task, making it contain only the text build outputs needed for webpage runtime, and dependent on the production build task.
+6. Create a mobile portrait, touch interaction, and remote asset loading validation task, dependent on the production build task.
+
+## Output
+Output a flat task dependency list in Markdown. Keep the initial list rough and include only the main tasks currently needed; as work advances, add refined tasks in the same list. All task nodes are arranged directly under the title. Each task uses a stable and unique task ID and references prerequisites by task ID.
+
+```markdown
+# Game Development Task List
+
+- [ ] T001 [Decision Task - Developer] <task name>
+- [ ] T002 [Generation Task - Agent] <task name> (depends on: T001)
+- [ ] T003 [Automation Task - Agent] <task name> (depends on: T001)
+- [ ] T004 [Detail Adjustment Task - Developer] <task name> (depends on: T002, T003)
+- [x] T005 [Generation Task - Agent] <completed task name>
+```
+
+Task types use "Generation Task, Automation Task, Decision Task, Detail Adjustment Task". Use `[ ]` for incomplete and `[x]` for complete. Task IDs increase in creation order and remain stable. Initial tasks may represent larger milestones; when refining, keep the original number and assign new numbers to new tasks. When direct dependencies exist, reference the corresponding task IDs at the end of the task, and keep the task relationship as a directed acyclic graph.

package/dist/skills/en-US/game-maker/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Game Maker"
+  short_description: "Organize a game idea into development tasks and dependencies that can be progressively refined and continuously maintained"
+  default_prompt: "Please use $game-maker to create a rough development task list from my game idea, and progressively supplement and update it as development proceeds."

package/dist/skills/en-US/game-perfect-pixel/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: game-perfect-pixel
+description: Use evomeme_perfect_pixel to organize an existing pixel-style image into a crisp pixel grid, detecting or specifying source cells, sampling each cell and exporting one PNG at an integer scale. Use for pixel-style assets with uneven grids or blurred edges after generation or enlargement, and explicitly requested pixelation. Explains processing, outputs, logical pixels, grid size, color sampling, alpha thresholds and nearest-neighbor export. Not for new content generation, splitting or automatic cutout.
+---
+
+# Perfect Pixel
+
+Use `evomeme_perfect_pixel` to organize an existing image's pixel grid. Inspect recognizable source blocks and any translucent effects before choosing automatic/manual grid and alpha settings. The tool name does not guarantee recovery of the original pixel artwork.
+
+## What it does and produces
+
+One call runs locally:
+
+1. Read an existing workspace image and decode its color and alpha pixels.
+2. By default, analyze repeated horizontal/vertical edges to estimate a grid and refine its boundaries. Manual mode divides regions from the top-left using `pixel_size`.
+3. Sample one color and alpha per region to create a low-resolution **logical pixel grid**.
+4. Enlarge by integer `export_scale` with nearest-neighbor sampling, save **one new PNG** into `assets/`, preserve the source and register the task.
+
+No AI calls, automatic uploads, multiple split files, new characters, scenes or animation. The intermediate low-resolution grid is not saved separately; set `export_scale=1` to obtain it. The output name derives from the source name with a `_perfect-pixel` marker; use the actual returned path.
+
+MCP and canvas submissions both use the `perfect_pixel` task to call `processPerfectPixel` in `image/perfectPixel.ts`, sharing decoding, grid detection, sampling and PNG encoding. The algorithm runs in a local Node background thread, without browser Workers. Canvas previews use the same processing pipeline and return only a temporary preview; confirmation processes the current parameters again and saves the asset. The task layer resolves paths, saves results and records tasks. No MCP-to-MCP calls.
+
+## When to use it
+
+| Need | Choice |
+| --- | --- |
+| Smoothed enlargement has softened pixel-style block edges, but a repeated grid remains visible | Try automatic detection and inspect the actual result and detected dimensions. |
+| Known source blocks, such as 8×8 regions per logical pixel | Disable automatic detection and set the actual `pixel_size`. |
+| Automatic detection fails, flat areas dominate or different grids conflict | Inspect the source and choose a manual grid. Failure is not completion, and not every image has an original grid to recover. |
+| Coarse pixelation of an ordinary image | Manual mode can do this, losing detail; it is not equivalent to artist-redrawn pixel art. |
+| Only enlarge already crisp native pixel art proportionally | Prefer the project's existing nearest-neighbor resizing. This tool resamples, with a minimum manual source cell of 2; it is not a lossless 1×1 pixel enlarger. |
+| Separate multiple assets in an atlas | Use the [image splitting skill](../game-image-splitter/SKILL.md). This tool always outputs a single image. |
+| Remove white, a key color or a complete background | Use the [image and background processing skill](../game-asset-image-generator/SKILL.md). This tool processes existing alpha, not background identification. |
+
+Best suited to relatively consistent pixel blocks. Rotated grids, mixed-resolution atlases, fine text, photographs and broad soft gradients are not guaranteed to be detected correctly or retain detail. Inspect according to the actual purpose rather than promising lossless repair.
+
+## Parameters and terminology
+
+| Parameter | Meaning, default and range |
+| --- | --- |
+| `id` | Required workspace image asset ID, e.g. `assets/hero.png`, or a previous tool's `asset_id`. No URL, absolute file path or Base64. |
+| `workspace_dir` | Optional absolute workspace root; set explicitly when possible. Defaults to the MCP working directory. Source must be inside that workspace's `assets/`. |
+| `auto_grid` | Default `true`: estimate the grid. Set `false` for manual `pixel_size`. Detection failure reports an error without silently falling back to manual settings. |
+| `pixel_size` | Default 8, integer 2–256; controls only manual grid mode. Side length of a source region per logical pixel, not the exported block size or final image dimensions. |
+| `sample_method` | Default `median`; also `majority` or `center`. Chooses the color per cell, as described below. |
+| `export_scale` | Default 4, integer 1–16. Output block side length per logical pixel; 4 makes each cell a 4×4 block of output pixels. |
+| `alpha_mode` | Default `hard`, alternatively `preserve`; determines per-cell alpha. |
+| `alpha_threshold` | Default 128, integer 0–255. Only `hard` uses it to compare average cell opacity. |
+
+- **Logical pixel / grid**: The low-resolution sampled array, with one logical pixel per region. `grid_width × grid_height` counts its cells, not source image dimensions or image-splitting rows and columns.
+- **Source cell**: Region of the source contributing one logical pixel. Manual mode starts top-left and uses `pixel_size`, including partial edge regions. Automatic mode can refine boundaries; returned `pixel_size_x/y` are average source-region sizes, possibly fractional, not identical exact crop boxes for every cell.
+- **Nearest-neighbor**: Enlargement copies logical pixel colors without interpolated color transitions. Integer export scales preserve distinct pixel blocks.
+- **Alpha / opacity**: 0 is transparent, 255 opaque and intermediate values translucent. White or painted checkerboards are not actual transparency. `alpha_threshold` does not identify backgrounds by RGB color.
+- **Confidence**: An internal score from 0 to 1 for evidence of a repeated grid. It is not a reconstruction accuracy percentage or an art-quality guarantee. Manual mode omits it.
+
+Color sampling:
+
+| Value | Actual behavior and selection guidance |
+| --- | --- |
+| `median` | Takes the alpha-weighted median separately for red, green and blue, reducing some color noise. A useful default; not a median of complete pixel samples, so resulting colors may not occur in the original. |
+| `majority` | Splits visible color samples into two groups and takes the representative color of the group with greater total weight. Emphasizes dominant color regions; it is not exact color-frequency voting and does not limit the whole image to two colors. |
+| `center` | Takes the visible center pixel color, falling back to an alpha-weighted mean of visible samples when the center is nearly transparent. Useful for a known grid with representative cell centers. Alpha still follows the selected alpha mode. |
+
+Alpha modes:
+
+- `hard`: Output 255 when average cell opacity reaches the threshold, otherwise 0. Cells without visible color samples remain transparent. Suits hard-edged sprites; raising the threshold may lose thin edges and small details, while lowering it can thicken edges.
+- `preserve`: Uses the median sampled cell alpha, allowing partial transparency. It does not preserve original alpha pixel by pixel; narrow soft edges, smoke and shadows can still change. `alpha_threshold` does not control this mode.
+
+There are no `prompt`, `model`, target dimensions, palette-size, color-key or custom grid-offset parameters. All color methods may change details and colors; palette preservation is not guaranteed.
+
+## Invocation and size calculation
+
+To detect an existing pixel-style character's grid and export hard-edged artwork, call `evomeme_perfect_pixel`:
+
+```json
+{
+  "workspace_dir": "D:/my-game",
+  "id": "assets/hero.png",
+  "auto_grid": true,
+  "sample_method": "median",
+  "export_scale": 4,
+  "alpha_mode": "hard",
+  "alpha_threshold": 128
+}
+```
+
+For confirmed 8×8 source blocks with partial transparency:
+
+```json
+{
+  "workspace_dir": "D:/my-game",
+  "id": "assets/effect.png",
+  "auto_grid": false,
+  "pixel_size": 8,
+  "sample_method": "majority",
+  "export_scale": 4,
+  "alpha_mode": "preserve"
+}
+```
+
+Output dimensions = **logical grid dimensions × export scale**. A 512×384 source with manual `pixel_size=8` becomes a 64×48 logical grid. `export_scale=4` outputs **256×192**, not 2048×1536. With non-divisible dimensions, manual logical sizes are `ceil(source width/pixel_size)` and `ceil(source height/pixel_size)`; each partial edge cell still becomes a complete output block.
+
+Save limits match canvas: each logical grid dimension is at most 2048; each output dimension is at most 32768. For an oversized manual grid, increase `pixel_size` or use a smaller source. Lowering `export_scale` reduces final image size but not logical cell count.
+
+## Result fields and use
+
+MCP returns text metadata, without embedded image bytes or Base64:
+
+| Field | Actual meaning |
+| --- | --- |
+| `asset_id`, `local_path`, `mime_type` | New output's workspace ID, absolute local path and `image/png`. |
+| `source_id`, `operation_id`, `status` | Original image ID, local operation ID and success status. No remote AI `job_id`. |
+| `width`, `height` | Actual final PNG dimensions. |
+| `grid_width`, `grid_height` | Sampled logical grid dimensions. |
+| `pixel_size_x`, `pixel_size_y` | Actual source-region sizes, potentially fractional in automatic mode. |
+| `auto_grid`, `pixel_size`, `sample_method`, `export_scale`, `alpha_mode`, `alpha_threshold` | Actual request settings. `pixel_size` may still appear in automatic mode and `alpha_threshold` in preserve mode, but they do not control the inactive branches. |
+| `confidence` | Grid-detection score returned only in automatic mode. |
+
+Compare source and output for outlines, colors, details, transparent edges and aspect ratio. In automatic mode, check whether repeated content was mistaken for a grid. Read a failure's specific error before choosing manual size from the actual source; do not blindly repeat identical automatic requests.
+
+Use the result as a normal PNG texture or sprite with nearest-neighbor/point filtering and integer display scales so runtime smoothing does not blur the blocks again. Resolution may change, so check display size, pivots, atlas coordinates and colliders when replacing artwork. Use `game-image-splitter` if an atlas must be divided; Perfect Pixel does not maintain atlas coordinates for you.
+
+The final file is local only. Upload its `local_path` through `evomeme_upload_game_asset` when a public URL is needed; do not substitute the source image URL for the processed result.

package/dist/skills/en-US/game-perfect-pixel/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Perfect Pixel"
+  short_description: "Restore pixel grids with sampling, alpha and export guidance"
+  default_prompt: "Use $game-perfect-pixel to inspect this pixel-style image, choose grid and alpha settings, and export a crisp PNG with its actual dimensions."
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/en-US/game-scroll-generator/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: game-scroll-generator
+description: Generate, edit and optimize horizontal scrolling-map image resources, including backgrounds, optional midground and foreground layers, per-layer left/right seam repair and transparent overlays. Always use this skill for scrolling maps, horizontally looping backgrounds, parallax layers or seam repair of existing scrolling images. Explains both MCP workflows, parameters, output files and scrolling, parallax, color-key and seam-repair terminology.
+---
+
+# Scrolling Map Resource Generation and Editing
+
+Always use this skill when generating or editing scrolling maps, horizontally looping backgrounds or parallax layers. It produces scene image resources. Scrolling speed, direction, layer placement, collision and level data belong to the game project or canvas preview.
+
+| Tool | Actual work and outputs | When to use |
+| --- | --- | --- |
+| `evomeme_generate_scroll_image` (Scrolling Scene Generation) | Always generates a background, optionally a midground and foreground; each requests 3024×1296. Each layer can receive left/right seam repair, and overlay layers can receive automatic color key processing. Produces 1–3 final layer files and retains generated, repaired and keyed stage files. | Create a horizontal scene from text or references, or a consistent set of layers for parallax scrolling. |
+| `evomeme_eliminate_scroll_background_seam` (Scrolling Map Seam Elimination) | Runs one AI left/right seam repair on an existing 3024×1296 image, saves and uploads one new same-size PNG, and preserves the source. | An existing background, midground or foreground needs better horizontal looping continuity. |
+
+For square tiles, four-edge tiling and terrain transition atlases, use [Tilemap Resource Generation and Editing](../game-tile-generator/SKILL.md). For ordinary illustrations and scene images, use [Game Image Generation and Processing](../game-asset-image-generator/SKILL.md). This workflow generates separate layers; it does not semantically decompose an existing flattened image.
+
+## Terms and Scope
+
+- **Scrolling image / horizontally looping background**: A wide scene that moves horizontally. Repeating copies are placed side by side so content leaving one end can continue at the other. This tool requests a fixed width of 3024 and height of 1296 pixels, not an arbitrary-length map. It does not make top and bottom edges repeatable.
+- **Background, midground and foreground**: The complete distant scene, separate middle-distance scenery and scenery closest to the camera. They are independent images on equally sized canvases, stacked through transparent empty areas, not three panels packed into one image.
+- **Parallax scrolling**: Moving layers at different speeds to imply depth, usually slower for distant layers and faster for near layers. The tool supplies images, not scrolling code or an animated video.
+- **Native transparency / alpha channel**: The model directly outputs transparent areas. Alpha records each pixel's opacity: zero means transparent and the maximum means fully opaque. Transparent areas reveal lower layers; they are not painted white. This scroll workflow only allows `asset-max` to request native transparency.
+- **Color key / background-color removal**: Generate scenery on a solid background, then make pixels similar to that color transparent. This workflow uses strength 80, Oklab perceptual color space (color distances approximate human perception), and soft edges. It processes matching colors throughout the image, not only areas connected to its edges, and disables despill. **Despill** reduces residual key-color tint around subject edges. Matching subject colors may also disappear, so choose a key color absent from the subject.
+- **Seam repair / circular offset / inpainting**: Circularly shift by half the width, 1512 pixels, along X; pixels leaving one edge re-enter at the other. Y is unchanged. The original left/right seam moves to the center, where a vertical strip is made transparent for AI completion, followed by reversing the offset. The repair strip is about 12.5% of the width, 378 pixels. This transparent strip marks the reference's repair area; it does not request a transparent final background.
+- **Scroll repair extent**: The current implementation retains the entire AI output and reverses its offset. Although the prompt asks to preserve other areas, there is no local composition that replaces only the repair strip as in the tile tool. Other scenery may change. Inspect both the complete image and its left/right seam afterward.
+
+## Workspace and References
+
+Explicitly pass an absolute `workspace_dir`, such as `D:/my-game`; otherwise the MCP process working directory is used. Files are saved under that workspace's `assets/`.
+
+`reference_ids` and `id` are paths relative to the workspace root, such as `assets/references/forest.png`, not absolute paths, URLs or Base64. Locate actual user attachments or external local files and copy them into `assets/` using non-overwriting names. Download an accessible image URL first when that is the only source. If the actual file is unavailable, identify the missing reference instead of inventing an ID. Reuse images already in the workspace and returned `asset_id` values.
+
+## Generate a Scrolling Scene
+
+| Parameter | Default / meaning |
+| --- | --- |
+| `prompt` | Required nonempty background description: theme, style, palette, lighting, horizontal composition and gameplay negative space. |
+| `model` | `asset-pro`; also `asset-max` or `asset-lite`. All three support the 3024×1296 request used here. |
+| `reference_ids` | `[]`; up to 10 for Pro, 14 for Max/Lite in this tool. References apply only to background generation. |
+| `seam_elimination_enabled` | `false`; add one left/right seam repair to the background. |
+| `midground_enabled` / `foreground_enabled` | Both `false`; independently enable the middle or near layer. |
+| `midground_prompt` / `foreground_prompt` | Required and nonempty when the corresponding layer is enabled. Describe its scenery, placement, density and occlusion instead of repeating the entire background. |
+| `midground_transparent_background` / `foreground_transparent_background` | Both `false`: generate on solid color, then automatically color-key. `true` requires Max, requests native transparency and skips color key processing. |
+| `midground_background_color` / `foreground_background_color` | Both `#ff00ff`; the solid background/key color for that layer. Accepts `#RGB` or `#RRGGBB`; native transparency does not use this solid background. |
+| `midground_seam_elimination_enabled` / `foreground_seam_elimination_enabled` | Both `false`; add one left/right seam repair to that layer. |
+| `workspace_dir` | Workspace root; explicitly specify it. |
+
+Do not pass `size`, scrolling speed or direction. Defaults generate only the background and add no seam repair. Enable repair for the relevant layers when looping is required; successful generation alone is not visual proof of seamlessness.
+
+Execution order: generate background → optionally repair background seams → use the final background as reference while processing midground and foreground in parallel. Within each enabled overlay: generate → optionally repair → automatically color-key unless native transparency was requested. User references are not passed directly to overlays, and the overlays do not reference each other. MCP and canvas call the same existing `executeScrollImage` task function, reusing existing image functions without chaining MCP calls. Do not change image implementations or built-in prompts merely to port a tool.
+
+Normal AI request count = enabled layers, including background, plus layers with seam repair, for a total of 1–6, excluding server retries. Color key is local and adds no AI request. With all three layers, all repairs and color key on both overlays, eight stage files are saved and three are the final layers. Enabled non-native-transparent overlays always receive color key processing; there is no separate switch to disable it.
+
+```json
+{
+  "workspace_dir": "D:/my-game",
+  "prompt": "Side-scrolling forest level, distant blue-green mountains and mist, soft consistent light, hand-painted style, clear central gameplay area, no characters or text",
+  "model": "asset-pro",
+  "seam_elimination_enabled": true,
+  "midground_enabled": true,
+  "midground_prompt": "Middle-distance tree trunks and sparse canopies, open central passage, match the background palette and lighting",
+  "midground_background_color": "#ff00ff",
+  "midground_seam_elimination_enabled": true,
+  "foreground_enabled": true,
+  "foreground_prompt": "A few close grass blades and rocks along the bottom, broad empty upper area, keep central gameplay unobstructed",
+  "foreground_background_color": "#ff00ff",
+  "foreground_seam_elimination_enabled": true
+}
+```
+
+Read the actual base-image format from `mime_type`; repaired and keyed outputs are PNG. Final keyed transparent PNGs remain local and are not automatically uploaded. When a remote URL is needed, pass that layer's final `local_path` to `evomeme_upload_game_asset`. Never substitute its `base` or `seam` cloud URL for the final keyed image.
+
+## Repair an Existing Scrolling Map
+
+| Parameter | Default / meaning |
+| --- | --- |
+| `id` | Required workspace ID of an existing 3024×1296 image. Dimensions are read from the file; no `size` parameter or automatic resizing. |
+| `model` | `asset-pro`; Max or Lite also supported. Requesting transparency requires Max. |
+| `prompt` | Optional continuity, style and preservation requirements. |
+| `has_background` | `false`: no constraint on empty-area background. This does not select the scene's background layer. Set true to constrain a solid or transparent background. |
+| `transparent_background` | `false`; only applies when `has_background=true`. True requests transparency and requires Max; false retains the solid color below. |
+| `background_color` | `#ff00ff`; constrains the solid background only when `has_background=true` and `transparent_background=false`. Accepts `#RGB` or `#RRGGBB`. |
+| `workspace_dir` | Workspace root; explicitly specify it. |
+
+For an ordinary opaque background, provide `id`, workspace and an optional prompt. For an existing transparent overlay, set `has_background=true`, `transparent_background=true` and `model=asset-max`. For a solid-color overlay, set `has_background=true` and the actual background color. If transparency is needed afterward, pass the repaired ID to `evomeme_color_key`; standalone repair does not automatically remove the color.
+
+```json
+{
+  "id": "assets/foreground-transparent.png",
+  "workspace_dir": "D:/my-game",
+  "model": "asset-max",
+  "prompt": "Continue grass and rocks naturally across the left/right boundary, retaining empty space and the original style",
+  "has_background": true,
+  "transparent_background": true
+}
+```
+
+Order: horizontal offset → upload reference with transparent central strip → one AI completion → reverse the offset of the entire output → save and upload the final PNG. Produces one new image and preserves the source. Temporary references and raw AI completion files are not deliverables. Final `asset_url` / `tos_url` refer to the restored PNG. Transparency settings constrain the generation; they do not add cutout processing.
+
+## Results, Integration and Failures
+
+MCP returns text metadata, not image bytes or Base64. `operation_id` identifies a local step and `job_id` a remote AI request; color key has no remote AI request ID. `status=SUCCEEDED` means processing finished, not visual approval. Standalone repair also returns `task_id`; scene generation reuses its existing result and does not promise that field.
+
+Scene generation returns JSON text for `background` and optional `midground` / `foreground`. Each layer's `id` / `asset_id`, `local_path`, `mime_type` and applicable cloud URLs describe its final file. `base` is the original generated image and `color_key` the optional keyed result. Top-level metadata describes the final background, not a flattened composition. Existing scene results have no `outputs`, separate `seam` or `ai_generation_count` fields and do not probe actual dimensions. Inspect workspace task records for intermediate files and processing details.
+
+Standalone repair lists only the new PNG in `outputs`, with `source_id`, model, size and background-constraint fields. Both workflows provide `transform` fields for `offset_x`, `offset_y`, `mask_width` and `offset_restored`. Scene repair's `feather=0` indicates no local feathered composition of the repair strip; this is separate from color-key edge softening.
+
+Stack final files background → midground → foreground, then configure horizontal repetition and layer speeds in the engine. Inspect side-by-side copies for horizon and object continuity, as well as transparent areas, key-color remnants, accidentally removed subject pixels and gameplay occlusion. The existing canvas scroll preview can show speed and direction; these MCPs do not generate preview pages.
+
+On failure, inspect `isError: true` details and retain source files. Completed earlier stages and successful sibling layers remain saved with task records; a failed branch waits for its sibling to settle before the operation reports failure. Locate completed assets through workspace task records or the canvas before deciding whether to run standalone repair or color key. If client waiting was interrupted, check the original task before resubmitting the whole scene to avoid duplicate generation.

package/dist/skills/en-US/game-scroll-generator/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Scrolling Map Resource Generation and Editing"
+  short_description: "Generate scrolling layers and repair horizontal seams"
+  default_prompt: "Use $game-scroll-generator to generate, edit or optimize scrolling-map images, create background, midground and foreground layers, or repair an existing image's left/right seam."
+
+policy:
+  allow_implicit_invocation: true

package/dist/skills/en-US/game-test/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: game-test
+description: After game development ends, perform smoke testing and gameplay QA for a 2D or 3D browser game, verifying that the game can start, display, and complete the core gameplay loop, while also checking main input, state transitions, failure/retry, and desktop and mobile behavior. Use when a just-completed game or Demo needs final self-checking, basic playability confirmation, or gameplay issue recording.
+---
+
+# Game Test
+
+## Goal
+
+After game development ends, perform one smoke test and gameplay QA pass to confirm from the player's perspective that the game can enter, be controlled, progress, end, and restart normally, and record issues that block the basic experience.
+
+## Smoke Testing And Gameplay QA
+
+Before testing, read the project's startup method, target devices, input methods, core gameplay loop, and win/loss conditions. Load [`references/checklists/playtest-qa.md`](references/checklists/playtest-qa.md) as the testing reference.
+
+### Workflow
+
+1. Install dependencies as needed by the project and run the existing build or type-check command.
+2. Start the development server or preview server and open the correct game page.
+3. Capture browser console, page, and network errors.
+4. Confirm the game screen displays normally, and the Canvas has a valid size and visible content.
+5. Starting from a clean load, actually play the core loop for at least 2 minutes.
+6. Test movement, aiming, jumping, attacking, dragging, or the primary inputs corresponding to the gameplay.
+7. Verify objective progress, scoring, collection, collisions, and other core state changes.
+8. Trigger actually existing paths such as success, failure, pause, resume, and restart.
+9. Rapidly switch inputs and test game boundaries, repeated actions, and state recovery after restart.
+10. Check visuals, HUD, text, safe areas, and touch regions under target desktop and mobile viewports.
+11. When audio is part of the core experience, verify first-interaction unlock, main sound effects, background music, pause behavior, and restart behavior.
+12. Record test results and discovered issues.
+
+### 2D Game Focus
+
+- Sprites, tiles, and platform positions are clear;
+- Animation, hit reaction, and state feedback are readable;
+- HUD and the core gameplay area remain clear;
+- Input results are consistent with game state.
+
+### 3D Game Focus
+
+- Scene, camera, materials, and lighting display normally;
+- Characters, environment, and objectives have clear silhouettes and depth relationships;
+- Camera controls, collision, and restart behavior are stable;
+- Models, textures, and animations can load and run during actual play.
+
+### Test Results
+
+Report using a brief format:
+
+```markdown
+# Smoke Testing And Gameplay QA
+
+- **Result**: <Pass / Fail>
+- **Runtime Environment**: <commands, page, and test viewports>
+- **Verified Paths**: <core operations and gameplay loop>
+- **Issues Found**: <none, or issue list>
+```
+
+For each issue, describe what the player sees, reproduction steps, and the impact on gameplay.

package/dist/skills/en-US/game-test/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Game Test"
+  short_description: "Complete game smoke testing and gameplay acceptance from the player's perspective, recording issues that affect the experience"
+  default_prompt: "Please use $game-test to playtest this game, complete smoke testing and core gameplay acceptance, and record the issues found."
+
+policy:
+  allow_implicit_invocation: true