Linha de comando

pxr renderiza os mesmos sprites que o app (o mesmo projeto dá os mesmos pixels) e serve para scripts de build e trabalho em lote. pxr help imprime todos os comandos e opções, pxr help COMMAND, um comando com suas opções, e pxr --version, a versão. Uma linha de comando que ele não consegue ler diz o que está errado, como aquele comando é usado, e para ver pxr help COMMAND.

Tarefas comuns

# 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

Um projeto é a sua própria receita: renderizar um lê o visual e a cena dele, e pega da linha de comando só para onde vão os arquivos (-o, --export, --names, --scale, --anim-scale, --no-recipe, --debug), as camadas extras (--paper-doll, --piece, --parallax, --haze), o backend e qual pipeline de asset ele grava. Qualquer outra opção é citada num aviso, já que não mudaria nada: defina-a no projeto com pxr project set.

Qual pipeline de asset. pxr render project.pixor grava o primeiro pipeline de asset do projeto, assim como a janela Exportar do app grava o escolhido nela, que começa pelo do cabeçalho; --pipeline NAME grava outro, e --pipeline all, todos. Um arquivo tem o mesmo nome seja qual for o gravado, então --pipeline all grava exatamente os arquivos que os pipelines gravam um a um. pxr names, pxr watch e pxr run também aceitam --pipeline.

Para onde vão os arquivos. -o PATH (ou --out PATH; todo comando aceita os dois) é onde um comando grava. Para um comando que grava um arquivo — render, stylize, effect, voxels, tiles, shapes, rebake, project blueprint, project set (a folha do projeto) —, é esse arquivo, ou uma pasta em que o arquivo entra com o próprio nome quando o caminho termina em / ou é uma pasta que existe: pxr render knight.glb -o out/ grava out/knight.png. Um projeto renderizado com -o grava todos os arquivos nessa pasta (D51): a pasta de folhas do projeto (out/ por padrão) passa a ser ela, um caminho dentro dela mantém o seu lugar abaixo, e qualquer outro caminho, a sua última parte — arquivos compactados, animações e ícones incluídos. A janela Exportar do app roda exatamente pxr render PROJECT --pipeline NAME -o FOLDER, numa cópia do projeto como está aberto, salvo ou não, com o nome do projeto; --recipe-project FILE.pixor (ou none para um projeto sem título) é o que a receita da cópia indica em vez da cópia. Os comandos que gravam muitos arquivos — batch, golden, gbuffer, stages, icons, run --jobs — recebem uma pasta.

Arquivos de clipe ao lado de um modelo chamados <model>@<clip>.<ext> são adicionados automaticamente. Outros arquivos com o mesmo esqueleto podem ser adicionados com --anim FILE.

Comandos

