pixel-mascot

Criando um mascote pixel

Um mascote é um único arquivo SVG de pixel art com animação CSS em steps. Ele pode ter vários estados (idle, feliz, dormir, andar, atacar…), cada um é uma classe no elemento raiz: <svg class="happy"> reproduz happy. Construa mascotes com código, nunca editando manualmente centenas de <rect>s: a pasta scripts/ desta skill (<kit> abaixo) contém um pequeno kit e um exemplo funcional. Tudo é biblioteca padrão Python; nada para instalar.

Leia LESSONS.md ao lado deste arquivo antes de desenhar qualquer coisa. Ele lista, com o sintoma, a causa e a correção, o que deu errado enquanto os primeiros mascotes eram feitos, e a maior parte vai dar errado novamente se for ignorada.

Onde as coisas vão

Pergunte ao usuário onde manter o mascote. Se ele não tiver preferência, use ~/pixel-mascots/<nome>/ (no Windows %USERPROFILE%\pixel-mascots\<nome>\):

Arquivo	O que é
make_<nome>.py	o construtor: toda mudança é uma edição aqui e uma reexecução
<nome>.svg	a saída da construção, o próprio mascote
<nome>_overrides.json	as edições manuais do usuário do estúdio, aplicadas por último pelo construtor
sheet.png	a prévia, um quadro fixo por estado

<nome> são letras minúsculas, dígitos e hífens. Nunca coloque arquivos do usuário em <kit>: ele pertence ao plugin instalado e é substituído na atualização.

Executando os scripts

Use qualquer Python que a máquina tiver: python3 (macOS, Linux), python (Windows), ou uv run python onde um shim bloqueia o python puro. Os construtores importam o kit, então coloque <kit> no PYTHONPATH ao executar um:

PYTHONPATH="<kit>" python3 make_<nome>.py <nome>.svg

$env:PYTHONPATH = "<kit>"; python make_<nome>.py <nome>.svg

preview.py e o estúdio não precisam de PYTHONPATH; o estúdio define ele para os construtores que executa.

O que o SVG deve fazer

