blender-physics-workflow

Blender Physik Nodes Workflow Skill (Blender 5.2.1 LTS)

Dieser Skill ist auf Blender 5.2.1 LTS (verifizierter Build 9e2066aef7ef) ausgelegt und bietet einen interaktiven 3D-Viewport N-Panel-Arbeitsbereich (Physics Nodes) sowie einen isolierten externen Batch-CLI-Einstiegspunkt <REPO_ROOT>/tools/physics_workflow_cli_v1/cli.py.

[!IMPORTANT] Nebenläufigkeit und Sicherheitsgrenzen: Das Physik-Workflow-Plugin und die CLI arbeiten völlig unabhängig von tools/blenderctl/, tools/geometry_nodes_workflow_addon/ und tools/uv_workflow_addon/. Das unbefugte Überschreiben von Quell-.blend-Dateien sowie das Überspringen der SHA-256-Prüfung und der Überprüfung auf abgelaufenen Festplattencache sind strengstens untersagt.

---

I. Kern-Node-Architektur: Wrapper + Core + 12 bearbeitbare Subgruppen

1. Wrapper-Ebene (PNW_Wrapper_<obj>_<mod>) : Äußerer Node-Gruppen, der direkt am Modifier montiert ist und eine einheitliche Schnittstelle für den Physik-Arbeitsbereich und die CLI bereitstellt. Benutzerdefinierte Nodes (z. B. User_Added_Realize) und neue Schnittstellen (z. B. User Custom Scale), die im Geometry Nodes Editor eingefügt werden, bleiben bei nachfolgenden update/parameters/bake-Operationen vollständig erhalten.
2. Core-Ebene (PNW_Core_<obj>_<mod>) : Enthält 1 root-level GeometryNodeSimulationInput/Output + ein abschließendes GeometryNodeBake + interne GeometryNodeRepeatInput/Output (Substeps = 1..8, dt_sub = Delta Time / Substeps), um eine exakte 1:1-Bindung einer einzelnen bake_id an den Festplattencache zu gewährleisten. Automatische Umwandlung von Welt-Ankerpunkten in lokalen Raum (Anchor - self_info.Location), Welt-Boden in lokale Ground Z und Materialweitergabe über generierte Geometrie (GeometryNodeSetMaterial).
3. 12 modulare, zustandslose Subgruppen (PN_*) :
   • Kraftfelder: PN_Force_GravityDrag, PN_Force_WindTurbulence
   • Kollision: PN_Collide_GroundPlane, PN_Collide_MeshSurface (mit Distanzschwellen-Unterdrückung zur Verhinderung unendlicher Ausdehnung außerhalb des Netzes)
   • Constraints: PN_Constraint_PinAnchor, PN_Constraint_DistanceChain
   • Schrittweise Solver: PN_Solver_RigidScatterStep, PN_Solver_ClothRopeStep (basiert auf relativer Ruheverschiebung p_pred - pnw_rest_pos; PBD-Diffusion und Geschwindigkeitskopplung, keine Schrumpfung oder Kollaps), PN_Solver_FluidParticleStep
   • Nachbearbeitung: PN_Post_InstanceRigid, PN_Post_FluidSDFMesh (PointsToSDFGrid -> GridToMesh), PN_Post_SmokeVolume (PointsToVolume + VolumeToMesh)

---

II. Unterstützte drei Domänen, 6 Voreinstellungen und explizite Brücken

• Contract-ID : BLENDER_PHYSICS_WORKFLOW_CONTRACT_V1 (schema_version: 1.0)
• Drei Domänen und Voreinstellungen (PRESET_DEFINITIONS) :
  1. rigid_scatter: rigid_drop_pack (Multi-Instanz-Streuung und Kollision mit Ablage), rigid_chain_pendulum (Anker-Distanz-Constraint-Kettenpendel)
  2. cloth_rope: cloth_banner_wind (automatische obere Kantenverankerung für windgeblasenen Stoff), rope_catenary_swing (unterstützt CURVE-Ausgabe zur automatischen Netzumwandlung)
  3. fluid_emission: fluid_fountain_sdf (Partikelemission + Kollision + SDF-Oberflächennetz), smoke_plume_volume (Auftrieb + Windwirbel + Volumen-/Vorschaunetz)
• Solver Bridge Modes : GN_NATIVE (standardmäßig reiner Node-Kern), XPBD_ASSET_BRIDGE (Brücke zu Blender 5.2 integrierter Cloth Dynamics (Experimental)), BULLET_BRIDGE (Brücke zu RigidBodyWorld), MANTAFLOW_BRIDGE (Brücke zum nativen FLUID-Modifier).
• Exportformate : NONE, STATIC_MESH, ALEMBIC (.abc-Animationssequenzen), OPENVDB (Rückmeldung/Volumen-Adapter-Export).

