Командная строка

pxr рендерит те же спрайты, что и приложение (один и тот же проект дает одни и те же пиксели), и подходит для скриптов сборки и пакетной работы. pxr help выводит все команды и параметры, pxr help COMMAND — одну команду с ее параметрами, а pxr --version — версию. Если командную строку не удается прочитать, команда сообщает, что не так, как используется эта команда, и предлагает посмотреть pxr help COMMAND.

Частые задачи

# One sprite, 64 px, three-quarter view
pxr render knight.glb -o knight.png

# Every clip, 8 sides, 12 fps, all export formats
pxr render knight.glb --clip all --ring 8 --export all -o out/knight.png

# Two clips, hand-picked frames for the attack
pxr render knight.glb --clip walk --clip attack --keys 0,0.2,0.35,0.6 -o out/knight.png

# A different look
pxr render knight.glb --preset selout --view isometric --light -30,50 --bands 4 --aa 1 -o knight.png

# Your palette
pxr render knight.glb --palette my-palette.hex -o knight.png

# Save the settings as a project, then render it again later (or open it in the app)
pxr render knight.glb --clip all --ring 8 --export aseprite -o out/knight.png --save-project knight.pixor
pxr render knight.pixor

# A whole folder, every clip of every model, with a report
pxr batch models/ --recursive -o out/ --ring 8 --export all

Проект — это собственный рецепт: при рендере облик и сцена читаются из него, а из командной строки берется только то, куда идут файлы (-o, --export, --names, --scale, --anim-scale, --no-recipe, --debug), дополнительные слои (--paper-doll, --piece, --parallax, --haze), бэкенд и то, какой конвейер ассета записывать. Любой другой флаг упоминается в предупреждении, так как ничего бы не изменил: задайте его в проекте через pxr project set.

Какой конвейер ассета. pxr render project.pixor записывает первый конвейер ассета проекта, так же как окно экспорта приложения записывает выбранный в нем, который сначала совпадает с выбранным в заголовке; --pipeline NAME записывает другой, а --pipeline all — все. Файл называется одинаково, какой бы конвейер ни записывался, поэтому --pipeline all записывает ровно те же файлы, что конвейеры по отдельности. pxr names, pxr watch и pxr run тоже принимают --pipeline.

Куда идут файлы. -o PATH (или --out PATH; каждая команда принимает оба) — место, куда пишет команда. Для команды, которая пишет один файл, — render, stylize, effect, voxels, tiles, shapes, rebake, project blueprint, project set (лист проекта), — это сам файл или папка, в которую файл попадает под своим именем, если путь заканчивается на / или это существующая папка: pxr render knight.glb -o out/ записывает out/knight.png. Проект, отрендеренный с -o, записывает все файлы в эту папку (D51): ею становится папка листов проекта (по умолчанию out/), путь внутри нее сохраняет свое место ниже, а любой другой путь — свою последнюю часть, включая архивы, анимации и иконки. Окно экспорта приложения выполняет ровно pxr render PROJECT --pipeline NAME -o FOLDER на копии проекта в том виде, в каком он открыт, сохраненном или нет, и названной как проект; --recipe-project FILE.pixor (или none для проекта без названия) — то, что рецепт копии называет вместо самой копии. Команды, которые пишут много файлов, — batch, golden, gbuffer, stages, icons, run --jobs — принимают папку.

Файлы клипов рядом с моделью с именем <model>@<clip>.<ext> добавляются автоматически. Другие файлы с тем же скелетом можно добавить через --anim FILE.

Команды

