PixelForge — Criação, Refinamento e Animação de Pixel Art para Modelos de Linguagem Visual
Esta habilidade, através de ./scripts/pforge.py (que oferece tanto CLI quanto a biblioteca Python pixelforge, dependendo apenas de Pillow), capacita um LLM visual com capacidade industrial de produção e refinamento reverso de ativos de pixel art.
1. Regras Cardinais (Violação Proibida)
- Proibido escrever listas esparsas de pontos de coordenadas: É estritamente proibido empilhar dezenas de linhas de
putpixel((x, y)). Formas básicas devem usar grade de caracteres ASCII monoespaçada (.e espaços representam transparência), partes locais compactasRig(desenhe apenas a parte e posicione comoffset=(ox, oy), sem preencher a tela inteira com pontos), ouPixelCanvaspara primitivas geométricas (linhas anti-canto L, elipses simétricas, dithering Bayer ordenado). - Escolha a arquitetura correta com base na resolução:
16x16 ~ 32x32: Escreva diretamente uma grade ASCII de tela cheia ouRigleve.48x48 ~ 64x64: Deve ser dividido em camadas/partes (use partes coloridas sem contorno externo +Rig(..., outline_mode="selout"|"outer")para contorno unificado automático); para modificar detalhes, prefira Region Patch (fatia local) em vez de redesenhar a imagem inteira.64x64 ~ 128x128+: Use rascunho geométricoPixelCanvas+stamp()para carimbo local +dither_rect()para dithering ordenado + Region Patch local para refinamento.
- Ciclo de Visão Holográfico Multimodal Obrigatório:
- Cada geração ou modificação gera um painel de diagnóstico holográfico
<name>_inspect.png(contendo: legenda da paleta de caracteres[char] #HEX+ grade de coordenadas(X, Y)iniciando em 0 e linha de base do solo + pré-visualização em fundo claro/escuro sem grade + silhueta e trajetória de movimento em cebola vermelha/ciano) e um relatório dePixel Linterno terminal. - Antes de entregar, você DEVE usar uma ferramenta de visualização (como
read_file/view_image/Read) para inspecionar pessoalmente o<name>_inspect.png(para tarefas de modificação, também veja<name>_diff.png)! - Usando as coordenadas na imagem e os avisos do Linter, verifique um a um: aberturas no contorno externo (especialmente ao verificar contornos escuros em fundo claro), serrilhado em linhas diagonais/arcos (Jaggies), deslocamento da base dos pés entre quadros (
baseline_y) e pixels alterados inesperadamente. Corrija e verifique novamente antes de entregar.
- Cada geração ou modificação gera um painel de diagnóstico holográfico
2. Árvore de Decisão do Caminho Mais Curto Zero Atrito para Agentes (Priorize saída direta sem script!)
Antes de agir, escolha o método de chamada que economiza mais tokens e requer menos código boilerplate, na seguinte ordem de prioridade:
- Consultar tons de caracteres da paleta (evite chutar caracteres e receber erro):
- MCP:
pixelforge_palette_guide(palette="endesga32"); CLI:python3 <SKILL_DIR>/scripts/pforge.py palette-guide endesga32 - Obtenha diretamente as cadeias de caracteres agrupadas por matiz (
Sombra -> Tom Médio -> Realce), por exemplo'b' -> 'B' -> 'C', sem precisar consultar tabelas.
- MCP:
- Personagens multi-partes / Chefes /
.asepritede múltiplas ações em camadas (0 linhas de código Python, zero aritmética de ajuste)::- Chame MCP
pixelforge_build_rig(ou CLIpforge.py build-spec spec.json/ Pythonbuild_from_spec(spec)):- Sintaxe de grade tolerante a erros: Suporta
|..BBBB..| # comentário no final da linhacom barras verticais para alinhamento visual epad_ragged=Truepara preencher automaticamente.faltantes no final! - Ajuste de juntas semântico (sem calcular coordenadas e eixos): O tronco principal define
at="center", outras partes escrevem diretamenteattach_to="torso", side="top"|"left"|"right"|"bottom", hinge="grip",canvas_size="auto"calcula automaticamente a caixa delimitadora do corpo inteiro e adiciona margem para evitar corte ao balançar uma espada. - Presets de ação em uma linha:
clips={"idle": "idle_breathe", "attack": "melee_attack", "hit": "hurt_flash"}(também suporta"float_bob","slime_bounce"ouposespersonalizadas), que adiciona automaticamente efeitos de corte/fumaça, sombras e.asepritede múltiplas camadas!
- Sintaxe de grade tolerante a erros: Suporta
- Chame MCP
- Ícones e objetos pequenos de 16x16 ~ 32x32:
- Chame MCP
pixelforge_build(suporta desenhar blocos de cor sem contorno e passaroutline_mode="selout", add_shadow=Truepara adicionar contorno e sombra automaticamente).
- Chame MCP
- Geometria programática complexa / Isométrica / Scripts de sandbox de combate real:
- Primeiro execute
python3 <SKILL_DIR>/scripts/pforge.py init-script work/run.py --template rig|sprite|scene|isopara gerar um scaffold executável configurado automaticamente comsys.pathrelativo, depois preencha a lógica (evitando a depuração manual de concatenação de caminhos).
- Primeiro execute
3. Seis Fluxos de Trabalho Padrão
1. Construindo Pixel Art e Animações Multi-Ação do Zero
- Selecione a paleta: Prefira paletas clássicas integradas
"endesga32","pico8","sweetie16","resurrect64","gameboy", ou usepforge.py palette <ref.png>para extrair a paleta e os tons de uma imagem de referência. Fonte de luz padrão no canto superior esquerdo (realce superior esquerdo quente, sombra inferior direito fria); recomenda-se ativaroutline_mode="selout"(contorno adaptativo à fonte de luz). - Construir e Rigging:
- Grandes mudanças topológicas (pernas cruzadas ao andar, deformação de presas ao abrir a boca) → Use quadros-chave ASCII ou dicionário de multi-estado
Part{"closed": ..., "open": ...}. - Rotação/compressão de corpo rígido (tampa de caixa abrindo na dobradiça, balançar de espada, respiração quicando) → Use
Rig+rotspritepara rotação em torno de ponto de ancoragem esquash_stretch. - Ritmo de impacto → Deve usar
durations_msnão uniformes (ex.: carregamento180ms→ golpe rápido40ms→ quadro de pausa55ms→ amortecimento150ms), combinado comvfx_slash_arc/vfx_dust_puff/vfx_hit_spark. - Múltiplas ações para um único personagem (
idle/walk/attack) → UseSpriteActorpara exportar GIFs independentes e atlas combinado<actor>_master_atlas.png/.json.
- Grandes mudanças topológicas (pernas cruzadas ao andar, deformação de presas ao abrir a boca) → Use quadros-chave ASCII ou dicionário de multi-estado
- Execute o script para exportar GIF + APNG com transparência real + WebP dinâmico sem perdas + Aseprite JSON, leia
_inspect.pngpara auto-inspeção visual e corrija defeitos.
2. Modificando Pixel Art Existente (PNG / GIF / Spritesheet)
- Diagnóstico visual primeiro:
(Nota: O motor reconhece automaticamente imagens de pré-visualização ampliadas em múltiplos inteirospython3 <SKILL_DIR>/scripts/pforge.py inspect input.png -o work/4x/8xe as restaura sem perdas para a grade de pixels nativa1x; se precisar manter a escala original, adicione--keep-scale.) - Descompilação e modificação de imagem pequena/quadro completo:
Desmonta automaticamente todos os quadros e suas durações, gerandopython3 <SKILL_DIR>/scripts/pforge.py decompile walk.gif -o work/walk_proj/edit_walk.pycom paleta de caracteres semântica e_inspect.png. Depois de modificar o script, execute novamente. - Cirurgia local em imagem grande (Region Patch, altamente recomendado para 48x48+):
Deve ler o# 1) Recorte a grade local pela caixa de coordenadas (X,Y,W,H) iniciando em 0. A imagem de auto-inspeção gerada retém automaticamente as marcações de coordenadas X/Y globais! python3 <SKILL_DIR>/scripts/pforge.py region-extract hero.png --box 14,6,20,18 -o work/patch/ # 2) Edite o arquivo de grade de caracteres .txt recortado e depois escreva de volta, gerando automaticamente uma imagem de comparação Before | After | Diff python3 <SKILL_DIR>/scripts/pforge.py region-apply hero.png --patch work/patch/hero_x14_y6_w20_h18.json -o work/out/*_diff.pnggerado, confirmando que as alterações estão estritamente dentro da área alvo e a conexão das bordas é natural. - Recolorização semântica com um clique / Variação de facção:
python3 <SKILL_DIR>/scripts/pforge.py recolor slime.gif --map B=R,b=r,C=Y -o work/fire_slime/
3. Convertendo Imagens de Alta Resolução / Esboços Conceituais de IA para Pixel Art (Pixelate & Clean)
Quando o usuário fornece ilustrações de alta resolução, fotos ou "pseudo pixel art" de IA com bordas borradas:
# Use contrast_box para ilustrações/conceitos; use --mode dominant_block para pseudo pixel art de IA para eliminar grades distorcidas e ruído de cor
python3 <SKILL_DIR>/scripts/pforge.py pixelate draft.png --size 48x48 --palette endesga32 --outline "#181425" -o work/px/
Leia os *_compare.png e *_inspect.png gerados. No edit_*.py gerado automaticamente, acenda manualmente os brilhos dos olhos, suavize os degraus do contorno e depois entregue.
4. Tilesets Sem Costura, Auto-Tile de 47 Blocos, UI 九宫格, Isométrico e Auto-Inspeção de Brilho de Cena Real
- Tijolo sem costura e UI 九宫格:
pforge.py tile grass.png(detecção de falhas 3x3 destacada em vermelho);pforge.py nine-slice frame.png --margins 4,4,4,4 --size 160x56. - Auto-tile de 47 Blob / 16 Wang: Forneça apenas dois tijolos base de primeiro plano/fundo, chame
pforge.py autotile --fg grass.png --bg water.png --mode blob47(ou Pythongenerate_blob47_tileset), ele combinará automaticamente todas as curvas internas/externas e criará um mapa de teste de ilhas*_blob47_inspect.png. - Edifícios isométricos
2:1e personagens RPG 4/8 direcionais: UseIsoScenepara construir cenas de blocos isométricos2:1com três faces iluminadas e sem lacunas; useDirectionalRig+export_multidir_sheetspara derivar atlas de rotação e caminhada de 4 ou 8 direções (S/E/N/W) a partir de uma parte frontal, e leia*_alignment_inspect.pngpara verificar as linhas de alinhamento horizontal do topo da cabeça/base dos pés. - Sandbox de cena real com múltiplos ativos e auto-inspeção de brilho/escala de cinza: Use
SceneComposer+render_pixel_text(fonte de pixel compacta integrada) +build_scene_mockuppara compor GIFs de combate/exploração com ordenação de oclusão no eixo Y e UI de caracteres. Deve ler*_scene_inspect.pngpara verificar o mapa de calor de contorno e a imagem de olho semicerrado em escala de cinza pura, eliminando problemas de brilho onde o personagem se funde com o fundo.
5. Iluminação Dinâmica HD-2D com Mapas de Normais e "Concept Art → Auto-Rig"
- Mapa de normais HD-2D e iluminação de tocha 360°: Chame
pforge.py normalmap hero.png --emit "#2CE8F5"ouexport_hd2d_bundle(..., part_layers=rig.render_part_layers(..., part_profiles={"sword": "ridge"}))para exportar com um clique*_albedo.png,*_normal.png,*_emission.pnge*_torch_orbit_6x.gifcompatíveis com Godot/Unity, e veja a imagem de verificação de ponto de luz de quatro quadrantes*_hd2d_inspect.png. - Decomposição automática de concept art e rigging (Sketch-to-Rig): Para imagens de concept art de partes decompostas em fundo sólido, execute
pforge.py autorig sheet.png --canvas 56x56 --palette endesga32(remoção segura de fundo por inundação de borda, decomposição de componentes conectados, escala unificada de cores, inferência de eixos de ombro/pescoço/cabo de espada). Veja*_autorig_pipeline.pnge depois refine os movimentos norig_*.pygerado.
6. Leitura e Escrita de Projetos Binários .aseprite Nativos com Camadas e Ferramentas MCP Diretas
- Suporte bidirecional a projetos
.aseprite: Todos os fluxos de construção geram por padrão o binário nativo<name>.aseprite; usandoRig.render_named_layers_sequence(poses)+write_aseprite(...)é possível salvar partes e efeitos como camadas de linha do tempo independentes + tags de ação + Slice de eixo de junta para que artistas humanos possam continuar desenhando em camadas diretamente no Aseprite; arquivos.ase/.asepriteexistentes podem ser desmontados reversamente compforge.py aseprite-inspect file.aseprite --unpack-layersoudecompile. - Prioridade para ferramentas MCP nativas: Se a sessão atual já estiver conectada ao MCP Server
pixelforge(que expõe 12 ferramentas, incluindopixelforge_palette_guide,pixelforge_build,pixelforge_build_rig,pixelforge_region_patch,pixelforge_scene_check,pixelforge_aseprite_inspect, e cada retorno vem comagent_checklist.must_view_imagese(x, y)de prescrições de reparo), prefira chamar diretamente as ferramentas MCP em vez de escrever scripts temporários.
4. Modelo Declarativo Python sem Aritmética
import sys
sys.path.insert(0, "/caminho/para/pixel-forge/scripts")
from pforge import build_from_spec, format_palette_guide
# Construção de personagem multi-partes, multi-ação com .aseprite de camadas independentes sem aritmética de coordenadas
res = build_from_spec({
"name": "ember_knight",
"palette": "endesga32",
"canvas_size": "auto",
"outline_mode": "selout",
"parts": [
{"name": "torso", "at": "center", "grid": ["|..RRRR..| # Peitoral", "|.RYYYYR.|", "|RRRRRRRR|", "|.rrrrrr.|"]},
{"name": "head", "attach_to": "torso", "side": "top", "grid": ["|.1111.|", "|1KKKK1|", "|.2222.|"]},
{"name": "sword", "attach_to": "torso", "side": "right", "hinge": "grip", "outline_group": 1,
"grid": ["|.W.|", "|.1.|", "|YYY|", "|.o.|"]},
],
"clips": {"idle": "idle_breathe", "attack": "melee_attack", "hit": "hurt_flash"},
}, output_dir="output")
# Em seguida, use OBRIGATORIAMENTE uma ferramenta visual para verificar todos os painéis em res["agent_checklist"]["must_view_images"]!
5. Manual de Referência Avançado (Leia Conforme Necessário, Divulgação Progressiva)
Antes de executar sub-tarefas específicas, consulte os guias especializados neste diretório de habilidades conforme necessário:
- Modelagem de pixel art, anti-aliasing de clusters de cores, tons claro-escuro e técnicas de dithering: craft_and_shading.md
- Desmontagem reversa, cirurgia de patch local em imagens grandes e refinamento de pixel art de IA: edit_and_pixelate.md
- Rigging de ossos multi-partes, rotação RotSprite, receitas de duração de quadros de golpe e biblioteca de efeitos: animation_and_rigging.md
- Design de Tileset Sem Costura 3x3 e Especificação de UI 9-Slice: tileset_and_ui.md
- Auto-terreno de 47 blocos, auto-inspeção de brilho de cena real, isométrico 2:1 e derivação de personagem 4/8 direções: world_iso_and_scene.md
- Iluminação dinâmica HD-2D com mapas de normais e auto-rigging de concept art de IA: hd2d_and_autorig.md
- Leitura e escrita de projetos binários
.asepritenativos com camadas e guia do MCP Server: aseprite_and_mcp.md - Dicionário de consulta rápida de parâmetros CLI completos e API Python: cli_and_api.md
- Scripts de exemplo práticos executáveis: Veja o diretório
./examples/para 10 scripts de ponta a ponta (01a10).