CommunityImagemgithub.com

forge3d

Crie modelos 3D que correspondam de perto a uma imagem de referência ou a um breve desejo, no Blender (com script, headless, sem instalação) e Blockbench (.bbmodel). Mede a referência, organiza o modelo como um layout de slots, esculpe cada parte individualmente (por subagentes quando disponíveis), verifica cada parte e o modelo montado contra a referência e adiciona a arte linear do desenho. Use para solicitações de modelagem, escultura, voxelização, texturização, renderização ou exportação de um ativo 3D, como um personagem, criatura, adereço, veículo ou modelo estilo Minecraft (3D建模, Blender, Blockbench, 体素, 低模).

O que é forge3d?

forge3d é uma habilidade de agente de IA projetada para criar modelos 3D precisos a partir de imagens de referência ou descrições curtas. Ela suporta duas plataformas principais de modelagem: Blender (executado em modo headless com bpy, sem necessidade de instalação) e Blockbench (formato .bbmodel para modelos de malha, cuboides ou voxel). A habilidade resolve o desafio de construir um modelo 3D consistente a partir de referências 2D, como folhas de turnaround, medindo automaticamente a referência, dividindo o modelo em partes gerenciáveis (slots) e coordenando a construção e revisão de cada parte por subagentes. O fluxo de trabalho é orientado por comandos: 'f3d ref' mede a referência, 'f3d blockout' cria um layout de slots, 'f3d next' gerencia a construção e revisão iterativas de cada parte, e 'f3d build' monta e exporta o modelo final. A saída inclui verificação de qualidade, como IoU de contorno e comparação visual, garantindo alta fidelidade à referência. É ideal para ativos 3D complexos, como personagens, criaturas e props, especialmente quando a precisão de referência é crucial. A habilidade também suporta modelos de bloco (Minecraft) e voxelização, com etapas opcionais para adicionar arte linear e realizar verificações de retrato para rostos visíveis.

Funciona com✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/quasar2333/forge3d/tree/main/forge3d

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

O que forge3d faz?

Você pode escrever boa geometria 3D. O que você não consegue fazer sozinho é medir uma imagem, ver o que seu código produziu e manter um modelo inteiro em vista enquanto dá atenção total a cada parte. O forge3d fornece essas três coisas: ele mede a referência, mostra cada construção ao lado dela e divide o modelo em partes que são cada uma esculpida e verificada por conta própria dentro de um quadro compartilhado. Um modelo construído fora dele não tem nada verificando-o contra a referência.

F3D="<pasta deste SKILL.md>/scripts/f3d.py"
python3 "$F3D" doctor

Use o caminho absoluto do lançador ao iniciar um novo shell. Trabalhe na pasta de trabalho atual. Para um anexo de desktop, use o caminho em "Arquivos mencionados pelo usuário" e copie-o para a pasta de trabalho se estiver em outro lugar. Coloque ambos os caminhos de arquivo entre aspas. Para uma construção não supervisionada, decida os detalhes rotineiros do design a partir do desenho. Construa a partir da referência: não procure em outras pastas por modelos anteriores para reutilizar, a menos que o usuário aponte um.

Ao revisar um modelo existente, trabalhe em uma cópia. Reconstrua o slot solicitado contra seus vizinhos finalizados, inspecione-o na cena montada e mantenha a geometria aprovada. Uma revisão de rosto pode usar o cabelo e o corpo existentes em todo o processo. Reconstruir cada slot descartaria o trabalho aprovado do usuário.

O Blender já está aqui. O f3d executa um Blender headless privado (o módulo bpy, em ~/.cache/forge3d; defina F3D_HOME se um sandbox proibir essa pasta). Nunca instale, baixe ou procure por um aplicativo Blender. Cada construção salva um arquivo .blend que abre no aplicativo Blender; python3 "$F3D" python script.py executa qualquer script Python do Blender.

Os comandos f3d levam de 5 a 120 s. Execute-os em primeiro plano e aguarde-os em uma única chamada (Codex: yield_time_ms de 120000 ou mais), em vez de fazer polling. Mantenha os arquivos de trabalho na pasta de trabalho, não em /tmp.

Convenções em todos os lugares: metros, Z para cima, o sujeito está em z = 0 em x = y = 0 e olha para -Y; +X é a direita do visualizador na vista frontal. Um sujeito de referência tem 1,0 de altura, a menos que você passe --height.