Команда	Операция
pxr render MODEL | PROJECT.pixor	спрайт или лист, если запрошены клипы, стороны или действия; проект записывает по листу на каждую группу камер, кадрируемых вместе
pxr stages MODEL -o DIR	изображение каждого этапа конвейера (альбедо, нормали, глубина, покрытие, свет, полосы, ребра, линии, очистка, проверка…), --only edges,lines — для некоторых; --node N вместо этого записывает то, что создает узел N графа стиля, как KIND.still.png (экран CRT): неподвижный кадр, никогда не спрайт и не лист
pxr batch FOLDER -o DIR	все модели в папке (.gltf, .glb, .fbx, .obj, .vox; --recursive — с подпапками); о неудачных моделях сообщается, и они пропускаются; DIR/report.json; --blueprint B.pixorblueprint прогоняет каждую модель через один шаблон проекта; --cache DIR отдает модели, которые не изменились (см. библиотеки). В приложении перетащите папку на окно
pxr run BLUEPRINT.pixorblueprint --in model=M	шаблон проекта с заполненными входами (см. граф сцены); --set NODE.SETTING=VALUE меняет один параметр, --set PIPELINE/NODE.SETTING=VALUE — то же только в одном конвейере (--set hold.times=4 — узел «Удержание» каждого конвейера ассета); --jobs TABLE.csv -o DIR выполняет по одной строке таблицы на рендер; --pipeline NAME|all — как для render
pxr rebake SHEET.aseprite	отрендерить проект заново в лист, на котором вы рисовали, сохранив ваши слои и правки (см. Aseprite)
pxr cache stat|gc DIR	что хранит кэш; gc --keep 20GiB удаляет давно не использовавшиеся рендеры, пока кэш не уложится в объем
pxr golden CASES.txt	рендерить тестовые случаи и сравнивать с сохраненными изображениями (см. ниже); --only TEXT запускает случаи, в имени которых есть этот текст, --tolerance F допускает долю F отличающихся пикселей, -o DIR (по умолчанию target/golden) — куда идут результаты; --graph вместо этого рендерит их через граф узлов облика — пресета в виде поставляемой группы Пикселизация, — а --flat — через тот же граф, где каждая группа развернута до атомов; оба должны совпадать с теми же изображениями. --cache DIR записывает спрайт каждого случая в --out через кэш и сравнивает этот файл, отданный из кэша или отрендеренный; --no-cache записывает те же файлы без кэша
pxr bench MODEL	измерить каждый бюджет в tests/budgets.txt и сообщить met или MISSED; --rounds N (по умолчанию 10) усредняет время по N запускам; --from INFO.json добавляет то, что измеряет приложение
pxr import MODEL --report	что происходит с файлом при импорте, без рендера: что найдено, что исправлено и почему, что рекомендуется, чего не хватает, треугольников на пиксель спрайта; --json — для пакета, который сначала находит сломанные файлы
pxr reference SPRITE.png	параметры, считанные со спрайта, который у вас есть: палитра, размер, обводка, полосы, сдвиг оттенка, дизеринг, каждый с объяснением; pxr project set P --match-sprite S.png их задает
pxr voxels MODEL -o OUT.vox	модель в виде вокселей, высотой --height (от 1 до 256), в палитре облика: файл MagicaVoxel; --stack записывает также стопку спрайтов (см. Воксели и стопки спрайтов)
pxr nodes [--graph G] [--json]	все узлы четырех графов (стиля, действия, сцены, ассета) в том виде, в каком они есть в этой версии Pixor: что узел делает, что принимает и выдает, каждый параметр с диапазоном и значением по умолчанию; --json — для инструментов (справочник узлов на сайте собирается из него)
pxr inspect FILE	что импортер нашел в любом файле, который импортирует Pixor (форматы, также в pxr help inspect): для модели — объекты, материалы, кости, клипы, предупреждения; для .vdb — его сетки и их размер; для изображения — его размер; для палитры — ее цвета
pxr gbuffer MODEL -o DIR	сырые цели рендера для отчетов об ошибках; дамп .pxrg содержит ребра меша, если облик их рисует
pxr stylize DUMP.pxrg	выполнить пиксельные проходы над сохраненным рендером, включая каркас
pxr diff OLD NEW	две папки экспорта (или два листа): какие файлы новые, исчезли или отличаются, на сколько пикселей и, по рецепту каждого файла, какой параметр или вход это вызвал; --all перечисляет и одинаковые файлы, --exact завершается с кодом 1 при любом изменении. Два дампа .pxrg сравниваются цель за целью (--depth-tolerance EPS, --samples N)
pxr adapters	GPU, которые может использовать Pixor
pxr doctor	чем эта машина может рендерить и согласуется ли ее GPU с эталоном на CPU
pxr project new|set|show PROJECT.pixor	создать, изменить или вывести проект из сценариев и инструментов: --name NAME дает ему имя (имя в заголовке, а не имя файла; show выводит его вместе с остальным)
pxr project key PROJECT.pixor TARGET CHANNEL	один ключ клипа, созданного в Pixor (--clip, --frame, --value, --how, --remove…), чтобы сценарий мог собрать клип
pxr project bake PROJECT.pixor CLIP	собственный клип модели как клип, созданный в Pixor, с ключом на каждой кости в каждом кадре (--as NAME, --fps F)
pxr project scene PROJECT.pixor [NODE]	граф сцены по одному узлу: ring, row, grid, scatter, look-at, vary… добавляются в конец цепочки, а опции каждого узла названы по его параметрам (--count, --radius, --size у Vary, --box у Scatter, --bumps у Displace и --hills у Height field в метрах, --times у Subdivide, --how у Select); узел, который ничего не принимает (object, import), начинает цепочку вместо голого импорта, а рядом с более длинной цепочкой встает отдельно, слитый с ней; без узла выводит граф
pxr project blueprint PROJECT.pixor -o B.pixorblueprint	проект как шаблон проекта, где его модель, палитра, файлы реквизита и объемов вынесены в именованные слоты
pxr style new KIT --from PROJECT	сохранить первый Стиль проекта как набор Стиля
pxr kit show FILE.pixorkit	что содержит набор: группу узлов, Стиль, пресет или конвейер
pxr names PROJECT.pixor [--names T] [--pipeline NAME|all]	имена, которые запишет проект, и идентификатор каждого кадра, без рендера, файлы каждого рендера по их собственному пути; два кадра на одно имя, два рендера на один файл (would be written twice) или два файла на один путь (основа бумажной куклы и основа набора света, вариант палитры и слой) — это ошибка здесь, а не потерянный файл позже
pxr graph list|set|add|drop|wire|save|swap|flatten|extra FILE --which scene|action|style|asset	любой из четырех графов из сценария. --pipeline NAME выбирает, какой: действие по имени, Стиль или конвейер ассета, первый, если имя не задано. Выведите его, измените один параметр, добавьте узел в цепочку (или рядом с ней с --alone, подключая к нему другие через --in SLOT=NODE), удалите узел, соедините два с помощью wire --from N --to M --slot S, сохраните как набор (save -o KIT.pixorkit: граф стиля целиком, граф сцены, действия или ассета как один узел, --as-pipeline — целый конвейер ассета, который другой проект использует через pxr project set --use-pipeline), вставьте набор узлов как группу (add --kit KIT) или вместо узла (swap --kit KIT) либо выпишите граф с раскрытыми группами; extra --node N --name LAYER делает изображение узла стиля еще и слоем экспорта, а --drop это отменяет. --node (и --set NODE.SETTING в pxr run) называет узел по номеру, виду, имени группы, по тому, что написано в его поле Название (у файла изображения, у листа), или по имени, данному ему в приложении (F2); узел object — это модель (of=model), а предмет, фигура или изображение — отдельные узлы. Узлы sprites, frame-range и hold графа ассета настраиваются как любые другие (--node sprites --set action=walk,Static — action=every-one-except-static у нового узла, action= — все действия, включая Статику, — --set smart=6, --node frame-range --set from=2 --set to=5, --node hold --set times=2); узлы действия — clip, bob, spin, merge… — по виду или номеру, и добавленный без --alone сразу играет, слитый с тем, что там есть. В графе стиля узел добавляется ни с чем не соединенным, --in SLOT=NODE и wire подключают его. Правка, после которой граф не смог бы работать, отклоняется, а файл остается как был (см. граф сцены, граф ассета и узлы)
pxr shapes [PROJECT] -o OUT.glb	выписать фигуры, построенные в приложении, в виде геометрии, для редактора моделей или движка
pxr icons MODELS... -o DIR	иконки инвентаря с атласом на каждый размер; редкость берется из имени каждого файла, а --save сохраняет рецепт для повторного запуска (см. Экспорт)
pxr audit FILE|FOLDER... [--style KIT]	проверить, что экспортированные листы согласованы: пресет, схема освещения, вид, наклон, свет, полосы, линии, палитра и пиксели на метр — по рецепту каждого файла, а с набором Стиля — что каждый цвет есть в его палитре (иначе код выхода 1)
pxr watch PROJECT.pixor	экспортировать снова всякий раз, когда меняется проект, его модель или палитра
pxr effect KIND[:FRAMES]	отдельный пиксельный эффект: explosion, hit-spark, slash, magic-burst, heal, portal, smoke-puff, dust, fire-loop, rain, snow, fireflies, falling-leaves
pxr console list|check SHEET.png	режимы консоли или то, подходит ли лист под один из них (иначе код выхода 1); консоль берется из --console или из рецепта листа

