Exportar para engines

A janela Exportar

Exportar (Ctrl+E) fica logo depois de Importar no cabeçalho da janela, e abre uma janela desenhada como a de Importar (D51):

1. Pipeline de asset — de início, aquele que o seletor de Asset do cabeçalho mostra. O que ele grava é projetado no grafo de asset.
2. Pasta de exportação — digite um caminho, ou Escolher… um. O projeto o guarda.
3. Exportar agora — o projeto como está aberto, salvo ou não: exportar nunca o salva, e um projeto sem título é exportado como está.

Antes de você pressionar Exportar, a janela lista cada arquivo que a exportação vai gravar, como o pxr names os nomeia: cada um pelo caminho na pasta e pelo tipo (folha de sprites, JSON, GIF…), e vai substituir num arquivo que a pasta já tem. A lista é refeita — com um pequeno indicador de carregamento, sem nunca travar a janela — quando você muda o pipeline de asset, a pasta ou o projeto. Um pipeline que não pode ser exportado como está (duas saídas gravando um mesmo arquivo, por exemplo) diz ali o porquê, e Exportar espera até que seja corrigido.

Ao apertar, essas mesmas linhas, nos seus lugares, são a exportação: cada uma com um indicador de carregamento até ser gravada, depois um visto, seu tamanho, Abrir (no programa com que o seu sistema a abre) e Mostrar pasta. O que dá errado é dito no arquivo em que parou. Parar encerra uma exportação pela metade: o que foi gravado fica, o arquivo que estava sendo gravado é removido. A janela pode ser fechada enquanto roda; Exportar a abre de novo.

Ela executa exatamente o que a linha de comando executa: pxr render PROJECT --pipeline NAME -o FOLDER, num processo próprio, para que o Pixor continue respondendo — sobre um instantâneo do projeto como está aberto, gravado na pasta gerada (com os caminhos dos seus arquivos tornados absolutos) e removido quando a exportação termina. Os arquivos são nomeados como o pxr render nomeia os daquele projeto: com o nome do projeto, ou, num projeto sem título, com o nome do seu modelo. Cada arquivo é gravado do zero a partir do pipeline: o que os nós do grafo de asset Geram nunca é copiado.

Todo arquivo vai para a pasta. A folha recebe o nome de arquivo do nó PNG do projeto (out/hero.png grava FOLDER/hero.png); um arquivo cujo caminho está dentro da pasta da folha mantém seu lugar abaixo de FOLDER, e qualquer outro caminho (um arquivo compactado, uma animação, ícones nomeados em outro lugar) mantém só sua última parte.

O que uma exportação grava

Toda exportação grava uma folha: uma linha por ação e lado, uma coluna por quadro, todas as células do mesmo tamanho, com o pivô no mesmo pixel em cada uma. Adicione nós Arquivo à folha no grafo de asset (ou use --export na linha de comando) para ter arquivos ao lado dela com o mesmo nome. Cada um é um nó conectado a partir da folha, com seus próprios ajustes. --export all grava todos os formatos abaixo, exceto p8 e video, que só são gravados quando nomeados: um cartucho só comporta uma folha feita para ele, e um vídeo sem compressão de cada clipe e lado pode ter gigabytes. Nenhum par deles grava o mesmo arquivo: pxr names recusa um projeto em que dois gravariam.

Formato	Arquivo	Para
png	name.png	a folha, um PNG indexado (índice 0 transparente)
json	name.json	retângulos das células, durações dos quadros, uma tag por ação e lado, o pivô. O layout “array” do Aseprite, para que importadores escritos para o Aseprite o leiam
aseprite	name.aseprite	um arquivo Aseprite indexado: camadas final, lines, flat e uma por saída extra do grafo de Estilo; uma tag por ação e lado; durações por quadro; uma fatia pivot
normal	name_normal.png	um mapa de normais com o mesmo layout, para iluminação 2D
profundidade	name_depth.png	profundidade com o mesmo layout: branco o mais próximo, escuro o mais distante, uma escala para a folha inteira (meta.pixor.depth dá os dois em metros); transparente onde não há nada. Para ordenação, névoa e iluminação 2.5D
emissão	name_emission.png	cada pixel luminoso na sua própria cor, tão claro quanto brilha (um material luminoso, ou o mapa de emissão do modelo); transparente no resto. Para brilho e bloom
camadas	name_lines.png, name_flat.png e name_LAYER.png para cada saída extra do grafo de Estilo	as camadas de traço e de cor chapada como folhas, e a imagem de um nó onde o grafo de Estilo nomeia uma
paleta	name.hex, name.gpl	a paleta (formatos do Lospec e do GIMP)
godot	name.tres	um recurso SpriteFrames do Godot 4
gif	name_walk_Southeast.gif, …	um GIF animado por ação e lado, com retenções como atrasos de quadro, para compartilhar e para prévias
apng	name_walk_Southeast.apng, …	o mesmo como PNGs animados, com atrasos exatos em milissegundos
vídeo	name_walk_Southeast.avi, …	um vídeo por ação e lado: um AVI sem compressão, cada pixel como é, para um trailer ou uma página de loja
light-kit	name_ramps.png, name_normal.png, name_light.png, shaders	iluminação fiel à paleta nas engines (veja abaixo)
relatório	name_report.png	a folha com as descobertas de cada verificação marcadas (veja abaixo)
p8	name.p8	um cartucho de PICO-8 (veja Modos do console)
zip	o caminho no seu nó	um nó Arquivo ZIP no grafo de asset: os arquivos conectados a ele, ou tudo o que a exportação gravou