Uma imagem de referência é um desenho de design, não um conjunto de fotografias. Uma folha de turnaround é três desenhos que concordam aproximadamente e enganam livremente: o perfil desenha um olho que é o mesmo olho que a vista frontal mostra, arcos e orelhas olham para o visualizador em todas as vistas, uma cauda fica no mesmo lado do papel na frente e atrás. Ela diz quais partes existem, quão grandes, onde, quais cores, quais detalhes. Construa isso como um objeto 3D consistente.

Qual rota

  • Um personagem, uma criatura, qualquer coisa feita de várias coisas -> a rota de partes abaixo.
  • Um objeto simples de algumas formas (uma caneca, uma espada, uma caixa, um acessório low-poly) -> um script com o kit e python3 "$F3D" build model.py --ref refs; veja references/modeling.md.
  • Blockbench -> além de qualquer um, veja "Blockbench" abaixo.
  • Nenhuma imagem de referência, ou apenas uma vista, e você pode gerar imagens -> primeiro faça uma folha de turnaround (frente, lado esquerdo, costas; ortográfica, mesma escala, linha de chão comum, fundo branco liso, luz plana, sem texto); solicite em references/reference-and-gen3d.md.

A rota de partes

Em ordem, sem pular nenhum: (1) f3d ref, e aguarde; (2) faça o inventário; (3) blockout.py e f3d blockout; (4) f3d next, repetidamente: ele nomeia os subagentes a serem gerados, e esta habilidade os solicita: construtores, depois revisores independentes, depois reparadores; (5) model.py, f3d build, entregue. Seu próprio trabalho é o layout e as notas; construir e julgar são o trabalho dos agentes.

1. Meça a referência

python3 "$F3D" ref sheet.png -o refs (30 a 90 s) recorta o sujeito, divide uma folha de turnaround em vistas, coloca cada vista em uma grade de coordenadas e relata se o sujeito é desenhado com contornos de tinta. Aguarde antes de escrever qualquer coisa: cada etapa posterior é medida a partir de suas imagens, e a geometria digitada a partir da folha bruta enquanto isso precisa ser refeita. Abra refs/overview.png e verifique os nomes das vistas; se estiverem errados, execute novamente com --views front,right,back (ordem de leitura; right significa que o sujeito olha para a ESQUERDA nessa imagem, left significa que olha para a DIREITA, skip ignora uma imagem, por exemplo, uma segunda pose das costas).

2. Faça o inventário

Liste as partes em sua resposta: cada coisa que é seu próprio material ou que sairia em uma peça. Para um personagem, tipicamente de 9 a 14. Um personagem tem um corpo, e ele é uma parte: body é o pescoço, tronco, quadris e as pernas até os quadris como um sólido contínuo, a base sobre a qual todo o resto se apoia. Roupas são partes sobre ele (on="body"): uma saia ou jaqueta construída sem o corpo por baixo é um tubo vazio. Em seguida, cabeça (o rosto pertence a ela), cabelo (cabelo longo ou detalhado são duas partes: hair_front com franja e mechas laterais, hair_back), cada peça de vestuário, cada acessório, braços e mãos, sapatos, cauda. Divida onde o material muda, onde uma coisa está sobre outra, onde algo se repete (pares são uma parte). Para cada parte, decida a verdade 3D uma vez onde as vistas enganam: quantas existem, onde realmente fica, para que lado realmente olha. Quando a roupa cobre uma articulação, nomeie o slot que possui a anatomia subjacente. Por exemplo, coloque os braços e pulsos no slot do corpo ou braço e o punho no slot da manga. Ambas as coxas devem se juntar à pelve, incluindo o lado oculto no perfil. Quando outro slot fornece as pernas inferiores ou meias, anexe-o à anatomia com on= para que a ferramenta verifique ambos os lados independentemente.

3. Layout

Escreva blockout.py: o modelo inteiro como formas de placeholder ásperas e sem pintura, cada uma no lugar certo no tamanho certo, cada uma dada a um slot. Este é o contrato que faz as partes construídas separadamente se encaixarem. Leia as posições e tamanhos de refs/<view>_grid.png.

