3d-builder

Criação e edição de modelos 3D orientada por especificações no Blender ou FreeCAD. Mantém tudo para um modelo na pasta models/<nome>/. Escreve um arquivo de especificação, faz perguntas esclarecedoras uma de cada vez, registra cada decisão e suposição. Para construções, discute a planta baixa e desenha um plano SVG por andar para aprovação, depois constrói o modelo via servidor MCP do Blender/FreeCAD ou um script Python gerado e o salva na mesma pasta.

O que é 3d-builder?

O *3d-builder* é uma skill para agentes de IA (como Claude Code, Cursor, etc.) que automatiza a criação e edição de modelos 3D de forma estruturada e livre de suposições. Em vez de começar a modelar diretamente, o agente primeiro documenta uma especificação detalhada, faz perguntas esclarecedoras ao usuário uma de cada vez e registra todas as decisões e suposições. Isso evita retrabalho causado por dimensões adivinhadas. A skill suporta tanto o Blender quanto o FreeCAD, escolhendo a ferramenta ideal conforme a tarefa: FreeCAD para peças funcionais e precisas (suportes, invólucros, peças para impressão 3D) e Blender para formas orgânicas, objetos decorativos e ativos para jogos/web. O fluxo de trabalho segue quatro fases rígidas: especificação → perguntas → plantas baixas (apenas para construções) → modelagem. Para construções, o agente desenha plantas SVG de cada andar para aprovação do usuário antes de modelar. A skill pode construir o modelo usando servidores MCP (preferencial) ou, como fallback, gerar e executar um script Python autônomo. No final, o modelo é salvo no formato nativo (.blend ou .FCStd) e, se for um ativo para jogos/web, exportado como .glb ou .fbx, respeitando orçamentos de polígonos e requisitos de engine.

Funciona com~Claude Code~Codex CLI~Cursor
Part ofMobile
npx skills add https://github.com/thanikc/3d-builder/tree/HEAD/skills/3d-builder

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

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

Documentação

O que 3d-builder faz?

Não adivinhe um modelo 3D. Escreva o que será construído, esclareça o que está ambíguo com o usuário, registre cada suposição e só então modele. Um modelo construído com dimensões adivinhadas é corrigido repetidamente; uma especificação captura os palpites antes que se tornem geometria.

O fluxo de trabalho tem estas fases, sempre nesta ordem: especificação → perguntas → plantas baixas (apenas construções) → modelo. Não abra o Blender ou FreeCAD, e não escreva código de modelagem, antes que a especificação exista e as perguntas sejam concluídas. Para uma construção, o usuário também deve ter aprovado as plantas baixas primeiro.

Estrutura do projeto

Um projeto pode conter vários modelos, portanto tudo que pertence a um modelo vive em sua própria pasta:

models/
  <nome>/
    specs/
      <aaaa-mm-dd-hhmmss>-<solicitacao>.md   # uma especificação por solicitação
    plans/                               # apenas construções
      layout.json
      floor-<id>.svg
    <nome>.blend | <nome>.FCStd          # o modelo
    <nome>.py                            # apenas fallback de script
    <nome>.glb | <nome>.fbx              # apenas exportações para jogos/web
.3d-builder.json                         # escolha da ferramenta lembrada, para todo o projeto

<nome> é um nome curto em kebab-case para o objeto (phone-holder, router-wall-mount). Ele nomeia a pasta e os arquivos do modelo. Todos os caminhos abaixo são relativos a models/<nome>/, a menos que indicado o contrário.

Projetos antigos podem ainda usar a estrutura plana anterior (specs/ e plans/ na raiz do projeto, models/<nome>.blend). Se você encontrar um, trabalhe com ele como está e ofereça uma vez para mover os arquivos para esta estrutura. Não mova nada sem perguntar.

Fase 1: Escrever a especificação

  1. Escolha o <nome> do modelo. Para um novo modelo, verifique se models/<nome>/ não existe ainda, então crie-o e sua pasta specs/.
  2. Obtenha o timestamp do relógio do sistema (ex.: date +%Y-%m-%d-%H%M%S) em vez de inventar um.
  3. Crie specs/<aaaa-mm-dd-hhmmss>-<solicitacao>.md usando o template em references/spec-template.md. <solicitacao> é um rótulo curto em kebab-case para esta solicitação: initial para um novo modelo, ou a alteração para uma edição (thicker-hook, move-kitchen-wall).