Uma linha recebe o nome da sua ação e do seu lado: walk_Southeast.

Quais quadros uma folha recebe, como são organizados e quantos arquivos uma renderização grava é assunto do grafo de asset: um nó Folha e seus nós Arquivo, até você reconectá-lo.

Como os quadros se chamam, e o que são

Cada quadro de uma folha tem um nome e um id, e eles respondem a duas perguntas diferentes.

O nome é um modelo, um padrão sobre as próprias palavras do seu projeto, então o padrão simples é o que um iniciante quer, e um estúdio pode seguir uma convenção que não escolheu:

{project}_{action}_{side}_{index:2}.{ext}     hero_walk_East_00.png

As palavras são {project}, {object}, {action}, {side}, {layer}, {set} (o conjunto de partes com que um nó Sprites desenhou o quadro), {size}, {index} e {ext}. {index:3} preenche um número com zeros até três dígitos. {{ e }} escrevem uma chave. Uma palavra que o Pixor não conhece é um erro quando você digita o modelo, não um arquivo chamado hero_{genre}_00.png, e uma palavra vazia leva junto o separador antes dela, então um sprite sem lado é hero_Static_00.png.

Um valor que não pode fazer parte de um nome de arquivo (/ \ : * ? " < > |) é recusado em vez de substituído em silêncio; um espaço vira _. A única exceção é a palavra do próprio Pixor: um clipe da biblioteca chamado lib:walk vira lib-walk num nome, porque esses dois-pontos são do Pixor, não seus.

Dois quadros que cairiam no mesmo nome são recusados antes de qualquer renderização. Defina-o com --names na linha de comando, ou guarde-o no projeto:

pxr project set hero.pixor --names '{object}/{action}-{side}-{index:3}.{ext}'
pxr names hero.pixor                  # what it will write, without rendering
pxr names hero.pixor --json           # the same, for a build script

O id diz o que um quadro é, nunca onde ele foi parar. É um hash do objeto, da ação, do lado, do tempo na ação e da camada, e é gravado ao lado de cada quadro no JSON e nos dados de usuário do .aseprite. Reempacotar uma folha, adicionar um clipe ou mudar o espaçamento move retângulos e não mexe nos ids, então um build que se refere a quadros por id não quebra toda vez que o empacotador roda. Reamostrar um clipe em outra taxa de quadros muda os ids, porque esses são outros quadros.

Folhas menores

No nó Organizar do grafo de asset (ou na linha de comando):

• Recortar espaço vazio (--trim) reduz cada quadro aos seus pixels. O JSON dá o lugar de cada quadro na célula completa (spriteSourceSize, trimmed: true) e o arquivo do Godot define a margin de cada quadro, então as engines ainda põem cada quadro no pivô.
• Guardar quadros repetidos uma vez (--dedupe): quadros exatamente iguais (poses retidas, lados de um objeto parado) compartilham um único lugar.
• Largura máxima da folha (--max-width 4096) começa uma nova linha antes que a folha fique mais larga, para engines e GPUs com limite de tamanho de textura.
• Altura máxima da folha (--max-height 2048) divide uma folha mais alta que isso em páginas, com clipes inteiros por página: hero_1.png, hero_2.png, cada uma com seu próprio JSON e os outros arquivos ao lado.
• Quadros por linha (--columns 8) coloca essa quantidade de quadros numa linha, cada clipe emendado depois do anterior: uma folha de contatos, ou a grade fixa que o importador de uma engine pede.
• Um lado desenhado a partir de outro (o nó Espelhar do grafo de asset): um modelo simétrico entre esquerda e direita parece igual visto da esquerda e numa vista espelhada da direita, então o lado oeste nem precisa ser renderizado — pegue os sprites da câmera leste, espelhe-os como Oeste, e a folha tem walk_West desenhado a partir de walk_East, com pixels, normais, caixas e root motion espelhados. Renderize só as câmeras que diferem; espelhe o resto.
• Os graus de cada lado estão no JSON: em cada quadro (pixor.degrees) e, para todos eles, em meta.pixor.sides ({"South": 0, "Southeast": 45, ...}): graus a partir da frente, no sentido anti-horário visto de cima, como --sides os recebe. Um jogo transforma um ângulo numa linha com essa tabela.

Camada de sombra

Camada de sombra (--shadow contact ou --shadow drop) grava name_shadow.png, disposto como a folha: preto onde a sombra cai, transparente no resto. Contato é uma mancha sob os pés do tamanho da pegada do modelo; Projetada é a silhueta lançada no chão, para longe da luz principal. Desenhe-a sob os seus sprites com a opacidade que quiser, ou ordene-a à parte. O nó Camada de um grafo de asset pode indicar shadow, e uma Sobreposição a põe sob o sprite numa só folha (Grafo de asset).

Ciclo de cores em tempo de execução

Com materiais em ciclo, o JSON lista cada um em meta.pixor.cycles ("material" e seus "indices" na paleta, na ordem do ciclo), e o Pixor grava name_index.png, a folha como índices de paleta. Uma engine pode girar essas entradas da paleta a cada tick em vez de guardar mais quadros. Outros materiais que compartilham os mesmos tons entram no ciclo junto, como em qualquer ciclo de paleta; dê a um material em ciclo cores próprias para mantê-lo separado.

Cenas com vários modelos e fundos com paralaxe

Um projeto pode ter mais de uma coisa: modelos dispostos num plano de chão e renderizados como uma única imagem, com uma luz e sombras entre eles — um canto de vila, uma sala de masmorra, um acampamento, arte para página de loja a partir da biblioteca grátis.

Cada um é um item: um modelo, onde ele fica, para que lado está virado e qual o seu tamanho — um nó Item do grafo de Cena, adicionado ao fim da sua cadeia, que um anel ou uma dispersão depois dele repete. Na linha de comando, cada --item é um:

pxr project new camp.pixor \
  --item tent.glb@-1.8,-1.6,25,1.2 \
  --item campfire.pixoritem@0,0 \
  --item barrel.glb@2,1,0,1,2 \
  --ground 7,5,#5d7a45 \
  --size 200
pxr render camp.pixor

@x,z[,yaw[,scale[,layer]]] é onde um item fica (em metros, x para a direita, z em direção à câmera); --ground W,D[,#rrggbb] coloca um plano de chão sob eles. Acrescente :clip[,phase] e esse item reproduz um clipe próprio, num ponto próprio dele, enquanto os que estão ao lado ficam parados. Os caminhos são relativos ao projeto.

Camadas de paralaxe (um nó Arquivo Camadas de paralaxe, de 2 a 8 camadas, ou --parallax N) dividem a imagem por profundidade em camadas para um fundo com rolagem: cada uma é renderizada sozinha no mesmo palco e na mesma paleta, e as camadas mais distantes ficam mais escuras e azuladas em direção à cor da névoa (--haze), como a distância parece (Névoa nas camadas distantes desligado, ou --haze none, mantém cada camada na paleta como está, para um jogo de paleta fixa). A camada de um item o põe numa camada (0 é a mais distante); os outros são distribuídos por profundidade. O Pixor grava name_layer0.png, name_layer1.png, …, name_parallax.json (a imagem de cada camada e uma velocidade de rolagem sugerida, de 0.25 para a mais distante a 1 para a mais próxima) e name_parallax.png, as camadas empilhadas. Qualquer modelo pode ser dividido, não só uma cena com vários. O nó Camada de um grafo de asset nomeia uma camada como layer0, layer1, … para pô-la numa folha própria (Grafo de asset). pxr project set --parallax N --haze #rrggbb|none define os dois num projeto.

Modos do console

Para consoles homebrew e de fantasia, escolha um Console em Estilo (ou --console). O Pixor então usa as cores do próprio console e seus limites:

Console	Cores	Por sprite	Notas
Game Boy	os 4 tons de verde	3 + transparente	tons por luminosidade
NES	a paleta mestra de 54 cores	3 + transparente	verificado também por tile de 8 × 8
PICO-8	seu 16	todos os 16	exportar um cartucho .p8 (marque p8; a folha precisa caber em 128 × 128: defina uma largura máxima de 128)
TIC-80	seus 16 (Sweetie 16)	todos os 16	importe o PNG com o import sprites do TIC-80
C64	seu 16	3 + transparente	sprites multicoloridos: pixels com o dobro da largura; mantenha a largura par (os sprites do C64 têm 24 px)

Onde um sprite só pode usar três cores, o Pixor escolhe as três cores do console que melhor cobrem o seu modelo em sombra, cor base e luz, para que todos os quadros e lados usem as mesmas três. A seção Estilo diz se o quadro na tela cabe; pxr console check sheet.png verifica uma folha inteira (cores, cores por quadro e por tile, pares de largura dupla, tamanho) e lê o console a partir da receita dentro da folha. Toda renderização num modo de console faz a mesma verificação na folha que gravou, e falha (código de saída 1, com os problemas listados) quando ela não cabe. Uma paleta sua é mantida sob um modo de console, não substituída pela do console — então uma paleta de dezesseis cores num Game Boy é apontada, em voz alta, em vez de trocada em silêncio pelos quatro verdes. As cores do NES são calculadas pelo Pixor a partir do sinal de vídeo do console; as outras são os valores publicados dos consoles.

Iluminação fiel à paleta nas engines

As engines iluminam sprites a partir de mapas de normais com sombreamento suave, o que traz cores que sua paleta nunca teve. Marque Light kit (ou --export light-kit) e os sprites reagem à luz do jogo enquanto cada pixel iluminado fica num degrau da rampa da sua própria cor, com as faixas, o deslocamento de matiz e os brilhos do Pixor. O Pixor grava, ao lado da folha:

Arquivo	O que é
name_ramps.png	a rampa de cor de cada pixel (número da rampa + 1 no vermelho; 0 para pixels que a luz não toca, como os traços)
name_normal.png	as normais, no espaço da vista: x para a direita, y para cima, z em direção à câmera
name_light.png	a consulta: uma linha por rampa, uma coluna por nível de luz, depois a cor do brilho, depois duas colunas que não são cores — os limiares de brilho da própria rampa, porque um material brilhante ou metálico recebe brilho com mais facilidade do que um fosco
pixor_palette_light.gdshader, name_light.tres	o shader do Godot e um material com todas as texturas definidas: ponha o material num Sprite2D ou AnimatedSprite2D
PixorPaletteLight.shader	o shader do Unity: crie um material com ele para um SpriteRenderer e defina seus três mapas
pixor_palette_light.fsh, .vsh	o shader do GameMaker; os comentários mostram como ligar os mapas

Os shaders iluminam com uma luz principal (light_dir, em direção à luz, no espaço das normais), a luz de preenchimento da predefinição e brilhos especulares e de contorno cujos limiares vêm da textura de consulta, por rampa, como os do próprio Pixor. Definir specular ou rim como um número entre -1 e 1 os substitui no sprite inteiro; acima de 1 desliga esses brilhos; abaixo de -1 (o padrão) usa os da consulta. Um brilho só é desenhado onde um dos quatro pixels vizinhos também recebe um, que é a regra do próprio Pixor contra um pixel claro isolado — min_highlight 1 desliga isso. Mova a luz por um script, por exemplo em direção a uma tocha: material.set_shader_parameter("light_dir", dir). Importe os três mapas sem filtragem, sem compressão e sem mipmaps. Para ver antes de exportar, ligue a Prévia de iluminação 2D (L) sobre o sprite e escolha Luz como: o kit de luz: a luz se vira em direção ao ponteiro e o quadro é iluminado pela mesma consulta, pelas mesmas regras (brilhos só ao lado de outro, pixels sem rampa intocados), como os shaders o iluminam. Com a luz da renderização, um quadro fica exatamente como o Pixor o desenhou (as exceções são alguns pixels nas bordas das faixas); sombras projetadas, pontilhado e a suavização de cintilação das folhas animadas são só do Pixor, então desligue as sombras projetadas nas folhas que você ilumina na engine. O JSON lista os arquivos e a luz em meta.pixor.light_kit.

Variantes de paleta

Adicionar variante (--variant NAME, repetível) exporta a mesma folha em outras cores. O Pixor desenha em índices de paleta, então uma variante muda só a paleta: cada pixel, traço e tom fica onde está.

• Efeitos: hit-flash, frozen, poisoned, petrified, burning, silhouette, selected, as horas do dia dawn, noon, dusk, night, e as estações autumn e winter (os verdes ficam laranja, ou pálidos e com neve).
• Cores de equipe: team:blue (ou red, green, yellow, purple, orange, teal, pink, white, black, ou team:#3050e0) recolore só a cor de equipe — os materiais ou cores marcados com --team ou em Materiais — e deixa pele, aço e ouro como estão. Cada tom mantém sua luminosidade, então a rampa continua legível. Quatro equipes a partir de um sprite: --team cloth --variant team:red --variant team:blue --variant team:green --variant team:yellow. O JSON lista os índices de paleta da equipe em meta.pixor.team, para engines que recolorem em tempo de execução pela textura de consulta abaixo.
• Todas as cores giradas: hue:120 gira cada tom colorido em 120 graus; os cinzas continuam cinzas.
• Outras paletas: palette:pixor-8 ou palette:my-colours.hex move cada cor para a mais próxima dessa paleta, mantendo claro e escuro separados.

Cada variante é name_<variant>.png. Com qualquer variante, o Pixor também grava dois arquivos para trocar paletas em tempo de execução, para que uma folha sirva a todos os níveis e times:

• name_index.png: a folha com o índice de paleta de cada pixel como valor de cinza (0 é transparente);
• name_lut.png: uma textura de consulta com 256 pixels de largura, uma linha por paleta (a linha 0 é a da própria folha, a linha k é a variante k).

Um shader consulta lut(index / 255, row). O JSON lista as variantes e as linhas delas em meta.pixor.variants.

A receita dentro de cada exportação

Todo arquivo que o Pixor exporta lembra o projeto que o fez: a folha, suas folhas de camadas e mapas (_lines, _flat, _normal, _depth, _emission, _shadow), suas variantes de paleta e folha de índices, o .aseprite e cada GIF (num comentário) e APNG. Solte qualquer um deles no Pixor (ou escolha-o em Abrir projeto) para recuperar o projeto: o arquivo .pixor, se ainda existir, ou um novo projeto reconstruído a partir da receita. Os caminhos são guardados relativos ao arquivo exportado; um caminho que não pode ser relativo guarda só o nome do arquivo, então uma folha que você compartilha não mostra os nomes das suas pastas. Desmarque Receita nos arquivos (ou passe --no-recipe) para deixá-la de fora.

Godot 4

1. Copie name.png e name.tres para o seu projeto, lado a lado.
2. O .tres carrega a folha de res://name.png. Se você a colocar em outro lugar, passe --godot-path res://path/name.png ao exportar pela linha de comando, ou edite o caminho no topo do .tres.
3. Crie um AnimatedSprite2D e defina o Sprite Frames dele como name.tres. Cada ação e lado é uma animação, em loop, com suas retenções de quadro.
4. Para pixels nítidos, defina Texture > Filter como Nearest.

Unity

• Com o pacote Aseprite Importer (2D Aseprite Importer): solte name.aseprite em Assets. Cada tag vira um clipe de animação; use a camada final.
• Sem ele: importe name.png como Sprite (Multiple), Filter Mode Point, Compression None, e fatie por tamanho de célula (o tamanho da célula está em name.json, em meta.pixor.cell). O pivô está em meta.pixor.pivot, em pixels a partir do canto superior esquerdo da célula.

GameMaker

Importe name.png como uma tira de sprites: use uma exportação com layout Strip (--layout strip) por animação, ou corte a grade pelo tamanho da célula. Defina a origem no pivô de name.json.

Aseprite

Abra name.aseprite, ou clique em Abrir no nó Arquivo Aseprite (o Pixor encontra o Aseprite no PATH e nas pastas de costume da Steam e do itch, e pergunta onde ele está nos outros casos). As tags listam cada ação e lado. A camada final fica visível; lines e flat são auxiliares ocultas para retocar à mão, assim como cada saída extra que o grafo de Estilo nomeia, acima de final. O arquivo fica em modo indexado com a paleta do Pixor.

Pinte por cima e mantenha o seu trabalho. Adicione as suas próprias camadas e pinte, depois mude o modelo ou o visual no Pixor e gere de novo:

pxr rebake out/hero.aseprite

O Pixor é dono do que ele gravou, e de nada mais. Uma nova geração renderiza o projeto de novo e:

• substitui os pixels das camadas que o Pixor fez (final, lines, flat), onde ninguém pintou;
• deixa suas camadas exatamente como estão — nunca movidas, renomeadas, reordenadas ou recoloridas — com cada cel pintado no quadro em que foi pintado. Cada quadro traz um id feito do que ele é (ação, lado, tempo), então se a caminhada ganhar três quadros no meio, os olhos que você pintou ficam nas suas próprias poses em vez de deslizar para as novas — e a nova renderização avisa, quadro a quadro: moved your paint on frame 1 is on frame 2 now, e quais quadros são novos (moved e new_at em --json);
• mantém cada cor com que você pintou no seu índice, adicionando cores novas no fim da paleta — ou, numa folha que você converteu para tons de cinza ou RGB no Aseprite, grava a renderização em cinzas ou em cores para combinar;
• mantém suas fatias, com as chaves nos quadros em que estavam, para onde quer que esses quadros tenham ido;
• marca com uma tag os quadros em que o modelo saiu de baixo da sua pintura, pxr check, e deixa a pintura onde está.

Duas coisas que ele não decide sozinho, e mantém ambas até você decidir:

O que aconteceu	O que a nova renderização faz
Você pintou numa das camadas do próprio Pixor	A camada do Pixor recebe a nova renderização; a sua edição vai para uma camada sua, final edits, logo acima dela; o quadro recebe a tag pxr conflict
Um quadro que você pintou não está na nova renderização (o clipe ficou mais curto)	o quadro é mantido no fim, com sua pintura, marcado com a tag pxr removed

Nada se perde, de um jeito ou de outro. pxr rebake então termina com o código 7 até você dizer para que lado vai: --resolve keep mantém suas edições como camadas suas, --resolve pixor fica com a renderização do Pixor e as descarta. --dry-run diz o que um novo rebake faria sem gravar nada, e --json diz isso para uma ferramenta; a extensão faz a mesma pergunta numa caixa de diálogo.

GIF e APNG

Cada ação e lado vira um arquivo próprio em loop (um clipe que não faz loop toca uma vez). Os quadros usam a paleta do sprite, com o índice 0 transparente. Escala, no nó GIF ou APNG (--anim-scale K), os amplia por um número inteiro, de 1 a 16, para que um sprite de 64 px possa sair como um GIF de 256 px com cada pixel ainda nítido.

O GIF guarda os atrasos em centésimos de segundo, então o atraso de cada quadro é arredondado, mas a duração total do clipe é mantida. Os navegadores mostram atrasos abaixo de 20 ms como 100 ms, então nenhum quadro de GIF é mais curto que 20 ms: acima de 50 fps o GIF deixa de fora os quadros que ficariam visíveis por menos tempo e toca pelo tempo do clipe. O APNG guarda os milissegundos exatos, arredondados no total acumulado como os do JSON, então os quadros de um clipe a 12 fps têm 83 e 84 ms. Renomeie um arquivo .apng para .png se um site só aceitar PNG. Um clipe que o nó Camada de um grafo de asset desenhou anima essa camada — só os traços, as cores chapadas — como a folha a mostra; uma Camada dos mapas de normais, de profundidade ou de emissão anima o sprite, já que um GIF só guarda cores da paleta.

Vídeo

Vídeo por clipe grava cada ação e lado como name_walk_Southeast.avi: um AVI sem compressão, cor de 24 bits, que todo editor e conversor abre e que não perde nada — nenhum codec borra um pixel. O nó dele tem três ajustes:

• Escala (1 a 16, 4 de início): quantos pixels de vídeo valem um pixel da arte.
• Quadros por segundo (1 a 100, 30 de início): um vídeo roda numa só taxa, então um quadro de sprite é gravado tantas vezes quanto dura, e o clipe mantém sua duração com precisão de um quadro de vídeo.
• Fundo: o que fica atrás do sprite. Um vídeo não tem transparência.

--export video na linha de comando usa os valores iniciais, ou --video-scale K, --video-fps N e --video-background #RRGGBB. --export all deixa os vídeos de fora: nomeie-os.

Não é comprimido, então é grande — um sprite de 64 px em escala 4 tem cerca de 200 KB por quadro — e um vídeo acima de um gigabyte é recusado em vez de gravado. Para colocá-lo online, converta-o: ffmpeg -i hero_walk_South.avi -crf 0 hero_walk_South.mp4.

Engines simples e o seu próprio código

Leia name.json: frames[i].frame é o retângulo da célula e frames[i].duration sua retenção em milissegundos; meta.frameTags agrupa quadros em animações, e uma tag que toca uma vez em vez de fazer loop leva "repeat": "1", como o Aseprite grava. frames[i].pixor nomeia a tag do quadro (o nome da sua tag de quadro), seu index nela, sua action e seu side, seu id e seu pivot — o ponto da célula em que a engine apoia o sprite, que é o da folha, a menos que um nó Tag tenha dado ao clipe um próprio. A slice de pivô em meta.slices tem uma chave onde quer que o pivô mude, e a slice de pivô do arquivo .aseprite tem as mesmas chaves.

Root motion

Um clipe exportado No lugar tem mais dois valores por quadro, em pixels com as frações mantidas (x para a direita, y para baixo):

• frames[i].pixor.root: onde a raiz do modelo estaria, medida a partir de onde estava no início do clipe.
• frames[i].pixor.root_delta: quanto a raiz se move até o próximo quadro. No último quadro é o movimento até o fim do clipe, então caminhadas em loop continuam na mesma velocidade.

Para mover o personagem como o clipe fazia, some root_delta à posição do sprite cada vez que um quadro termina.

Ícones de inventário

pxr icons (ou um nó Ícones no grafo de asset, feito quando o projeto é exportado) transforma modelos em ícones de inventário que combinam entre si: cada modelo do mesmo ângulo de ¾ sob o conjunto de luzes Estúdio, a 16, 24, 32 e 48 pixels (ou --sizes), com a silhueta na cor da sua raridade (--rarity common|uncommon|rare|epic|legendary) e, com --framed, num tile emoldurado como um espaço de inventário. Cada ícone é um PNG, e cada tamanho ganha um atlas icons_N.png com icons_N.json dizendo onde cada ícone está. Aponte-o para uma pasta para transformar um pacote inteiro num conjunto de ícones — no app, solte a pasta na janela e ligue Ícones em vez de sprites: os tamanhos, a raridade (do nome de cada arquivo, a menos que você escolha uma) e a moldura estão ali, e a receita é salva ao lado dos ícones como icons.pixoricons:

pxr icons library/pickups --out icons --rarity epic --framed

--rarity from-name dá a cada modelo a raridade que uma palavra do nome do arquivo indica (potion_rare.glb, Sword-Epic.glb; sem essa palavra, é comum), e o JSON informa a de cada ícone. Os arquivos são lidos em ordem de nome, então o atlas é o mesmo independentemente de como a pasta os lista.

Uma receita guarda o pacote: --save pack.pixoricons grava as pastas e os ajustes (caminhos relativos à receita), e pxr icons pack.pixoricons refaz o pacote, byte a byte. Um objeto de cena adicionado à pasta entra na próxima execução; uma flag depois da receita altera um ajuste para aquela execução (pxr icons pack.pixoricons --sizes 64).

Voxels e pilhas de sprites

Um .vox do MagicaVoxel abre como qualquer outro modelo: cada modelo da sua cena onde o grafo de cena o coloca (girado e movido como o MagicaVoxel mostra), sua paleta, e os voxels de um material brilhante brilhando. Um voxel é lido como um décimo de metro, +Z para cima.

pxr voxels MODEL -o hero.vox --height 32 transforma qualquer modelo em voxels, com 32 de altura: a superfície amostrada das suas texturas e cores, o interior preenchido, cada voxel na própria paleta do visual (--preset, --palette e as outras opções de visual), para que os voxels combinem com os sprites. Com --stack, ele também grava uma pilha de sprites: hero_stack.png, o modelo cortado em fatias horizontais lado a lado, de baixo para cima, cada uma vista de cima, e hero_stack.json com o tamanho e a quantidade de fatias. Um jogo desenha a fatia k um pixel acima da fatia k - 1 e gira todas juntas, que é como o sprite stacking simula o 3D.

pxr voxels knight.glb -o knight.vox --height 32 --stack --preset selout

Verificando se tudo bate

pxr audit folder --style game.pixorkit lê cada PNG e arquivo .aseprite exportado numa pasta e os confere com o kit, usando a receita dentro de cada arquivo: predefinição, conjunto de luzes, vista, inclinação da câmera, luz principal, faixas de luz, traços, paleta e pixels por metro, e se cada cor usada está na paleta do kit. Sem um kit, o primeiro arquivo é a referência. Cada diferença é listada; qualquer diferença faz o código de saída ser 1, então ele pode proteger um build.

No app, o quadro de consistência (o botão de três figuras, Quadro de consistência: todos os lados de uma vez, ou B) mostra o quadro atual de cada lado lado a lado numa mesma linha do chão, com o topo de cada silhueta marcado e a largura, a altura e a contagem de cores embaixo. Sob o botão:

• Silhuetas desenha cada lado só com a sua forma, numa cor: uma pose que não se lê como silhueta não se lê no tamanho do jogo.
• Pivôs marca o pixel em que cada lado se apoia e em torno do qual gira. Um lado cujos pés estão fora dele desliza quando o sprite gira.
• Contagem de cores grava a contagem de cada lado; o quadro avisa quando as alturas diferem mais de um pixel entre os lados (As alturas diferem … entre os lados), ou quando um lado tem bem mais cores que outro (normalmente uma luz que só um lado pega).

pxr audit, acima, é a metade que cobre a pasta inteira: cada folha contra um kit.

O que as verificações encontraram, nos pixels a que se referem

Cada verificação que o Pixor faz — pixels soltos, cantos de traço desenhados num pixel, traços grossos, uma cor fora da paleta, um tile ou um quadro com mais cores do que um modo de console permite — marca os pixels a que se refere, em vez de só imprimir uma linha de texto na hora de exportar.

• No app: o botão Verificações sobre o sprite (o triângulo de aviso) desenha as marcas no quadro, e a seção Relatório nas etapas Estilo e Asset lista cada achado de cada quadro renderizado até agora. Clique num deles e o Pixor vai para aquele quadro e lado com as marcas ligadas. Sob a lista, cada tipo de achado diz qual ajuste o decide — pixels soltos a limpeza, cantos serrilhados os traços, cores a paleta, limites de console o modo de console, um lado espelhado que não bate com o espelhamento da exportação — e Ir para abre esse ajuste.
• Lados espelhados: com um nó Espelhar no grafo de asset, um lado que vai ser desenhado espelhado é comparado com aquele que ele espelha, e, onde o modelo não é simétrico o bastante para isso, os pixels que mudam são marcados enquanto você ainda está escolhendo — não só um aviso na exportação.
• Na exportação: marque Relatório (ou --export report) e o Pixor grava name_report.png ao lado da folha: a folha com cada achado marcado. Pixels isolados são preenchidos; um tile ou um quadro ganha uma caixa em volta, para que aquilo de que se trata continue visível.

Cor	O quê
ciano	um pixel solto (um órfão)
amarelo	um traço que vira uma esquina em um pixel
magenta	um bloco de traço de dois por dois: um traço grosso
vermelho	um pixel fora da paleta
laranja	um tile de 8 x 8 com mais cores do que o console permite
laranja escuro	um quadro com mais cores do que o console permite
rosa	uma cor que o console não tem
violeta	um pixel que difere do lado de que é espelhado
caixa verde	uma parte desenhada na cor lisa porque o arquivo de textura está faltando: coloque o arquivo ao lado do modelo

Efeitos de pixel

Um nó Efeito do Grafo de cena (listado em Efeitos na Estrutura) adiciona um efeito desenhado a partir de partículas 3D: Explosão, Faísca de impacto, Corte, Explosão mágica, Cura, Portal, Baforada de fumaça, Poeira, Fogo em loop, Chuva, Neve, Vaga-lumes e Folhas caindo. Cada um é uma ação própria (fx-explosion, …), renderizada pelo mesmo pipeline que o modelo, então recebe a paleta, o tamanho de pixel, a luz e os traços do sprite: parece que pertence ao mesmo jogo. Defina os quadros, o tamanho, a energia, onde ele está e a semente (a mesma semente sempre dá os mesmos pixels); faça-o seguir um osso (um corte saindo da mão, um clarão num cano de arma) e tocar sobre um clipe (o golpe sob o corte, ou um clipe com chaves feito no Pixor); marque Só o efeito para desenhá-lo sem o modelo, como uma camada própria alinhada com a folha do personagem. Quadro de impacto marca o quadro em que o golpe acerta: o JSON o lista em meta.pixor.hits. Na linha de comando: --effect fireflies:12 --effect-clip shatter --effect-hit 6, com o clipe também feito no Pixor — estilhaços com chaves voando sob o brilho. Criar um efeito, na tela de um projeto vazio, ao lado de Importar… e Navegar por modelos gratuitos (ou pxr effect explosion -o fx.png), cria um efeito sem modelo nenhum.

Hitboxes, hurtboxes e pontos de fixação

A Caixa de uma parte no Inspetor (ou --hitbox, --hurtbox) a torna uma hitbox (ela causa golpes: uma espada) ou uma hurtbox (ela pode ser atingida: o corpo), e o Ponto de fixação no JSON de um osso (ou --socket) o torna um ponto de fixação (uma mão, um cano de arma). O JSON de cada quadro então traz pixor.boxes (part, kind, x, y, w, h em pixels da célula, a partir dos pixels que cada parte realmente cobre) e pixor.sockets (a posição de cada osso em pixels da célula), para que o código do jogo verifique golpes e prenda efeitos sem adivinhar. Um arquivo de modelo também pode marcar partes (pxr.box).

Camadas de paper doll

Com objetos de cena presos, Camadas de paper doll (--paper-doll) também grava name_base.png, o modelo sem os objetos de cena na mesma tela, e uma camada por objeto de cena (name_sword.png), com seus pixels visíveis e os traços ao redor. Empilhadas com a base primeiro, elas formam a folha completa; trocar a camada de um objeto de cena troca o equipamento. name_stacked.png é o empilhamento delas desse jeito, como a engine vai empilhá-las: a prévia que mostra que se alinham. Os pixels de cada peça são os da própria folha; a base é o corpo desenhado sem as peças, então só difere da folha a poucos pixels da borda de uma peça, e onde uma peça projeta sombra no corpo — desligue as sombras projetadas (--no-shadow) para camadas que se empilham com exatidão. Linhas que um nó Sprites desenha com um conjunto de partes pertencem à folha desse nó, não às camadas. (O app as faz com pxr a partir do projeto salvo, salvando-o antes quando ele mudou, então as camadas são o que está na tela.)

Equipamento que faz parte do modelo — um elmo, um escudo, uma capa modelados junto com o personagem em vez de presos como objeto de cena — é uma peça:

pxr render knight.glb --clip all --paper-doll --piece helmet:Knight_Helmet --piece gear:Round_Shield,1H_Sword
pxr project set knight.pixor --paper-doll --piece helmet:Knight_Helmet

Cada peça nomeia as partes de que é feita (como a Estrutura as lista) e vira uma camada própria, name_helmet.png, exatamente como a de um objeto de cena (no app, Sua própria camada de paper doll de uma parte a transforma numa, com o nome dela): só os pixels dela que aparecem, então um escudo atrás do corpo fica oculto onde o corpo o esconde. A base é renderizada sem nenhuma peça nem objeto de cena, então o que um elmo cobria — a cabeça embaixo dele — é desenhado ali. --no-pieces as remove de um projeto. O nó Camada de um grafo de asset nomeia base ou uma peça ou objeto de cena pelo nome como sua camada, para dispor as camadas como quiser (Grafo de asset).