graphic and manifest

.cursor/rules/pixellab-sprite-pipeline.mdc

@@ -0,0 +1,37 @@
+---
+description: PixelLab MCP — генерация спрайтов для AutoHero, сохранение в репо и ключи манифеста
+globs:
+  - frontend/public/assets/game/**
+  - frontend/src/game/assets/**
+  - docs/art-bible.md
+  - docs/pixellab-mcp-schema.md
+---
+
+# PixelLab AI MCP — пайплайн спрайтов
+
+## Когда использовать
+
+При добавлении или замене **растровой** графики сцены (тайлы, пропы, персонажи, здания как спрайты), если задача — сгенерировать PNG через подключённый **PixelLab** MCP в Cursor.
+
+Креативная дисциплина и префикс промптов: [docs/art-bible.md](docs/art-bible.md) §1 и §8. Сверка имён инструментов и параметров: [docs/pixellab-mcp-schema.md](docs/pixellab-mcp-schema.md) и живые [PixelLab MCP docs](https://api.pixellab.ai/mcp/docs).
+
+## Обязательное правило после генерации
+
+1. **Сразу после успешного `get_*` (статус completed)** сохранить изображение в репозиторий под стабильным именем, согласованным с будущим манифестом, например:
+   - каталог: `frontend/public/assets/game/` (подпапки по желанию: `terrain/`, `props/`, `characters/`, …);
+   - имя файла: совпадает с контент-ключом или префиксом ключа (`terrain.grass.v0.png`, `prop.tree.v1.png`, `enemy.wolf_forest.png`, …).
+2. **Если в проекте уже есть `manifest.json`** (или аналог для Pixi/atlas) — **добавить или обновить регион** для этого файла в том же PR/шаге. Не оставлять ассет только по временной ссылке MCP.
+3. Для **асинхронных** задач: вызвать `create_*`, затем периодически `get_*` по `tile_id` / `object_id` / `character_id`, пока не `completed`.
+
+## Маппинг задач на инструменты (кратко)
+
+- Изометрический тайл / куб / пол: `create_isometric_tile` → `get_isometric_tile` (в ответе может быть base64 PNG).
+- Проп или высокий объект с прозрачным фоном: `create_map_object` → `get_map_object`.
+- Герой / NPC / враг (пиксель-пайплайн): `create_character` → при необходимости `animate_character` → `get_character` (ZIP/URL — выгрузить кадры в репо).
+- Сетки Wang / платформер: `create_topdown_tileset` / `create_sidescroller_tileset` — только если осознанно нужны для контента.
+
+Имена в UI Cursor могут быть с префиксом сервера (`mcp_*_create_character` и т.д.) — вызывать те же семантические инструменты.
+
+## Безопасность
+
+Не вставлять **API token** PixelLab в файлы репозитория. Токен только в локальной конфигурации MCP пользователя.

docs/art-bible.md

@@ -117,11 +117,28 @@ Adjust only within the migration plan’s size tables; do not invent new keys wi
 
 ---
 
-## 8. Sign-off
+## 8. Generation pipeline (PixelLab MCP)
+
+**Product decision — hybrid (locked):** The **creative target** stays **painterly, Arcane-like** (sections 1–6). **Execution** for raster sprites in Cursor uses **PixelLab AI MCP** by default. PixelLab outputs are **pixel art**; they still must obey mood, palette, silhouette, and perspective here by **always** prepending the §1 English prompt prefix to every MCP `description`, then appending the row-specific brief from the sprite migration plan.
+
+| Need | MCP tool (names may be prefixed in Cursor, e.g. `mcp_pixellab_*`) | Notes |
+|------|-------------------------------------------------------------------|--------|
+| Isometric ground / blocky terrain pieces | `create_isometric_tile` | Default `size` in API is 32; target **96×48** world rhombus may require upscale or `create_tiles_pro` with `tile_type` isometric — see [docs/pixellab-mcp-schema.md](pixellab-mcp-schema.md). |
+| Props, buildings as sprites | `create_map_object` | Set `width` / `height` when known; optional `background_image` for style matching. |
+| Heroes, NPCs, enemies (humanoid or quadruped) | `create_character` | `n_directions` 4 or 8; `size` canvas; quadrupeds need `body_type` + `template`. |
+| Animation (phase 2) | `animate_character` | After `character_id` exists; use `get_character` for status and URLs. |
+
+Jobs are **asynchronous**: creation returns quickly — poll `get_isometric_tile`, `get_map_object`, `get_character`, etc., until status is completed, then **persist files immediately** (see [.cursor/rules/pixellab-sprite-pipeline.mdc](../.cursor/rules/pixellab-sprite-pipeline.mdc)). Later, individual textures may be swapped for hand-painted or non-pixel art **without changing content IDs** if anchors and manifest keys stay the same.
+
+**Authoritative tool list and parameters:** [https://api.pixellab.ai/mcp/docs](https://api.pixellab.ai/mcp/docs) (regenerated from server definitions; verify if behavior changes).
+
+---
+
+## 9. Sign-off
 
 Art direction is **locked** for phase-1 sprite replacement when:
 
-- All new sprites are reviewed against §§1–6,
+- All new sprites are reviewed against §§1–6 and **§8** (MCP descriptions and saved assets),
 - Palette and perspective exceptions are documented per asset only when technically required (e.g. HUD icons),
 - Placeholders (if used) follow the same muted palette and anchor rules until final art lands.
 

docs/pixellab-mcp-schema.md

@@ -0,0 +1,59 @@
+# 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 files under** `frontend/public/assets/game/` immediately.
+
+## 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.

frontend/public/assets/game/manifest.json

@@ -0,0 +1,201 @@
+{
+  "version": 3,
+  "note": "Terrain: v0–v2 per key. Props: tree/rock/cart x2 where present. Pending (PixelLab quota): prop.barrel v0/v1, building.house v0/v1, enemy.* x13, hero.player, hero.meet_partner — regenerate in batches of ≤8 after topping up generations.",
+  "textures": {
+    "terrain.grass.v0": {
+      "file": "terrain.grass.v0.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "5064b2f4-5f68-4f1b-b40d-a8c8fdef5ce8"
+    },
+    "terrain.grass.v1": {
+      "file": "terrain.grass.v1.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "f75118bd-cde7-4c95-93a0-b8276d9d183d"
+    },
+    "terrain.grass.v2": {
+      "file": "terrain.grass.v2.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "a5bb5a50-ea80-4054-bb0c-39346baaa859"
+    },
+    "terrain.dirt.v0": {
+      "file": "terrain.dirt.v0.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "a57e5ce3-0726-4049-86cd-c3470d2c9fae"
+    },
+    "terrain.dirt.v1": {
+      "file": "terrain.dirt.v1.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "f120f6d1-9c3e-47f5-abf7-c5f534dfc750"
+    },
+    "terrain.dirt.v2": {
+      "file": "terrain.dirt.v2.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "b0834e85-d4cd-438b-b7c1-e3dae12d5962"
+    },
+    "terrain.stone.v0": {
+      "file": "terrain.stone.v0.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "25109007-dcd4-46e5-a84d-b12aac187065"
+    },
+    "terrain.stone.v1": {
+      "file": "terrain.stone.v1.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "17227c21-758d-47d7-bfe5-052479d77c37"
+    },
+    "terrain.stone.v2": {
+      "file": "terrain.stone.v2.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "7e89f9fc-d228-4004-a509-5a17e643fb6e"
+    },
+    "terrain.road.v0": {
+      "file": "terrain.road.v0.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "9e76129e-f158-4bc5-8f88-a1167b209aff"
+    },
+    "terrain.road.v1": {
+      "file": "terrain.road.v1.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "6b210ee4-d15b-4929-9e63-afe66ff22d51"
+    },
+    "terrain.road.v2": {
+      "file": "terrain.road.v2.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "03ad957c-27a9-4fb9-88e0-cf826fa9117a"
+    },
+    "terrain.plaza.v0": {
+      "file": "terrain.plaza.v0.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "fa2de588-874b-471b-9c5b-aab09405edc7"
+    },
+    "terrain.plaza.v1": {
+      "file": "terrain.plaza.v1.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "22dfbf77-d8df-4e73-a151-b427cc4ff117"
+    },
+    "terrain.plaza.v2": {
+      "file": "terrain.plaza.v2.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "87feb620-ef7c-442a-b632-e2a210963c98"
+    },
+    "terrain.forest_floor.v0": {
+      "file": "terrain.forest_floor.v0.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "bc70968a-023e-4599-a6f9-958e157a459d"
+    },
+    "terrain.forest_floor.v1": {
+      "file": "terrain.forest_floor.v1.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "0f50401c-2db4-49e3-bf80-469b4c88d368"
+    },
+    "terrain.forest_floor.v2": {
+      "file": "terrain.forest_floor.v2.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "845d159b-2bf8-453c-9b3e-7e124d288e76"
+    },
+    "terrain.ruins_floor.v0": {
+      "file": "terrain.ruins_floor.v0.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "fbadf88a-8f35-454b-a615-9de55ddd7ee7"
+    },
+    "terrain.ruins_floor.v1": {
+      "file": "terrain.ruins_floor.v1.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "60967293-75e4-4a9f-b7e0-2bc6fdfb4442"
+    },
+    "terrain.ruins_floor.v2": {
+      "file": "terrain.ruins_floor.v2.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "22ef3ad0-77f5-42fb-bff3-35637956e936"
+    },
+    "terrain.canyon_floor.v0": {
+      "file": "terrain.canyon_floor.v0.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "ecb56a64-48c9-4036-ae84-a9e939515852"
+    },
+    "terrain.canyon_floor.v1": {
+      "file": "terrain.canyon_floor.v1.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "9d62ae3f-b94d-4618-b4ae-4a383c402375"
+    },
+    "terrain.canyon_floor.v2": {
+      "file": "terrain.canyon_floor.v2.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "43220b53-6a25-4f37-9e71-66292d1119f2"
+    },
+    "terrain.swamp_floor.v0": {
+      "file": "terrain.swamp_floor.v0.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "5d570f8f-57f7-45f7-8017-f8df68358976"
+    },
+    "terrain.swamp_floor.v1": {
+      "file": "terrain.swamp_floor.v1.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "53dda79c-ef06-427b-9d23-54f9a140c908"
+    },
+    "terrain.swamp_floor.v2": {
+      "file": "terrain.swamp_floor.v2.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "07d07b99-caae-4999-a3ee-96e1640a0555"
+    },
+    "terrain.volcanic_floor.v0": {
+      "file": "terrain.volcanic_floor.v0.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "2461e194-679e-4491-a3e0-dbb351ec8b16"
+    },
+    "terrain.volcanic_floor.v1": {
+      "file": "terrain.volcanic_floor.v1.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "6704b1e5-674f-4c36-a272-211275f2e664"
+    },
+    "terrain.volcanic_floor.v2": {
+      "file": "terrain.volcanic_floor.v2.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "c58a42db-55d8-4d7c-9b9e-792039c9a17d"
+    },
+    "terrain.astral_floor.v0": {
+      "file": "terrain.astral_floor.v0.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "40b81fe0-5c58-4605-a3cb-9ce8a81bbe79"
+    },
+    "terrain.astral_floor.v1": {
+      "file": "terrain.astral_floor.v1.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "39fa3752-acb2-4f0c-8f38-eeaeaefd8e67"
+    },
+    "terrain.astral_floor.v2": {
+      "file": "terrain.astral_floor.v2.png",
+      "kind": "isometric_tile",
+      "pixellabTileId": "e995a9ce-2dcc-41d1-999c-f4f693ed7f70"
+    },
+    "prop.tree.v0": {
+      "file": "prop.tree.v0.png",
+      "kind": "map_object",
+      "pixellabObjectId": "324d847e-5678-4b91-806f-4905ef69597f"
+    },
+    "prop.tree.v1": {
+      "file": "prop.tree.v1.png",
+      "kind": "map_object",
+      "pixellabObjectId": "f5ebfddc-f518-4b0e-b6c9-2cc9b038569b"
+    },
+    "prop.rock.v0": {
+      "file": "prop.rock.v0.png",
+      "kind": "map_object",
+      "pixellabObjectId": "e63619b4-29ed-40f2-a1e3-4a0f4a4c0e6a"
+    },
+    "prop.rock.v1": {
+      "file": "prop.rock.v1.png",
+      "kind": "map_object",
+      "pixellabObjectId": "90992b8c-643f-4566-b433-3a9ac0bac01c"
+    },
+    "prop.cart.v0": {
+      "file": "prop.cart.v0.png",
+      "kind": "map_object",
+      "pixellabObjectId": "b31728f7-b7be-49a1-a043-09d17eac3622"
+    },
+    "prop.cart.v1": {
+      "file": "prop.cart.v1.png",
+      "kind": "map_object",
+      "pixellabObjectId": "92bca514-f054-4ba3-b98b-1feb4201c89c"
+    }
+  }
+}