Параметры рендера

Вариант	По умолчанию
--view VIEW	пресета	side, three-quarter, isometric или top-down
--pitch DEG	вида	градусов ниже горизонта
--yaw DEG	0	повернуть отдельный спрайт или единственную сторону листа из одного спрайта
--camera GENRE		камера игры: platformer, fighting, beat-em-up, adventure, top-down-rpg, action-adventure, isometric, tactics, strategy, racing, top-down-shooter, shmup, icon (вид, наклон, поворот; размер и стороны, если не заданы)
--camera-yaw DEG	0	вращать камеру вокруг модели, все стороны
--size N	64	вписать в N x N, от 4 до 2048; --size 960x540 вписывает в холст такой ширины и высоты (заглавное изображение, фон)
--pixels-per-metre F		фиксированное число пикселей на метр вместо --size, от 0.5 до 4096 (Пикс./м в приложении)
--up AXIS	определяется при импорте	ось, которая в файле направлена вверх (y, z, -z, x, -x, -y): для модели, экспортированной лежа
--import-scale F, --import-offset X,Y,Z	определяется при импорте	юнит и ход, заданные вручную
--no-import-fix		отрендерить файл в точности как есть, ничего не исправляя
--samples N	4	выборок на пиксель по каждой стороне, от 1 до 8 (Примеры в приложении)
--light AZ,EL	-45,45	ключевой свет относительно камеры
--light-space S	камера	world: свет остается на месте в сцене, а не следует за камерой
--fill F	пресета	сила заполняющего света, от 0 до 1
--no-shadow		без отбрасываемых теней
--bands N	пресета	полосы света, от 1 до 4
--palette P		файл .hex, .gpl или .png либо встроенная палитра: pixor-16, pixor-8, dusk-12, forest-12, desert-12, ice-10, mono-8
--aa N	0	сглаживание: 0 — выкл., 1 — силуэт, 2 — каждая линия
--match-space S	oklab	как цвета находят ближайший в фиксированной палитре: oklab, srgb или weighted
--dither-pattern P	bayer	bayer (перекрестная штриховка) или blue-noise (равномерно рассеянный); оба остаются на поверхности, когда модель движется
--even-stairs	выкл.	прямые края силуэта с равными ступенями (2, 2, 2, а не 3, 1, 2)
--smear PX	0	кадры смазывания, от 0 до 64: то, что сдвинулось на PX пикселей или больше с предыдущего кадра, оставляет шлейф
--nudge X,Y	0,0	сдвинуть модель на долю пикселя по сетке (каждая ось от -0.5 до 0.5); меняется только выборка
--foot-plant	выкл.	опорные ступни гуманоида на одной и той же строке пикселей в каждом кадре клипа
--preset NAME	чистый	clean, selout, retro4, flat, wireframe или сохраненный набор пресета (.pixorkit)
--style KIT		набор Стиля (.pixorkit): целый Стиль (pxr style new, «Сохранить набор…» у Стиля), вместе с его графом стиля, или только граф стиля (pxr graph save --which style); последующие флаги все равно его меняют. В файле эталонного случая — относительно этого файла. pxr icons и pxr audit принимают то же
--dither F	0	упорядоченный дизеринг между соседними полосами света, от 0 до 1
--line-colour HEX	пресета	цвет линий Dark, #rrggbb (только для автоматических палитр)
--no-lines MATERIAL		без линий вокруг этого материала (можно повторять; pxr inspect их перечисляет)
--crease-angle DEG	55	насколько острая складка рисует линию сгиба, от 1 до 179
--depth-step PX	2.5	перепад глубины в пикселях, рисующий внутреннюю линию, от 0.1 до 40 (Перепад глубины в приложении)
--shortest-line N	3	кратчайшая сохраняемая внутренняя линия или линия сгиба, от 0 до 16 пикселей (Кратчайшая линия в приложении)
--no-part-lines		без линий между соприкасающимися частями без перепада глубины
--outline-inside		силуэт на собственном краю спрайта
--convex LINE	нет	светлая линия на складках, выпирающих к камере: none, dark или highlightN
--no-material-channels		игнорировать металличность, шероховатость, свечение, unlit и прозрачность материала glTF и затенять только по его цвету
--backend B	авто	auto, vulkan, metal, dx12, gl, webgpu или cpu (см. Выбор рендерера)

