Riga di comando

pxr renderizza gli stessi sprite dell'app (lo stesso progetto dà gli stessi pixel) ed è adatto agli script di build e al lavoro in lotto. pxr help stampa ogni comando e opzione, pxr help COMMAND un comando con le sue opzioni, e pxr --version la versione. Una riga di comando che non riesce a leggere dice cosa c'è di sbagliato, come si usa quel comando, e di consultare pxr help COMMAND.

Operazioni comuni

# 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 progetto è la sua stessa ricetta: renderizzarlo legge da esso il look e la scena, e dalla riga di comando prende solo dove vanno i file (-o, --export, --names, --scale, --anim-scale, --no-recipe, --debug), i livelli aggiuntivi (--paper-doll, --piece, --parallax, --haze), il backend e quale pipeline di Asset scrive. Qualsiasi altro flag viene nominato in un avviso, perché non cambierebbe nulla: impostalo nel progetto con pxr project set.

Quale pipeline di Asset. pxr render project.pixor scrive la prima pipeline di Asset del progetto, come la finestra di esportazione dell'app scrive quella scelta al suo interno, che parte da quella dell'intestazione; --pipeline NAME ne scrive un'altra, e --pipeline all tutte. Un file ha lo stesso nome qualunque venga scritta, quindi --pipeline all scrive esattamente i file che le pipeline scrivono una per una. Anche pxr names, pxr watch e pxr run accettano --pipeline.

Dove vanno i file. -o PATH (o --out PATH; ogni comando accetta entrambi) è dove scrive un comando. Per un comando che scrive un solo file — render, stylize, effect, voxels, tiles, shapes, rebake, project blueprint, project set (lo sheet del progetto) — è quel file, o una cartella in cui il file va con il suo nome quando il percorso finisce con / o è una cartella esistente: pxr render knight.glb -o out/ scrive out/knight.png. Un progetto renderizzato con -o scrive ogni file in quella cartella (D51): la cartella degli sheet del progetto (out/ di default) diventa quella, un percorso sotto di essa mantiene la sua posizione sotto, e qualsiasi altro percorso la sua ultima parte — archivi, animazioni e icone compresi. La finestra di esportazione dell'app esegue esattamente pxr render PROJECT --pipeline NAME -o FOLDER, su una copia del progetto così com'è aperto, salvato o no, con il nome del progetto; --recipe-project FILE.pixor (o none per un progetto senza titolo) è ciò che la ricetta della copia indica al posto della copia. I comandi che scrivono molti file — batch, golden, gbuffer, stages, icons, run --jobs — accettano una cartella.

I file di clip accanto a un modello chiamati <model>@<clip>.<ext> vengono aggiunti automaticamente. Altri file con lo stesso scheletro si aggiungono con --anim FILE.

Comandi