# blockout.py
from forge3d import kit as k
head = k.sphere(radii=(0.215, 0.20, 0.225), at=(0, 0.005, 0.635))
k.slot("head", head, review="face", note="Cabeça chibi com orelhas pequenas. Combine as aberturas dos olhos desenhadas, o olhar, as sobrancelhas e a boca. Modele a bochecha, o nariz e o maxilar a partir do perfil. O cabelo cobre parte da testa.")
skirt = k.cyl(r=0.235, r2=0.085, h=0.20, at=(0, 0, 0.17))
k.slot("skirt", skirt, on="torso", note="Saia azul-marinho em forma de sino, plissada, com uma faixa bordada a ouro perto da bainha em toda a volta e um babado de anágua branco recortado por baixo.")
bows = [k.box(size=(0.07, 0.10, 0.09), at=(sx * 0.275, 0.09, 0.645)) for sx in (-1, 1)]
k.slot("bows", bows, on="hair", note="Par de laços de fita azul-claro com uma conta dourada. Cada imagem os desenha olhando para o visualizador; em 3D, eles ficam nas laterais da cabeça olhando para fora e um pouco para a frente.")
  • Formas: k.sphere(radii=), k.box, k.cyl, k.loft, k.sweep(path, r=): áspero está certo.
  • on=: o(s) slot(s) sobre os quais uma parte se apoia ou dos quais pende. Uma parte é construída contra a parte finalizada sobre a qual se apoia, então nomeie apenas aquilo sobre o qual realmente se apoia e mantenha as cadeias curtas.
  • note=: tudo o que o construtor da parte saberá além das imagens. Diga o que é, seus materiais e cores, cada característica que carrega e a verdade 3D que você decidiu onde as vistas enganam. Uma nota vaga gera uma parte vaga.
  • review= atribui uma verificação focal quando o nome do slot é ambíguo. Use face para a parte que carrega a expressão, hair para mechas detalhadas e joint para o corpo que possui a conexão quadril-perna. Use detail para outra característica priorizada pelo usuário. Partes comuns compartilham a revisão de montagem. Os nomes usuais de cabeça, cabelo e corpo já selecionam suas verificações. Atribua um proprietário para o rosto.
python3 "$F3D" blockout blockout.py --ref refs     # 10 s -> parts/: plan.json, overview.png, uma ordem de serviço por slot

Abra parts/overview.png e parts/blockout_compare.png. Cada parte da referência precisa de um slot de aproximadamente o tamanho certo no lugar certo (IoU de contorno em torno de 0,8 é suficiente). Corrija e execute novamente até que isso se mantenha.

4. Construa e revise com f3d next

python3 "$F3D" next        # imprime o estado de cada parte e os agentes exatos a serem gerados agora

Esta habilidade solicita explicitamente subagentes. Faça o que f3d next imprime, depois execute-o novamente, até que imprima DONE:

  • Para uma construção complexa e orientada por referência no Codex, comece com gpt-6.2-astra como o líder. Quando a conta oferecer gpt-6.2-sol e a ferramenta de spawn aceitar um modelo por agente, defina-o para os construtores de partes. Mantenha o líder no planejamento, montagem e inspeção final. Uma sessão liderada por Sol também pode executar o fluxo de trabalho inteiro. Se o cliente não expor a seleção de modelo para um subagente, deixe o modelo não definido e use seu padrão.
  • Despache até três trabalhos independentes por vez. Para um novo construtor ou revisor, use spawn_agent, fork_turns: "none", o nome da tarefa impresso, esforço e mensagem. Aguarde um trabalhador relatar, depois pergunte ao next por trabalhos prontos. Dê a cada parte um proprietário ativo. Envie reparos ao seu construtor original com followup_task quando disponível. O revisor permanece independente.
  • Cada construtor inspeciona o ajuste e a renderização. Um rosto ou cabelo detalhado recebe um olhar atento independente e, após um reparo, uma verificação focada. Um corpo ou detalhe especificado recebe uma verificação independente. Outras partes compartilham a revisão de montagem, a menos que sua construção relate um problema estrutural. Mantenha os cruzamentos de cabelo desenhados e verifique cada coxa no corte do quadril ajustado, mesmo quando a vestimenta externa a cobre.
  • f3d review monta os slots finalizados para suas imagens. Ele solicita reparos por proprietário. Sua segunda passagem verifica essas descobertas e regressões de reparo. Construa a entrega uma vez que as partes se estabilizem. Inspecione quaisquer descobertas pendentes no limite na cena final salva.

Apenas onde nenhuma ferramenta de subagente existe: construa cada parte você mesmo a partir de seu resumo (references/parts.md; para um modelo cuboide "Construindo uma parte cuboide" em references/blockbench.md), siga o mesmo cronograma next e use references/review.md para as verificações visuais.

