sprite-canon

MCP-сервер, который заставляет AI-сгенерированные игровые спрайты выглядеть как ОДНА игра.

Один персонаж, три наряда — синяя и красная строки — это вызовы sprite_repaint, а не перегенерации. Тот же порядок затенения, тот же силуэт, тот же результат каждый раз.

AI-генераторы отлично умеют создавать красивый спрайт и ужасно — заставлять его соответствовать предыдущему. Попросите одного и того же персонажа дважды — и палитра дрейфует, наряд мутирует, новая шляпа парит на 3 пикселя выше головы — каждый ассет сам по себе хорош, а игра в сборке выглядит неправильно. Перегенерация «пока не совпадёт» не сходится; она сжигает деньги, и вы не можете сравнить результат.

sprite-canon использует противоположный подход, извлечённый из реального игрового проекта, который сгенерировал ~4000 кадров и усвоил все уроки на горьком опыте:

1. Ваши правила консистентности становятся данными — sprite-canon.json («канон»), содержащий палитру, именованные цветовые регионы (кожа, наряд, контур…), относительный масштаб и пороги проверки. Хранится рядом с вашими ассетами.

2. Проверка числовая, а не визуальная. Вы не можете просмотреть глазами 96 вариантов нарядов × 8 направлений × 4 кадра. sprite_verify возвращает жёсткие числа «прошло/не прошло» для дефектов, которые действительно попадают в игру: пиксели вне палитры, аксессуары, дрожащие между кадрами, регион, яркий сзади и тёмный спереди, перекраска, задевшая лицо.

3. Исправления — это детерминированные пиксельные операции, а не перегенерация. Перекраска региона на новый цветовой градиент сохраняет затенение и силуэты, никогда не касается защищённых регионов и даёт одинаковый результат каждый раз. Вариант наряда — это один вызов инструмента, а не лотерея с промптами.

Установка

Claude Desktop — один файл, без конфигурации

1. Скачайте sprite-canon.mcpb из последнего релиза.

2. В Claude Desktop откройте Настройки → Расширения (меню ☰ → Файл → Настройки в Windows).

3. Перетащите файл .mcpb на страницу «Расширения», просмотрите и нажмите «Установить».

(Двойной щелчок по файлу также работает, если в вашей ОС зарегистрирована ассоциация .mcpb — перетаскивание работает всегда. Альтернатива: Расширения → Дополнительные настройки → Установить расширение → выберите файл.)

Это вся установка: пакет поставляется со своими зависимостями, а Claude Desktop предоставляет среду выполнения Node. Требуется приложение Claude Desktop — для Claude Code см. ниже.

Claude Code / другие MCP-клиенты

git clone https://github.com/useka12-eng/sprite-canon
cd sprite-canon && npm install

Затем зарегистрируйте в .mcp.json вашего проекта (или в конфигурации любого MCP-клиента):

{
  "mcpServers": {
    "sprite-canon": {
      "command": "node",
      "args": ["/path/to/sprite-canon/src/mcp/server.mjs"]
    }
  }
}

Требуется Node 18+. Нет нативных зависимостей — кодеки PNG/GIF самодостаточны.

Соберите пакет самостоятельно

npx @anthropic-ai/mcpb pack . dist/sprite-canon.mcpb

Related MCP server: mcp-spritesheet-forge

Инструменты

Входные данные могут быть PNG, анимированными GIF или PNG-спрайтшитами (cellW/cellH).

Рабочий процесс

canon_init      → learn the palette from your existing good assets
canon_learn     → sample skin / outfit / outline once; mark face + outline protected
sprite_measure  → read the numbers before placing anything ("where do the eyes start?")
sprite_repaint  → make variants deterministically (outfits, teams, seasons)
sprite_verify   → prove it: face untouched, nothing left over, no jitter, on palette
sprite_sheet    → look at the result as a sheet, zoomed, before it enters the game

Уроки, которые кодирует этот инструмент

Это не гипотетика — каждый из них сначала проявился как реальный дефект:

• Измеряйте, а не предполагайте пропорции. Поля шляпы, размещённые на «52% высоты головы», попали точно на глаза: на голове в 20px глаза находятся в 7–9px от верха, поэтому любое фиксированное соотношение попадает в них. sprite_measure сообщает, где на самом деле начинается лицо, для каждого кадра.

• Перекрашивайте с фиксированным диапазоном яркости. Нормализация по каждому изображению отображает один и тот же исходный цвет в разные выходные в зависимости от того, какая часть региона видна — наша шляпа была яркой сзади и тёмной спереди. Канон записывает диапазон каждого региона один раз; перекраска всегда использует его.

• Защищайте регионы структурно. «Будь осторожен вокруг лица» не работает в масштабе. protected: true означает, что перекраска не может коснуться его, а проверка доказывает, что не коснулась.

• Патчите палитры GIF, а не перекодируйте. Цвета индексированного GIF живут в его таблицах цветов — глобальной и покадровых локальных (патч только глобальной таблицы — классическое половинчатое исправление). Замена записей таблицы переодевает каждый кадр в идеальной синхронизации с нулевой потерей.

• В определениях регионов есть пробелы; проводите перепись. 12 случайных пикселей старого цвета, переживших перекраску, невидимы глазу и очевидны для leftover. Когда он срабатывает, перепись canon_info показывает, какие цвета ваши регионы не покрывают.

Таблица масштабов

Проверка scale в sprite_verify читает canon.scale.heights — относительные размеры в единицах эталонного ассета (запись, равная 1). Ни один инструмент пока не записывает этот раздел; добавьте его в sprite-canon.json вручную:

"scale": { "heights": { "hero": 1, "house": 3.4, "chicken": 0.45 } }

Затем проверяйте с помощью scaleNames, сопоставляя имена файлов с этими ключами. Это ловит классическое «дом меньше героя» за неделю до того, как это заметят ваши игроки.

Практические замечания

• Всегда передавайте canonPath (или файл, над которым находится канон). Рабочий каталог stdio MCP-сервера принадлежит клиенту, а не вашему проекту, поэтому инструменты отказываются угадывать по cwd.

• Ограничения кодеков: PNG должен быть 8-битным, не чересстрочным, RGB/RGBA/палитровым (обычные случаи пиксель-арта; 16-битные или чересстрочные файлы отклоняются с понятной ошибкой). GIF-энкодер точен до 255 непрозрачных цветов на файл — сверх этого применяется привязка к ближайшей палитре.

• sprite_sheet возвращает изображение встроенным до ~800 КБ; большие листы возвращают только путь к файлу.

• Спрайтшиты проходят цикл ячейка-в-ячейку: пустые ячейки остаются пустыми, ничего не уплотняется.

Чем это не является

• Не генератор. Сочетайте его с любым инструментом создания арта (PixelLab, Aseprite, Gemini, ручные пиксели); sprite-canon — это слой, который сохраняет согласованность результатов.

• Не атлас-пакер / инструмент коллизий — sprite-tools отлично покрывает это.

• Не магия: вы тратите ~10 минут один раз на проект, обучая его своему канону. Эти инвестиции — именно то, что делает каждую последующую проверку и исправление надёжными.

Разработка

npm test          # unit + end-to-end MCP tests (22)

Тестовый набор включает регрессионные тесты для каждой ошибки, которую нашёл состязательный мультиагентный обзор в v0.1 — уплотнение ячеек листа, семантика удаления GIF, ложные успешные ответы, тихие прохождения нулевых проверок. Если один падает, значит, вернулась ошибка, которая уже существовала однажды.

MIT