Was macht polywright-blender?
Blender ist das Arbeitstier: kostenlos, auf jedem Betriebssystem lauffähig und bis zum letzten Knopf skriptbar. Ein Agent treibt es am besten headless an, auf Kopien, mit kurzen Textberichten, nicht durch Screenshots einer Live-Sitzung. Zurück zum Hub: ../polywright/SKILL.md. Tiefe: references/bpy-api-traps.md, references/bpy-recipes.md, references/bpy-recipes-scenes.md und references/bpy-recipes-physics.md (jedes Rezept wird von der Testsuite ausgeführt), references/mcp-bridges.md, references/tools-by-os.md.
Schritt 1: Welches Blender
python ../polywright/scripts/pw.py doctor findet es (POLYWRIGHT_BLENDER, PATH, Installationsordner unter Windows,
macOS und Linux) und gibt die Version aus. Ziel ist das aktuelle LTS (5.2, unterstützt bis Juli 2028). Schreibe die Version
in den ersten Kommentar des Skripts; API-Fakten unten beziehen sich auf 5.2.
Schritt 2: Skripte headless ausführen
python ../polywright/scripts/pw.py bpy build.py [--blend in.blend] [--timeout 1800] -- <Skript-Argumente>
pw.py's eigene Optionen können vor oder nach dem Skriptnamen stehen; alles nach -- geht an das Skript.
Es führt blender --background --factory-startup --python-exit-code 3 --python build.py -- args aus, entfernt
Blenders Log-Rauschen und gibt ok, die eigenen Ausgabezeilen des Skripts und den Traceback zurück. Ohne
--python-exit-code liefert ein Python-Fehler in Blender trotzdem Exit-Code 0: Beurteile den Erfolg niemals allein am Exit-Code.
Gib deine eigenen [pw]-Zeilen für die benötigten Zahlen aus (Größen, Anzahlen, Prüfungen).
Skriptregeln:
- Beginne mit
bpy.ops.wm.read_factory_settings(use_empty=True)oder einer expliziten.blend-Datei; verlasse dich niemals auf eine Benutzer-Startdatei. - Bevorzuge
bpy.dataundbmeshgegenüberbpy.ops. Wenn ein Operator benötigt wird, setze zuerst das aktive Objekt und die Auswahl, oder verwendewith bpy.context.temp_override(...). - Viewport-Operatoren schlagen headless fehl (
view3d.*,screen.screenshot,render.opengl): Rahme Kameras selbst aus den Grenzen ein (wiepw.py renderes tut). - Lies Enum-Elemente statt Namen zu raten:
m.bl_rna.properties["solver"].enum_items. - Reale Größe in Metern; wende Transformationen vor dem Messen an; glTF-Importe kommen im Quaternion-Modus mit der Achsenkorrektur auf einem Parent: Entferne Parents unter Beibehaltung der Transformationen, wende dann an, dann messe.
- Schreibe jeden Ausgabepfad absolut (
os.path.abspath) und gib danach aus, ob die Datei existiert: ein relativerrender.filepathmeldete Erfolg und schrieb nichts Sichtbares (L-004). - Speichere eine nummerierte
.blendpro Meilenstein inwork/; starte davon neu, anstatt eine lange Live-Sitzung fortzuführen. - Bake Simulationen vor dem Rendern, mit dem Cache-Ordner neben der
.blend(der Standard ist temporär und geht beim Beenden verloren). Bake-Fortschritt überschwemmt stdout undpw.py bpyschneidet die Mitte ab: Schreibe Ergebnisse in eine JSON-Datei. - Zwei Wiederholungen bei einem Traceback; dann schlage die API nach (Traps-Datei, Introspektion, die Docs-Suche des offiziellen MCP) anstatt ein drittes Mal zu raten.
Schritt 3: Die Fallen (kurze Liste; vollständige Liste in der Traps-Datei)
| Schreibt (alt) | Verwende in 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 ist weg |
BLENDER_EEVEE_NEXT | BLENDER_EEVEE |
import bgl | das gpu-Modul |
Principled Specular, Subsurface, Transmission, Emission, Clearcoat | Specular IOR Level, Subsurface Weight, Transmission Weight, Emission Color, Coat Weight |
action.fcurves | Slot-Aktionen: Layer, Strips, Channelbags |
mod["Socket_2"] = x bei 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 (2.7x-Bücher) | select_set, view_layer.objects.active, shade_auto_smooth oder set_sharp_from_angle, scene.compositing_node_group |
transform_apply(scale=True) allein | wendet auch Position und Rotation an: übergib location=False, rotation=False |
Schritt 4: Häufige Aufgaben
pw.py erledigt bereits Inspektion, Rendern, Konvertieren, LODs, druckbare und Vereinigung. Für alles andere nimm ein Rezept aus
references/bpy-recipes.md: Referenzbilder in Originalgröße, Modifikatoren und Anwenden, Boolesche
Operationen mit dem Manifold-Solver und einem EXACT-Fallback, Voxel-Remesh, QuadriFlow, Smart UV und Lightmap-UVs, Normal- und
AO-Bake von High auf Low, Materialien mit 5.x-Sockets, Drehteller-Standbilder, Tiefen- und Normalen-Pässe für Video,
Exports pro Engine und ein entworfenes Prop aus einer schriftlichen Beschreibung (Drehen, Sweep, Spiegel; L-003). Szenen:
references/bpy-recipes-scenes.md: Geometry Nodes Streuen, inverse Tiefe,
Masken, Nebel und Normalen aus einem Rendering, Lehm durch Material-Override, Strichzeichnung, MP4 über Blenders eigenes FFmpeg.
Physik und Rigs: references/bpy-recipes-physics.md: Starrkörper- und Stoff-
Bakes, warum ein Rigify-Rig kein Spiel-Skelett ist, Binden an ein Armature von Hand, Volumen-Remesh. Parentings, F-Modifikator-
Bewegung und Treiber: references/bpy-recipes-motion.md. Blätter eines
Modells mit spiegelbildlichen Teilen: Hebe die Seitenkamera um 10 bis 15 Grad an, oder ein Teil verdeckt das andere (L-005).
Schritt 5: Live-Sitzungen (MCP)
Es gibt zwei Server: Blender Labs offiziellen MCP (v1.0.3, Blender 5.1+, Szenenanalyse und API-Docs-Suche) und den
Community-MCP für Blender (ehemals blender-mcp; Asset-Suche und Generator-Hooks). Beide führen jedes Python aus, das das
Modell sendet, ohne Sandbox, auf Port 9876. Verwende einen, niemals beide; nur wenn der Benutzer Blender ansieht und
Live-Bearbeitungen wünscht; füge niemals Text aus heruntergeladenen Dateien in seinen Code ein. Setup und Fehlermodi:
references/mcp-bridges.md. Wickle in einer Live-Sitzung Editor-gebundene Operatoren in
context.temp_override(window=w, area=a, region=r) ein; modale Operatoren und bpy.app.timers laufen nur dort, niemals unter -b.
Andere Werkzeuge
Mesh-Prüfungen und Reparaturen ohne Blender: trimesh + manifold3d (+ PyMeshLab); Web-Auslieferung: gltf-transform oder gltfpack; Volumenkörper: OpenSCAD, build123d, CadQuery, FreeCAD; Slicer haben CLIs. Versionen und was auf welchem Betriebssystem läuft: references/tools-by-os.md. Unter macOS sind Blender 5.x und das bpy-Rad nur für Apple Silicon; das bpy-Rad benötigt genau das Python, das Blender mitliefert (3.13 für 5.2).
Wartung
Immergrüne Einheit, Stufe moderate (ein Blender-Release alle vier Monate; prüfe bei jedem). Begleiter:
RESEARCH.md, CHANGELOG.md, LEARNINGS.md, TESTS.md
mit evals/evals.json, MAINTENANCE.md, Status in evergreen.json. Lese evergreen.json bei
jeder Verwendung; aktualisiere, wenn fällig.