Comando	Faz
pxr render MODEL | PROJECT.pixor	um sprite, ou uma folha quando clipes, lados ou ações são pedidos; um projeto grava uma folha por grupo de câmeras enquadradas juntas
pxr stages MODEL -o DIR	uma imagem de cada estágio do pipeline (albedo, normais, profundidade, cobertura, luz, faixas, bordas, traços, limpeza, lint…), --only edges,lines para alguns; --node N grava, em vez disso, o que o nó N do grafo de Estilo produz como KIND.still.png (a tela de um CRT): uma imagem parada, nunca um sprite ou uma folha
pxr batch FOLDER -o DIR	cada modelo numa pasta (.gltf, .glb, .fbx, .obj, .vox; --recursive para subpastas); modelos com falha são relatados e pulados; DIR/report.json; --blueprint B.pixorblueprint passa cada modelo por um modelo de projeto; --cache DIR serve os modelos que não mudaram (veja bibliotecas). No app, solte a pasta na janela
pxr run BLUEPRINT.pixorblueprint --in model=M	um modelo de projeto com as entradas preenchidas (veja o grafo de cena); --set NODE.SETTING=VALUE muda um ajuste, --set PIPELINE/NODE.SETTING=VALUE o mesmo só num pipeline (--set hold.times=4 o nó Reter de todos os pipelines de asset); --jobs TABLE.csv -o DIR executa uma linha de uma tabela por renderização; --pipeline NAME|all como em render
pxr rebake SHEET.aseprite	renderizar o projeto de novo numa folha em que você pintou, mantendo suas camadas e edições (veja Aseprite)
pxr cache stat|gc DIR	o que um cache guarda; gc --keep 20GiB remove as renderizações usadas há mais tempo até caber
pxr golden CASES.txt	renderizar casos de teste e compará-los com imagens guardadas (veja abaixo); --only TEXT executa os casos cujo nome o contém, --tolerance F aceita uma fração F de pixels diferentes, -o DIR (padrão target/golden) é para onde vão os resultados; --graph os renderiza pelo grafo de nós do visual — o da predefinição como o grupo Pixelizar incluído — e --flat pelo mesmo grafo com cada grupo achatado em átomos; ambos precisam bater com as mesmas imagens. --cache DIR grava o sprite de cada caso em --out pelo cache e compara esse arquivo, servido ou renderizado; --no-cache grava os mesmos arquivos sem ele
pxr bench MODEL	medir cada orçamento em tests/budgets.txt e dizer met ou MISSED; --rounds N (padrão 10) tira a média dos tempos em N execuções; --from INFO.json adiciona os que o app mede
pxr import MODEL --report	o que acontece com o arquivo na importação, sem renderizá-lo: encontrado, corrigido e por quê, sugerido, faltando, triângulos por pixel de sprite; --json para um lote que encontre primeiro os arquivos quebrados
pxr reference SPRITE.png	ajustes lidos de um sprite que você tem: paleta, tamanho, contorno, faixas, deslocamento de matiz, pontilhado, cada um com o porquê; pxr project set P --match-sprite S.png os aplica
pxr voxels MODEL -o OUT.vox	o modelo como voxels, com --height de altura (de 1 a 256), na paleta do visual: um arquivo do MagicaVoxel; --stack também grava um sprite stack (veja Voxels e sprite stacks)
pxr nodes [--graph G] [--json]	cada nó dos quatro grafos (style, action, scene, asset) como este Pixor os tem: o que faz, o que recebe e fornece, cada ajuste com seu intervalo e padrão; --json para ferramentas (a referência de nós do site é gerada a partir disso)
pxr inspect FILE	o que o importador encontrou em qualquer arquivo que o Pixor importa (os formatos, também em pxr help inspect): para um modelo, objetos, materiais, ossos, clipes, avisos; para um .vdb, suas grades e o tamanho delas; para uma imagem, seu tamanho; para uma paleta, suas cores
pxr gbuffer MODEL -o DIR	os alvos de renderização crus, para relatórios de bug; o dump .pxrg leva as arestas da malha quando o visual as desenha
pxr stylize DUMP.pxrg	executar as passadas de pixel numa renderização salva, wireframe incluído
pxr diff OLD NEW	duas pastas de exportação (ou duas folhas): quais arquivos são novos, sumiram ou diferem, em quantos pixels e, a partir da receita de cada arquivo, qual ajuste ou entrada causou isso; --all lista também os arquivos idênticos, --exact sai com 1 em qualquer mudança. Dois dumps .pxrg são comparados alvo por alvo (--depth-tolerance EPS, --samples N)
pxr adapters	as GPUs que o Pixor pode usar
pxr doctor	com o que esta máquina consegue renderizar, e se a GPU dela concorda com a referência de CPU
pxr project new|set|show PROJECT.pixor	criar, alterar ou imprimir um projeto a partir de scripts e ferramentas: --name NAME o nomeia (o nome do cabeçalho, não o do arquivo; show o imprime com o resto)
pxr project key PROJECT.pixor TARGET CHANNEL	uma chave de um clipe feito no Pixor (--clip, --frame, --value, --how, --remove…), para que um script possa montar um clipe
pxr project bake PROJECT.pixor CLIP	um clipe do próprio modelo como um clipe feito no Pixor, com todos os ossos com chave em todos os quadros (--as NAME, --fps F)
pxr project scene PROJECT.pixor [NODE]	o grafo de cena um nó por vez: ring, row, grid, scatter, look-at, vary… adicionados ao fim da cadeia, com as opções de cada nó nomeadas pelos seus ajustes (--count, --radius, o --size de Variar, o --box de um Espalhar, o --bumps de Deslocar e o --hills de Campo de altura em metros, o --times de Subdividir, o --how de Selecionar); um nó que não recebe nada (object, import) inicia a cadeia no lugar da importação pura, e vai ao lado de uma cadeia mais longa, mesclado com ela; sem nó, ele a imprime
pxr project blueprint PROJECT.pixor -o B.pixorblueprint	o projeto como modelo de projeto, com os arquivos de modelo, paleta, objeto de cena e volume extraídos para slots nomeados
pxr style new KIT --from PROJECT	salvar o primeiro Estilo de um projeto como kit de Estilo
pxr kit show FILE.pixorkit	o que um kit guarda: um grupo de nós, um Estilo, uma predefinição ou um pipeline
pxr names PROJECT.pixor [--names T] [--pipeline NAME|all]	os nomes que o projeto vai gravar e o id de cada quadro, sem renderizar, os arquivos de cada renderização pelo seu caminho; dois quadros com um nome, duas renderizações num arquivo (would be written twice) ou dois arquivos num caminho (a base de um paper doll e a do kit de luz, uma variante de paleta e uma camada) são um erro aqui, em vez de um arquivo perdido depois
pxr graph list|set|add|drop|wire|save|swap|flatten|extra FILE --which scene|action|style|asset	qualquer um dos quatro grafos a partir de um script. --pipeline NAME escolhe qual: uma ação pelo nome, um Estilo ou um pipeline de asset, o primeiro se não for nomeado. Imprima-o, mude um ajuste, adicione um nó na cadeia (ou ao lado dela com --alone, conectando outros com --in SLOT=NODE), remova um, ligue dois com wire --from N --to M --slot S, salve-o como kit (save -o KIT.pixorkit: o grafo de Estilo inteiro, o grafo de cena, de ação ou de asset como um nó, --as-pipeline um pipeline de asset inteiro que outro projeto usa com pxr project set --use-pipeline), insira um kit de nós como grupo (add --kit KIT) ou no lugar de um nó (swap --kit KIT), ou grave um grafo com os grupos expandidos; extra --node N --name LAYER faz da imagem de um nó de Estilo também uma camada das exportações, e --drop desfaz isso. --node (e --set NODE.SETTING em pxr run) nomeia um nó pelo número, pelo tipo, pelo nome de um grupo, pelo que diz seu Chamado (um Arquivo de imagem, uma Folha) ou pelo nome que ele recebeu no app (F2); um nó object é o modelo (of=model), e um item, uma forma ou uma imagem é um nó próprio. Os nós sprites, frame-range e hold de um grafo de asset se ajustam como qualquer outro (--node sprites --set action=walk,Static — action=every-one-except-static é o de um nó novo, action= todas as ações, Estático incluído — --set smart=6, --node frame-range --set from=2 --set to=5, --node hold --set times=2); os de uma ação — clip, bob, spin, merge… — pelo tipo ou número, e um adicionado sem --alone toca imediatamente, mesclado com o que já está lá. No grafo de Estilo, um nó entra sem conexão; --in SLOT=NODE e wire o ligam. Uma edição que deixaria um grafo incapaz de rodar é recusada, e o arquivo fica como estava (veja o grafo de cena, o grafo de asset e nós)
pxr shapes [PROJECT] -o OUT.glb	exportar as formas construídas no app como geometria, para um modelador ou uma engine
pxr icons MODELS... -o DIR	ícones de inventário com um atlas por tamanho; raridade a partir do nome de cada arquivo, e --save guarda uma receita para executar de novo (veja Exportar)
pxr audit FILE|FOLDER... [--style KIT]	verificar se as folhas exportadas combinam: predefinição, conjunto de luzes, vista, inclinação, luz, faixas, traços, paleta e pixels por metro, a partir da receita de cada arquivo, e com um kit de Estilo, se cada cor está na paleta dele (saída 1 se não)
pxr watch PROJECT.pixor	exportar de novo sempre que o projeto, seu modelo ou sua paleta mudarem
pxr effect KIND[:FRAMES]	um efeito de pixel sozinho: explosion, hit-spark, slash, magic-burst, heal, portal, smoke-puff, dust, fire-loop, rain, snow, fireflies, falling-leaves
pxr console list|check SHEET.png	os modos de console, ou se uma folha cabe num deles (saída 1 se não); o console vem de --console ou da receita da folha

