Línea de comandos

pxr renderiza los mismos sprites que la aplicación (el mismo proyecto da los mismos píxeles) y es ideal para scripts de build y trabajo por lotes. pxr help imprime todos los comandos y opciones, pxr help COMMAND un comando con sus opciones, y pxr --version la versión. Ante una línea de comandos que no puede leer, indica qué está mal, cómo se usa ese comando y que consultes pxr help COMMAND.

Tareas habituales

# 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

Un proyecto es su propia receta: al renderizarlo se leen de él el aspecto y la escena, y de la línea de comandos solo se toma adónde van los archivos (-o, --export, --names, --scale, --anim-scale, --no-recipe, --debug), las capas adicionales (--paper-doll, --piece, --parallax, --haze), el backend y qué pipeline de Asset escribe. Cualquier otra opción se nombra en un aviso, ya que no cambiaría nada: fíjala en el proyecto con pxr project set.

Qué pipeline de Asset. pxr render project.pixor escribe el primer pipeline de Asset del proyecto, igual que la ventana de exportación de la aplicación escribe el elegido en ella, que empieza siendo el de la cabecera; --pipeline NAME escribe otro, y --pipeline all, todos. Un archivo se llama igual se escriba el que se escriba, así que --pipeline all escribe exactamente los archivos que escriben los pipelines uno por uno. pxr names, pxr watch y pxr run también aceptan --pipeline.

Adónde van los archivos. -o PATH (o --out PATH; todos los comandos aceptan ambos) es donde escribe un comando. Para un comando que escribe un solo archivo —render, stylize, effect, voxels, tiles, shapes, rebake, project blueprint, project set (la hoja del proyecto)—, es ese archivo, o una carpeta en la que el archivo entra con su propio nombre cuando la ruta termina en / o es una carpeta que existe: pxr render knight.glb -o out/ escribe out/knight.png. Un proyecto renderizado con -o escribe todos los archivos en esa carpeta (D51): la carpeta de hojas del proyecto (out/ por defecto) pasa a ser ella, una ruta dentro de ella conserva su lugar debajo, y cualquier otra ruta, su última parte, incluidos archivos comprimidos, animaciones e iconos. La ventana de exportación de la aplicación ejecuta exactamente pxr render PROJECT --pipeline NAME -o FOLDER, sobre una copia del proyecto tal como está abierto, guardado o no, con el nombre del proyecto; --recipe-project FILE.pixor (o none para un proyecto sin título) es lo que nombra la receta de la copia en lugar de la copia. Los comandos que escriben muchos archivos —batch, golden, gbuffer, stages, icons, run --jobs— reciben una carpeta.

Los archivos de clip junto a un modelo con el nombre <model>@<clip>.<ext> se añaden automáticamente. Otros archivos con el mismo esqueleto se pueden añadir con --anim FILE.

Comandos