Comando	Fa
pxr render MODEL | PROJECT.pixor	uno sprite, o uno sheet quando vengono richieste clip, lati o azioni; un progetto scrive uno sheet per ogni gruppo di camere inquadrate insieme
pxr stages MODEL -o DIR	un’immagine di ogni stadio della pipeline (albedo, normali, profondità, copertura, luce, bande, bordi, linee, pulizia, lint…), --only edges,lines per alcuni; --node N scrive invece ciò che crea il nodo N del grafo di Stile come KIND.still.png (lo schermo di un CRT): un’immagine fissa, mai uno sprite o uno sheet
pxr batch FOLDER -o DIR	ogni modello in una cartella (.gltf, .glb, .fbx, .obj, .vox; --recursive per le sottocartelle); i modelli che falliscono vengono segnalati e saltati; DIR/report.json; --blueprint B.pixorblueprint passa ogni modello attraverso uno schema; --cache DIR serve i modelli che non sono cambiati (vedi librerie). Nell’app, trascina la cartella sulla finestra
pxr run BLUEPRINT.pixorblueprint --in model=M	uno schema con i suoi ingressi compilati (vedi il grafo di Scena); --set NODE.SETTING=VALUE cambia un’impostazione, --set PIPELINE/NODE.SETTING=VALUE la stessa in una sola pipeline (--set hold.times=4 il nodo Tenuta di ogni pipeline di asset); --jobs TABLE.csv -o DIR esegue una riga di una tabella per render; --pipeline NAME|all come per render
pxr rebake SHEET.aseprite	renderizza di nuovo il progetto in uno sheet su cui hai dipinto, mantenendo i tuoi livelli e le tue modifiche (vedi Aseprite)
pxr cache stat|gc DIR	cosa contiene una cache; gc --keep 20GiB rimuove i render usati meno di recente finché non ci sta
pxr golden CASES.txt	renderizza casi di test e confrontali con immagini salvate (vedi sotto); --only TEXT esegue i casi il cui nome lo contiene, --tolerance F accetta una frazione F di pixel diversi, -o DIR (predefinito target/golden) è dove vanno i risultati; --graph li renderizza invece attraverso il grafo di nodi del look (quello del preset come gruppo Pixelizza fornito) e --flat attraverso lo stesso grafo con ogni gruppo appiattito in nodi base; entrambi devono corrispondere alle stesse immagini. --cache DIR scrive lo sprite di ogni caso in --out attraverso la cache e confronta quel file, servito o renderizzato; --no-cache scrive gli stessi file senza
pxr bench MODEL	misura ogni budget in tests/budgets.txt e indica met o MISSED; --rounds N (predefinito 10) fa la media dei tempi su N esecuzioni; --from INFO.json aggiunge quelli misurati dall’app
pxr import MODEL --report	cosa succede al file all’importazione, senza renderizzarlo: cosa è stato trovato, corretto e perché, suggerito, mancante, triangoli per pixel di sprite; --json per un batch che trova prima i file rotti
pxr reference SPRITE.png	impostazioni ricavate da uno sprite che hai: palette, dimensione, contorno, bande, spostamento di tinta, dithering, ognuna con il perché; pxr project set P --match-sprite S.png le imposta
pxr voxels MODEL -o OUT.vox	il modello in voxel, alto --height (da 1 a 256), nella palette del look: un file MagicaVoxel; --stack scrive anche uno sprite stack (vedi Voxel e sprite stack)
pxr nodes [--graph G] [--json]	ogni nodo dei quattro grafi (stile, azione, scena, asset) come li ha questo Pixor: cosa fa, cosa prende e dà, ogni impostazione con il suo intervallo e valore predefinito; --json per gli strumenti (il riferimento dei nodi del sito è costruito da qui)
pxr inspect FILE	ciò che l’importatore ha trovato in qualsiasi file importato da Pixor (i formati, anche in pxr help inspect): per un modello, oggetti, materiali, ossa, clip, avvisi; per un .vdb, le sue griglie e la loro dimensione; per un’immagine, la sua dimensione; per una palette, i suoi colori
pxr gbuffer MODEL -o DIR	i target di render grezzi, per le segnalazioni di bug; il dump .pxrg contiene gli spigoli della mesh quando il look li disegna
pxr stylize DUMP.pxrg	esegui i passaggi in pixel su un render salvato, wireframe compreso
pxr diff OLD NEW	due cartelle di esportazione (o due sheet): quali file sono nuovi, spariti o diversi, di quanti pixel, e, dalla ricetta di ogni file, quale impostazione o ingresso l’ha causato; --all elenca anche i file identici, --exact esce con 1 a ogni cambiamento. Due dump .pxrg vengono confrontati target per target (--depth-tolerance EPS, --samples N)
pxr adapters	le GPU che Pixor può usare
pxr doctor	con cosa può renderizzare questa macchina, e se la sua GPU concorda con il riferimento CPU
pxr project new|set|show PROJECT.pixor	crea, cambia o stampa un progetto da script e strumenti: --name NAME gli dà un nome (il nome nell’intestazione, non quello del file; show lo stampa insieme al resto)
pxr project key PROJECT.pixor TARGET CHANNEL	una chiave di una clip creata in Pixor (--clip, --frame, --value, --how, --remove…), così uno script può costruire una clip
pxr project bake PROJECT.pixor CLIP	una clip del modello come clip creata in Pixor, ogni osso con una chiave a ogni fotogramma (--as NAME, --fps F)
pxr project scene PROJECT.pixor [NODE]	il grafo di Scena un nodo alla volta: ring, row, grid, scatter, look-at, vary… aggiunti in fondo alla catena, con le opzioni di ogni nodo che prendono il nome dalle sue impostazioni (--count, --radius, --size di Vary, --box di uno Scatter, --bumps di Displace e --hills di Height field in metri, --times di Subdivide, --how di Select); un nodo che non prende ingressi (object, import) avvia la catena al posto della semplice importazione, e si affianca a una catena più lunga, unito a essa; nessun nodo la stampa
pxr project blueprint PROJECT.pixor -o B.pixorblueprint	il progetto come schema, con i file di modello, palette, oggetti di scena e volumi estratti in slot con nome
pxr style new KIT --from PROJECT	salva il primo Stile di un progetto come kit di Stile
pxr kit show FILE.pixorkit	cosa contiene un kit: un gruppo di nodi, uno Stile, un preset o una pipeline
pxr names PROJECT.pixor [--names T] [--pipeline NAME|all]	i nomi che scriverà il progetto e l’id di ogni fotogramma, senza renderizzare, i file di ogni render con il loro percorso; due fotogrammi con lo stesso nome, due render sullo stesso file (would be written twice), o due file sullo stesso percorso (la base di un paper doll e quella del light kit, una variante di palette e un livello) sono un errore qui invece di un file perso più tardi
pxr graph list|set|add|drop|wire|save|swap|flatten|extra FILE --which scene|action|style|asset	uno qualsiasi dei quattro grafi da uno script. --pipeline NAME sceglie quale: un’azione per nome, uno Stile o una pipeline di asset, il primo se non nominato. Stampalo, cambia un’impostazione, aggiungi un nodo nella catena (o accanto con --alone, collegandovi altri con --in SLOT=NODE), eliminane uno, uniscine due con wire --from N --to M --slot S, salvalo come kit (save -o KIT.pixorkit: il grafo di Stile intero, il grafo di scena, azione o asset come un solo nodo, --as-pipeline un’intera pipeline di asset che un altro progetto usa con pxr project set --use-pipeline), inserisci un kit di nodi come gruppo (add --kit KIT) o al posto di un nodo (swap --kit KIT), o scrivi un grafo con i suoi gruppi espansi; extra --node N --name LAYER fa dell’immagine di un nodo di Stile anche un livello delle esportazioni, e --drop lo interrompe. --node (e --set NODE.SETTING in pxr run) indica un nodo con il suo numero, il suo tipo, il nome di un gruppo, ciò che dice il suo Chiamato (un File immagine, uno Sheet) o il nome che gli è stato dato nell’app (F2); un nodo object è il modello (of=model), e un elemento, una forma o un’immagine è un nodo a sé. I nodi sprites, frame-range e hold di un grafo di Asset si impostano come gli altri (--node sprites --set action=walk,Static; action=every-one-except-static è quello di un nodo nuovo, action= ogni azione, anche Statica; --set smart=6, --node frame-range --set from=2 --set to=5, --node hold --set times=2); quelli di un’azione (clip, bob, spin, merge…) per tipo o numero, e uno aggiunto senza --alone si riproduce subito, unito a ciò che c’è. Nel grafo di Stile un nodo entra senza collegamenti, --in SLOT=NODE e wire lo collegano. Una modifica che lascerebbe un grafo impossibile da eseguire viene rifiutata, e il file resta com’era (vedi il grafo di Scena, il grafo di Asset e i nodi)
pxr shapes [PROJECT] -o OUT.glb	esporta come geometria le forme costruite nell’app, per un programma di modellazione o un motore
pxr icons MODELS... -o DIR	icone d’inventario con un atlas per dimensione; la rarità dal nome di ogni file, e --save conserva una ricetta da rieseguire (vedi Esportazione)
pxr audit FILE|FOLDER... [--style KIT]	controlla che gli sheet esportati combacino: preset, illuminazione, vista, inclinazione, luce, bande, linee, palette e pixel per metro, dalla ricetta di ogni file, e con un kit di Stile che ogni colore sia nella sua palette (uscita 1 in caso contrario)
pxr watch PROJECT.pixor	esporta di nuovo ogni volta che cambiano il progetto, il suo modello o la sua palette
pxr effect KIND[:FRAMES]	un effetto in pixel da 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	le modalità console, o se uno sheet rientra in una (uscita 1 in caso contrario); la console viene da --console o dalla ricetta dello sheet