1. Um estado por classe raiz. Estilize cada estado com seletores .<estado> .parte{...}; os nomes das classes são os nomes de estado do usuário (minúsculas, hífens). O construtor escreve um estado padrão na raiz (s.svg(..., state="idle")), então o arquivo anima sozinho no navegador ou em um <img>; um aplicativo mostra outro estado alterando a classe da raiz. Sem estados nomeados, crie um: idle.
2. Coloque toda cor em uma classe CSS dentro de seu próprio <style>. Uma variável CSS (var(--accent,#hex)) funciona apenas lá, nunca como atributo fill=.
3. Anime com keyframes steps(1) que movem células inteiras (translateY(-1px) em um viewBox de células) ou piscam opacidade.
4. Tenha um <title> (texto alternativo) e nenhum <script>, nenhum on…=, nenhuma imagem externa, fontes ou links, para que seja seguro exibir em qualquer lugar.
5. Defina seu tamanho desenhado com width/height na raiz, um múltiplo inteiro da grade: 32 células a 128 px (4 px por célula), 20 células a 80 px.
6. Respeite o movimento reduzido a menos que o usuário diga o contrário: @media (prefers-reduced-motion:reduce){*{animation:none!important}}.

O fluxo de trabalho

1. Defina o que é o mascote, seus estados e suas 3-5 características de identidade. Pergunte o que o torna reconhecível a 128 px, exagere exatamente essas e descarte todo o resto. Pergunte quais estados ele precisa; sem resposta, faça um loop idle. A ideia do usuário decide, não o exemplo aqui. Se o usuário compartilhar arte de outros artistas, use-a apenas como direção (proporções, estilo de contorno, como uma característica é desenhada): nunca copie os pixels deles, e nunca coloque um personagem protegido por direitos autorais em uma construção que seja compartilhada ou publicada.

2. Encontre seu tipo nesta tabela. Ela diz quais partes dividir (cada parte anima sozinha) e o que pode carregar movimento secundário, que é o que faz um mascote parecer vivo em vez de um adesivo que quica.

   Tipo	Características de identidade típicas	Partes, de trás para frente	Movimento secundário
   Personagem humanóide	formato e cor do cabelo, olhos, um acessório, roupa, um item segurado	cabelo-traseiro, corpo, cabeça (rosto, franja, mechas frontais), acessório	balanço/inclinação de cabeça, acompanhamento de cabelo, balanço do acessório
   Animal	orelhas, marcas, cauda, focinho, cor dos olhos	cauda, corpo, orelhas (aninhadas na cabeça), cabeça	orelhas balançam, cauda abana, inclinação de cabeça
   Objeto (lâmpada, caneca, planta, aspirador robô)	silhueta, um detalhe marcante	traseiro (cabo, suporte), corpo, rosto (um rosto desenhado nele), partes móveis	vapor ou folha balançam, luz pisca, rodas giram
   Criatura / blob / robô	silhueta, uma característica estranha (chifre, antena, viseira, brilho)	traseiro, corpo, cabeça, apêndice	compressão e estiramento, antena balança, brilho pisca

   Mascotes sem rosto ainda precisam de estados legíveis: mude a pose, os efeitos e a velocidade em vez da expressão.

3. Escolha a tela. 20×20 para uma forma simples com poucas características; 32×32 para qualquer coisa com várias características ou um rosto que precise expressar. Corte no peito ou no assento para personagens: o rosto e as características de identidade precisam mais do espaço do que as pernas. Desenhe a 4 px por célula.

4. Copie o template <kit>/example_mascot.py (Miso, um gato com três estados) para make_<nome>.py na pasta do mascote, defina NAME e substitua as formas e estados. Mantenha o construtor: o SVG é uma saída da construção. Mantenha o último passo do template, apply_overrides(...): ele aplica as edições manuais do usuário do estúdio (passo 10), então a reconstrução nunca as perde.

5. Desenhe de trás para frente, uma parte por coisa que se move sozinha. Aninhe um apêndice dentro do que ele está preso (orelhas dentro da cabeça), para que siga o movimento dessa parte e ainda possa se mover sozinho. Ferramentas do kit: rect, ellipse, polygon (orelhas, barbatanas, chifres), path (caudas, cabos, caules), line, zigzag_bottom (bordas de cabelo ou franja), paint(..., only=...) para desenhar detalhes em formas existentes, shade_edges para sombras e bordas. Chame s.outline() uma vez no final, para que cada parte carregue seu próprio contorno. Para personagens com cabelo, siga "Personagens com cabelo" em LESSONS.md.

6. Um rosto (ou pose) por estado, como grupos alternados com regras de opacidade: f-aberto por padrão, mais o que couber em cada estado. As reações são mais legíveis quando diferem na forma, não apenas na cor: olhos fechados ^ ^, olhos semicerrados, boca aberta, uma faixa de sombra. Rostos desenhados em um personagem com franja pulam as células de cabelo.

   • Ajuste cada estado ao personagem. Quando um estado não combina com ele, pergunte e ofereça momentos da própria história do personagem: um gesto ou cena marcante. Grandes mudanças na silhueta são legíveis a 128 px; pequenos detalhes (uma gema de 2 pixels, uma boca que abre e fecha) não.
   • Um estado pode trocar partes inteiras, não apenas rostos: um acessório ligado ou desligado, um chapéu puxado para dormir. Faça cada peça intercambiável sua própria parte e esconda ou mostre com .<estado> .parte{opacity:…}. Escopo toda regra assim para um estado, para que os outros estados mantenham suas partes.
   • Quando o usuário estiver em dúvida, construa alternativas em vez de argumentar por uma: faça o construtor aceitar um nome de variante como argumento, construa cada uma em seu próprio arquivo e mostre-as lado a lado. Mantenha a variante que o usuário gostou: uma reversão deve ser um argumento.

7. Efeitos com s.fx(nome, cls, quadros): brilhos, linhas de velocidade, Z's, marcas de oscilação, gotas de suor. Os quadros tornam-se s1, s2… para animar fora de sincronia.

8. Movimento: keyframes steps(1) e movimentos de célula inteira (pixel art deve pisar, não deslizar). A figura inteira fica em um grupo .rig que pula ou balança; sobre isso:

   • a cabeça balança, inclina ou acena sozinha (até 2 células);
   • apêndices (cabelo, orelhas, cauda, antena) seguem no máximo um quarto de ciclo atrasado; meio ciclo coloca-os no lado oposto e parece um rastro;
   • acessórios e partes móveis funcionam ligeiramente fora do ritmo. Um loop idle é lento e pequeno: respiração, uma piscada, uma cauda.

9. Construa e veja antes de mostrar a alguém (comandos como em "Executando os scripts"):

   PYTHONPATH="<kit>" python3 make_<nome>.py <nome>.svg
   python3 <kit>/preview.py <nome>.svg sheet.png
   

   então leia sheet.png: um quadro fixo por estado, da esquerda para a direita. A prévia mostra apenas poses de repouso. Para ver o movimento, inicie o estúdio em segundo plano e abra http://127.0.0.1:8765/ em um navegador (o painel de navegador embutido, se houver):

   python3 <kit>/studio/server.py --svg <nome>.svg --build make_<nome>.py
   

   Ele mostra cada estado animando em seu próprio quadro. --states a,b seleciona e ordena os estados (padrão: todo estado que o CSS usa, na ordem em que aparecem pela primeira vez); --port altera a porta. Os usuários revisam a partir de capturas de tela e frequentemente marcam problemas em vermelho: mapeie as marcas para células alinhando-as com características que você conhece (a fileira dos olhos, a boca), então redesenhe ao longo delas. Após uma refatoração que não deve mudar nada visível, construa a versão antiga e a nova e compare os arquivos byte por byte (cmp ou fc /b).

10. Edições manuais. Quando o usuário quiser corrigir pixels ele mesmo, envie-o para o /editor.html do estúdio: pinte, apague e selecione cores por estado, desfaça, depois salve, que escreve <nome>_overrides.json e reconstrói. Cada pixel pertence a uma parte e se move com ela; o editor diz qual parte e quais estados o mostram. Um mascote sem construtor também funciona (omitir --build): o estúdio mantém uma cópia intacta e as edições em <nome>_studio/ ao lado do SVG e escreve o resultado no SVG. Após o usuário editar, leia o arquivo de substituições e a prévia reconstruída antes de mudar qualquer outra coisa, e diga se uma edição parece acidental (um pixel solitário longe do resto).

11. Entregue: diga onde está o SVG, qual estado ele reproduz por padrão e como mostrar outro (defina a classe da raiz; um <img> não pode, então um aplicativo que alterna estados incorpora o SVG inline ou o carrega em um <object> ou <iframe>).

profile.json (para um aplicativo que mostra o mascote)

Um aplicativo pode precisar de mais do que classes raiz: variáveis CSS na raiz, classes extras, rótulos de estado fixos. Um profile.json colocado em <kit> ao lado de preview.py informa a prévia e o estúdio. Toda chave é opcional:

{
  "states": [{ "class": "happy", "name": "happy", "label": "happy · ao sucesso", "style": "--speed:.5s" }],
  "rootClass": "always-animate",
  "swatches": { "var": "--accent", "label": "acento", "colors": ["#8FA8E8", "#ED93B1"] },
  "workdir": "~/my-app/studio"
}

states fixa a ordem, os nomes dos botões, as legendas e um estilo raiz por estado; rootClass é adicionado à raiz em todo quadro; swatches adiciona botões de cor que definem uma variável CSS; workdir substitui <nome>_studio/ para mascotes sem construtor. Este plugin não envia nenhum.

Arquivos nesta skill

Arquivo	O que é
LESSONS.md	O que funcionou e o que não funcionou, com causas e correções. Leia primeiro.
scripts/pixelkit.py	Formas (rect, ellipse, polygon, path, line), partes, sombreamento, contornos por parte, saída SVG.
scripts/example_mascot.py	Miso: um gato 32×32 com idle, feliz e dormir; o template para copiar.
scripts/preview.py	Folha PNG, um quadro fixo por estado, apenas biblioteca padrão.
scripts/pixel_overrides.py	Aplica edições manuais a um SVG finalizado; construtores o chamam por último.
scripts/studio/	server.py + site/: cada estado animando, e um editor de pixels, para qualquer mascote. Apenas local (127.0.0.1).