lego-build

---
name: lego-build
description: Анимация, в которой объект собирается из деталей LEGO по шагам, в стиле фирменной инструкции. Все нарисовано кодом на Canvas 2D, без картинок и 3D-движка, рендер в mp4 вертикально 1080x1920 или горизонтально 1920x1080. Модель задается списком шагов из настоящих деталей LEGO (номера и цвета по каталогу BrickLink), на каждом шаге список деталей, желтая обводка новых и в конце поворот готовой модели. Используй, когда просят собрать что-то из лего в анимации или видео, сделать лего-инструкцию, ролик где из кубиков собирается кот, робот, логотип или любой объект, придумать лего-модель по картинке или описанию. Второй режим делает портрет из фотографии, мозаику в духе LEGO Art из круглых и квадратных плиток 1×1 на черных пластинах, со списком деталей, картой сборки и роликом, где портрет собирается. Используй на запросы "сделай меня из лего", "лего-портрет по фото", "мозаика из лего". Также на запросы LEGO build animation, brick by brick assembly video, building instructions render, LEGO mosaic portrait from photo.
---

# lego-build

Движок рисует детали LEGO на Canvas 2D в стиле бумажной инструкции. Светлые верхние грани, тонкие темные контуры, новые детали в желтой обводке, детали прошлых шагов бледнее. Модель описывается списком шагов, а готовый сценарий превращает ее в ролик со списком деталей, номером шага, падающими деталями и поворотом в финале.

Главное правило скилла. Модель собирается только из настоящих деталей в цветах, которые реально выпускались, без выдуманной печати.

## Что лежит в папке

- `src/lego.js` движок, библиотека из 47 деталей и 16 цветов.
- `src/booklet.js` сценарий ролика, вертикальный и горизонтальный.
- `src/models/cat.js` пример модели, рыжий кот из 106 деталей. `src/models/microduck.js` второй пример, мини-робот.
- `src/parts-sheet.js` страница-каталог всех деталей.
- `index.html` плеер. Пробел или клик ставят на паузу, стрелки листают кадры. Параметры `?model=cat`, `?format=horizontal`, `?t=12`, `?view=parts`.
- `src/mosaic.js` фото в мозаику, `src/mosaic-film.js` отрисовка мозаики и ролик ее сборки, `mosaic.html` то же в браузере, `tools/mosaic.cjs` из командной строки.
- `tools/check-model.cjs` проверка модели, `tools/snap.cjs` отдельные кадры в PNG, `tools/render.cjs` видео в mp4, `tools/parts-md.cjs` справочник деталей.
- `reference/modeling.md` как проектировать модель. Читай перед первой своей моделью.
- `reference/parts.md` таблица деталей и цветов.

## Подготовка

Скопируй папку скилла в рабочую папку проекта и работай в копии. Нужны Node.js 20 или новее и ffmpeg в PATH, либо путь к нему в переменной `FFMPEG`.

```bash
npm install
npx playwright install chromium
node tools/check-model.cjs cat
node tools/render.cjs --model cat
```

Готово, когда проверка кота зеленая, а `exports/cat.mp4` открывается и в нем кот собирается по шагам. Посмотреть без рендера можно, открыв `index.html` в браузере.

## Как сделать ролик про новый объект

1. **Бриф.** Спроси, что собираем и в какой ориентации нужен ролик. Остальное придумай сам и скажи, что придумал. Готово, когда объект описан одной фразой.
2. **Набросок.** Нарисуй модель на клетке в двух видах, спереди и сверху. Выбери размер, палитру из `reference/parts.md` и детали, которые передадут форму. Готово, когда понятно, из каких слоев модель и где у нее лицо или главный признак.
3. **Проверка деталей.** Для каждой пары деталь плюс цвет открой `https://www.bricklink.com/catalogColors.asp?itemType=P&itemNo=<номер>` и убедись, что цвет есть в списке. Если нет, поменяй цвет или деталь. Готово, когда каждая пара подтверждена, а дата проверки записана в шапку модели.
4. **Модель.** Скопируй `src/models/cat.js` в `src/models/<имя>.js`, замени в последней строке `root.MODELS.cat` на `root.MODELS.<имя>` и опиши шаги снизу вверх по правилам из `reference/modeling.md`. Добавь файл строкой в `index.html`. Готово, когда `node tools/check-model.cjs <имя>` пишет, что пересечений нет и все держится.
5. **Кадры.** Сними кадры командой `node tools/snap.cjs 3 6 9 12 <финал> --model <имя>` и посмотри на них. Финал идет за полсекунды до конца ролика. Проверь, что модель узнается, детали не залезают друг в друга, список деталей помещается на странице. Исправляй и снимай заново. Готово, когда модель узнается с первого взгляда в финальном кадре.
6. **Рендер.** Запусти `node tools/render.cjs --model <имя>`, для горизонтали добавь `--format horizontal`. Готово, когда mp4 лежит в `exports/` и просмотрен от начала до конца.