Opzioni di render

Opzione	Predefinito
--view VIEW	quelle del preset	side, three-quarter, isometric o top-down
--pitch DEG	della vista	gradi sotto l’orizzonte
--yaw DEG	0	ruota un singolo sprite, o l’unico lato di uno sheet di uno sprite
--camera GENRE		la camera di un genere di gioco: platformer, fighting, beat-em-up, adventure, top-down-rpg, action-adventure, isometric, tactics, strategy, racing, top-down-shooter, shmup, icon (vista, inclinazione, rotazione; dimensione e lati se non indicati)
--camera-yaw DEG	0	ruota la camera attorno al modello, ogni lato
--size N	64	adatta in N x N, da 4 a 2048; --size 960x540 adatta in una tela larga e alta così (un’immagine del titolo, uno sfondo)
--pixels-per-metre F		pixel per metro fissi invece di --size, da 0.5 a 4096 (il Pixel/m dell’app)
--up AXIS	deciso all’importazione	l’asse che nel file punta in alto (y, z, -z, x, -x, -y): per un modello esportato sdraiato
--import-scale F, --import-offset X,Y,Z	deciso all’importazione	l’unità e la mossa, indicate a mano
--no-import-fix		renderizza il file esattamente com’è, senza correggere nulla
--samples N	4	campioni per pixel lungo ogni lato, da 1 a 8 (i Campioni dell’app)
--light AZ,EL	-45,45	luce principale relativa alla camera
--light-space S	camera	world: la luce resta ferma nella scena invece di seguire la camera
--fill F	quelle del preset	intensità della luce di riempimento, da 0 a 1
--no-shadow		nessuna ombra proiettata
--bands N	quelle del preset	bande di luce, da 1 a 4
--palette P		un file .hex, .gpl o .png, o una palette integrata: pixor-16, pixor-8, dusk-12, forest-12, desert-12, ice-10, mono-8
--aa N	0	antialiasing: 0 spento, 1 sagoma, 2 ogni linea
--match-space S	oklab	come i colori trovano il loro più vicino in una palette fissa: oklab, srgb o weighted
--dither-pattern P	bayer	bayer (il tratteggio incrociato) o blue-noise (sparso in modo uniforme); entrambi restano sulla superficie quando il modello si muove
--even-stairs	spento	bordi della sagoma dritti con gradini regolari (2, 2, 2 invece di 3, 1, 2)
--smear PX	0	fotogrammi di scia, da 0 a 64: ciò che si è mosso di PX pixel o più dal fotogramma precedente lascia una scia
--nudge X,Y	0,0	sposta il modello di una frazione di pixel sulla griglia (ciascuno da -0.5 a 0.5); cambia solo il campionamento
--foot-plant	spento	i piedi a terra di un umanoide sulla stessa riga di pixel in ogni fotogramma di una clip
--preset NAME	pulito	clean, selout, retro4, flat, wireframe, o un kit di preset salvato (.pixorkit)
--style KIT		un kit di Stile (.pixorkit): un intero Stile (pxr style new, Salva kit… di uno Stile), anche il suo grafo di Stile, o solo un grafo di Stile (pxr graph save --which style); i flag successivi lo modificano ancora. In un file di caso di riferimento, relativo a esso. pxr icons e pxr audit accettano lo stesso
--dither F	0	dithering ordinato tra bande di luce vicine, da 0 a 1
--line-colour HEX	quelle del preset	colore delle linee Scure, #rrggbb (solo palette automatiche)
--no-lines MATERIAL		nessuna linea attorno a questo materiale (ripetibile; pxr inspect li elenca)
--crease-angle DEG	55	quanto deve essere netta una piega per disegnare una linea di piega, da 1 a 179
--depth-step PX	2.5	il salto di profondità, in pixel, che disegna una linea interna, da 0.1 a 40 (il Gradino di profondità dell’app)
--shortest-line N	3	la linea interna o di piega più corta tenuta, da 0 a 16 pixel (la Linea più corta dell’app)
--no-part-lines		nessuna linea tra parti a contatto senza un salto di profondità
--outline-inside		la sagoma sul bordo stesso dello sprite
--convex LINE	nessuno	una linea chiara sulle pieghe che sporgono verso la camera: none, dark o highlightN
--no-material-channels		ignora metallo, ruvidità, emissione, unlit e trasparenza di un materiale glTF, e ombreggia solo dal suo colore
--backend B	auto	auto, vulkan, metal, dx12, gl, webgpu o cpu (vedi Scegliere un renderer)