Параметры света и цвета

Вариант
--rig NAME	схема освещения: noon, dusk, torchlight, moonlight или studio
--cycle MATERIAL	зациклить цвета этого материала в действии --colour-cycle (можно повторять)
--team MATERIAL|#RRGGBB	цвет команды: материал или все рампы оттенка этого цвета (можно повторять); --variant team:blue перекрашивает только его
--console C	режим консоли: gameboy, nes, pico8, tic80, c64 (см. Режимы консоли)

Параметры анимации

Вариант
--clip NAME	клип для рендера (повторите для нескольких) или all
--anim FILE	также использовать клипы из FILE
--ring N	стороны против часовой стрелки от передней (от 1 до 64, по умолчанию 1), с именами South, Southeast, East…: по камере на каждую, с общим размером, в одном листе
--sides A1,A2,...	сторона на каждый угол вместо этого, в градусах (0 — спереди, 90 — смотрит вправо)
--fps F	кадров в секунду времени клипа (по умолчанию 12) — нарезка каждого узла «Спрайты»
--keys T1,T2,...	выбранные вручную моменты клипа, в секундах, — нарезка каждого узла «Спрайты»
--clip lib:NAME	клип библиотеки движений, подогнанный под скелет модели: idle, walk, run, jump, attack, hit, death
--parallax N	разделить изображение по глубине на N слоев (2–8) для прокручиваемых фонов (см. Сцены из нескольких моделей)
--haze #RRGGBB	цвет, к которому затеняются дальние слои параллакса; none оставляет каждый слой на палитре как есть
--spring NODE[:S,D,G]	NODE и все ниже него качаются с движением: жесткость, затухание, гравитация (можно повторять); в проекте — узел Spring графа сцены
--smart-frames N	оставить N кадров каждого клипа, выбранных из его поз (каждый удерживается до следующего), — нарезка каждого узла «Спрайты»
--root-motion M	keep (по умолчанию), in-place (закрепить корневую кость по горизонтали) или in-place-sway (убрать только итоговое перемещение клипа)
--turntable N	добавить действие из N кадров, поворачивающее модель на один оборот
--turntable-seconds S	сколько длится этот поворот (по умолчанию: N кадров при --fps)
--motion M[:N[:A]]	добавить цикл: spin, bob, swing, pulse, squash или flicker, N кадров, сила A (для spin — доля оборота, которую делает цикл: spin:8:0.125 поворачивает самоцвет с восемью гранями на одну грань — бесшовный цикл)
--colour-cycle N	добавить действие из N кадров, поворачивающее оттенки циклических материалов
--prop FILE:BONE[@at=X,Y,Z][@turn=X,Y,Z][@scale=S][@grip=NODE]	прикрепить другую модель к кости, которую та держит за grip, перемещая и поворачивая ее по осям кости (см. Реквизит на костях)
--shape SPEC	добавить фигуру: [NAME=]KIND[:SIZE[:AT[:#RRGGBB[:TURN]]]], например box:1,0.5,1:0,0.25,0:#c86432 или wheel=cylinder:0.5,0.2,0.5:0.7,0.25,0.5:#14101c:90,0,0 для именованного колеса, лежащего на боку (можно повторять). KIND — это box, sphere, cylinder, cone, torus, plane, capsule, wedge, pyramid, prism, stairs, arch или letters (pxr help render перечисляет их из того же списка, который читает флаг): letters — пиксели шрифта, выдавленные в блоки, складывающиеся в PIXOR, или в слова проекта, pxr project set --add-shape letters --words WORDS --font NAME (render не принимает --words)
--volume SPEC	добавить объем: puff, flame, cloud, mist или путь к .vdb, затем [:SIZE[:AT]], затем [:FRAMES[,EVERY[,LOOP]]] для нумерованной последовательности .vdb, затем @BONE, чтобы его несла кость, или @effect:N — излучатель N-го эффекта (Объемы)
--wire LINE	облик каркаса: none, dark или seloutN, с --wire-fill, --wire-hidden, --wire-angle (от 0 до 180), --wire-all-edges и --wire-glow MATERIAL (параметры)
--light-sweep N	добавить действие из N кадров, двигающее свет
--effect KIND[:N]	добавить действие пиксельного эффекта из N кадров (см. pxr effect) с --effect-size, --effect-energy, --effect-seed, --effect-at X,Y,Z, --effect-bone BONE, --effect-clip CLIP, --effect-hit FRAME и --effect-alone
--hitbox PART, --hurtbox PART, --socket BONE	коробки и положения костей на каждый кадр в JSON (можно повторять; см. Экспорт)
--paper-doll, --piece NAME:PARTS	слои бумажной куклы (см. Экспорт)
--item MODEL@X,Z[,YAW,SCALE[,LAYER]][:CLIP[,PHASE]], --ground W,D[,#RRGGBB]	дополнительные модели рядом с первой, каждая — узел «Предмет» графа сцены в проекте, а под ними плоскость земли (см. Экспорт)
--chunks COLSxROWS	записать большую карту фрагментами с точными швами; --chunk-margin N (по умолчанию 8)
--max-flicker F	предупреждать, если доля мерцания выше этой (например, 0.01); в эталонном случае — ошибка
--require-visible OBJECT	предупреждать, если OBJECT исчезает в каком-либо кадре

Параметры экспорта

Вариант
--export LIST	через запятую или повторением: png, json, aseprite, normal, depth, emission, layers, palette, godot, gif, apng, light-kit, p8, report, video или all (все, кроме p8 и video, которые записываются только если названы); PNG записывается всегда (см. Экспорт). render, batch, run, watch, project set и tiles (со своими форматами) читают его так же
--layout L	сетка (строка на каждое действие и сторону, по умолчанию) или полоса
--padding N	прозрачные пиксели между ячейками, от 0 до 256 (по умолчанию 0)
--extrude N	повторять края ячеек на N пикселей наружу, от 0 до 64 (по умолчанию 0)
--pot	размер листа — степень двойки
--godot-path RES	где Godot находит лист (по умолчанию res://<png name>)
--anim-scale K	целочисленный масштаб файлов GIF и APNG, от 1 до 16 (по умолчанию 1)
--video-scale K, --video-fps N, --video-background #RRGGBB	как записываются видео: масштаб от 1 до 16 (по умолчанию 4), от 1 до 100 кадров в секунду (по умолчанию 30), поверх чего рисуется спрайт (по умолчанию черный)
--trim	обрезать каждую ячейку до ее пикселей (JSON и файл Godot сохраняют размещение)
--dedupe	хранить одинаковые кадры один раз
--max-width N	начинать новую строку, прежде чем лист станет шире N пикселей (от 0 до 65536; 0 — без ограничения)
--columns N	N кадров в ряду, каждый клип продолжается после предыдущего: контактный лист
--max-height N	разбить лист выше N пикселей на страницы, целыми клипами на страницу (NAME_1.png, NAME_2.png; от 0 до 65536)
--variant NAME	также экспортировать вариант палитры (можно повторять): эффект вроде hit-flash или night, hue:DEG, team:COLOUR (имя или #rrggbb; нужен --team) или palette:NAME|FILE; добавляет лист индексов и текстуру-таблицу
--shadow KIND	также записать name_shadow.png: contact или drop
--names TEMPLATE	как называются файлы и ключи JSON: шаблон из {project}, {object}, {action}, {side}, {layer}, {set}, {size}, {index} и {ext}, где {index:3} дополняется до трех цифр (см. Экспорт)
--no-recipe	не сохранять рецепт (как был сделан лист) в PNG и .aseprite
--scale K	увеличить PNG в K раз (только для превью; не с другими форматами)
--save-project FILE.pixor	также записать эту командную строку как проект
--debug DIR	цели рендера, палитра, изображения проверки и мерцания

Эталонные тесты для вашего собственного конвейера

Файл cases перечисляет по одному рендеру на строку: имя, путь к модели или проекту (относительно файла) и параметры.

hero-walk   models/hero.glb --clip walk --ring 8 --max-flicker 0.02
hero-proj   hero.pixor

pxr golden cases.txt --bless сохраняет результаты как NAME.png рядом с файлом; затем pxr golden cases.txt завершается ошибкой, если меняется хоть один пиксель, если линтер находит проблемы в спрайте (одиночные пиксели, L-образные углы линий, линии по 2 px) или если не проходит проверка --max-flicker или --require-visible; ошибка сообщает, у каких случаев отличаются пиксели (их NAME.actual.png и NAME.diff.png лежат в target/golden) и какие не прошли проверки. --bless сохраняет изображения, даже если проверка не прошла, и завершается с кодом 1, называя эти случаи. Используйте это, чтобы замечать, когда изменение модели меняет ваши спрайты.

Библиотека, а не прогон

Студия заново рендерит те же пять тысяч спрайтов, потому что сдвинулась одна рампа. Три вещи превращают это в осознанное решение, а не в работу на всю ночь.

Кэш, который переживает процесс. --cache DIR в pxr batch и pxr run сохраняет каждый сделанный рендер вместе с прочитанными файлами и хешем их содержимого: модель, файлы клипов рядом с ней, текстуры, на которые ссылается .gltf, палитры, наборы, изображения и объемы. Следующий запуск отдает каждый рендер, чьи файлы дают тот же хеш, и рендерит остальное.

pxr batch models/ --cache .pxrcache --out out/     # renders what changed
pxr cache stat .pxrcache
pxr cache gc .pxrcache --keep 20GiB                # least recently used go first

Кэш никогда не является источником истины: --no-cache дает те же байты, сохраненный файл, хеш которого не совпадает с его именем, рендерится заново, а не отдается, а новая сборка Pixor начинает новый кэш, а не доверяет старому.

Файл задания. Таблица с одной строкой на рендер, одним столбцом на слот шаблона проекта и, по желанию, столбцами name (папка строки), out (ее лист внутри --out) и NODE.SETTING (--set для этой строки):

model,name,palette,sprites.fps
heroes/knight.glb,knight,palettes/steel.hex,8
heroes/mage.glb,mage,palettes/robes.hex,

Здесь sheet.pixorblueprint получен командой pxr project blueprint sheet.pixor из проекта с heroes/knight.glb и палитрой, поэтому его слоты — model и palette; рыцарь нарезается с частотой 8 кадров в секунду, а маг, у которого ячейка пуста, — с собственной частотой шаблона проекта. Каждая строка записывает out/NAME/NAME.png.

pxr run sheet.pixorblueprint --jobs assets.csv --cache .pxrcache --out out/ --jobs-report report.json
pxr run sheet.pixorblueprint --jobs assets.csv --cache /shared/cache --out out/ --rows 400..   # the second machine, of 800 rows

Пути указываются относительно таблицы. Строка — это ровно pxr run с добавленными --in и --set этой строки, поэтому неудачную строку можно запустить отдельно. Сбой одной строки никогда не останавливает остальные: отчет перечисляет каждую строку — отрендерена ли она, взята из кэша или завершилась сбоем и почему, — и задание в конце завершается с кодом 1, если сбой был.

Бюджеты как флаги. --max-pixels N, --max-memory SIZE и --max-time DURATION действуют на рендер (на строку, на модель). То, что план уже знает, — сколько пикселей будет в листе, примерно сколько памяти он займет, — проверяется до того, как что-либо нарисовано; время и память проверяются между кадрами. Превышение завершает работу с кодом 6, указывая, что превышено и где остановилось; в задании строка завершается неудачей с этой причиной, а остальные продолжаются.

pxr run sheet.pixorblueprint --jobs assets.csv --out out/ --max-memory 1.5GiB --max-time 5m --max-pixels 16M

Длинные клипы. Кадры клипа рисуются, а затем доводятся вместе, потому что проходы, которые не дают клипу мерцать, смотрят вдоль него. То, что они читают, держится в пределах 512 MiB (половина --max-memory, если он задан), по несколько сторон за раз; клип, слишком длинный даже для одной стороны, хранится на диске, пока рисуется, — в ~/.cache/pixor/spill или PXR_SPILL_DIR — и считывается по мере надобности: те же пиксели, только медленнее, а папка удаляется вместе с завершением рендера.

Коды выхода

Код
0	успех
1	неудачный рендер, экспорт, пакетная модель, строка задания или эталонный случай
2	ошибка использования: сообщение, справка по команде и see pxr help COMMAND в stderr
3	вход, который не удалось прочитать: модель, проект, палитра, набор, файл случая или дамп
4	бэкенд, запрошенный по имени, которого нет
5	выход, который не удалось записать: файл или папка
6	превышение бюджета --max-pixels, --max-memory или --max-time
7	повторное запекание, сохранившее прорисовку, о которой оно не станет решать само (--resolve keep|pixor)

Отсутствие GPU — не ошибка: тогда Pixor рисует собственным растеризатором. Ошибка везде сообщает, что не так, одинаково: --flag takes A to B, got X.

Выбор рендерера

--backend auto|vulkan|metal|dx12|gl|webgpu|cpu задает, кто рисует геометрию. Облик — каждый пиксельный проход — рассчитывается на CPU, что бы здесь ни было указано.

• auto (по умолчанию) берет то, что есть на компьютере, и переходит на CPU, если ни один адаптер не работает.
• cpu — собственный растеризатор Pixor. Ему не нужны ни адаптер, ни драйвер, он встроен в исполняемый файл и рисует одни и те же пиксели на любом компьютере — переносимый выбор для пака ассетов или CI-сборки.
• Бэкенд, который назван, но недоступен, — это ошибка (код выхода 4), потому что молча рендерить на чем-то другом хуже, чем сказать об этом.

Рецепт каждого экспорта фиксирует, какой бэкенд его нарисовал. pxr doctor выводит найденные адаптеры, тот, который выбрал бы Pixor, версии драйверов и то, рисует ли этот бэкенд то же изображение, что и эталон на CPU:

adapter  NVIDIA GeForce RTX 3070 Ti (Vulkan, DiscreteGpu) driver NVIDIA 610.57.04
backend  vulkan (NVIDIA GeForce RTX 3070 Ti (Vulkan, DiscreteGpu))
agrees   vulkan vs the CPU reference: coverage 0.00%, ids 0.00%, albedo 0.00% (allowed 1.00%); normals within 0.028 deg, depth within 9.5e-7

В приложении тот же выбор — Настройки › Рендерер › Рисовать спрайты на CPU, а на один сеанс — pixor --backend B с теми же именами, что у pxr (cpu, auto или GPU-бэкенд по имени), что оставляет настройку как есть. Каждый сохраняет то, что нарисовал: переключение на другой рендерит кадры заново, а возврат обратно возвращает кадры первого без рендера, если в сцене ничего не изменилось.

Для инструментов и скриптов

Добавьте --json к любой команде: тогда стандартный вывод несет по одному JSON-событию на строку (progress, wrote, warning, error, done), а читаемый журнал переходит в стандартный поток ошибок. Команды, которые читают, а не пишут, тоже выдают напечатанное одним событием: inspect, adapters, tiles --list (terrains), graph list и graph flatten, а также diff двух дампов.