## Портрет из фото

Фото сжимается в сетку, где один шип равен одному пикселю. Каждой клетке достается настоящая плитка LEGO: круглая 98138 или квадратная 3070 в цвете, в котором она выпускается. Цвета сравниваются так, как их видит глаз (CIELAB, CIEDE2000). Палитра подбирается под конкретное фото, дизеринг смешивает соседние плитки в промежуточные тона, одиночные точки убираются. Круглая плитка оставляет вокруг себя видимую черную пластину, и это учитывается.

1. **Фото.** Лучше всего работает портрет анфас на ровном фоне с ровным светом. Готово, когда фото лежит локально и лицо в кадре.
2. **Мозаика.** Запусти `node tools/mosaic.cjs <фото> --name <имя>`. По умолчанию размер 64×64, круглые и квадратные плитки вперемешку, портретная палитра до 12 цветов. Черно-белое фото определяется само и собирается из четырех серых. В папке `exports/` скилла (или в папке из `--out`) появятся `<имя>-compare.png` (фото, сетка, LEGO), `<имя>-lego.png`, `<имя>-map.png` (карта сборки) и `<имя>-parts.md` (детали с номерами BrickLink). HEIC с айфона сначала пересохрани в JPEG, остальные частые форматы открываются.
3. **Сходство.** Открой compare и сравни глазами. Если лицо не узнается, крути параметры. `--size 80` или `96` дают больше деталей. Если лицо мелкое в кадре, поставь `--zoom 1.3` и сдвиги `--dx`, `--dy`. Если на коже лишние точки, уменьши `--dither 0.3`. Для плоского фото подними `--contrast 0.7`, для мелких черт подними `--sharpen 0.7`. Готово, когда очки, усы, прическа и прочие приметы читаются в LEGO-версии.
4. **Ролик.** Сначала сними несколько кадров ключом `--frames 3,9,15` и посмотри на них. Потом добавь `--video`, для вертикали еще `--format vertical`. Получится `<имя>-build.mp4`, для вертикали `<имя>-build-vertical.mp4`. Сначала падают пластины, потом камера ныряет к плите и летит вдоль фронта сборки, где сыплются плитки. В конце она поднимается над готовым портретом, и рядом появляется фото. Готово, когда ролик просмотрен.

Страница `mosaic.html` делает то же в браузере. Перетащил фото, покрутил настройки, скачал картинку, карту или видео. Видео там пишется в реальном времени, для ровного ролика есть консольная команда.

## Правила

- Никакой выдуманной печати. Глаза, носы и узоры собирай из простых деталей. Примеры есть в `reference/modeling.md`.
- Детали лица крепи на шипы сбоку (87087 и похожие), а не просто прикладывай к модели.
- Проверка модели должна быть зеленой перед каждым рендером.
- Не называй модель проверенной в живую, если ее никто не собирал руками.
- В коде отрисовки нельзя использовать `Math.random` и `Date`, кадр должен зависеть только от времени.
- Название LEGO принадлежит LEGO Group. Не подавай ролик как официальный и не рисуй логотип LEGO.

## Если нужной детали нет

Добавь ее в `src/lego.js` одним из помощников `box`, `slope`, `ridge`, `curve`, `round`, с номером по BrickLink. Затем пересобери справочник командой `node tools/parts-md.cjs` и посмотри деталь на `index.html?view=parts`. Подробности в `reference/modeling.md`.