Opzioni di luce e colore

Opzione
--rig NAME	un’illuminazione: noon, dusk, torchlight, moonlight o studio
--cycle MATERIAL	fai ciclare i colori di questo materiale in un’azione --colour-cycle (ripetibile)
--team MATERIAL|#RRGGBB	il colore della squadra: un materiale, o ogni rampa della tinta di quel colore (ripetibile); --variant team:blue ricolora solo quello
--console C	una modalità console: gameboy, nes, pico8, tic80, c64 (vedi Modalità della console)

Opzioni di animazione

Opzione
--clip NAME	una clip da renderizzare (ripeti per altre), o all
--anim FILE	usa anche le clip di FILE
--ring N	lati, in senso antiorario dal davanti (da 1 a 64, predefinito 1), chiamati South, Southeast, East…: una camera ciascuno, con una dimensione condivisa, in un unico sheet
--sides A1,A2,...	un lato per ogni angolo invece, in gradi (0 = davanti, 90 = rivolto a destra)
--fps F	fotogrammi al secondo del tempo della clip (predefinito 12), il taglio di ogni nodo Sprite
--keys T1,T2,...	tempi della clip scelti a mano, in secondi, il taglio di ogni nodo Sprite
--clip lib:NAME	una clip della libreria di movimenti adattata allo scheletro del modello: idle, walk, run, jump, attack, hit, death
--parallax N	dividi l’immagine per profondità in N livelli (2–8) per sfondi a scorrimento (vedi Scene di più modelli)
--haze #RRGGBB	il colore verso cui sfumano i livelli di parallasse lontani; none mantiene ogni livello sulla palette così com’è
--spring NODE[:S,D,G]	NODE e ciò che sta sotto oscillano con il movimento: rigidità, smorzamento, gravità (ripetibile); in un progetto, un nodo Molla del grafo di Scena
--smart-frames N	tieni N fotogrammi di ogni clip, scelti tra le sue pose (ognuno tenuto fino al successivo), il taglio di ogni nodo Sprite
--root-motion M	keep (default), in-place (blocca l'osso radice in orizzontale) o in-place-sway (toglie solo lo spostamento netto della clip)
--turntable N	aggiungi un’azione di N fotogrammi che fa fare un giro al modello
--turntable-seconds S	quanto dura quel giro (predefinito: N fotogrammi a --fps)
--motion M[:N[:A]]	aggiungi un loop: spin, bob, swing, pulse, squash o flicker, N fotogrammi, intensità A (per spin, la frazione di giro compiuta dal loop: spin:8:0.125 ruota una gemma a otto facce di una faccia, un loop senza giunture)
--colour-cycle N	aggiungi un’azione di N fotogrammi che fa ruotare le tonalità dei materiali a ciclo
--prop FILE:BONE[@at=X,Y,Z][@turn=X,Y,Z][@scale=S][@grip=NODE]	aggancia un altro modello a un osso, tenuto per l’impugnatura, spostato e ruotato sugli assi dell’osso (vedi Oggetti di scena sulle ossa)
--shape SPEC	aggiungi una forma: [NAME=]KIND[:SIZE[:AT[:#RRGGBB[:TURN]]]], per es. 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 per una ruota con nome sul fianco (ripetibile). KIND è box, sphere, cylinder, cone, torus, plane, capsule, wedge, pyramid, prism, stairs, arch o letters (pxr help render li elenca dalla stessa lista che legge il flag): letters sono i pixel del font estrusi in blocchi, che compongono PIXOR, o le parole di un progetto, pxr project set --add-shape letters --words WORDS --font NAME (render non accetta --words)
--volume SPEC	aggiungi un volume: puff, flame, cloud, mist o un percorso .vdb, poi [:SIZE[:AT]], poi [:FRAMES[,EVERY[,LOOP]]] per una sequenza .vdb numerata, poi @BONE per farlo portare da un osso o @effect:N dall’emettitore dell’N-esimo effetto (Volumi)
--wire LINE	il look wireframe: none, dark o seloutN, con --wire-fill, --wire-hidden, --wire-angle (da 0 a 180), --wire-all-edges e --wire-glow MATERIAL (impostazioni)
--light-sweep N	aggiungi un’azione di N fotogrammi che muove la luce
--effect KIND[:N]	aggiungi un’azione di effetto in pixel di N fotogrammi (vedi pxr effect), con --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	riquadri e posizioni delle ossa per fotogramma nel JSON (ripetibile; vedi Esportazione)
--paper-doll, --piece NAME:PARTS	livelli paper doll (vedi Esportazione)
--item MODEL@X,Z[,YAW,SCALE[,LAYER]][:CLIP[,PHASE]], --ground W,D[,#RRGGBB]	altri modelli accanto al primo, ognuno un nodo Elemento del grafo di Scena in un progetto, e un piano del terreno sotto di essi (vedi Esportazione)
--chunks COLSxROWS	scrivi una grande mappa in blocchi con giunture esatte; --chunk-margin N (predefinito 8)
--max-flicker F	avvisa sopra questa quota di sfarfallio (per es. 0.01); in un caso di riferimento, fallisce
--require-visible OBJECT	avvisa se OBJECT scompare in un qualsiasi fotogramma

Opzioni di esportazione

Opzione
--export LIST	separati da virgole o ripetuti: png, json, aseprite, normal, depth, emission, layers, palette, godot, gif, apng, light-kit, p8, report, video, o all (tutti tranne p8 e video, che vengono scritti solo se nominati); il PNG viene sempre scritto (vedi Esportazione). render, batch, run, watch, project set e tiles (con i suoi formati) lo leggono allo stesso modo
--layout L	griglia (una riga per azione e lato, il predefinito) o striscia
--padding N	pixel trasparenti tra le celle, da 0 a 256 (predefinito 0)
--extrude N	ripeti i bordi delle celle di N pixel verso l’esterno, da 0 a 64 (predefinito 0)
--pot	dimensione dello sheet a potenza di due
--godot-path RES	dove Godot trova lo sheet (predefinito res://<png name>)
--anim-scale K	scala intera dei file GIF e APNG, da 1 a 16 (predefinito 1)
--video-scale K, --video-fps N, --video-background #RRGGBB	come vengono scritti i video: scala da 1 a 16 (predefinito 4), da 1 a 100 fotogrammi al secondo (predefinito 30), su cosa viene disegnato lo sprite (predefinito nero)
--trim	riduci ogni cella ai suoi pixel (il JSON e il file Godot mantengono la posizione)
--dedupe	salva una sola volta i fotogrammi identici
--max-width N	inizia una nuova riga prima che lo sheet diventi più largo di N pixel (da 0 a 65536; 0: nessun limite)
--columns N	N fotogrammi per riga, ogni clip che continua dopo l’ultima: un provino a contatto
--max-height N	dividi uno sheet più alto di N pixel in pagine, con clip intere per pagina (NAME_1.png, NAME_2.png; da 0 a 65536)
--variant NAME	esporta anche una variante di palette (ripetibile): un effetto come hit-flash o night, hue:DEG, team:COLOUR (un nome o #rrggbb; richiede --team), o palette:NAME|FILE; aggiunge uno sheet di indici e una texture di lookup
--shadow KIND	scrivi anche name_shadow.png: contact o drop
--names TEMPLATE	come si chiamano i file e le chiavi del JSON: un modello su {project}, {object}, {action}, {side}, {layer}, {set}, {size}, {index} e {ext}, con {index:3} completato a tre cifre (vedi Esportazione)
--no-recipe	non salvare la ricetta (come è stato fatto lo sheet) nel PNG e nel file .aseprite
--scale K	ingrandisci il PNG K volte (solo anteprime; non con altri formati)
--save-project FILE.pixor	scrivi anche questa riga di comando come progetto
--debug DIR	target di render, palette, immagini di lint e di sfarfallio

Test golden per la tua pipeline

Un file di casi elenca un render per riga: un nome, il percorso di un modello o di un progetto (relativo al file) e le opzioni.

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

pxr golden cases.txt --bless salva i risultati come NAME.png accanto al file; in seguito, pxr golden cases.txt fallisce quando un pixel cambia, quando uno sprite ha segnalazioni del lint (pixel isolati, angoli di linea a L, linee di 2 px), o quando un controllo --max-flicker o --require-visible fallisce; l'errore dice di quali casi differiscono i pixel (i loro NAME.actual.png e NAME.diff.png sono in target/golden) e quali hanno fallito i controlli. --bless salva le immagini anche quando un controllo fallisce, ed esce con 1 nominando quei casi. Usalo per accorgerti quando una modifica a un modello altera i tuoi sprite.

Una libreria, non un’esecuzione

Uno studio renderizza di nuovo gli stessi cinquemila sprite perché si è spostata una rampa. Tre cose ne fanno una decisione invece di un lavoro notturno.

Una cache che sopravvive al processo. --cache DIR su pxr batch e pxr run conserva ogni render che fa, con i file che ha letto e un hash del loro contenuto: il modello, i file delle clip accanto, le texture a cui punta un .gltf, palette, kit, immagini e volumi. L’esecuzione successiva serve ogni render i cui file hanno ancora lo stesso hash, e renderizza il 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 cache non è mai la fonte di verità: --no-cache dà gli stessi byte, un file salvato il cui hash non corrisponde al nome viene renderizzato di nuovo invece di essere servito, e una nuova build di Pixor avvia una nuova cache invece di fidarsi della vecchia.

Un file di lavoro. Una tabella con una riga per render, una colonna per slot dello schema e, facoltativamente, le colonne name (la cartella della riga), out (il suo sheet sotto --out) e NODE.SETTING (un --set per quella riga):

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

Qui sheet.pixorblueprint viene da pxr project blueprint sheet.pixor, un progetto di heroes/knight.glb con una palette, quindi i suoi slot sono model e palette; il cavaliere viene tagliato a 8 fotogrammi al secondo e il mago, con la cella vuota, alla cadenza dello schema stesso. Ogni riga scrive 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

I percorsi sono relativi alla tabella. Una riga è esattamente pxr run con aggiunti --in e --set della riga, così una riga che va storta si può eseguire da sola. Una riga che fallisce non ferma mai le altre: il rapporto elenca ogni riga indicando se è stata renderizzata, servita dalla cache o è fallita e perché, e il job esce con 1 alla fine se è successo a qualcuna.

Budget come flag. --max-pixels N, --max-memory SIZE e --max-time DURATION valgono per render (per riga, per modello). Ciò che il piano sa già (quanti pixel avrà uno sheet, circa quanta memoria occuperà) viene controllato prima di disegnare qualsiasi cosa; tempo e memoria vengono controllati tra un fotogramma e l’altro. Superarne uno esce con 6 indicando quale e dove si è fermato; in un lavoro la riga fallisce con quel motivo e le altre proseguono.

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

Clip lunghe. I fotogrammi di una clip vengono disegnati, poi rifiniti insieme, perché i passaggi che evitano lo sfarfallio di una clip guardano lungo di essa. Ciò che leggono viene tenuto entro 512 MiB (metà di --max-memory quando è indicato), pochi lati alla volta; una clip troppo lunga anche per un solo lato viene tenuta su disco mentre viene disegnata (sotto ~/.cache/pixor/spill, o PXR_SPILL_DIR) e riletta quando serve: gli stessi pixel, più lentamente, e la cartella sparisce con il render.

Codici di uscita

Codice
0	successo
1	un render, un’esportazione, un modello batch, una riga di lavoro o un caso di riferimento falliti
2	un errore d’uso: il messaggio, l’uso del comando e see pxr help COMMAND su stderr
3	un ingresso che non è stato possibile leggere: un modello, un progetto, una palette, un kit, un file di caso o un dump
4	un backend richiesto per nome che non c’è
5	un’uscita che non è stato possibile scrivere: un file o una cartella
6	oltre un budget di --max-pixels, --max-memory o --max-time
7	una ricottura che ha tenuto pittura su cui non deciderà da sola (--resolve keep|pixor)

L’assenza di GPU non è un errore: Pixor disegna invece con il suo rasterizzatore. Un errore dice cosa non andava allo stesso modo ovunque: --flag takes A to B, got X.

Scegliere un renderer

--backend auto|vulkan|metal|dx12|gl|webgpu|cpu dice chi disegna la geometria. Il look, ogni passaggio sui pixel, viene calcolato sulla CPU qualunque cosa dica questa opzione.

• auto (il default) prende ciò che la macchina ha, e ripiega sulla CPU quando nessun adattatore funziona.
• cpu è il rasterizzatore di Pixor. Non ha bisogno di adattatore né di driver, è nel binario, e disegna gli stessi pixel su ogni macchina — la scelta portabile per un asset pack o una build di CI.
• Un backend indicato e non presente è un errore (codice di uscita 4), perché renderizzare in silenzio da un'altra parte è peggio che dirlo.

La ricetta di ogni esportazione registra quale backend l’ha disegnata. pxr doctor stampa gli adattatori trovati, quello che Pixor sceglierebbe, le versioni dei driver, e se quel backend disegna la stessa immagine del riferimento 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

Nell’app la stessa scelta è Preferenze › Renderer › Disegna gli sprite sulla CPU, o per una sola sessione pixor --backend B con gli stessi nomi di pxr (cpu, auto, o un backend GPU per nome), che lascia la preferenza com’è. Ognuno conserva ciò che ha disegnato: passare all’altro renderizza di nuovo i fotogrammi, e tornare indietro riporta i fotogrammi del primo senza un render, finché nulla della scena è cambiato.

Per strumenti e script

Aggiungi --json a qualsiasi comando: lo standard output contiene allora un evento JSON per riga (progress, wrote, warning, error, done) e il log leggibile passa allo standard error. Anche i comandi che leggono invece di scrivere danno ciò che stampano come un unico evento: inspect, adapters, tiles --list (terrains), graph list e graph flatten, e diff di due dump.