5. Monte e entregue

# model.py
from forge3d import kit as k
parts = k.assemble()             # cada parte finalizada em seu slot; formas de layout cinza para o resto
k.outline()                      # o contorno a tinta do desenho em torno de cada peça separada (quando f3d ref relatou arte linear)
k.export("out/name.glb")        # também .fbx .obj .stl .usdz .bbmodel

python3 "$F3D" build model.py --ref refs (um a dois minutos) faz lint do modelo, renderiza out/model_sheet.png e out/model_compare.png, e salva out/model.blend. Após f3d next dizer DONE, olhe você mesmo uma vez: python3 "$F3D" view out/model.blend --views az40el10,az-40el10,az140el10,az0el-50 --tile 1024 --cols 2 (o último é de baixo). Lide com descobertas de layout em blockout.py, execute novamente f3d blockout e siga f3d next para reajustar os slots afetados. No limite da revisão, compare as descobertas listadas com a construção final salva antes da entrega.

Feito significa: f3d next imprime DONE; um lint limpo; vistas de três quartos nas quais cada característica desenhada está inteira e exatamente uma vez e nada está flutuando, oco ou enterrado; IoU de contorno de aproximadamente 0,85 ou mais em cada vista, exceto onde você decidiu que uma vista engana.

Entregue o que foi solicitado: a exportação, o .blend, uma renderização de apresentação (k.stage, k.camera, k.render com o motor EEVEE padrão, veja references/modeling.md). Informe ao usuário os números finais, mostre a imagem de comparação e uma vista de três quartos, e diga claramente o que foi simplificado, o que as revisões deixaram em aberto e quais diferenças de vista você deixou de propósito.

Para um personagem com um rosto visível, renderize python3 "$F3D" portrait out/name.blend a partir do arquivo final encenado. Inspecione a expressão, profundidade dos olhos, sombras da bochecha e boca com o cabelo, materiais e luzes reais. A folha inclui recortes de referência alinhados, frente, perfil e ambos os close-ups de três quartos. Se a cena tiver vários slots de rosto, escolha um com --slot. Quando o rosto parecer muito largo, estreito ou plano, use portrait out/name.blend --form para comparar os planos da mandíbula e bochecha nus. Para cada ponto de referência desobstruído, passe --span Z LEFT_X RIGHT_X usando suas coordenadas de referência frontal medidas. A ferramenta relata a largura da malha ali e marca os dois pontos finais de referência.

Blockbench

Pergunte (ou infira) qual tipo de modelo Blockbench é desejado; eles são produtos diferentes:

  • Modelo de malha (mais próximo da referência; formas suaves com a textura real; formato Generic Model): termine o modelo como acima, então k.export("out/name.bbmodel") no script, ou python3 "$F3D" bb mesh model.py --ref refs -o out/name.bbmodel. Cada objeto se torna uma malha nomeada e editável.
  • Modelo cuboide projetado (caixas em ossos com uma textura pixel art; o que mods de Minecraft, entidades Bedrock / Java e animadores precisam). Um sujeito de várias partes segue a rota de partes com uma linha extra no layout, bb.plan(height=80, format="bedrock"): cada parte é então construída como cuboides em ossos e bb.assemble() as une. Um mob ou acessório simples é um script com bb.Model.
  • Modelo voxel (estátua em blocos de qualquer modelo, muitos cuboides, sem rig): python3 "$F3D" bb voxelize model.py --ref refs --height 48 -o out/name.bbmodel.

Com apenas "faça no Blockbench", faça o modelo cuboide: é para isso que o Blockbench serve, e um sujeito mecânico, em blocos ou pixel art se adequa a ele. Faça o modelo de malha apenas para um desenho suave e curvo (uma figura chibi, um animal) ou quando solicitado. Diga qual você fez e que o outro está disponível.

Prove o arquivo no aplicativo real quando o Blockbench estiver instalado: python3 "$F3D" bb check out/name.bbmodel o abre em um Blockbench oculto privado (offline, perfil próprio), relata o que carregou, salva a própria visão do Blockbench dele e pode executar os exportadores do Blockbench (--export bedrock:out/name.geo.json).

API, formatos e orientação de pixel art: references/blockbench.md. Leia antes de escrever um script Blockbench.

Coisas que dão errado

  • Uma parte está faltando no...

Habilidades Relacionadas