|
|
# PixelLab MCP — verified tool surface (AutoHero)
|
|
|
|
|
|
Reference date: aligned with [https://api.pixellab.ai/mcp/docs](https://api.pixellab.ai/mcp/docs) (auto-generated from FastMCP). **Re-check the live docs** if tools fail or names differ in your Cursor client (tools may appear as `mcp__pixellab__<name>` or similar).
|
|
|
|
|
|
## Cross-cutting behavior
|
|
|
|
|
|
- Creation tools **return immediately** with IDs; generation runs in the background (order of minutes).
|
|
|
- Poll with matching **`get_*`** tools until status is **completed** (or handle `processing` / `failed` per response).
|
|
|
- **Do not** treat remote URLs as durable storage for the repo: **download or decode base64 and write PNGs under** `frontend/assets/` (`tiles/`, `prop/`, `building/`, `enemies/`, `characters/`). Register each texture in `frontend/public/assets/game/manifest.json` (`file` paths are relative to `frontend/assets/`).
|
|
|
|
|
|
## Character and animation
|
|
|
|
|
|
| Tool | Role | Key parameters |
|
|
|
|------|------|----------------|
|
|
|
| `create_character` | Queue 4/8-direction character | `description`, `n_directions` (4\|8), `size` (default 48), `body_type` (`humanoid`\|`quadruped`), `template` (quadruped: bear, cat, dog, horse, lion), `proportions` (JSON preset), `view` |
|
|
|
| `animate_character` | Queue animation on existing character | `character_id`, `template_animation_id`, optional `action_description`, `confirm_cost` |
|
|
|
| `get_character` | Status, rotations, animations, download | `character_id` |
|
|
|
| `list_characters` | Paginated list | `limit`, `offset`, `tags` |
|
|
|
| `delete_character` | Remove character | `character_id`, `confirm` |
|
|
|
|
|
|
Per docs: characters are **stored on PixelLab** for reuse; still **export PNGs/ZIP into the repo** for builds and versioning.
|
|
|
|
|
|
## Isometric tiles
|
|
|
|
|
|
| Tool | Role | Key parameters |
|
|
|
|------|------|----------------|
|
|
|
| `create_isometric_tile` | Single isometric tile | `description`, `size` (default **32**, docs recommend ≥32), `tile_shape` (`thin`\|`thick`\|`block`), `outline`, `shading`, `detail`, `seed` |
|
|
|
| `get_isometric_tile` | Status + **base64 PNG** / download URL | `tile_id` |
|
|
|
| `list_isometric_tiles` | Paginated list | `limit`, `offset` |
|
|
|
| `delete_isometric_tile` | Delete | `tile_id` |
|
|
|
|
|
|
## Map objects (transparent props)
|
|
|
|
|
|
| Tool | Role | Key parameters |
|
|
|
|------|------|----------------|
|
|
|
| `create_map_object` | Prop with alpha | `description`, `width`, `height`, `view`, `outline`, `shading`, `detail`, `background_image`, `inpainting` |
|
|
|
| `get_map_object` | Status and asset data | `object_id` |
|
|
|
|
|
|
Marketing copy elsewhere mentioned **time-limited hosting** for some assets; **treat all MCP outputs as ephemeral until checked into the project.**
|
|
|
|
|
|
## Tiles Pro (optional)
|
|
|
|
|
|
| Tool | Role | Key parameters |
|
|
|
|------|------|----------------|
|
|
|
| `create_tiles_pro` | Batch / pro tiles | `description`, `tile_type` (default `isometric`), `tile_size`, `n_tiles`, `tile_view`, `seed`, `style_images`, … |
|
|
|
| `get_tiles_pro` | Status and data | `tile_id` |
|
|
|
| `list_tiles_pro` | List | `limit`, `offset` |
|
|
|
| `delete_tiles_pro` | Delete | `tile_id` |
|
|
|
|
|
|
## Top-down and sidescroller Wang tilesets
|
|
|
|
|
|
- `create_topdown_tileset` / `get_topdown_tileset` / `list_topdown_tilesets` / `delete_topdown_tileset` — corner Wang sets, `tile_size` default 16×16, chain via `lower_base_tile_id`.
|
|
|
- `create_sidescroller_tileset` / `get_sidescroller_tileset` / `list_sidescroller_tilesets` / `delete_sidescroller_tileset` — platformer side-view sets.
|
|
|
|
|
|
Less central to AutoHero’s **diamond isometric** ground plane but valid for experiments or UI.
|
|
|
|
|
|
## MCP configuration (local)
|
|
|
|
|
|
Cursor `mcp.json` should use HTTP transport and Bearer token (see PixelLab setup). **Never commit API tokens** to the game repository.
|
|
|
|
|
|
## Batch: 220 enemy templates (south, transparent)
|
|
|
|
|
|
For all `enemies.type` slugs, use the repo script (API v2, same backend as MCP `create_map_object`):
|
|
|
|
|
|
1. Ensure archetype reference PNGs exist under `frontend/assets/enemies/` (`enemy.wolf.png`, … per `manifest.json`).
|
|
|
2. Set `PIXELLAB_API_TOKEN` (same token as MCP Bearer).
|
|
|
3. From `frontend/`: `npm run gen:enemy-south:pixellab -- --limit 3` (smoke), then without `--limit` for the full run. State file: `frontend/scripts/.enemy-south-pixellab-state.json` (resume-safe). Updates `enemy.<slug>.south` in `manifest.json` and writes `enemies/enemy.<slug>.south.png`.
|
|
|
|
|
|
Implementation: `frontend/scripts/pixellab-enemy-south-batch.mjs` (uses `POST /v2/map-objects`, polls `https://api.pixellab.ai/mcp/map-objects/{id}/download`).
|