# Blender пользователя (сцены, материалы, узлы, рендер)

## S0. ГДЕ ИДЁТ ХОД: проверь до всего остального

Машину хода называет блок `<environment>`, а не набор инструментов: `exec_command` бывает и на облачном маршруте.

## S1. ПРАВИЛА

**1. Первый вызов хода: `scene_probe`.** Версия Blender, язык интерфейса, движок и состав сцены известны до первой строки кода, а не угадываются:

В `data`: `blender.version_tuple`, `ui.language` и `ui.use_translate_new_dataname`, `render.engine`, все объекты с типом, трансформом, `world_bbox`, модификаторами и материалами; материалы и мир узлами по `type`/`bl_idname` со связями по `identifier`; коллекции, камеры. Большая сцена: `--max-objects 200` (счёт `object_count` остаётся полным).

**2. Узлы по роду, сокеты по identifier.** Узел ищется по `n.type == "BSDF_PRINCIPLED"` или `n.bl_idname`, создаётся по `bl_idname`, сокет берётся по `identifier`. Имена локализованы: на русском интерфейсе с `use_translate_new_dataname` новый узел получает русское имя, и `nodes["Principled BSDF"]` падает KeyError. Имена сокетов меняются между версиями (Principled переименовал входы в 4.0).

**3. Enum не пиши по памяти.** Идентификаторы меняются между версиями (EEVEE: `BLENDER_EEVEE` до 4.2, `BLENDER_EEVEE_NEXT` в 4.2-4.5, снова `BLENDER_EEVEE` с 5.0; Boolean `FAST` стал `FLOAT` в 5.0). Допустимые значения читаются из живого `bl_rna`:

**4. `material.diffuse_color` красит только вьюпорт.** Цвет в рендере задают входы узлов (`Base Color` у Principled). В срезе поле так и названо: `diffuse_color_viewport_only`.

**6. Маленькие шаги.** Один вызов делает одно изменение и печатает, что сделал. Каждый вызов `blender_exec` через сокет становится одним шагом отмены, и при ошибке тоже: Ctrl+Z пользователя откатывает ровно этот вызов, упавший на десятой строке вместе с первыми девятью (`undo: "pushed"` в ответе; `unavailable` значит, что шаг не лёг, и откатывать нечем). Имя шага задаёт `--label "<что сделано>"`. Правку данных делай в режиме OBJECT: шаг, положенный из режима правки меша, откатывается не так, как ждёшь. Headless шагов отмены не кладёт (`undo: null`). Каждый вызов исполняется в свежем пространстве имён: переменные прошлого вызова не живут.

Человек читает её и приносит недостающее (версию, файл, скриншот окна, настройку аддона).

## S2. ТРИ ПУТИ, ОДНА ДВЕРЬ

На порту 9876 говорят два аддона, дверь понимает оба и на каждом вызове узнаёт ответивший по его кадру (`protocol` в ответе, у blender-mcp ещё `addon`: имя, версия, протокол): сменил пользователь аддон, следующий вызов это уже видит. Как включить сервер аддона, говорит `hint` двери при закрытом порте: пересказывай его, а не память.

Отдельный MCP-сервер (`uvx mcp-for-blender`) не нужен: он только мост stdio → тот же сокет, а дверь говорит с сокетом напрямую. Порт не 9876: `--port`.

### Код в Blender

Коротко: `--code "..."`; в `cmd` heredoc нет, поэтому код кладётся файлом в папку чата (`edit_file`) и передаётся `--file <путь>`. Флаги правки: `--label "<что сделано>"` (имя шага отмены), `--look` (кадр после кода в том же вызове, `data.snapshot`; в headless ракурс `--view`). Ответ: `{status, hint, via, protocol, blender_version, stdout, traceback, data, undo}`. `traceback` со строкой из твоего кода: читай его и `hint`, прежде чем править. Строка stdout, начатая `BLENDER_RU_JSON:`, переезжает разобранной в `data`: так удобно вернуть структуру (`print("BLENDER_RU_JSON:" + json.dumps(d))`, `json` импортируй в коде сам).

Сокет: потолок вызова 180 с (`--timeout`), рукопожатие и ответ делят его. Долгий рендер или тяжёлая операция держит интерфейс пользователя всё это время: предупреди и дроби. Таймаут не значит, что код не исполнился: сначала `scene_probe`, потом решение о повторе.

## S3. СНИМОК

После правки кадр снимает `--look` того же вызова (правило 5). Отдельный вызов снимка нужен, когда правки не было: первый взгляд на сцену, другой ракурс рендером, файл с диска.

- Сокет: 3D-вид открытого окна рисуется offscreen (`GPUOffScreen.draw_view3d`), так что картинка не зависит от того, на переднем ли плане окно; без GPU-контекста запасной ход `screenshot_area`. Ракурс и режим затенения те, что у пользователя в окне.
- Headless (или `--mode render`): Workbench-рендер во временную камеру, наведённую на всю видимую геометрию (`--view iso|front|back|left|right|top`), либо камерой сцены (`--camera scene`). Движок, камера и разрешение сцены возвращаются. Временная камера каждый раз заново охватывает сцену: сдвиг всей сцены целиком на снимке не виден, для положения верь срезу. Workbench показывает цвета вьюпорта (`diffuse_color`) и текстуры, а не узлы Principled: вид материала в рендере проверяй рендером нужного движка через `blender_exec`.
- PNG не больше 1000 px ложится в `$WORK_ROOT/blender/` (путь в `data.path`); в артефакты попадает только с явным `-o имя.png` (копия в `$OUTPUT_ROOT`), и только когда снимок и есть результат для человека.
- С `-o имя.png` рядом ложится `имя.glb`: та же сцена glTF-экспортом (видимые объекты, модификаторы применены, без камер и света). В чате GLB открывается 3D-вьюером, человек вращает модель, а картинка остаётся для мессенджера. Путь в поле `glb`; `glb_error` значит, что выложен только PNG. `--no-glb`, когда результат и есть картинка (кадр рендера, композиция), а не модель.
- Сам `.blend` в `$OUTPUT_ROOT` кладёшь, только если человек попросил исходник: копией, файл пользователя не трогая (правило 9): в headless `--save-as "$OUTPUT_ROOT/имя.blend"`, через сокет `bpy.ops.wm.save_as_mainfile(filepath=..., copy=True)` в коде, путь `$OUTPUT_ROOT` раскрыт шеллом (у Blender этой переменной нет).
- Посмотреть картинку: `analyze` с `kind="describe"` и путём из `data.path`; если путь с компьютера не читается, сначала `copy_from_computer`. `change`: `FIRST`, `CHANGED` (с `ahash_distance`, насколько сдвинулся кадр) или `UNCHANGED` (правило 5).

## S7. ГРАНИЦЫ

*Сначала узнай, где ход и какая версия; меняй маленьким шагом; сверяй числом, потом глазами; упёрся трижды, отдай человеку строку HUMAN_REVIEW.*