Comando	Hace
pxr render MODEL | PROJECT.pixor	un sprite, o una hoja cuando se piden clips, lados o acciones; un proyecto escribe una hoja por cada grupo de cámaras encuadradas juntas
pxr stages MODEL -o DIR	una imagen de cada etapa del pipeline (albedo, normales, profundidad, cobertura, luz, bandas, aristas, líneas, limpieza, lint…), --only edges,lines para algunas; --node N escribe en su lugar lo que hace el nodo N del grafo de Estilo como KIND.still.png (la pantalla de un CRT): una imagen fija, nunca un sprite ni una hoja
pxr batch FOLDER -o DIR	todos los modelos de una carpeta (.gltf, .glb, .fbx, .obj, .vox; --recursive para las subcarpetas); los modelos que fallan se informan y se omiten; DIR/report.json; --blueprint B.pixorblueprint pasa cada modelo por una plantilla de proyecto; --cache DIR sirve los modelos que no han cambiado (consulta bibliotecas). En la app, suelta la carpeta en la ventana
pxr run BLUEPRINT.pixorblueprint --in model=M	una plantilla de proyecto con sus entradas rellenadas (consulta el grafo de Escena); --set NODE.SETTING=VALUE cambia un ajuste, --set PIPELINE/NODE.SETTING=VALUE lo mismo solo en un pipeline (--set hold.times=4 el nodo Mantener de cada pipeline de asset); --jobs TABLE.csv -o DIR ejecuta una fila de una tabla por render; --pipeline NAME|all como en render
pxr rebake SHEET.aseprite	renderiza de nuevo el proyecto en una hoja sobre la que pintaste, conservando tus capas y tus ediciones (consulta Aseprite)
pxr cache stat|gc DIR	lo que contiene una caché; gc --keep 20GiB elimina los renders usados hace más tiempo hasta que quepa
pxr golden CASES.txt	renderiza casos de prueba y los compara con imágenes guardadas (ver más abajo); --only TEXT ejecuta los casos cuyo nombre lo contiene, --tolerance F acepta una fracción F de píxeles distintos, -o DIR (por defecto target/golden) es donde van los resultados; --graph los renderiza en su lugar a través del grafo de nodos del aspecto (el del preset como el grupo Pixelar incluido) y --flat a través del mismo grafo con todos los grupos aplanados en átomos; ambos deben coincidir con las mismas imágenes. --cache DIR escribe el sprite de cada caso en --out a través de la caché y compara ese archivo, servido o renderizado; --no-cache escribe los mismos archivos sin ella
pxr bench MODEL	mide cada presupuesto de tests/budgets.txt y dice met o MISSED; --rounds N (por defecto 10) promedia los tiempos sobre N ejecuciones; --from INFO.json añade los que mide la app
pxr import MODEL --report	lo que le pasa al archivo al importarlo, sin renderizarlo: lo encontrado, lo corregido y por qué, lo sugerido, lo que falta, triángulos por píxel de sprite; --json para un lote que encuentre primero los archivos rotos
pxr reference SPRITE.png	ajustes leídos de un sprite que ya tienes: paleta, tamaño, contorno, bandas, desplazamiento de tono, tramado, cada uno con su porqué; pxr project set P --match-sprite S.png los aplica
pxr voxels MODEL -o OUT.vox	el modelo como vóxeles, de --height de alto (de 1 a 256), con la paleta del aspecto: un archivo de MagicaVoxel; --stack también escribe un sprite stack (consulta Vóxeles y sprite stacks)
pxr nodes [--graph G] [--json]	cada nodo de los cuatro grafos (estilo, acción, escena, asset) tal como los tiene este Pixor: qué hace, qué recibe y qué da, cada ajuste con su rango y su valor por defecto; --json para herramientas (la referencia de nodos del sitio web se genera a partir de ello)
pxr inspect FILE	lo que encontró el importador en cualquier archivo que importa Pixor (los formatos, también en pxr help inspect): en un modelo, objetos, materiales, huesos, clips, avisos; en un .vdb, sus rejillas y su tamaño; en una imagen, su tamaño; en una paleta, sus colores
pxr gbuffer MODEL -o DIR	los destinos de render en bruto, para informes de errores; el volcado .pxrg lleva las aristas de la malla cuando el aspecto las dibuja
pxr stylize DUMP.pxrg	ejecuta las pasadas de píxeles sobre un render guardado, alámbrico incluido
pxr diff OLD NEW	dos carpetas de exportación (o dos hojas): qué archivos son nuevos, han desaparecido o difieren, en cuántos píxeles y, a partir de la receta de cada archivo, qué ajuste o entrada lo causó; --all lista también los archivos idénticos, --exact sale con 1 ante cualquier cambio. Dos volcados .pxrg se comparan destino a destino (--depth-tolerance EPS, --samples N)
pxr adapters	las GPU que puede usar Pixor
pxr doctor	con qué puede renderizar este equipo, y si su GPU coincide con la referencia de la CPU
pxr project new|set|show PROJECT.pixor	crea, cambia o imprime un proyecto desde scripts y herramientas: --name NAME le pone nombre (el nombre de la cabecera, no el del archivo; show lo imprime con lo demás)
pxr project key PROJECT.pixor TARGET CHANNEL	una clave de un clip hecho en Pixor (--clip, --frame, --value, --how, --remove…), para que un script pueda construir un clip
pxr project bake PROJECT.pixor CLIP	un clip propio del modelo como un clip hecho en Pixor, con cada hueso con clave en cada fotograma (--as NAME, --fps F)
pxr project scene PROJECT.pixor [NODE]	el grafo de Escena nodo a nodo: ring, row, grid, scatter, look-at, vary… añadidos al final de la cadena, con las opciones de cada nodo nombradas como sus ajustes (--count, --radius, --size de Variar, --box de un Dispersar, --bumps de Desplazar y --hills de Campo de alturas en metros, --times de Subdividir, --how de Seleccionar); un nodo que no recibe nada (object, import) empieza la cadena en lugar de la importación sola, y va junto a una cadena más larga, fusionado con ella; sin nodo, lo imprime
pxr project blueprint PROJECT.pixor -o B.pixorblueprint	el proyecto como plantilla de proyecto, con sus archivos de modelo, paleta, accesorios y volúmenes sacados a ranuras con nombre
pxr style new KIT --from PROJECT	guarda el primer Estilo de un proyecto como kit de Estilo
pxr kit show FILE.pixorkit	lo que contiene un kit: un grupo de nodos, un Estilo, un preset o un pipeline
pxr names PROJECT.pixor [--names T] [--pipeline NAME|all]	los nombres que escribirá el proyecto y el id de cada fotograma, sin renderizar, los archivos de cada render por su propia ruta; dos fotogramas con un mismo nombre, dos renders sobre un mismo archivo (would be written twice) o dos archivos en una misma ruta (la base de un paper doll y la del kit de luz, una variante de paleta y una capa) son aquí un error en lugar de un archivo perdido más tarde
pxr graph list|set|add|drop|wire|save|swap|flatten|extra FILE --which scene|action|style|asset	cualquiera de los cuatro grafos desde un script. --pipeline NAME elige cuál: una acción por su nombre, un Estilo o un pipeline de asset, el primero salvo que se nombre. Imprímelo, cambia un ajuste, añade un nodo a la cadena (o junto a ella con --alone, conectando otros con --in SLOT=NODE), quita uno, une dos con wire --from N --to M --slot S, guárdalo como kit (save -o KIT.pixorkit: el grafo de Estilo entero, el grafo de escena, de acción o de asset como un solo nodo, --as-pipeline un pipeline de asset entero que otro proyecto usa con pxr project set --use-pipeline), mete un kit de nodos como grupo (add --kit KIT) o en lugar de un nodo (swap --kit KIT), o escribe un grafo con sus grupos expandidos; extra --node N --name LAYER hace que la imagen de un nodo de Estilo sea también una capa de las exportaciones, y --drop lo detiene. --node (y --set NODE.SETTING en pxr run) nombra un nodo por su número, su tipo, el nombre de un grupo, lo que dice su Llamado (un Archivo de imagen, una Hoja) o el nombre que se le dio en la app (F2); un nodo object es el modelo (of=model), y un objeto, una forma o una imagen es un nodo propio. Los nodos sprites, frame-range y hold de un grafo de Asset se ajustan como cualquier otro (--node sprites --set action=walk,Static; action=every-one-except-static es el de un nodo nuevo, action= todas las acciones, Static incluida; --set smart=6, --node frame-range --set from=2 --set to=5, --node hold --set times=2); los de una acción (clip, bob, spin, merge…) por tipo o número, y uno añadido sin --alone se reproduce de inmediato, fusionado con lo que haya. En el grafo de Estilo un nodo entra sin conectar a nada; --in SLOT=NODE y wire lo conectan. Una edición que dejaría un grafo sin poder ejecutarse se rechaza y el archivo queda como estaba (consulta el grafo de Escena, el grafo de Asset y los nodos)
pxr shapes [PROJECT] -o OUT.glb	escribe las formas construidas en la app como geometría, para un programa de modelado o un motor
pxr icons MODELS... -o DIR	iconos de inventario con un atlas por tamaño; la rareza sale del nombre de cada archivo, y --save guarda una receta para volver a ejecutarla (consulta Exportar)
pxr audit FILE|FOLDER... [--style KIT]	comprueba que las hojas exportadas coinciden: preset, juego de luces, vista, inclinación, luz, bandas, líneas, paleta y píxeles por metro, a partir de la receta de cada archivo, y con un kit de Estilo que cada color esté en su paleta (sale con 1 si no)
pxr watch PROJECT.pixor	exporta de nuevo cada vez que cambien el proyecto, su modelo o su paleta
pxr effect KIND[:FRAMES]	un efecto de píxeles por sí solo: explosion, hit-spark, slash, magic-burst, heal, portal, smoke-puff, dust, fire-loop, rain, snow, fireflies, falling-leaves
pxr console list|check SHEET.png	los modos de consola, o si una hoja encaja en uno (sale con 1 si no); la consola viene de --console o de la receta de la hoja

