命令行
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 |
每个管线阶段的图像（albedo、normals、depth、coverage、light、bands、edges、lines、cleanup、lint…），--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 |
原始渲染目标，用于提交 bug 报告；当外观需要绘制网格边时，.pxrg 转储中会包含它们 |
pxr stylize DUMP.pxrg |
在保存的渲染上运行像素处理，包括线框 |
pxr diff OLD NEW |
两个导出文件夹（或两张精灵表）：哪些文件是新增、删除或不同的，相差多少像素，并根据每个文件的配方指出是哪项设置或输入导致的；--all 也列出相同的文件，--exact 在有任何变化时以 1 退出。两个 .pxrg 转储会逐个目标进行比较（--depth-tolerance EPS、--samples N） |
pxr adapters |
Pixor 可以使用的 GPU |
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、Vary 的 --size、Scatter 的 --box、Displace 的 --bumps 和 Height field 的 --hills（以米为单位）、Subdivide 的 --times、Select 的 --how）；不接受输入的节点（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] |
不进行渲染，列出项目将写出的名称和每一帧的 id，每次渲染的文件按各自的路径列出；两帧同名、两次渲染写同一个文件（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（以及 pxr run 中的 --set NODE.SETTING）可以通过编号、类型、组名、名为中的内容（图像文件、精灵表）或在应用中起的名字（F2）来指定节点；object 节点是模型（of=model），物品、形状或图像各自都是独立的节点。资产节点图的 sprites、frame-range 和 hold 节点的设置方式与其他节点相同（--node sprites --set action=walk,Static——action=every-one-except-static 是新节点的默认值，action= 表示所有动作，包括 Static——--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 |
预设的 | 侧视、四分之三视角、等距或俯视 |
--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 |
预设的 | 深色线条的颜色，#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 |
忽略 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 |
转一圈所需的时间（默认：按 --fps 计的 N 帧） |
--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] |
把另一个模型挂到骨骼上，以其握把握持，沿骨骼的轴移动和旋转（参见骨骼上的道具） |
--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 表示一个侧放的、名为 wheel 的轮子（可重复）。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]]，然后是用于编号 .vdb 序列的 [:FRAMES[,EVERY[,LOOP]]]，然后是 @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 |
grid（每个动作和朝向一行，默认）或 strip |
--padding N |
单元格之间的透明像素，0 到 256（默认 0） |
--extrude N |
把单元格边缘向外重复 N 像素，0 到 64（默认 0） |
--pot |
2 的幂的精灵表尺寸 |
--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 |
渲染目标、调色板、检查和闪烁图像 |
为你自己的管线做黄金测试
用例文件每行列出一次渲染：名称、模型或项目路径（相对于该文件）以及选项。
hero-walk models/hero.glb --clip walk --ring 8 --max-flicker 0.02
hero-proj hero.pixorpxr golden cases.txt --bless 把结果作为 NAME.png 保存在该文件旁边；之后，当任何像素发生变化、精灵有检查问题（孤立像素、L 形线条拐角、2 px 的线条），或 --max-flicker 或 --require-visible 检查失败时，pxr golden cases.txt 就会失败；错误信息会说明哪些用例的像素不同（它们的 NAME.actual.png 和 NAME.diff.png 位于 target/golden），以及哪些用例未通过检查。--bless 即使检查失败也会保存图像，并以 1 退出，列出这些用例。用它来发现模型的改动何时改变了你的精灵。
是素材库，不是一次运行
工作室因为一个色阶的改动就要把同样的五千个精灵重新渲染一遍。有三件事让这成为一个可以权衡的决定，而不是一个通宵任务。
进程结束后依然保留的缓存。pxr batch 和 pxr run 上的 --cache DIR 会保存每次渲染的结果，以及它读取的文件和这些文件内容的哈希：模型、旁边的片段文件、.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路径相对于表格。一行就是加上该行 --in 和 --set 的 pxr run，所以出错的行可以单独运行。失败的行不会中断其他行：报告列出每一行是已渲染、来自缓存，还是失败及失败原因；只要有任何一行失败，任务最后以 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 | 用法错误：在 stderr 上输出消息、命令用法以及 see pxr help COMMAND |
| 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。