Preencha o que a solicitação já declarou, então liste os pontos em aberto: tudo que afeta a geometria mas não foi especificado. Pontos em aberto típicos:

  • Dimensões gerais e unidades, e quais dimensões são fixas vs. livres
  • Ajuste e folga em relação a objetos reais (um telefone de 60 mm precisa de um encaixe ligeiramente maior que 60 mm; quanto?)
  • Espessura da parede, filetes/chanfros, tamanhos de furos, tipos de parafusos
  • Método de montagem, orientação, carga
  • Propósito e fabricação (impressão 3D → saliências, paredes mínimas, base plana; CNC; apenas render; ativo para jogo/web)
  • Para ativos de jogo/web: engine alvo, orçamento de polígonos, escala em unidades da engine, posição do pivô, UVs e texturas vs. cores sólidas, LODs, malha de colisão
  • Nível de detalhe, materiais (Blender), necessidades paramétricas (FreeCAD)
  • Para construções: andares, pegada, cômodos e seus tamanhos, escadas, portas e janelas. Estes serão resolvidos na Fase 3 com as plantas baixas, então liste-os lá e não aqui

Editando um modelo existente: encontre primeiro a pasta do objeto em models/. Escreva uma nova especificação para a alteração (cada solicitação tem seu próprio arquivo, para que o histórico permaneça legível), vincule-a à especificação anterior e declare o que muda e o que deve permanecer igual. Leia o modelo existente (via MCP, ou o script que o construiu) antes de editar, para que a edição comece a partir do que realmente está lá. Para uma construção com uma pasta plans/, uma alteração de layout passa primeiro pelas plantas (Fase 3, "Editando uma construção").

Fase 2: Perguntas esclarecedoras

Se a solicitação deixar pontos em aberto, pergunte sobre eles antes de modelar. O usuário sabe coisas que você não pode inferir (a largura real do telefone, onde os parafusos de parede vão), e uma pergunta agora evita uma reconstrução depois.

Regras:

  • Uma pergunta de cada vez. Espere a resposta antes de fazer a próxima. Ordene as perguntas por quanto elas afetam a geometria: tamanho geral e propósito primeiro, detalhes cosméticos por último.
  • Sim/não quando possível. "O slot do cabo deve ser centralizado?" é melhor que "Onde o slot do cabo deve ficar?".
  • Caso contrário, múltipla escolha: a opção recomendada primeiro e marcada como "(recomendado)", depois as alternativas e, por último, uma resposta de texto livre. Use a ferramenta de perguntas do agente (ex.: AskUserQuestion) se houver uma; ela geralmente adiciona a opção de texto livre para você.
  • Lotes de 5. Após cada 5 perguntas, pergunte se deseja continuar com mais até 5, dizendo aproximadamente quantos pontos em aberto restam. Se o usuário disser não, pare de perguntar.
  • Não pergunte sobre coisas que não importam para este modelo, e não pergunte o que o usuário já disse.
  • Registre cada resposta na seção Decisões da especificação imediatamente, para que a especificação esteja sempre atualizada.

Pare quando nada importante permanecer incerto, ou quando o usuário parar de responder. Para cada ponto em aberto que restar, decida por si mesmo, escolhendo o padrão sensato para o propósito declarado, e escreva-o em Suposições com uma razão de uma linha. O usuário deve ser capaz de ler a especificação e ver cada escolha feita em seu nome.

Se a solicitação já estiver totalmente especificada, pule as perguntas e diga isso em uma linha.

Fase 3: Plantas baixas (apenas construções)

Se o modelo é uma construção ou tem cômodos, resolva o layout no papel antes de modelar. Leia references/floorplans.md e siga-o:

  1. Discuta a planta baixa com o usuário, usando as regras de perguntas acima: andares, pegada, cômodos, adjacência, escadas, portas e janelas.
  2. Desenhe uma planta vetorial para cada andar. Escreva plans/layout.json e gere plans/floor-<id>.svg com o script incluído scripts/draw_plans.py.
  3. Revise as plantas com o usuário e revise-as até que o usuário aprove. Registre a aprovação em Decisões.

O layout.json aprovado é a fonte da verdade para as paredes, aberturas, cômodos e escadas do modelo. Pule esta fase para qualquer coisa que não seja uma construção.

Fase 4: Modelo

Salve o resultado em <nome>.blend (Blender) ou <nome>.FCStd (FreeCAD) na pasta do modelo. Para um ativo de jogo ou web, também exporte-o ao lado do arquivo fonte (veja Exportar para engines).

Escolher a ferramenta