Opções de renderização

Opção	Padrão
--view VIEW	da predefinição	lado, três quartos, isométrico ou visão de cima
--pitch DEG	a da vista	graus abaixo do horizonte
--yaw DEG	0	girar um único sprite, ou o único lado de uma folha de um
--camera GENRE		a câmera de um gênero: platformer, fighting, beat-em-up, adventure, top-down-rpg, action-adventure, isometric, tactics, strategy, racing, top-down-shooter, shmup, icon (vista, inclinação, giro; tamanho e lados, a menos que informados)
--camera-yaw DEG	0	girar a câmera ao redor do modelo, todos os lados
--size N	64	caber em N x N, de 4 a 2048; --size 960x540 cabe numa tela com essa largura e altura (uma imagem de título, um fundo)
--pixels-per-metre F		pixels por metro fixos em vez de --size, de 0.5 a 4096 (o Pixels/m do app)
--up AXIS	decidido na importação	o eixo que aponta para cima no arquivo (y, z, -z, x, -x, -y): para um modelo exportado deitado
--import-scale F, --import-offset X,Y,Z	decidido na importação	a unidade e o movimento, informados à mão
--no-import-fix		renderizar o arquivo exatamente como está, sem corrigir nada
--samples N	4	amostras por pixel ao longo de cada lado, de 1 a 8 (o Amostras do app)
--light AZ,EL	-45,45	luz principal relativa à câmera
--light-space S	câmera	mundo: a luz fica parada na cena em vez de seguir a câmera
--fill F	da predefinição	força da luz de preenchimento, 0 a 1
--no-shadow		sem sombras projetadas
--bands N	da predefinição	faixas de luz, de 1 a 4
--palette P		um arquivo .hex, .gpl ou .png, ou uma paleta incluída: pixor-16, pixor-8, dusk-12, forest-12, desert-12, ice-10, mono-8
--aa N	0	anti-aliasing: 0 desligado, 1 silhueta, 2 todos os traços
--match-space S	oklab	como as cores encontram a mais próxima numa paleta fixa: oklab, srgb ou weighted
--dither-pattern P	bayer	bayer (a trama cruzada) ou blue-noise (espalhado por igual); qualquer um fica na superfície enquanto o modelo se move
--even-stairs	desligado	bordas de silhueta retas com degraus uniformes (2, 2, 2 em vez de 3, 1, 2)
--smear PX	0	quadros de rastro, de 0 a 64: o que se moveu PX pixels ou mais desde o quadro anterior deixa um rastro
--nudge X,Y	0,0	mover o modelo uma fração de pixel na grade (cada um de -0.5 a 0.5); só a amostragem muda
--foot-plant	desligado	os pés apoiados de um humanoide na mesma linha de pixels em todos os quadros de um clipe
--preset NAME	limpo	clean, selout, retro4, flat, wireframe, ou um kit de predefinição salvo (.pixorkit)
--style KIT		um kit de Estilo (.pixorkit): um Estilo inteiro (pxr style new, Salvar kit… de um Estilo), incluindo o grafo de Estilo, ou só um grafo de Estilo (pxr graph save --which style); flags posteriores ainda o alteram. Num arquivo de caso golden, relativo a ele. pxr icons e pxr audit aceitam o mesmo
--dither F	0	pontilhado ordenado entre faixas de luz vizinhas, de 0 a 1
--line-colour HEX	da predefinição	cor dos traços Escuro, #rrggbb (só paletas automáticas)
--no-lines MATERIAL		sem traços ao redor deste material (repetível; pxr inspect os lista)
--crease-angle DEG	55	a partir de que nitidez uma dobra desenha um traço de vinco, de 1 a 179
--depth-step PX	2.5	o degrau de profundidade, em pixels, que desenha um traço interno, de 0.1 a 40 (o Degrau de profundidade do app)
--shortest-line N	3	o traço interno ou de vinco mais curto mantido, de 0 a 16 pixels (o Traço mais curto do app)
--no-part-lines		sem traços entre partes que se tocam sem degrau de profundidade
--outline-inside		a silhueta na própria borda do sprite
--convex LINE	nenhum	uma linha clara nas dobras que se projetam em direção à câmera: none, dark ou highlightN
--no-material-channels		ignorar metal, rugosidade, emissão, unlit e transparência de um material glTF, e sombrear só pela cor
--backend B	auto	auto, vulkan, metal, dx12, gl, webgpu ou cpu (veja Escolhendo um renderizador)

