Que fait polywright-blender ?
Blender est le cheval de bataille : gratuit, tous les OS, scriptable jusqu'au dernier bouton. Un agent le conduit mieux en mode headless, sur des copies, avec des rapports textuels courts, pas à travers des captures d'écran d'une session live. Retour au hub : ../polywright/SKILL.md. Profondeur : references/bpy-api-traps.md, references/bpy-recipes.md, references/bpy-recipes-scenes.md et references/bpy-recipes-physics.md (chaque recette est exécutée par la suite de tests), references/mcp-bridges.md, references/tools-by-os.md.
Étape 1 : quel Blender
python ../polywright/scripts/pw.py doctor le trouve (POLYWRIGHT_BLENDER, PATH, dossiers d'installation sur Windows,
macOS et Linux) et affiche la version. Ciblez la LTS actuelle (5.2, supportée jusqu'en juillet 2028). Écrivez la version
dans le premier commentaire du script ; les faits d'API ci-dessous sont pour la 5.2.
Étape 2 : exécuter des scripts en headless
python ../polywright/scripts/pw.py bpy build.py [--blend in.blend] [--timeout 1800] -- <args du script>
Les propres options de pw.py peuvent se placer avant ou après le nom du script ; tout ce qui suit -- va au script.
Il exécute blender --background --factory-startup --python-exit-code 3 --python build.py -- args, supprime
le bruit des logs de Blender et renvoie ok, les lignes de sortie du script et la traceback. Sans
--python-exit-code, une erreur Python dans Blender renvoie encore 0 : ne jugez jamais le succès par le seul code de sortie
sinon. Affichez vos propres lignes [pw] pour les nombres dont vous avez besoin (tailles, comptages, vérifications).
Règles du script :
- Commencez par
bpy.ops.wm.read_factory_settings(use_empty=True)ou un.blendexplicite ; ne dépendez jamais du fichier de démarrage d'un utilisateur. - Préférez
bpy.dataetbmeshàbpy.ops. Quand un opérateur est nécessaire, définissez d'abord l'objet actif et la sélection, ou utilisezwith bpy.context.temp_override(...). - Les opérateurs de la vue échouent en headless (
view3d.*,screen.screenshot,render.opengl) : cadrez les caméras à partir des limites vous-même (comme le faitpw.py render). - Lisez les éléments d'énumération au lieu de deviner les noms :
m.bl_rna.properties["solver"].enum_items. - Taille réelle en mètres ; appliquez les transformations avant de mesurer ; les importations glTF arrivent en mode quaternion avec le correctif d'axe sur un parent : effacez les parents en conservant les transformations, puis appliquez, puis mesurez.
- Écrivez chaque chemin de sortie en absolu (
os.path.abspath) et affichez si le fichier existe ensuite : unrender.filepathrelatif a rapporté un succès et n'a rien écrit de visible (L-004). - Sauvegardez un
.blendnuméroté par étape danswork/; redémarrez à partir de celui-ci plutôt que de porter une longue session live. - Faites cuire les simulations avant le rendu, avec le dossier de cache à côté du
.blend(la valeur par défaut est temporaire et perdue à la fermeture). La progression de la cuisson inonde stdout etpw.py bpyen coupe le milieu : écrivez les résultats dans un fichier JSON. - Deux tentatives en cas de traceback ; puis consultez l'API (fichier des pièges, introspection, recherche dans la documentation du MCP officiel) au lieu de deviner une troisième fois.
Étape 3 : les pièges (liste courte ; liste complète dans le fichier des pièges)
| Écrit (ancien) | Utilisez dans 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 a disparu |
BLENDER_EEVEE_NEXT | BLENDER_EEVEE |
import bgl | le module gpu |
Principled Specular, Subsurface, Transmission, Emission, Clearcoat | Specular IOR Level, Subsurface Weight, Transmission Weight, Emission Color, Coat Weight |
action.fcurves | actions à slot : couches, bandes, channelbags |
mod["Socket_2"] = x sur 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 (livres 2.7x) | select_set, view_layer.objects.active, shade_auto_smooth ou set_sharp_from_angle, scene.compositing_node_group |
transform_apply(scale=True) seul | applique aussi la position et la rotation : passez location=False, rotation=False |
Étape 4 : tâches courantes
pw.py fait déjà inspecter, rendre, convertir, LODs, printable et union. Pour tout le reste, prenez une recette dans
references/bpy-recipes.md : images de référence à l'échelle, modificateurs et application, Booléen
avec le solveur Manifold et un fallback EXACT, remaillage voxel, QuadriFlow, UV Smart et UV lightmap, bakes normal et
AO du haut vers le bas, matériaux avec les sockets 5.x, photos de tournette, passes de profondeur et normale pour la vidéo,
exports par moteur, et un objet conçu à partir d'une description écrite (tournage, balayage, miroir ; L-003). Scènes :
references/bpy-recipes-scenes.md : dispersion Geometry Nodes, profondeur inverse,
masques, Brume et normales à partir d'un rendu, argile par remplacement de matériau, Line Art, MP4 via le propre FFmpeg de Blender.
Physique et armatures : references/bpy-recipes-physics.md : cuissons de corps rigides et de tissu,
pourquoi une armature Rigify n'est pas un squelette de jeu, liaison à une armature à la main, remaillage de volume.
Parentage, mouvement F-modifier et drivers : references/bpy-recipes-motion.md. Feuilles d'un
modèle avec des pièces en miroir : élevez la caméra latérale de 10 à 15 degrés, ou une pièce en cache une autre (L-005).
Étape 5 : sessions live (MCP)
Deux serveurs existent : le MCP officiel de Blender Lab (v1.0.3, Blender 5.1+, analyse de scène et recherche de documentation API) et le
communautaire mcp-for-blender (anciennement blender-mcp ; recherche d'actifs et crochets de générateur). Les deux exécutent tout Python que le
modèle envoie, sans sandbox, sur le port 9876. Utilisez-en un, jamais les deux ; seulement quand l'utilisateur regarde Blender et
veut des modifications en direct ; ne collez jamais de texte provenant de fichiers téléchargés dans son code. Configuration et modes de défaillance :
references/mcp-bridges.md. Dans une session live, enveloppez les opérateurs liés à l'éditeur dans
context.temp_override(window=w, area=a, region=r) ; les opérateurs modaux et bpy.app.timers ne s'exécutent que là, jamais sous -b.
Autres outils
Vérifications et réparations de maillage sans Blender : trimesh + manifold3d (+ PyMeshLab) ; livraison web : gltf-transform ou gltfpack ; solides : OpenSCAD, build123d, CadQuery, FreeCAD ; les trancheurs ont des CLI. Versions et ce qui tourne sur quel OS : references/tools-by-os.md. Sur macOS, Blender 5.x et la roue bpy sont Apple Silicon uniquement ; la roue bpy a besoin exactement du Python que Blender empaquette (3.13 pour 5.2).
Maintenance
Unité permanente, niveau moderate (une version de Blender tous les quatre mois ; vérifier à chaque fois). Compagnons :
RESEARCH.md, CHANGELOG.md, LEARNINGS.md, TESTS.md
avec evals/evals.json, MAINTENANCE.md, état dans evergreen.json. Lisez evergreen.json à
chaque utilisation ; rafraîchissez quand nécessaire.