Verifique quais servidores MCP estão configurados: olhe suas ferramentas disponíveis para ferramentas MCP do Blender ou FreeCAD (nomes geralmente contêm blender ou freecad).

  1. Escolha lembrada: se .3d-builder.json existir na raiz do projeto, use seu "tool" ("blender" ou "freecad") a menos que o usuário peça outra coisa.
  2. Exatamente um servidor MCP configurado: use essa ferramenta.
  3. Ambos ou nenhum configurado: pergunte ao usuário qual ferramenta usar (uma pergunta de múltipla escolha). Recomende FreeCAD para peças funcionais com dimensões precisas (suportes, invólucros, qualquer coisa impressa ou usinada), e Blender para formas orgânicas, objetos esculpidos ou decorativos, qualquer coisa destinada a renderização e ativos para jogos ou web (as malhas tesseladas do FreeCAD são pouco adequadas para uso em tempo real).
  4. Lembre a escolha escrevendo {"tool": "blender"} ou {"tool": "freecad"} em .3d-builder.json. Registre a ferramenta na especificação também.

Construir via MCP (preferencial)

  1. Faça uma chamada barata primeiro (ex.: obter informações da cena/documento). Se der erro ou não responder em 10 segundos, trate o servidor como indisponível e mude para o fallback de script. Diga ao usuário o motivo em uma linha.
  2. Construa o modelo passo a passo a partir da especificação. Verifique as dimensões enquanto avança (consultando bounding boxes ou propriedades de objetos) em vez de confiar que o código fez o que você pretendia.
  3. Salve no caminho acima.

Fallback de script

Quando nenhum servidor MCP estiver utilizável, escreva um script Python autônomo, <nome>.py na pasta do modelo, que construa o modelo do zero e salve <nome>.blend ou <nome>.FCStd ao lado de si mesmo. Coloque as dimensões-chave como constantes nomeadas no topo para que o usuário possa ajustá-las. Para uma construção, o script lê plans/layout.json e não copia as coordenadas para o código (veja references/floorplans.md, "Construir o modelo a partir do layout").

Em seguida, tente executá-lo sem interface gráfica, se a ferramenta estiver instalada:

  • Blender: blender --background --python models/<nome>/<nome>.py
  • FreeCAD: freecadcmd models/<nome>/<nome>.py (em alguns sistemas FreeCADCmd ou freecad.cmd)

Se funcionar, verifique a saída (arquivo existe, bounding box impressa corresponde à especificação). Se falhar, corrija o script e execute novamente. Se a ferramenta não estiver no PATH, diga ao usuário o comando exato para executar.

Armadilhas específicas da ferramenta e esqueletos de script: references/blender.md, references/freecad.md. Leia o da ferramenta escolhida antes de escrever código.

Exportar para engines

Apenas para ativos de jogo ou web. Mantenha o .blend como fonte editável e exporte ao lado dele:

AlvoFormatoArquivo
Web (three.js, Babylon.js), Godot, uso geralglTF binário<nome>.glb
Unity, UnrealFBX (ou .glb se o pipeline do usuário importar glTF)<nome>.fbx

As engines são em tempo real, então o ativo deve respeitar o orçamento da especificação: verifique a contagem de triângulos, aplique transformações, coloque o pivô onde a especificação diz e corresponda à escala e eixos da engine. Configurações de exportação e armadilhas: a seção "Ativos para jogos e web" em references/blender.md.

Esta skill entrega o arquivo do ativo. Carregá-lo em uma cena, escrever scripts de engine ou construir uma página three.js está fora do seu escopo; se o usuário também quiser isso, faça como uma etapa separada após este fluxo de trabalho estar concluído.

Finalizar

  1. Verifique o modelo contra a especificação: dimensões gerais, cada recurso listado presente e quaisquer requisitos de ajuste ou folga. Para ativos de jogo/web, também a contagem de triângulos contra o orçamento e o bounding box do arquivo exportado em unidades da engine. Para construções, também verifique contra as plantas aprovadas: dimensões gerais, posições das paredes, cada porta e janela e níveis dos andares.
  2. Atualize a especificação: defina Status como done, preencha Saída (caminhos de arquivo incluindo exportações e plantas, ferramenta, MCP ou script) e anote qualquer coisa que tenha ficado diferente do planejado.
  3. Relate ao usuário brevemente: o que foi construído, onde estão os arquivos e as principais suposições que ele pode querer revisitar (aponte para a especificação para o resto).

Se o usuário pedir alterações depois disso, trate-as como uma nova solicitação de edição (Fase 1, "Editando um modelo existente"). Pequenos acompanhamentos na mesma conversa ("um pouco mais grosso") podem ir na mesma especificação sob Revisões.

Habilidades Relacionadas