Opciones de render

Opción	Predeterminado
--view VIEW	el del preset	lateral, tres cuartos, isométrica o cenital
--pitch DEG	el de la vista	grados bajo el horizonte
--yaw DEG	0	gira un solo sprite, o el único lado de una hoja de uno
--camera GENRE		la cámara de un juego: platformer, fighting, beat-em-up, adventure, top-down-rpg, action-adventure, isometric, tactics, strategy, racing, top-down-shooter, shmup, icon (vista, inclinación, giro; tamaño y lados salvo que se indiquen)
--camera-yaw DEG	0	girar la cámara alrededor del modelo, todos los lados
--size N	64	encajar en N x N, de 4 a 2048; --size 960x540 encaja en un lienzo de ese ancho y ese alto (una imagen de título, un fondo)
--pixels-per-metre F		píxeles por metro fijos en lugar de --size, de 0.5 a 4096 (Píxeles/m en la app)
--up AXIS	decidido al importar	el eje que apunta hacia arriba en el archivo (y, z, -z, x, -x, -y): para un modelo exportado tumbado
--import-scale F, --import-offset X,Y,Z	decidido al importar	la unidad y el movimiento, indicados a mano
--no-import-fix		renderiza el archivo exactamente como es, sin corregir nada
--samples N	4	muestras por píxel en cada lado, de 1 a 8 (Muestras en la app)
--light AZ,EL	-45,45	luz principal relativa a la cámara
--light-space S	cámara	mundo: la luz se queda fija en la escena en lugar de seguir a la cámara
--fill F	el del preset	intensidad de la luz de relleno, de 0 a 1
--no-shadow		sin sombras proyectadas
--bands N	el del preset	bandas de luz, de 1 a 4
--palette P		un archivo .hex, .gpl o .png, o una paleta integrada: pixor-16, pixor-8, dusk-12, forest-12, desert-12, ice-10, mono-8
--aa N	0	antialiasing: 0 desactivado, 1 silueta, 2 todas las líneas
--match-space S	oklab	cómo encuentran los colores su más cercano en una paleta fija: oklab, srgb o weighted
--dither-pattern P	bayer	bayer (el sombreado cruzado) o blue-noise (disperso de forma uniforme); ambos se quedan sobre la superficie mientras el modelo se mueve
--even-stairs	desactivado	bordes rectos de silueta con escalones regulares (2, 2, 2 en lugar de 3, 1, 2)
--smear PX	0	fotogramas de barrido, de 0 a 64: lo que se haya movido PX píxeles o más desde el fotograma anterior deja una estela
--nudge X,Y	0,0	mueve el modelo una fracción de píxel en la cuadrícula (cada uno de -0.5 a 0.5); solo cambia el muestreo
--foot-plant	desactivado	los pies apoyados de un humanoide en la misma fila de píxeles en cada fotograma de un clip
--preset NAME	limpio	clean, selout, retro4, flat, wireframe, o un kit de preset guardado (.pixorkit)
--style KIT		un kit de Estilo (.pixorkit): un Estilo entero (pxr style new, Guardar kit… de un Estilo), también su grafo de Estilo, o solo un grafo de Estilo (pxr graph save --which style); las opciones posteriores aún lo cambian. En un archivo de caso de referencia, relativo a él. pxr icons y pxr audit aceptan lo mismo
--dither F	0	tramado ordenado entre bandas de luz vecinas, de 0 a 1
--line-colour HEX	el del preset	color de las líneas Oscuro, #rrggbb (solo paletas automáticas)
--no-lines MATERIAL		sin líneas alrededor de este material (repetible; pxr inspect los lista)
--crease-angle DEG	55	lo marcado que debe ser un pliegue para dibujar una línea de pliegue, de 1 a 179
--depth-step PX	2.5	el salto de profundidad, en píxeles, que dibuja una línea interior, de 0.1 a 40 (Paso de profundidad en la app)
--shortest-line N	3	la línea interior o de pliegue más corta que se conserva, de 0 a 16 píxeles (Línea más corta en la app)
--no-part-lines		sin líneas entre partes en contacto sin salto de profundidad
--outline-inside		la silueta en el propio borde del sprite
--convex LINE	ninguno	una línea clara en los pliegues que sobresalen hacia la cámara: none, dark o highlightN
--no-material-channels		ignora el metal, la rugosidad, lo emisivo, lo no iluminado y la transparencia de un material glTF, y sombrea solo a partir de su color
--backend B	auto	auto, vulkan, metal, dx12, gl, webgpu o cpu (consulta Elegir un renderizador)

