CommunityImagemgithub.com

pixel-forge

Ferramenta multimodal completa para criação, edição e animação de pixel art com suporte a PNG/GIF/APNG/WebP e spritesheets.

O que é pixel-forge?

PixelForge é um kit de ferramentas profissional para agentes de IA (como Claude Code, Cursor, Codex) que capacita modelos de linguagem visual a produzir, modificar e animar pixel art em escala industrial. Ele oferece uma abordagem declarativa e de baixo atrito, permitindo construir sprites, ícones, tilesets e animações complexas sem necessidade de coordenadas manuais ou código boilerplate. O sistema suporta múltiplos fluxos de trabalho: criação do zero com grade ASCII ou partes modulares (Rig), edição cirúrgica de imagens existentes via patches regionais, pixelização de imagens de alta resolução ou rascunhos de IA, animação com RotSprite e quadros de duração variável, geração de tilesets seamless e UI 九宫格, e até mesmo rigging automático a partir de concept art. A ferramenta prioriza o uso direto de ferramentas MCP (12 ferramentas expostas, como `pixelforge_palette_guide`, `pixelforge_build_rig`, `pixelforge_region_patch`) e requer verificação visual obrigatória através de painéis de diagnóstico (`_inspect.png`) para garantir a qualidade do resultado final.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/scvxzf1/pixel-forge/tree/main

Installed? Explore more Imagem skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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)

  1. 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 compactas Rig (desenhe apenas a parte e posicione com offset=(ox, oy), sem preencher a tela inteira com pontos), ou PixelCanvas para primitivas geométricas (linhas anti-canto L, elipses simétricas, dithering Bayer ordenado).
  2. Escolha a arquitetura correta com base na resolução:
    • 16x16 ~ 32x32: Escreva diretamente uma grade ASCII de tela cheia ou Rig leve.
    • 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étrico PixelCanvas + stamp() para carimbo local + dither_rect() para dithering ordenado + Region Patch local para refinamento.
  3. 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 de Pixel Linter no 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.

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:

  1. 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.
  2. Personagens multi-partes / Chefes / .aseprite de múltiplas ações em camadas (0 linhas de código Python, zero aritmética de ajuste)::
    • Chame MCP pixelforge_build_rig (ou CLI pforge.py build-spec spec.json / Python build_from_spec(spec)):
      • Sintaxe de grade tolerante a erros: Suporta |..BBBB..| # comentário no final da linha com barras verticais para alinhamento visual e pad_ragged=True para preencher automaticamente . faltantes no final!
      • Ajuste de juntas semântico (sem calcular coordenadas e eixos): O tronco principal define at="center", outras partes escrevem diretamente attach_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" ou poses personalizadas), que adiciona automaticamente efeitos de corte/fumaça, sombras e .aseprite de múltiplas camadas!
  3. Ícones e objetos pequenos de 16x16 ~ 32x32:
    • Chame MCP pixelforge_build (suporta desenhar blocos de cor sem contorno e passar outline_mode="selout", add_shadow=True para adicionar contorno e sombra automaticamente).
  4. 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|iso para gerar um scaffold executável configurado automaticamente com sys.path relativo, depois preencha a lógica (evitando a depuração manual de concatenação de caminhos).

3. Seis Fluxos de Trabalho Padrão

1. Construindo Pixel Art e Animações Multi-Ação do Zero

  1. Selecione a paleta: Prefira paletas clássicas integradas "endesga32", "pico8", "sweetie16", "resurrect64", "gameboy", ou use pforge.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 ativar outline_mode="selout" (contorno adaptativo à fonte de luz).
  2. 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 + rotsprite para rotação em torno de ponto de ancoragem e squash_stretch.
    • Ritmo de impacto → Deve usar durations_ms não uniformes (ex.: carregamento 180ms → golpe rápido 40ms → quadro de pausa 55ms → amortecimento 150ms), combinado com vfx_slash_arc / vfx_dust_puff / vfx_hit_spark.
    • Múltiplas ações para um único personagem (idle / walk / attack) → Use SpriteActor para exportar GIFs independentes e atlas combinado <actor>_master_atlas.png/.json.
  3. Execute o script para exportar GIF + APNG com transparência real + WebP dinâmico sem perdas + Aseprite JSON, leia _inspect.png para auto-inspeção visual e corrija defeitos.

2. Modificando Pixel Art Existente (PNG / GIF / Spritesheet)

  • Diagnóstico visual primeiro:
    python3 <SKILL_DIR>/scripts/pforge.py inspect input.png -o work/
    
    (Nota: O motor reconhece automaticamente imagens de pré-visualização ampliadas em múltiplos inteiros 4x/8x e as restaura sem perdas para a grade de pixels nativa 1x; se precisar manter a escala original, adicione --keep-scale.)
  • Descompilação e modificação de imagem pequena/quadro completo:
    python3 <SKILL_DIR>/scripts/pforge.py decompile walk.gif -o work/walk_proj/
    
    Desmonta automaticamente todos os quadros e suas durações, gerando edit_walk.py com 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+):
    # 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/
    
    Deve ler o *_diff.png gerado, 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 Python generate_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:1 e personagens RPG 4/8 direcionais: Use IsoScene para construir cenas de blocos isométricos 2:1 com três faces iluminadas e sem lacunas; use DirectionalRig + export_multidir_sheets para 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.png para 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_mockup para compor GIFs de combate/exploração com ordenação de oclusão no eixo Y e UI de caracteres. Deve ler *_scene_inspect.png para 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" ou export_hd2d_bundle(..., part_layers=rig.render_part_layers(..., part_profiles={"sword": "ridge"})) para exportar com um clique *_albedo.png, *_normal.png, *_emission.png e *_torch_orbit_6x.gif compatí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.png e depois refine os movimentos no rig_*.py gerado.

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; usando Rig.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/.aseprite existentes podem ser desmontados reversamente com pforge.py aseprite-inspect file.aseprite --unpack-layers ou decompile.
  • Prioridade para ferramentas MCP nativas: Se a sessão atual já estiver conectada ao MCP Server pixelforge (que expõe 12 ferramentas, incluindo pixelforge_palette_guide, pixelforge_build, pixelforge_build_rig, pixelforge_region_patch, pixelforge_scene_check, pixelforge_aseprite_inspect, e cada retorno vem com agent_checklist.must_view_images e (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 .aseprite nativos 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 (01 a 10).

Habilidades Relacionadas