Opções de luz e cor

Opção
--rig NAME	um conjunto de luzes: noon, dusk, torchlight, moonlight ou studio
--cycle MATERIAL	ciclar as cores deste material numa ação --colour-cycle (repetível)
--team MATERIAL|#RRGGBB	a cor do time: um material, ou cada rampa do matiz dessa cor (repetível); --variant team:blue recolore só ela
--console C	um modo de console: gameboy, nes, pico8, tic80, c64 (veja Modos do console)

Opções de animação

Opção
--clip NAME	um clipe a renderizar (repita para mais), ou all
--anim FILE	usar também os clipes de FILE
--ring N	lados, no sentido anti-horário a partir da frente (de 1 a 64, padrão 1), chamados South, Southeast, East…: uma câmera cada, compartilhando um tamanho, numa folha
--sides A1,A2,...	um lado em cada ângulo, em graus (0 = frente, 90 = virado para a direita)
--fps F	quadros por segundo do tempo do clipe (padrão 12), o corte de cada nó Sprites
--keys T1,T2,...	tempos do clipe escolhidos à mão, em segundos, o corte de cada nó Sprites
--clip lib:NAME	um clipe da biblioteca de movimentos ajustado ao esqueleto do modelo: idle, walk, run, jump, attack, hit, death
--parallax N	dividir a imagem por profundidade em N camadas (2–8) para fundos com rolagem (veja Cenas com vários modelos)
--haze #RRGGBB	a cor para a qual as camadas de paralaxe distantes esmaecem; none mantém cada camada na paleta como está
--spring NODE[:S,D,G]	NODE e o que está abaixo dele balançam com o movimento: rigidez, amortecimento, gravidade (repetível); num projeto, um nó Mola do grafo de Cena
--smart-frames N	manter N quadros de cada clipe, escolhidos a partir das suas poses (cada um retido até o próximo), o corte de cada nó Sprites
--root-motion M	keep (padrão), in-place (prende o osso raiz na horizontal) ou in-place-sway (remove só o deslocamento líquido do clipe)
--turntable N	adicionar uma ação de N quadros que gira o modelo uma vez
--turntable-seconds S	quanto tempo leva esse giro (padrão: N quadros a --fps)
--motion M[:N[:A]]	adicionar um loop: spin, bob, swing, pulse, squash ou flicker, N quadros, força A (para spin, a fração de volta que o loop dá: spin:8:0.125 gira uma gema de oito facetas em uma faceta, um loop sem emendas)
--colour-cycle N	adicionar uma ação de N quadros que gira os tons dos materiais em ciclo
--prop FILE:BONE[@at=X,Y,Z][@turn=X,Y,Z][@scale=S][@grip=NODE]	prender outro modelo a um osso, segurado pela empunhadura, movido e girado nos eixos do osso (veja Objetos de cena em ossos)
--shape SPEC	adicionar uma forma: [NAME=]KIND[:SIZE[:AT[:#RRGGBB[:TURN]]]], por exemplo box:1,0.5,1:0,0.25,0:#c86432, ou wheel=cylinder:0.5,0.2,0.5:0.7,0.25,0.5:#14101c:90,0,0 para uma roda nomeada deitada de lado (repetível). KIND é box, sphere, cylinder, cone, torus, plane, capsule, wedge, pyramid, prism, stairs, arch ou letters (pxr help render as lista a partir da mesma lista que a flag lê): letters são os pixels da fonte extrudados em blocos, soletrando PIXOR, ou as palavras de um projeto, pxr project set --add-shape letters --words WORDS --font NAME (render não aceita --words)
--volume SPEC	adicionar um volume: puff, flame, cloud, mist ou um caminho .vdb, depois [:SIZE[:AT]], depois [:FRAMES[,EVERY[,LOOP]]] para uma sequência .vdb numerada, depois @BONE para ser levado por um osso ou @effect:N pelo emissor do N-ésimo efeito (Volumes)
--wire LINE	o visual wireframe: none, dark ou seloutN, com --wire-fill, --wire-hidden, --wire-angle (de 0 a 180), --wire-all-edges e --wire-glow MATERIAL (ajustes)
--light-sweep N	adicionar uma ação de N quadros que move a luz
--effect KIND[:N]	adicionar uma ação de efeito de pixel de N quadros (veja pxr effect), com --effect-size, --effect-energy, --effect-seed, --effect-at X,Y,Z, --effect-bone BONE, --effect-clip CLIP, --effect-hit FRAME e --effect-alone
--hitbox PART, --hurtbox PART, --socket BONE	caixas e posições de ossos por quadro no JSON (repetível; veja Exportar)
--paper-doll, --piece NAME:PARTS	camadas de paper doll (veja Exportar)
--item MODEL@X,Z[,YAW,SCALE[,LAYER]][:CLIP[,PHASE]], --ground W,D[,#RRGGBB]	mais modelos ao lado do primeiro, cada um um nó Item do grafo de cena num projeto, com um plano de chão embaixo (veja Exportar)
--chunks COLSxROWS	gravar um mapa grande em blocos com emendas exatas; --chunk-margin N (padrão 8)
--max-flicker F	avisar acima desta proporção de cintilação (por exemplo 0.01); num caso golden, falhar
--require-visible OBJECT	avisar se OBJECT desaparecer em algum quadro

Opções de exportação

Opção
--export LIST	separados por vírgula ou repetidos: png, json, aseprite, normal, depth, emission, layers, palette, godot, gif, apng, light-kit, p8, report, video, ou all (todos menos p8 e video, que só são gravados quando nomeados); o PNG é sempre gravado (veja Exportação). render, batch, run, watch, project set e tiles (com seus próprios formatos) o leem do mesmo jeito
--layout L	grade (uma linha por ação e lado, o padrão) ou tira
--padding N	pixels transparentes entre células, de 0 a 256 (padrão 0)
--extrude N	repetir as bordas das células N pixels para fora, de 0 a 64 (padrão 0)
--pot	tamanho de folha em potência de dois
--godot-path RES	onde o Godot encontra a folha (padrão res://<png name>)
--anim-scale K	escala inteira dos arquivos GIF e APNG, de 1 a 16 (padrão 1)
--video-scale K, --video-fps N, --video-background #RRGGBB	como os vídeos são gravados: escala de 1 a 16 (padrão 4), de 1 a 100 quadros por segundo (padrão 30), sobre o que o sprite é desenhado (padrão preto)
--trim	recortar cada célula até seus pixels (o JSON e o arquivo do Godot mantêm o posicionamento)
--dedupe	guardar quadros idênticos uma só vez
--max-width N	começar uma nova linha antes que a folha fique mais larga que N pixels (de 0 a 65536; 0: sem limite)
--columns N	N quadros por linha, cada clipe continuando depois do anterior: uma folha de contatos
--max-height N	dividir uma folha mais alta que N pixels em páginas, com clipes inteiros por página (NAME_1.png, NAME_2.png; de 0 a 65536)
--variant NAME	exportar também uma variante de paleta (repetível): um efeito como hit-flash ou night, hue:DEG, team:COLOUR (um nome ou #rrggbb; exige --team) ou palette:NAME|FILE; adiciona uma folha de índices e uma textura de consulta
--shadow KIND	gravar também name_shadow.png: contact ou drop
--names TEMPLATE	como os arquivos e as chaves do JSON são nomeados: um padrão sobre {project}, {object}, {action}, {side}, {layer}, {set}, {size}, {index} e {ext}, com {index:3} preenchido até três dígitos (veja Exportação)
--no-recipe	não guardar a receita (como a folha foi feita) no PNG e no .aseprite
--scale K	ampliar o PNG K vezes (só prévias; não com outros formatos)
--save-project FILE.pixor	gravar também esta linha de comando como projeto
--debug DIR	alvos de renderização, paleta, imagens de lint e de cintilação

Testes golden para o seu próprio pipeline

Um arquivo de casos lista uma renderização por linha: um nome, um caminho de modelo ou projeto (relativo ao arquivo) e opções.

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

pxr golden cases.txt --bless guarda os resultados como NAME.png ao lado do arquivo; depois, pxr golden cases.txt falha quando qualquer pixel muda, quando um sprite tem achados de lint (pixels soltos, cantos de traço em L, traços de 2 px) ou quando uma verificação --max-flicker ou --require-visible falha; o erro diz quais casos têm pixels diferentes (os NAME.actual.png e NAME.diff.png deles ficam em target/golden) e quais falharam nas verificações. --bless guarda as imagens mesmo quando uma verificação falha, e sai com 1 nomeando esses casos. Use-o para perceber quando uma mudança no modelo altera os seus sprites.

Uma biblioteca, não uma execução

Um estúdio renderiza de novo os mesmos cinco mil sprites porque uma rampa mudou. Três coisas fazem disso uma decisão, e não um trabalho de uma noite inteira.

Um cache que sobrevive ao processo. --cache DIR no pxr batch e no pxr run guarda cada renderização que faz, com os arquivos que leu e um hash do que havia neles: o modelo, os arquivos de clipe ao lado dele, as texturas para as quais um .gltf aponta, paletas, kits, imagens e volumes. A próxima execução serve toda renderização cujos arquivos ainda têm o mesmo hash, e renderiza o resto.

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

O cache nunca é a fonte da verdade: --no-cache gera os mesmos bytes, um arquivo guardado cujo hash não corresponde ao nome é renderizado de novo em vez de servido, e um novo build do Pixor começa um cache novo em vez de confiar no antigo.

Um arquivo de tarefas. Uma tabela com uma linha por renderização, uma coluna por slot do modelo de projeto e, opcionalmente, colunas name (a pasta da linha), out (sua folha dentro de --out) e NODE.SETTING (um --set para aquela linha):

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

Aqui sheet.pixorblueprint vem de pxr project blueprint sheet.pixor, um projeto de heroes/knight.glb com uma paleta, então seus espaços são model e palette; o cavaleiro é cortado a 8 quadros por segundo e o mago, com a célula vazia, na taxa do próprio modelo de projeto. Cada linha grava 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

Os caminhos são relativos à tabela. Uma linha é exatamente pxr run com o --in e o --set da linha acrescentados, então uma linha que dá errado pode ser executada sozinha. Uma linha com falha nunca para as outras: o relatório lista cada linha dizendo se foi renderizada, servida do cache ou falhou e por quê, e a tarefa termina com 1 no fim se alguma falhou.

Orçamentos como flags. --max-pixels N, --max-memory SIZE e --max-time DURATION valem por renderização (por linha, por modelo). O que o plano já sabe — quantos pixels uma folha vai ter, mais ou menos quanta memória vai ocupar — é verificado antes de qualquer coisa ser desenhada; tempo e memória são verificados entre os quadros. Ultrapassar um deles sai com 6, dizendo qual foi e onde parou; numa tarefa, a linha falha com esse motivo e as outras continuam.

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

Clipes longos. Os quadros de um clipe são desenhados e depois finalizados juntos, já que as passadas que evitam a cintilação de um clipe olham ao longo dele. O que elas leem é mantido dentro de 512 MiB (metade de --max-memory, quando informado), alguns lados por vez; um clipe longo demais até para um só lado fica no disco enquanto é desenhado — em ~/.cache/pixor/spill, ou PXR_SPILL_DIR — e é lido de volta conforme necessário: os mesmos pixels, mais devagar, e a pasta some quando a renderização termina.

Códigos de saída

Código
0	sucesso
1	uma renderização, exportação, modelo de lote, linha de job ou caso golden que falhou
2	um erro de uso: a mensagem, o uso do comando e see pxr help COMMAND no stderr
3	uma entrada que não pôde ser lida: um modelo, projeto, paleta, kit, arquivo de caso ou dump
4	um backend pedido pelo nome que não existe
5	uma saída que não pôde ser gravada: um arquivo ou uma pasta
6	acima de um orçamento de --max-pixels, --max-memory ou --max-time
7	uma nova renderização que manteve pintura sobre a qual não decide sozinha (--resolve keep|pixor)

Não ter GPU nenhuma não é um erro: o Pixor desenha com seu próprio rasterizador. Um erro diz o que estava errado do mesmo jeito em todo lugar: --flag takes A to B, got X.

Escolhendo um renderizador

--backend auto|vulkan|metal|dx12|gl|webgpu|cpu diz quem desenha a geometria. O visual — cada passada de pixel — é calculado na CPU, seja qual for o valor.

• auto (o padrão) usa o que a máquina tiver, e recorre à CPU quando nenhum adaptador funciona.
• cpu é o rasterizador próprio do Pixor. Não precisa de adaptador nem de driver, está no binário e desenha os mesmos pixels em todas as máquinas — a escolha portátil para um pacote de assets ou um build de CI.
• Um backend indicado e ausente é um erro (saída 4), porque renderizar em outro lugar sem avisar é pior que dizer.

A receita de cada exportação registra qual backend a desenhou. pxr doctor mostra os adaptadores encontrados, o que o Pixor escolheria, as versões dos drivers e se esse backend desenha a mesma imagem que a referência de 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

No app, a mesma escolha é Preferências › Renderizador › Desenhar sprites na CPU, ou, para uma sessão, pixor --backend B com os mesmos nomes do pxr (cpu, auto ou um backend de GPU pelo nome), que deixa a preferência como está. Cada um guarda o que desenhou: trocar para o outro renderiza os quadros de novo, e voltar traz de volta os quadros do primeiro sem renderizar, desde que nada na cena tenha mudado.

Para ferramentas e scripts

Acrescente --json a qualquer comando: a saída padrão passa a trazer um evento JSON por linha (progress, wrote, warning, error, done) e o log legível vai para a saída de erro padrão. Os comandos que leem em vez de gravar também dão o que imprimem como um evento: inspect, adapters, tiles --list (terrains), graph list e graph flatten, e diff de dois dumps.