Opciones de luz y color

Opción
--rig NAME	un juego de luces: noon, dusk, torchlight, moonlight o studio
--cycle MATERIAL	cicla los colores de este material en una acción --colour-cycle (repetible)
--team MATERIAL|#RRGGBB	el color de equipo: un material, o cada rampa del tono de ese color (repetible); --variant team:blue recolorea solo eso
--console C	un modo de consola: gameboy, nes, pico8, tic80, c64 (consulta Modos de consola)

Opciones de animación

Opción
--clip NAME	un clip que renderizar (repítelo para más), o all
--anim FILE	usa también los clips de FILE
--ring N	lados, en sentido antihorario desde el frente (de 1 a 64, por defecto 1), llamados South, Southeast, East…: una cámara cada uno, con un mismo tamaño, en una sola hoja
--sides A1,A2,...	en su lugar, un lado en cada ángulo, en grados (0 = frente, 90 = mirando a la derecha)
--fps F	fotogramas por segundo del tiempo del clip (por defecto 12), el corte de cada nodo Sprites
--keys T1,T2,...	tiempos del clip elegidos a mano, en segundos, el corte de cada nodo Sprites
--clip lib:NAME	un clip de la biblioteca de movimientos adaptado al esqueleto del modelo: idle, walk, run, jump, attack, hit, death
--parallax N	divide la imagen por profundidad en N capas (2–8) para fondos con desplazamiento (consulta Escenas de varios modelos)
--haze #RRGGBB	el color hacia el que se desvanecen las capas de parallax lejanas; none deja cada capa en la paleta tal cual
--spring NODE[:S,D,G]	NODE y lo que hay debajo oscilan con el movimiento: rigidez, amortiguación, gravedad (repetible); en un proyecto, un nodo Muelle del grafo de Escena
--smart-frames N	conserva N fotogramas de cada clip, elegidos entre sus poses (mantenido cada uno hasta el siguiente), el corte de cada nodo Sprites
--root-motion M	keep (predeterminado), in-place (fija el hueso raíz en horizontal) o in-place-sway (quita solo el desplazamiento neto del clip)
--turntable N	añade una acción de N fotogramas que gira el modelo una vez
--turntable-seconds S	cuánto tarda ese giro (por defecto: N fotogramas a --fps)
--motion M[:N[:A]]	añade un bucle: spin, bob, swing, pulse, squash o flicker, N fotogramas, intensidad A (para spin, la parte de una vuelta que da el bucle: spin:8:0.125 gira una gema de ocho facetas una faceta, un bucle sin costuras)
--colour-cycle N	añade una acción de N fotogramas que rota los tonos de los materiales cíclicos
--prop FILE:BONE[@at=X,Y,Z][@turn=X,Y,Z][@scale=S][@grip=NODE]	acopla otro modelo a un hueso, sujeto por su empuñadura, movido y girado sobre los ejes del hueso (consulta Accesorios en huesos)
--shape SPEC	añade una forma: [NAME=]KIND[:SIZE[:AT[:#RRGGBB[:TURN]]]], p. ej. box:1,0.5,1:0,0.25,0:#c86432, o wheel=cylinder:0.5,0.2,0.5:0.7,0.25,0.5:#14101c:90,0,0 para una rueda con nombre tumbada de lado (repetible). KIND es box, sphere, cylinder, cone, torus, plane, capsule, wedge, pyramid, prism, stairs, arch o letters (pxr help render las lista a partir de la misma lista que lee la opción): letters son los píxeles de la fuente extruidos en bloques, que forman PIXOR o las palabras de un proyecto, pxr project set --add-shape letters --words WORDS --font NAME (render no acepta --words)
--volume SPEC	añade un volumen: puff, flame, cloud, mist o una ruta .vdb, luego [:SIZE[:AT]], luego [:FRAMES[,EVERY[,LOOP]]] para una secuencia .vdb numerada, y luego @BONE para que lo lleve un hueso o @effect:N para que lo lleve el emisor del enésimo efecto (Volúmenes)
--wire LINE	el aspecto alámbrico: none, dark o seloutN, con --wire-fill, --wire-hidden, --wire-angle (de 0 a 180), --wire-all-edges y --wire-glow MATERIAL (ajustes)
--light-sweep N	añade una acción de N fotogramas que mueve la luz
--effect KIND[:N]	añade una acción de efecto de píxeles de N fotogramas (consulta pxr effect), con --effect-size, --effect-energy, --effect-seed, --effect-at X,Y,Z, --effect-bone BONE, --effect-clip CLIP, --effect-hit FRAME y --effect-alone
--hitbox PART, --hurtbox PART, --socket BONE	cajas y posiciones de huesos por fotograma en el JSON (repetible; consulta Exportar)
--paper-doll, --piece NAME:PARTS	capas de paper doll (consulta Exportar)
--item MODEL@X,Z[,YAW,SCALE[,LAYER]][:CLIP[,PHASE]], --ground W,D[,#RRGGBB]	más modelos junto al primero, cada uno un nodo Objeto del grafo de Escena en un proyecto, y un plano de suelo debajo (consulta Exportar)
--chunks COLSxROWS	escribe un mapa grande en fragmentos con uniones exactas; --chunk-margin N (por defecto 8)
--max-flicker F	avisa por encima de esta proporción de parpadeo (p. ej., 0.01); en un caso de referencia, falla
--require-visible OBJECT	avisa si OBJECT desaparece en algún fotograma

Opciones de exportación

Opción
--export LIST	separados por comas o repetidos: png, json, aseprite, normal, depth, emission, layers, palette, godot, gif, apng, light-kit, p8, report, video, o all (todos salvo p8 y video, que solo se escriben cuando se nombran); el PNG siempre se escribe (consulta Exportar). render, batch, run, watch, project set y tiles (con sus propios formatos) lo leen igual
--layout L	cuadrícula (una fila por acción y lado, por defecto) o tira
--padding N	píxeles transparentes entre celdas, de 0 a 256 (por defecto 0)
--extrude N	repite los bordes de celda N píxeles hacia fuera, de 0 a 64 (por defecto 0)
--pot	tamaño de hoja en potencia de dos
--godot-path RES	dónde encuentra Godot la hoja (por defecto res://<png name>)
--anim-scale K	escala entera de los archivos GIF y APNG, de 1 a 16 (por defecto 1)
--video-scale K, --video-fps N, --video-background #RRGGBB	cómo se escriben los vídeos: escala de 1 a 16 (por defecto 4), de 1 a 100 fotogramas por segundo (por defecto 30), sobre qué se dibuja el sprite (por defecto, negro)
--trim	recorta cada celda hasta sus píxeles (el JSON y el archivo de Godot conservan la colocación)
--dedupe	guardar una sola vez los fotogramas idénticos
--max-width N	empieza una fila nueva antes de que la hoja supere los N píxeles de ancho (de 0 a 65536; 0: sin límite)
--columns N	N fotogramas por fila, cada clip a continuación del anterior: una hoja de contactos
--max-height N	divide una hoja más alta de N píxeles en páginas, con clips enteros por página (NAME_1.png, NAME_2.png; de 0 a 65536)
--variant NAME	exporta también una variante de paleta (repetible): un efecto como hit-flash o night, hue:DEG, team:COLOUR (un nombre o #rrggbb; necesita --team) o palette:NAME|FILE; añade una hoja de índices y una textura de consulta
--shadow KIND	escribe también name_shadow.png: contact o drop
--names TEMPLATE	cómo se nombran los archivos y las claves del JSON: un patrón con {project}, {object}, {action}, {side}, {layer}, {set}, {size}, {index} y {ext}, con {index:3} rellenado a tres dígitos (consulta Exportar)
--no-recipe	no guardar la receta (cómo se hizo la hoja) en el PNG y el .aseprite
--scale K	amplía el PNG K veces (solo vistas previas; no con otros formatos)
--save-project FILE.pixor	escribe también esta línea de comandos como proyecto
--debug DIR	destinos de render, paleta, lint e imágenes de parpadeo

Pruebas de referencia para tu propio pipeline

Un archivo de casos enumera un render por línea: un nombre, una ruta de modelo o de proyecto (relativa al archivo) y opciones.

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

pxr golden cases.txt --bless guarda los resultados como NAME.png junto al archivo; después, pxr golden cases.txt falla cuando cambia cualquier píxel, cuando un sprite tiene avisos del lint (píxeles sueltos, esquinas de línea en L, líneas de 2 px) o cuando falla una comprobación --max-flicker o --require-visible; el error indica qué casos tienen píxeles distintos (sus NAME.actual.png y NAME.diff.png están en target/golden) y cuáles no pasaron sus comprobaciones. --bless guarda las imágenes incluso cuando falla una comprobación, y sale con 1 nombrando esos casos. Úsalo para darte cuenta de cuándo un cambio en un modelo altera tus sprites.

Una biblioteca, no una ejecución

Un estudio vuelve a renderizar los mismos cinco mil sprites porque se movió una rampa. Tres cosas hacen que eso sea una decisión y no un trabajo de toda la noche.

Una caché que sobrevive al proceso. --cache DIR en pxr batch y pxr run guarda cada render que hace, con los archivos que leyó y un hash de su contenido: el modelo, los archivos de clips a su lado, las texturas a las que apunta un .gltf, paletas, kits, imágenes y volúmenes. La siguiente ejecución sirve cada render cuyos archivos siguen dando el mismo hash, y renderiza el 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

La caché nunca es la fuente de verdad: --no-cache da los mismos bytes, un archivo guardado cuyo hash no coincide con su nombre se renderiza de nuevo en lugar de servirse, y una nueva compilación de Pixor empieza una caché nueva en lugar de fiarse de la antigua.

Un archivo de trabajos. Una tabla con una fila por render, una columna por ranura de la plantilla de proyecto y, opcionalmente, columnas name (la carpeta de la fila), out (su hoja bajo --out) y NODE.SETTING (un --set para esa fila):

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

Aquí sheet.pixorblueprint sale de pxr project blueprint sheet.pixor, un proyecto de heroes/knight.glb con una paleta, así que sus huecos son model y palette; el caballero se corta a 8 fotogramas por segundo y el mago, con su celda vacía, al ritmo propio de la plantilla de proyecto. Cada fila escribe 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

Las rutas son relativas a la tabla. Una fila es exactamente pxr run con el --in y el --set de la fila añadidos, así que una fila que falla se puede ejecutar por separado. Una fila que falla nunca detiene a las demás: el informe lista cada fila indicando si se renderizó, se sirvió desde la caché o falló y por qué, y el trabajo sale con 1 al final si alguna falló.

Presupuestos como opciones. --max-pixels N, --max-memory SIZE y --max-time DURATION rigen por render (por fila, por modelo). Lo que el plan ya sabe (cuántos píxeles tendrá una hoja, cuánta memoria ocupará aproximadamente) se comprueba antes de dibujar nada; el tiempo y la memoria se comprueban entre fotogramas. Superar uno termina con 6 indicando cuál fue y dónde se detuvo; en un trabajo, la fila falla con ese motivo y las demás continúan.

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

Clips largos. Los fotogramas de un clip se dibujan y luego se terminan juntos, ya que las pasadas que evitan que un clip parpadee miran a lo largo de él. Lo que leen se mantiene dentro de 512 MiB (la mitad de --max-memory cuando se indica), unos pocos lados a la vez; un clip demasiado largo incluso para un solo lado se guarda en disco mientras se dibuja (en ~/.cache/pixor/spill, o PXR_SPILL_DIR) y se vuelve a leer según se necesita: los mismos píxeles, más despacio, y la carpeta desaparece cuando termina el render.

Códigos de salida

Código
0	éxito
1	un render, una exportación, un modelo de lote, una fila de trabajo o un caso de referencia que falló
2	un error de uso: el mensaje, el uso del comando y see pxr help COMMAND en stderr
3	una entrada que no se pudo leer: un modelo, proyecto, paleta, kit, archivo de caso o volcado
4	un backend pedido por nombre que no está disponible
5	una salida que no se pudo escribir: un archivo o una carpeta
6	por encima de un presupuesto de --max-pixels, --max-memory o --max-time
7	un re-bake que conservó pintura sobre la que no decidirá solo (--resolve keep|pixor)

No tener GPU no es un error: Pixor dibuja entonces con su propio rasterizador. Un error dice qué ha fallado de la misma forma en todas partes: --flag takes A to B, got X.

Elegir un renderizador

--backend auto|vulkan|metal|dx12|gl|webgpu|cpu indica quién dibuja la geometría. El aspecto —cada pasada de píxeles— se calcula en la CPU diga lo que diga esto.

• auto (el valor predeterminado) usa lo que tenga la máquina, y recurre a la CPU cuando ningún adaptador funciona.
• cpu es el rasterizador propio de Pixor. No necesita adaptador ni controlador, está dentro del binario y dibuja los mismos píxeles en cualquier máquina: la opción portátil para un pack de assets o una build de CI.
• Un backend nombrado que no está disponible es un error (código de salida 4), porque renderizar en otro sitio sin avisar es peor que decirlo.

La receta de cada exportación registra qué backend la dibujó. pxr doctor imprime los adaptadores encontrados, el que elegiría Pixor, las versiones de los controladores y si ese backend dibuja la misma imagen que la referencia 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

En la aplicación, la misma elección es Preferencias › Renderizador › Dibujar sprites en la CPU, o para una sola sesión pixor --backend B con los mismos nombres que pxr (cpu, auto, o un backend de GPU por su nombre), lo que deja la preferencia como está. Cada uno conserva lo que dibujó: cambiar al otro vuelve a renderizar los fotogramas, y volver al primero recupera sus fotogramas sin renderizar, siempre que nada de la escena haya cambiado.

Para herramientas y scripts

Añade --json a cualquier comando: la salida estándar llevará entonces un evento JSON por línea (progress, wrote, warning, error, done) y el registro legible pasa a la salida de error estándar. Los comandos que leen en lugar de escribir también dan lo que imprimen como un evento: inspect, adapters, tiles --list (terrains), graph list y graph flatten, y diff de dos volcados.