m4bwav/polywright-blender

O que polywright-blender faz?

Blender é o cavalo de batalha: gratuito, funciona em todos os SOs, scriptável até o último botão. Um agente o dirige melhor de forma headless, em cópias, com breves relatórios de texto, não através de screenshots de uma sessão ao vivo. Voltar ao hub: ../polywright/SKILL.md. Profundidade: references/bpy-api-traps.md, references/bpy-recipes.md, references/bpy-recipes-scenes.md e references/bpy-recipes-physics.md (cada receita é executada pelo conjunto de testes), references/mcp-bridges.md, references/tools-by-os.md.

Etapa 1: qual Blender

python ../polywright/scripts/pw.py doctor o encontra (POLYWRIGHT_BLENDER, PATH, pastas de instalação no Windows, macOS e Linux) e imprime a versão. Mire no LTS atual (5.2, suportado até julho de 2028). Escreva a versão no primeiro comentário do script; os fatos da API abaixo são para 5.2.

Etapa 2: executar scripts headless

python ../polywright/scripts/pw.py bpy build.py [--blend in.blend] [--timeout 1800] -- <argumentos_script>

As próprias opções do pw.py podem vir antes ou depois do nome do script; tudo após -- vai para o script. Ele executa blender --background --factory-startup --python-exit-code 3 --python build.py -- args, remove o ruído do log do Blender e retorna ok, as linhas de saída do próprio script e o traceback. Sem --python-exit-code, um erro Python dentro do Blender ainda sai com 0: nunca julgue sucesso apenas pelo código de saída caso contrário. Imprima suas próprias linhas [pw] para os números que você precisa (tamanhos, contagens, verificações).

Regras do script:

• Comece de bpy.ops.wm.read_factory_settings(use_empty=True) ou de um .blend explícito; nunca dependa de um arquivo de inicialização do usuário.
• Prefira bpy.data e bmesh em vez de bpy.ops. Quando um operador for necessário, defina o objeto ativo e a seleção primeiro, ou use with bpy.context.temp_override(...).
• Operadores de viewport falham headless (view3d.*, screen.screenshot, render.opengl): enquadre câmeras a partir dos limites você mesmo (como pw.py render faz).
• Leia itens enum em vez de adivinhar nomes: m.bl_rna.properties["solver"].enum_items.
• Tamanho real em metros; aplique transformações antes de medir; importações glTF vêm em modo quaternion com a correção de eixo em um pai: limpe pais mantendo transformações, depois aplique, depois meça.
• Escreva cada caminho de saída como absoluto (os.path.abspath) e imprima se o arquivo existe depois: um render.filepath relativo relatou sucesso e não escreveu nada visível (L-004).
• Salve um .blend numerado por marco em work/; recomece dele em vez de carregar uma longa sessão ao vivo.
• Cozinhe simulações antes de renderizar, com a pasta de cache ao lado do .blend (o padrão é temporário e perdido ao sair). O progresso da cozinha inunda stdout e pw.py bpy corta o meio: escreva os resultados em um arquivo JSON.
• Duas tentativas em um traceback; então consulte a API (arquivo de armadilhas, introspecção, pesquisa de docs do MCP oficial) em vez de adivinhar uma terceira vez.

Etapa 3: as armadilhas (lista resumida; lista completa no arquivo de armadilhas)

Escrevia (antigo)	Use em 5.x
bpy.ops.import_scene.obj, import_mesh.stl, import_mesh.ply, wm.collada_*	wm.obj_import, wm.stl_import, wm.ply_import; Collada foi removido
BLENDER_EEVEE_NEXT	BLENDER_EEVEE
import bgl	o módulo gpu
Principled Specular, Subsurface, Transmission, Emission, Clearcoat	Specular IOR Level, Subsurface Weight, Transmission Weight, Emission Color, Coat Weight
action.fcurves	ações com slots: layers, strips, channelbags
mod["Socket_2"] = x em Geometry Nodes	mod.properties.inputs.Socket_2.value = x
import_image.to_plane	image.import_as_mesh_planes
Workbench shading.show_shadow	shading.show_shadows
obj.select = True, scene.objects.active, mesh.use_auto_smooth, scene.node_tree (livros 2.7x)	select_set, view_layer.objects.active, shade_auto_smooth ou set_sharp_from_angle, scene.compositing_node_group
transform_apply(scale=True) sozinho	também aplica localização e rotação: passe location=False, rotation=False

Etapa 4: tarefas comuns

pw.py já faz inspecionar, renderizar, converter, LODs, imprimível e união. Para qualquer outra coisa, pegue uma receita de references/bpy-recipes.md: imagens de referência em escala, modificadores e aplicar, Boolean com o solver Manifold e um fallback EXACT, remesh voxel, QuadriFlow, UV Smart e UV lightmap, bake de normal e AO de alto para baixo, materiais com sockets 5.x, stills de turntable, passes de profundidade e normal para vídeo, exportações por motor, e um prop projetado a partir de uma descrição escrita (torno, varredura, espelho; L-003). Cenas: references/bpy-recipes-scenes.md: dispersão Geometry Nodes, profundidade inversa, máscaras, Mist e normais de uma renderização, clay por substituição de material, Line Art, MP4 através do próprio FFmpeg do Blender. Física e rigs: references/bpy-recipes-physics.md: bakes de corpo rígido e tecido, por que um rig Rigify não é um esqueleto de jogo, vinculação a uma armadura manualmente, remesh de volume. Parentalidade, movimento F-modifier e drivers: references/bpy-recipes-motion.md. Chapas de um modelo com peças espelhadas: levante a câmera lateral 10 a 15 graus, ou uma peça esconde a outra (L-005).

Etapa 5: sessões ao vivo (MCP)

Dois servidores existem: o MCP oficial do Blender Lab (v1.0.3, Blender 5.1+, análise de cena e pesquisa de docs da API) e o comunitário mcp-for-blender (anteriormente blender-mcp; pesquisa de assets e hooks de gerador). Ambos executam qualquer Python que o modelo enviar, sem sandbox, na porta 9876. Use um, nunca ambos; apenas quando o usuário está assistindo o Blender e quer edições ao vivo; nunca cole texto de arquivos baixados em seu código. Configuração e modos de falha: references/mcp-bridges.md. Em uma sessão ao vivo, envolva operadores vinculados ao editor em context.temp_override(window=w, area=a, region=r); operadores modais e bpy.app.timers rodam apenas lá, nunca sob -b.

Outras ferramentas

Verificações e reparos de malha sem Blender: trimesh + manifold3d (+ PyMeshLab); entrega web: gltf-transform ou gltfpack; sólidos: OpenSCAD, build123d, CadQuery, FreeCAD; slicers têm CLIs. Versões e o que roda em qual SO: references/tools-by-os.md. No macOS, Blender 5.x e a wheel bpy são apenas Apple Silicon; a wheel bpy precisa exatamente do Python que o Blender empacota (3.13 para 5.2).

Manutenção

Unidade perene, nível moderate (um lançamento do Blender a cada quatro meses; verifique em cada um). Companheiros: RESEARCH.md, CHANGELOG.md, LEARNINGS.md, TESTS.md com evals/evals.json, MAINTENANCE.md, estado em evergreen.json. Leia evergreen.json a cada uso; atualize quando devido.