@energy8platform/golem
v0.9.4
Published
AI-first 2D rigging for slot games: rig.json format, PixiJS v8 runtime, MCP tools and a browser editor
Readme
@energy8platform/golem — прототип AI-first риггинга для слотов
Документ (rig.json, формат v2) — источник истины. Агент работает через MCP, человек — через вьюер и редактор в браузере (npm run editor). Рантайм — PixiJS v8.
Поддержан рабочий процесс для персонажей в полный рост: утверждённый арт + скрытые дорисовки, плавное прохождение ключей, длинные IK-цепи, передача реквизита, запекание вторички, clipping, редактирование весов и проверяемые прозрачные кадры/MP4 60 fps. Что изменилось, как использовать и результаты проверок.
В 0.4 добавлен пилот параметрической мимики: независимые глаза, совместные формы «улыбка × открытие рта», ползунки и ключевые формы в редакторе, дорожки параметров и проверка сочетаний через реальный рендер. Устройство и API, воспроизводимый персонаж Milo.
В 0.5 добавлен редактор деталей и костей для встраиваемых превью: правки мышью, группы, отмена и отдельные JSON-поправки. Поправки костей применяются поверх параметрической мимики и сохраняются при смене анимации. Результаты объединения и проверок.
В 0.6 по официальным примерам Spine и Rive обновлены скиллы нарезки и анимации, исправлены импорт skins, linked meshes, кривые, преобразования и активные clipping-маски. Источники, результаты и ограничения проверки.
src/rig-format.ts схема документа (zod) + семантическая валидация; v1: deform-треки, asset.frame (атлас)
src/rig-anim.ts чистая математика: easing, семплирование, Pose, аффинные матрицы костей, контуры слотов
src/rig-deform.ts 3×3 деформер картинки: именованные параметры → смещения точек, биквадратичный патч, якобиан
src/rig-constraints.ts ограничения без решателя: кто кем управляет, цепь IK, знак сгиба, досягаемость, кривая по точкам
src/rig-state.ts AnimationState: base-цикл, очередь с приоритетами, overlay-слои (моргание), crossfade
src/rig-runtime.ts RigPlayer для PixiJS v8: Sprite или MeshPlane на слот, setPose, createTextures (атлас)
src/rig-symbol.ts RigSymbol — адаптер под SymbolView из @energy8platform/game-engine
src/rig-presets.ts пресеты: idle_breathing, weight_shift, win_bounce, anticipation_shake, blink, mouth_talk, dim, symbol_idle, symbol_win
src/rig-tools.ts операции над документом, импорт слоёв (swap/bone), createSymbol, replaceAsset, layerPrompt
src/rig-check.ts автокритика без рендера: out_of_canvas, static_track, loop_seam, deform_flip, patch_offset, motion_pop, …
src/rig-motion.ts градиент/сглаживание/фиксация весов, attach-to-bone, запекание вторички
src/rig-quality.ts проходные ключи, скорость петли, вторичка, порядок слоёв, ориентиры сменных рисунков
src/rig-gates.ts пороги движения, контакты/пропорции, условия FX, реальные переходы AnimationState
src/rig-qa.ts манифесты кадров с хешами исходных данных и проверкой полноты
src/rig-history.ts снимки .rig-history/, undo, структурный diff
src/rig-atlas.ts упаковка PNG-слоёв в atlas.png с экструзией краёв
src/rig-templates.ts rig_save_as_preset: шаблон из готовой анимации (треки относительно rest, кости по role, множители)
src/preview/ renderPreview: headless Chromium → контакт-лист PNG (onion skin) для агента
src/rig-api.ts реестр инструментов — MCP, CLI и редактор регистрируют один список
src/mcp-server.ts MCP (stdio) поверх всего этого
src/editor/ редактор: сервер (HTTP/SSE), сцена, гизмо, таймлайн, панели
scripts/smoke.ts прогон всей петли без агента + проверки меша/атласа/символа
scripts/verify-mcp.ts интеграционный маршрут через настоящий stdio MCP
scripts/verify-engine.mjs RigSymbol внутри настоящей SymbolCell движка (из соседнего проекта игры)
scripts/rig-cli.ts те же MCP-инструменты из shell: `npm run rig -- <tool> '<json>'`
examples/hero/ тестовый персонаж из прямоугольников + layers.json
examples/cashier/ настоящий персонаж (cashier.png) и список его анимаций anim.md
ross/ настоящий Spine-проект (json + atlas + ktx2) — оракул и демо импорта
docs/superpowers/specs/ проектные решения этапа 2 (mesh, состояние, атлас, агентский UX)Установка
npm install
npx playwright install chromium # один раз
npm run build:harness # бандл для headless-рендера (после правок runtime/harness — повторить)
npm run typecheck
npm testШаг 1 — smoke без агента
npm run smokeПишет examples/hero/rig.json, examples/hero/out/{rest,idle,win,anticipation,win_onion}.png,
экспорт с атласом в examples/hero/out/export/, символ из одной картинки в examples/symbol/.
Проверяет: непустой WebGL-кадр, различие кадров, меш при нулевой деформации = спрайт (0 px),
рендер из атласа = рендер из файлов (0 px) в том числе для деформированного торса, onion skin, rig_check без ошибок.
Что должно быть видно глазами:
rest.png— персонаж собран, кости (оверлей) стоят в суставах, подписиid (role).idle.png— грудь дышит (меш, шея и пояс закреплены, голова не тянется), голова покачивается, руки чуть ходят.win.png— два прыжка с затуханием, squash/stretch;win_onion.png— то же с призраком предыдущего кадра.examples/symbol/out/win.png— pop масштаба и затухающее желе одной картинки.
Шаг 2 — петля с агентом
Подключи MCP в Claude Code (.mcp.json в корне проекта):
{ "mcpServers": { "rig": { "command": "npx", "args": ["tsx", "src/mcp-server.ts"], "cwd": "<абсолютный путь к rig>" } } }Инструменты:
| Группа | Инструменты |
|---|---|
| Документ | rig_create, rig_create_symbol (риг из одной картинки), rig_set_meta (имя, холст, notes, референс-подложка reference; null убирает подложку), rig_get, rig_get_attachment (одно вложение целиком — массивы vertices/weights для сырой правки), rig_rename (переименование кости/слота/attachment/ассета/ограничения с переписыванием всех ссылок; presets.json и preset.params анимаций не переписываются — ответ называет, где остался старый id), rig_validate, rig_check |
| Ассеты | rig_set_asset (ассет из целой картинки или прямоугольника frame в ней — файлов-вырезок нет; переразметка кадра держит на месте исходный пиксель под центром картинки; меш при этом сохраняет старые uvs, инструмент называет его в ответе — перетрассируйте его заново (rig_mesh_from_image)), rig_remove_asset (отказ, пока ассет показан хоть одним attachment), rig_place_asset (слот + region + показ одним вызовом, z = max + 1) |
| Слои | rig_import_layers (layers.json: swap, bone), rig_replace_asset, rig_layer_prompt (промпт перегенерации по провенансу) |
| История | rig_undo(steps), rig_diff(steps) — снимки в .rig-history/ рядом с rig.json |
| Скелет | rig_add_bone (bind сразу переносит слоты на новую кость, не сдвигая картинку), rig_update_bone, rig_remove_bone (слоты уходят к родителю тоже без сдвига), rig_set_slot (смена bone сохраняет мировое положение: regions пересчитываются в новой кости, взвешенные меши не трогаются), rig_remove_slot, rig_set_draw_order (список слоёв сзади наперёд одним вызовом, z = index) |
| Поза и цель | rig_get_pose (обратная связь числами: мировые x,y,angle,scaleX/Y и локальные x,y,rotation по костям, показанное вложение и мировой bbox по слотам — без animation rest-поза, иначе поза в t со всеми применёнными ограничениями), rig_set_goal (кость в точку документа; под живым IK правка уходит на кость-цель ограничения, под transform/path — отказ), rig_copy_tracks (треки одних костей на другие пара за парой, сдвиг фазы, зеркало по x — знак меняют x, rotation, shearX, shearY, и лево-правым оно будет только при зеркальных системах родителей) |
| Анимация | rig_apply_preset (встроенные и шаблоны), rig_set_keys (merge), rig_set_tracks, rig_adjust_track (amplitude / offset / timeScale), rig_remove_animation |
| Шаблоны | rig_save_as_preset (анимация → шаблон в presets.json), rig_list_presets |
| Вывод | rig_render_preview (onionSkin, region для crop/zoom, сводка rig_check по анимации), rig_export (атлас) |
На риге с ключами drawOrder слот теперь можно добавить и удалить, не сломав валидацию: rig_set_slot дописывает новый
слот в конец каждого ключа, rig_remove_slot вычёркивает из них старый. rig_mesh_from_image трассирует и framed-ассеты
(кадр вырезается из листа в памяти); отказ остаётся только для rotate/trim экспортных атласов.
Каждая мутация отвечает списком «changed:» (структурные операции — ещё и сводкой рига); невалидный результат не
сохраняется, предыдущая версия уходит в историю. rig_get verbose=true показывает pivot/offset слотов и треки с диапазонами ключей.
Те же инструменты из shell (для скриптов и для агентов без MCP-конфига):
npm run rig -- list # все инструменты с параметрами
npm run rig -- rig_check '{"path":"examples/hero/rig.json"}'
npm run rig -- rig_render_preview '{"path":"…","animation":"idle","scale":0.4,"saveTo":"out/idle.png"}'npm run verify:mcp проходит маршрут через настоящий stdio MCP: три задания README, deform-ключи с заведомым
переворотом меша (rig_check обязан его найти), diff/undo, onion skin, символ с экспортом в атлас, шаблон из ручной
анимации, merge/verbose/region. Журнал и превью — в examples/hero/out/mcp/.
Слепая оценка двух агентов на риге cashier (задания из anim.md и поиск внесённых дефектов) — отчёт.
Деформация картинки (mesh)
Слот, у которого есть deform-трек, рендерится как MeshPlane 9×9 поверх 3×3 контрольных точек.
Параметры безразмерные (доли размера картинки), все складываются:
| prop | что делает | закреплено |
|---|---|---|
| bulge | средний ряд расходится по горизонтали (дыхание, пульс) | верх и низ |
| bend | средний ряд сдвигается вбок (мягкий наклон, C-изгиб) | верх и низ |
| sway | сдвиг ряда пропорционально расстоянию от pivot (волосы, наклон от опоры) | ряд pivot |
| squash | сжатие к pivot по вертикали с расширением по горизонтали, не задевая детей | pivot |
| p<r><c>x, p<r><c>y | прямое смещение точки в пикселях, ряды/колонки 0..2 сверху-слева | — |
|bend|,|sway| ≤ 1, |bulge|,|squash| ≤ 0.9. Переворот треугольников (в том числе из-за overshoot easing между ключами)
ловит rig_check как deform_flip. Обоснование и сравнение вариантов — в спеке этапа 2.
Свечение и VFX-слои
slot.blend: normal | add | multiply | screen (в layers.json — поле blend). Слой свечения рисуется на чёрном и кладётся
с add: чёрное исчезает, никаких «наклеек» с краями кожи; alpha-трек управляет силой свечения. Так делаются светящиеся глаза и
подсветка пламени у символов. Превью рендерится на непрозрачном фоне внутри WebGL (как в игре), иначе аддитивный слой
над пустотой давал бы чёрные прямоугольники; призрак onion skin кладётся сверху.
Шаблоны из ручных анимаций
rig_save_as_preset(animation, name, groups?) сохраняет анимацию как шаблон: треки костей относительно rest и по role,
масштаб как отношение, deform как есть. Параметры шаблона: amplitude (все относительные значения), speed (время) и
именованные группы треков ({"turn": ["bone.root.rotation"]}) — каждая становится своим множителем. Применение на другом
риге: rig_apply_preset(preset: "<имя>", params) — кости ищутся по роли, затем по id; чего нет в целевом риге, пропускается.
Библиотека — presets.json рядом с рига или любой путь в library.
Состояния в игре
const player = new RigPlayer(doc, await createTextures(doc, src => loadTexture(base + src)), { mix: 0.15 });
player.state.setBase("idle"); // цикл
player.state.setOverlay("eyes", "blink"); // независимый цикл поверх
await player.state.play("win", { priority: 1 }); // прерывает idle, после завершения — обратно; промис всегда резолвится
player.state.setBase("dim"); // незацикленный base держит последнюю позуRigSymbol (src/rig-symbol.ts) заворачивает это в playIdle / playWin / showStatic / resize / setDim — интерфейс
SymbolView из @energy8platform/game-engine (≥ 0.43: resize принимает и number, и {width, height}), без
зависимости от движка.
В игре
Пакет публикуемый: npm run build собирает dist/lib/ (esbuild по entry, .d.ts от tsc) и клиент редактора.
Exports: @energy8platform/golem/runtime (браузер: RigPlayer, RigSymbol, createTextures, parse; pixi.js —
peer, в игре должна быть одна копия), /tools (реестр инструментов), /editor (startEditorServer). Bin:
golem editor --root public/assets/rigs # редактор над ригами игры; в шаблоне create-slot — `npm run rigs`--root — папка ригов (список open, загрузки, /rig/*), сам editor.html и dist/ отдаются из пакета.
Движок подключает риги через @energy8platform/game-engine/golem (loadRigs, re-export'ы, compile-time контракт
RigSymbol = SymbolView), а defineGameConfig вырезает .rig-history/ из vite build — риги лежат прямо в
public/, vite dev перезагружает игру на каждую запись редактора. Спека:
docs/superpowers/specs/2026-09-15-engine-integration-design.md.
Правки мышью прямо в превью
Отдельный браузерный модуль @energy8platform/golem/interactive-editor подключается к
RigPlayer: выбор по видимым пикселям, перемещение, масштаб по осям и углам, вращение,
группы связанных деталей, отмена и JSON с правками. Подключение и ограничения.
Полный редактор по-прежнему отвечает за кости, веса, IK и ключи анимации.
Настоящие данные
npm run verify:engine # RigSymbol внутри SymbolCell из ../kitsune-wrath (KITSUNE_DIR=… для другого пути)Символ из одной картинки, как это делает агент:
S=examples/symbol/rig.json
npm run rig -- rig_create_symbol '{"path":"'$S'","image":"../hero/layers/head.png","name":"gem","margin":0.2}'
for p in symbol_idle symbol_win dim; do npm run rig -- rig_apply_preset '{"path":"'$S'","preset":"'$p'"}'; done
npm run rig -- rig_render_preview '{"path":"'$S'","animation":"win","fps":10,"onionSkin":true,"scale":0.5,"saveTo":"examples/symbol/out/win.png"}'Модуль e8-engine
golem — e8-row golem1 (@energy8platform/golem). Что даёт: тулы rig_* в MCP e8, node golem в сцене, вкладка
редактора для rig.json в IDE, undo через историю golem. Риги лежат в assets/rigs/<name>/.
Node golem в игре, тулы rig_* и skills приходят со строкой golem1 бандла e8-base (проект без него добавляет ту же
строку в e8.patch.yml). Строка в e8.yml добавляет вкладку редактора rig.json в IDE и мост undo:
- id: golem1
name: '@energy8platform/golem'
config: {}Что изменилось после третьего прогона e8 (2026-10-13). rig_batch { path, ops: [{ tool, args }] } применяет
несколько правок одним вызовом и одним шагом истории; упавшая или ничего не изменившая пачка rig.json не трогает.
Провалы rig_run_gates называют, где: кость или слот, время, отрезок ключей (или ключевого предка). rig_export сам
сравнивает упакованный риг с исходником и отвечает максимальной разницей пикселей по анимации — для этого он запускает
Chromium: одноразовый скрипт вызывает closeTools() в конце или передаёт check: false. saveTo и framesDir
(rig_render_preview, rig_verify_render) считаются от папки рига, недостающие папки создаются. rig_apply_preset
отвечает диффом (verbose: true — полное описание рига). Ступенчатый сброс цикла — loop_step, а не мнимый
loop_velocity. Проверка: docs/verification-2026-10-13.md.
Шаг 3 — слои (риск №1 закрыт)
Спайк сегментации на cashier.png (артефакты удалены при чистке репозитория): вырезание из плоской картинки + bleed 6 px даёт чистый
rest и микро-движение; большое движение (стакан ко рту) требует скрытых частей — их выгоднее генерировать сразу по
частям. Маршрут для агента: rig_layer_prompt(id) → генерация своим инструментом на #00FF00 → rig_replace_asset(id, file).
Патчи выражений (веки, рот) — swap: true в layers.json; несколько состояний одного места (mouth_open_small, mouth_sip)
объединяются полем slot: "mouth" в один скрытый слот. Анимируются пресетами blink / mouth_talk и в игре идут как overlay
(во вьюере — поле overlays).
Посмотреть анимацию живьём / GIF / видео
npm run viewer # → http://localhost:8000/viewer.html
npm run export -- examples/hero/rig.json idle 24 # mp4 + gif через ffmpegАгенту по-прежнему отдаём контакт-лист (rig_render_preview) — видео вижн-модели не читают.
Редактор
npm run editor # → http://127.0.0.1:8765/editor.html?rig=examples/hero/rig.json
npm run editor -- --watch # пересборка клиента при правках src/editorРедактор и агент делят один rig.json и одну историю: каждая правка мышью — вызов того же инструмента из src/rig-api.ts
(rig_update_bone, rig_set_keys merge, rig_apply_preset, …), сервер применяет его к актуальному файлу и делает снимок в
.rig-history/. Правки агента через MCP появляются в редакторе сразу (сервер следит за файлом), rig_undo / rig_redo
общие. Режимы как в Spine: Setup правит rest (drag сустава, поворот за конец кости, масштаб, рамка картинки), Animate
пишет ключи на времени плейхеда (автоключ). Таймлайн — dopesheet: выбор, перенос и удаление ключей, длительность за правый
край. Панель свойств: поля с ромбами ключей, easing — четырьмя числами и, у выделенного ключа, ещё и перетаскиваемой
кривой в единичном квадрате (рисуется той же ease(), которой считает рантайм, так что картинка не может разойтись с
воспроизведением; первое перетаскивание ручки переводит именованный ease в bezier, step рисуется ступенькой),
слайдеры параметров пресета и amplitude/offset/timeScale трека с предпросмотром до отпускания.
Спека: docs/superpowers/specs/2026-09-08-editor-stage-a-design.md.
Ручная сборка
Риг собирается мышью с нуля, без CLI: new и open в верхней панели создают риг и переключаются на существующий.
+ pngгрузит картинки в папку рига; у каждой в списке файлов — кнопкиatlas,ref,whole.- с пустым выделением панель свойств показывает форму документа: имя, холст, notes и поля подложки
reference(src,opacity,x,y,scale). - режим
atlas(клавишаA):detectс ползункамиgap/min areaпредлагает прямоугольники,snapподжимает их по альфе, нажатие на пустом месте рисует новый прямоугольник, 8 ручек меняют размер,Deleteубирает выделенные,mergeобъединяет несколько в один; имя прямоугольника (Enter) — этоrig_set_assetсframe; предложенные прямоугольники живут только в памяти страницы и не переживают перезагрузку. - корзина ассетов — миниатюры; drag на холст или на строку кости кладёт ассет, двойной клик — в центр холста; уже размещённые притушены.
- инструмент
B: нажатие ставит сустав кости, перетаскивание — направление и длину; с выделенной частью она сама перепривязывается на новую кость. - строка слота, перетащенная на кость, и выбор
boneв форме слота — оба сохраняют картинку на месте. - список layers: слои идут передними сверху; перетаскивание в Setup —
rig_set_draw_order, в Animate — ступенчатый ключdrawOrderна плейхеде; полеzправится только в Setup. - по две ручки масштаба у кости и у картинки, Shift — равномерно (оба масштаба по отношению вдоль тянущейся оси), курсор каждой — по направлению её оси.
- галочка
lock images: клик по картинке выбирает её кость. - поле
idу кости, слота, attachment, ассета и ограничения — редактируемое; Enter — этоrig_rename.
Спека: docs/superpowers/specs/2026-09-11-editor-stage-e-authoring-design.md.
Каждый коммит редактора несёт версию документа, с которым он сделан (mtimeMs:size); если файл на диске успел
измениться — правкой агента через MCP, другим процессом, — сервер отвечает 409 и актуальным документом вместо того,
чтобы выполнить инструмент, а редактор подставляет пришедший документ и предупреждает статусом, не считая это своей
ошибкой. Без версии в запросе (MCP, CLI, curl) поведение прежнее — агент не затронут. Запись rig.json атомарна
(временный файл рядом, затем rename): раньше writeFile мог отдать параллельному читателю усечённый файл.
Внутри одного процесса операции над одним путём рига выполняются последовательно; HTTP-проверка версии входит
в ту же очередь. Отдельные процессы MCP, CLI и редактора общей блокировки не имеют: если они одновременно
редактируют один файл, правки всё ещё могут потеряться. Пока назначайте одному ригу одного активного писателя.
Результаты проверки и оставшиеся ограничения — в аудите от 11 сентября 2026.
Спека: docs/superpowers/specs/2026-09-09-editor-stage-d-design.md.
Меши
Агент: rig_mesh_from_image {id, spacing, tolerance} превращает region-attachment в меш по alpha картинки (контур + сетка +
Делоне), rig_auto_weights {id, bones?, radius?, maxInfluences} раздаёт веса по расстоянию до костей — вершина берёт
maxInfluences ближайших костей с весом 1/(d/radius + 1)² (radius — масштаб спада в мировых пикселях; без параметра
— 1, то есть результат побайтово прежний; больше — влияние ровнее и захватывает дальние кости, меньше — жёстче и
локальнее; жёсткого обрыва нет ни при каком радиусе — именно обрыв давал шов на середине конечности), rig_set_mesh /
rig_set_weights пишут массивы целиком, rig_set_keys принимает массивы (deform vertices, drawOrder, color), rig_check
ловит mesh_fold (ошибка, если свёрнуто ≥ 5 % площади меша, иначе предупреждение) и weights_sum. npm run verify:mesh
собирает cashier из слоёв этими инструментами с параметрами по умолчанию и кладёт контакт-лист в
examples/cashier/out/auto-maxwin.png рядом с авторским (maxwin-reference.png). Фикстуры кассира (examples/cashier/rig.json
и layers/) локальные, в репозитории их нет: без них скрипт выходит с кодом 2 и называет недостающий файл
(npm run cashier:build пересобирает их, если исходники на месте). Скрипт держит базовую линию KNOWN_FOLDS: на
полностью сложенном локте в maxwin веса по расстоянию складывают меш (upper_l, forearm_l) — известное ограничение,
разобрано в разделе 9 спеки, лечится кистью весов, поэтому выход 0; любая НОВАЯ ошибка — код 1, а если известная
перестала падать, скрипт скажет «improved — update KNOWN_FOLDS».
Редактор: у меша видны вершины и контур; drag вершины в Setup пишет rig_set_mesh, в Animate — ключ deform.<id>.vertices
(такой трек кладётся на таймлайн как обычный: двойной клик ставит ключ с формой, которая уже видна в этот момент, ключи
двигаются и удаляются); W — режим весов (только в Setup): тепловая карта выбранной кости, кисть ([ ] — радиус,
Shift — убавить), auto weights, to mesh у региона.
Спека: docs/superpowers/specs/2026-09-08-editor-stage-b-meshes-design.md.
Пути
Агент: rig_set_path_attachment {path, id, slot, points?, vertices?, weights?, closed?} создаёт или заменяет PATH
attachment — ровно одна из двух форм за вызов (минимум 2 опорные точки, 3 — для замкнутого пути). points — опорные
точки в координатах документа: кривая строится заново по Catmull-Rom, поэтому у скинированного пути это рвёт веса и
авторские касательные — форма для рисования пути с нуля. vertices / weights — сырые контрольные точки
[cPrev, p, cNext] на узел (в пространстве кости слота, либо скинированные — список влияний на точку, как у
rig_set_weights) — единственная форма, которая сохраняет веса и касательные, поэтому редактор коммитит правку
существующего пути только ею. rig_path_anchor {path, id, op: insert|remove, index, t?} добавляет и убирает один узел:
insert делит сегмент после index в параметре t (0..1, по умолчанию 0.5) де Кастельжо — кривая не меняет форму НИ В
ОДНОЙ позе, потому что положение каждой новой контрольной точки в пространстве кости-влияния — это смесь исходных точек
в ТОЙ ЖЕ кости с теми же коэффициентами де Кастельжо, а это тождество по матрицам костей; remove убирает тройку узла
(форма меняется — это неизбежно). Обе операции пересчитывают lengths и отбрасывают deform-ключи, которым не подошла
новая длина.
Редактор правит взвешенные пути наравне с мешами — запрет из C снят. Узел тащится вместе с двумя касательными, ручки
касательных показываются только у выделенного узла (иначе на пятиузловом tail_path их стало бы вдвое больше), клик
рядом с кривой выбирает путь, Ctrl-клик вставляет узел в ближайшей точке параметра, Delete на узле — удаляет. Коммит
идёт сырой формой rig_set_path_attachment, поэтому взвешенный путь остаётся взвешенным, а нетронутые касательные —
авторскими: правка — это дельта в пространстве каждой кости-влияния (та же математика, которой deformOffsetsFor
считает deform-ключ в Animate), а не переигрывание всех влияний из одной мировой точки — это схлопывает разброс между
образами вершины в разных костях, а этот разброс и несёт анимацию (крошечный, 0.01 px, сдвиг узла в Setup у наивного
пересчёта даёт в позе смещение до 489 px на меше n_fur и до 24 px на самом tail_path). В Animate путь пишет
deform-ключи так же, как меш (tail_path в ross приходит из Spine с 17 такими треками).
Спека: docs/superpowers/specs/2026-09-09-editor-stage-d-design.md.
Ограничения
Агент: rig_add_ik_chain {bone} оснащает конечность одной командой — ставит кость-цель (role: ik_target, ребёнком
корня, а не внутри цепи, иначе решатель тянул бы сам себя) в текущий конец цепи и IK <bone>_ik со знаком сгиба из
текущей позы, так что от появления ограничения риг не шелохнётся; если двухкостная цепь дотянулась бы до самого
корня, берётся одна кость, и инструмент об этом говорит. На свежеимпортированном риге это ДВА шага: кости из
rig_import_layers нулевой длины и сидят в своих суставах, а цель встаёт в конец цепи — поэтому сначала
rig_update_bone {id: "leg_l", length: 60} # столько, сколько кость реально занимает на картинке
rig_add_ik_chain {bone: "leg_l"} # → кость-цель leg_l_ik и IK; дальше позу задаёт она(без длины одно-костный IK целился бы в собственное начало кости, и инструмент честно отказывается). После импорта
Spine длины уже есть, и хватает второй строки. rig_set_ik / rig_set_transform / rig_set_path создают
и правят ограничения (поля сливаются: {id, mix} правит только mix), rig_remove_constraint удаляет вместе с
треками, rig_set_path_attachment строит и правит кривую пути (rig_path_anchor добавляет и убирает узел — раздел
«Пути» выше). rig_check добавляет
constraint_dead (все mix — 0 и ни один ключ их не поднимает), constraint_cycle (цель сидит на кости, которую это
же ограничение пишет), ik_unreachable (цель за пределами досягаемости двухкостной цепи — она висит прямой; одинокая
кость целится, а не тянется, и не считается) и path_missing (слот-цель никогда не показывает путь).
Редактор: выделенное ограничение подсвечивает свои кости и ведёт пунктир от конца цепи к цели — к ромбу на
кости-цели, у path — к ближайшей опорной точке кривой, которая тоже обводится. Кость, которой прямо сейчас управляет
IK, тащить напрямую нельзя: жест перенаправляется на цель ограничения (Alt отключает перенаправление, ручка
масштаба по-прежнему правит саму кость), а кость под transform или path отклоняется со статусом. «Прямо сейчас» —
по значениям на плейхеде: ограничение, у которого на этом кадре все mix равны 0, решатель пропускает, и кость
правится как обычная. Кривая пути рисуется у каждого показанного пути, опорные точки видны и тащатся у выделенного —
как вершины меша, включая взвешенные, импортированные из Spine (раздел «Пути» выше). Числовые поля ограничения
(mix, softness, у path ещё
position и spacing) в Animate пишут обычные ключи на времени плейхеда. В дереве: «add ik chain» на кости,
«add ik / transform / path» на заголовке группы (занятый id отклоняется: rig_set_* считает известный id патчем и
переписал бы чужое ограничение), Delete удаляет ограничение вместе с его треками (о них спросит).
Спека: docs/superpowers/specs/2026-09-08-editor-stage-c-constraints-design.md.
Шаг 4 — риг класса Spine: формат v2 и импорт настоящего Spine-проекта (ross)
Инструмент больше не «двигает картинки»: документ v2 — это меши с весами костей, регионы, пути, shear и режимы наследования, ограничения IK (1–2 кости с softness/stretch/compress; длинные цепи через CCD), transform (мировой и локальный, relative) и path (4 режима шага, 3 режима поворота, замкнутые и открытые пути), треки деформации вершин, порядка отрисовки, цвета слота и миксов ограничений. Это своя реализация по документированной семантике Spine, не порт рантайма; spine-core используется только как оракул в тестах.
Проверка на ross/ (Spine 4.0: 163 кости, 116 слотов, 110 мешей, из них 49 взвешенных, 2 IK, 17 transform, 7 path,
17 анимаций): в каждой анимации на 9 моментах времени все кости совпадают с spine-core лучше 0.01 px, вершины мешей и путей
с deform-ключами лучше 0.05 px, attachments, порядок отрисовки и цвета совпадают точно (tests/spine-import.test.ts).
Кадр (163 кости + 110 мешей + все ограничения) считается ~0.9 мс.
npm run rig -- rig_import_spine '{"path":"ross/rig.json","json":"ross.json"}' # атлас и страница находятся сами; .ktx2 → PNG рядом с rig.json
npm run rig -- rig_render_preview '{"path":"ross/rig.json","animation":"jump","fps":4,"scale":0.25,"saveTo":"ross/out/jump.png"}'
npm run render:ross # листы simple / jump / sitting в ross/out/
npm run render:spine -- devil # любой другой экспорт Spine: json + атлас из каталога, все анимации
npm run spine:sweep # невязки к spine-core по каждой анимации
npm run ktx2 -- ross/ross.ktx2 ross/ross.png # транскодер из three (devDependency), нужен только для KTX2Импорт делает холст по объединению всех кадров всех анимаций (а не по setup-позе, иначе прыжок вылетает за край),
выбрасывает треки, целиком равные setup-значению (Spine ключует всё подряд, они ничего не меняют), и переводит y-вверх
в y-вниз сопряжением отражением. rig_check на таких ригах шумит меньше: постоянный трек с не-setup значением — это
удержание позы (info), рывок ровно на stepped-ключе — авторский (info).
Что пришлось воспроизвести, чтобы совпасть с оракулом: до первого ключа трека действует setup-значение (импортёр вставляет
явный ключ); безье-кривые Spine — это 10 линейных отрезков (9 внутренних точек), не точная кривая; deform у взвешенных
вершин — смещение на каждое влияние; у path-ограничения при constantSpeed длина меряется по уже деформированной кривой
(4 хорды на кривую для суммы, 10 внутри), замкнутый путь заворачивает позицию, открытый продолжает касательные за концами;
transform- и path-ограничения правят мировую матрицу и раскладываются обратно в локальные значения (иначе при неравномерном
масштабе родителя поворот «уезжает»); двухкостный IK при отрицательном масштабе добавляет 180° и зеркалит сгиб.
Не поддержано или отличается при импорте Spine: linked mesh, clipping/bounding box/point attachments (пропускаются с предупреждением; собственные clipping-маски Golem задаются через slot.clip), скины
сливаются в один с префиксом (переключения нет), physics 4.2 и sequence 4.1 нет, смешивание анимаций — наш AnimationState
(кроссфейд поз), а не MixBlend-треки; в локальном режиме transform-ограничения масштаб смешивается линейно (spine-core делит
на масштаб кости); IK у костей с нестандартным inherit приближённый.
Что дальше по коду
- Редактор: кисть весов с учётом направления сгиба; режимы шага пути в UI сверх трёх имеющихся; кривая ease сразу для нескольких выделенных ключей и её правка прямо на таймлайне (сейчас — только в панели свойств одного ключа).
- Ручная сборка — вне объёма этапа (спека E §7): мультивыбор частей, перетаскивание подложки мышью, переименование
внутри
presets.json, ключиdrawOrderсмещениями в духе Spine. - Агентский слой поверх v2: агент читает позу числами (
rig_get_pose) и ставит кость в точку документа (rig_set_goal, то же правило разрешения цели, что у драга в редакторе), а перенос треков между костями со сдвигом фазы и зеркалом (rig_copy_tracks) делает вторую ногу цикла из первой. Пресетов движения это не добавляет — библиотеки походок и параметризованных циклов по-прежнему нет; IK-пресеты (ходьба и прочие циклы;rig_add_ik_chain— это оснастка, а не движение), пресеты на мешах и экспорт в Spine остаются впереди. - Многопользовательский режим: 409 защищает от затирания правки версией, которую клиент уже не держит, но не сливает две одновременные правки — совместного редактирования пока нет.
- Два долга версии записи, которых 409 не закрывает (спека D §7): версию успешного ответа
/api/tool/*сервер берётstat-ом ПОСЛЕ того, как инструмент записал файл, поэтому чужая запись в это субмиллисекундное окно отдаст клиенту версию чужих байт — закрывается, только если инструмент сам вернёт версию тех байт, которые записал он сам; и потеря обновления при двух одновременныхmutate, которые оба читают файл до того, как первый из них успел записать — 409 этого не видит, лечится очередью коммитов на клиенте.