---

III. Interaktive N-Panel-Arbeitsbereichsnutzung

• Panel-Position : 3D Viewport -> N-Panel -> Physics Nodes (VIEW_3D_PT_physics_nodes_workbench)
• Kern-Operatoren :
  • pnw.load_preset_defaults: Laden der Standardparameter einer Voreinstellung
  • pnw.build_workflow: Aufbau der drei Node-Ebenen und Schreiben des Anfangszustands
  • pnw.update_parameters: Aktualisierung des Workflows/der Parameter unter Beibehaltung von Benutzer-Nodes und externen Verbindungen; bei Änderung des Parameter-Hash automatische Ungültigmachung des alten Caches
  • pnw.bake_cache / pnw.invalidate_cache: Verwaltung von DISK-Bakes (kurzer Pfad < 240 Zeichen, um Windows MAX_PATH-Grenze zu vermeiden)
  • pnw.inspect_workflow: Zählen von Entitäten, Verschiebung, Bodenberührung und Cache-Konsistenz

---

IV. CLI-Overlay-Automatisierung (physics_workflow_cli_v1)

Einstiegspunkt: <REPO_ROOT>/tools/physics_workflow_cli_v1/cli.py. Stellen Sie vor der Ausführung mit der ausführbaren Blender-Datei die Umgebungsvariable BLENDER_PATH (oder BLENDERCTL_BLENDER) ein.

1. Contract und Voreinstellungen abfragen

python tools/physics_workflow_cli_v1/cli.py describe

2. Einzelszenario-Build, Bake, Kaltwiedereröffnungs-Verifikation und Alembic-Export (run)

$env:BLENDER_PATH = "<path-to-blender-5.2.1>"
python tools/physics_workflow_cli_v1/cli.py run `
  --request "path/to/request.json" `
  --jobs-dir "./jobs/my-job" `
  --timeout-seconds 300

Minimales request.json-Beispiel:

{
  "schema_version": "1.0",
  "operation": "build",
  "preset_id": "fluid_fountain_sdf",
  "target_object": "Fountain_Emitter",
  "collider_object": "Dome_Deflector",
  "input_blend": "./input/scene_in.blend",
  "output_blend": "./output/scene_baked.blend",
  "bake": true,
  "verify_cold_reopen": true,
  "export_format": "ALEMBIC",
  "export_path": "./output/fluid.abc",
  "parameters": {
    "substeps": 3,
    "frame_start": 1,
    "frame_end": 120,
    "emit_rate": 16,
    "emit_speed": 1.85,
    "particle_radius": 0.15,
    "sdf_voxel_size": 0.07,
    "contact_thickness": 0.15,
    "ground_z": 0.0
  }
}

3. Parameterscan (sweep) und Stapelverarbeitung (batch)

• sweep: Injektion einer Liste von Parametervarianten in eine Basisanfrage, paralleler Vergleich von Verschiebung/Geschwindigkeit/Stabilität.
• batch: Sequenzielle/isolierte Ausführung mehrerer unabhängiger .blend-Simulationsjobs mit Ausgabe einer zusammenfassenden Rückmeldung.

---

V. Wichtige Fallstrick-Liste für Blender 5.2.1

1. Modifier-Eingabe-Zuweisung : Wertzuweisung muss über getattr(mod.properties.inputs, identifier).value = val erfolgen (nicht mod[id] = val); Metadaten werden in obj[f"pnw_state_json__{mod.name}"] gespeichert.
2. Eingabesteckplatz-Eigenschaften von Nodes : CollectionInfo["Separate Children"], InstanceOnPoints["Pick Instance"], CurveToMesh["Fill Caps"], PointsToVolume["Resolution Mode"], VolumeToMesh["Resolution Mode"] befinden sich alle in node.inputs[...] und nicht als Node-Eigenschaften; der erste Eingabeport von GeometryNodeSetShadeSmooth heißt "Mesh".
3. Alembic-Export-Keyword : bpy.ops.wm.alembic_export in Blender 5.2.1 hat keinen Parameter visible_objects_only; as_background_job=False muss explizit gesetzt werden, um eine synchrone Festplatten-Ablage zu gewährleisten.
4. Physik-Lokalkoordinaten und PBD-Schrumpfungsprävention : Die Simulation Zone läuft im lokalen Koordinatensystem des Objekts; Ankerpunkte und Boden müssen um die Position des Self Object korrigiert werden; die PBD-Diffusion für Stoff/Seil muss auf die relative Ruheverschiebung (p_pred - pnw_rest_pos) angewendet werden, nicht direkt auf absolute Koordinaten.