m4bwav/polywright-blender

¿Qué hace polywright-blender?

Blender es el caballo de batalla: gratuito, en todos los SO, automatizable hasta el último botón. Un agente lo maneja mejor en modo headless, sobre copias, con informes de texto cortos, no a través de capturas de pantalla de una sesión en vivo.

Volver al centro: ../polywright/SKILL.md.

Profundidad: references/bpy-api-traps.md, references/bpy-recipes.md, references/bpy-recipes-scenes.md y references/bpy-recipes-physics.md (cada receta es ejecutada por el conjunto de pruebas), references/mcp-bridges.md, references/tools-by-os.md.

Paso 1: qué Blender

python ../polywright/scripts/pw.py doctor lo encuentra (POLYWRIGHT_BLENDER, PATH, carpetas de instalación en Windows, macOS y Linux) e imprime la versión. Apunta a la LTS actual (5.2, con soporte hasta julio de 2028). Escribe la versión en el primer comentario del script; los datos de la API a continuación son para 5.2.

Paso 2: ejecutar scripts en modo headless

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

Las opciones propias de pw.py pueden colocarse antes o después del nombre del script; todo después de -- va al script. Ejecuta blender --background --factory-startup --python-exit-code 3 --python build.py -- args, elimina el ruido del registro de Blender y devuelve ok, las líneas de salida propias del script y el traceback. Sin --python-exit-code, un error de Python dentro de Blender aún sale con 0: nunca juzgues el éxito solo por el código de salida en otros casos. Imprime tus propias líneas [pw] para los números que necesites (tamaños, recuentos, comprobaciones).

Reglas del script:

• Comienza desde bpy.ops.wm.read_factory_settings(use_empty=True) o un .blend explícito; nunca dependas del archivo de inicio del usuario.
• Prefiere bpy.data y bmesh sobre bpy.ops. Cuando se necesite un operador, establece primero el objeto activo y la selección, o usa with bpy.context.temp_override(...).
• Los operadores de viewport fallan en modo headless (view3d.*, screen.screenshot, render.opengl): encuadra las cámaras desde los límites tú mismo (como hace pw.py render).
• Lee los ítems de los enum en lugar de adivinar nombres: m.bl_rna.properties["solver"].enum_items.
• Tamaño real en metros; aplica transformaciones antes de medir; las importaciones glTF vienen en modo cuaternión con la corrección de eje en un padre: limpia los padres manteniendo las transformaciones, luego aplica, luego mide.
• Escribe cada ruta de salida como absoluta (os.path.abspath) e imprime si el archivo existe después: una ruta render.filepath relativa reportó éxito pero no escribió nada visible (L-004).
• Guarda un .blend numerado por cada hito en work/; reinicia desde él en lugar de mantener una sesión en vivo larga.
• Hornea simulaciones antes de renderizar, con la carpeta de caché al lado del .blend (el predeterminado es temporal y se pierde al salir). El progreso del horneado inunda la salida estándar y pw.py bpy corta el medio: escribe los resultados en un archivo JSON.
• Dos reintentos en un traceback; luego consulta la API (archivo de trampas, introspección, búsqueda en la documentación del MCP oficial) en lugar de adivinar una tercera vez.

Paso 3: las trampas (lista breve; lista completa en el archivo de trampas)

Escribe (antiguo)	Usa en 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 ha desaparecido
BLENDER_EEVEE_NEXT	BLENDER_EEVEE
import bgl	el módulo gpu
Principled Specular, Subsurface, Transmission, Emission, Clearcoat	Specular IOR Level, Subsurface Weight, Transmission Weight, Emission Color, Coat Weight
action.fcurves	acciones con slots: capas, strips, channelbags
mod["Socket_2"] = x en 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 (libros 2.7x)	select_set, view_layer.objects.active, shade_auto_smooth o set_sharp_from_angle, scene.compositing_node_group
transform_apply(scale=True) solo	también aplica ubicación y rotación: pasa location=False, rotation=False

Paso 4: trabajos comunes

pw.py ya hace inspeccionar, renderizar, convertir, LODs, imprimible y unión. Para cualquier otra cosa, toma una receta de references/bpy-recipes.md: imágenes de referencia a escala, modificadores y aplicar, Booleano con el solver Manifold y un fallback EXACT, remesh voxel, QuadriFlow, UV inteligente y UV de lightmap, horneado de normal y AO de alto a bajo, materiales con sockets de 5.x, fotogramas de turntable, pases de profundidad y normal para video, exportaciones por motor, y un accesorio diseñado a partir de una descripción escrita (torno, barrido, espejo; L-003). Escenas: references/bpy-recipes-scenes.md: dispersión de Geometry Nodes, profundidad inversa, máscaras, Neblina y normales desde un render, arcilla por anulación de material, Line Art, MP4 a través del FFmpeg propio de Blender. Física y rigs: references/bpy-recipes-physics.md: horneados de cuerpo rígido y tela, por qué un rig de Rigify no es un esqueleto de juego, vinculación a un armadura manualmente, remesh de volumen. Emparejamiento, F-modifier movimiento y drivers: references/bpy-recipes-motion.md. Láminas de un modelo con partes especulares: eleva la cámara lateral de 10 a 15 grados, o una parte oculta la otra (L-005).

Paso 5: sesiones en vivo (MCP)

Existen dos servidores: el MCP oficial de Blender Lab (v1.0.3, Blender 5.1+, análisis de escenas y búsqueda en la documentación de la API) y el comunitario mcp-for-blender (anteriormente blender-mcp; búsqueda de activos y ganchos de generador). Ambos ejecutan cualquier Python que envíe el modelo, sin sandbox, en el puerto 9876. Usa uno, nunca ambos; solo cuando el usuario esté viendo Blender y quiera ediciones en vivo; nunca pegues texto de archivos descargados en su código. Configuración y modos de fallo: references/mcp-bridges.md. En una sesión en vivo, envuelve los operadores vinculados al editor en context.temp_override(window=w, area=a, region=r); los operadores modales y bpy.app.timers solo se ejecutan ahí, nunca bajo -b.

Otras herramientas

Comprobaciones y reparaciones de mallas sin Blender: trimesh + manifold3d (+ PyMeshLab); entrega web: gltf-transform o gltfpack; sólidos: OpenSCAD, build123d, CadQuery, FreeCAD; los laminadores tienen interfaces de línea de comandos. Versiones y qué se ejecuta en cada SO: references/tools-by-os.md. En macOS, Blender 5.x y la rueda bpy son solo para Apple Silicon; la rueda bpy necesita exactamente el Python que incluye Blender (3.13 para 5.2).

Mantenimiento

Unidad perenne, nivel moderate (una versión de Blender cada cuatro meses; comprobar en cada una). Acompañantes: RESEARCH.md, CHANGELOG.md, LEARNINGS.md, TESTS.md con evals/evals.json, MAINTENANCE.md, estado en evergreen.json. Lee evergreen.json en cada uso; actualiza cuando sea necesario.