blender-physics-workflow

Compétence Workflow Physique Nodes Blender (Blender 5.2.1 LTS)

Cette compétence cible Blender 5.2.1 LTS (build vérifié 9e2066aef7ef), fournissant un poste de travail interactif 3D via le panneau N (Physics Nodes) ainsi qu'une entrée CLI externe isolée <REPO_ROOT>/tools/physics_workflow_cli_v1/cli.py.

[!IMPORTANT] Concurrence et limites de sécurité : Le module complémentaire de workflow physique et la CLI sont complètement indépendants de tools/blenderctl/, tools/geometry_nodes_workflow_addon/ et tools/uv_workflow_addon/ ; il est strictement interdit de modifier sans autorisation les fichiers .blend source ou de contourner la vérification SHA-256 et l'invalidation du cache disque.

---

1. Architecture nodale centrale : Wrapper + Core + 12 sous-groupes modifiables

1. Couche Wrapper (PNW_Wrapper_<obj>_<mod>) : Groupe de nœuds externe monté directement sur le modificateur, exposant une interface unifiée pour le poste de travail physique et la CLI. Les nœuds personnalisés insérés dans l'éditeur Geometry Nodes (comme User_Added_Realize) et les nouvelles interfaces (comme User Custom Scale) sont entièrement préservés lors des opérations ultérieures update / parameters / bake.
2. Couche Core (PNW_Core_<obj>_<mod>) : Contient 1 GeometryNodeSimulationInput/Output racine + GeometryNodeBake en fin de chaîne + GeometryNodeRepeatInput/Output interne (Substeps = 1..8, dt_sub = Delta Time / Substeps), garantissant une liaison exacte 1:1 entre un seul bake_id et le cache disque ; et effectue automatiquement la conversion des points d'ancrage mondiaux en espace local (Anchor - self_info.Location), le plan de sol mondial en Ground Z local et la transmission du matériau maillé généré (GeometryNodeSetMaterial).
3. 12 sous-groupes modulaires sans état (PN_*) :
   • Champs de force : PN_Force_GravityDrag, PN_Force_WindTurbulence
   • Collisions : PN_Collide_GroundPlane, PN_Collide_MeshSurface (avec masquage par seuil de distance pour éviter les extensions infinies hors maillage)
   • Contraintes : PN_Constraint_PinAnchor, PN_Constraint_DistanceChain
   • Solveurs pas à pas : PN_Solver_RigidScatterStep, PN_Solver_ClothRopeStep (basé sur le déplacement relatif au repos p_pred - pnw_rest_pos avec flou PBD et couplage de vitesse, sans rétrécissement ni effondrement), PN_Solver_FluidParticleStep
   • Post-traitement : PN_Post_InstanceRigid, PN_Post_FluidSDFMesh (PointsToSDFGrid -> GridToMesh), PN_Post_SmokeVolume (PointsToVolume + VolumeToMesh)

---

2. Trois domaines pris en charge, 6 jeux de préréglages et ponts explicites

• Identifiant de contrat : BLENDER_PHYSICS_WORKFLOW_CONTRACT_V1 (schema_version: 1.0)
• Trois domaines et préréglages (PRESET_DEFINITIONS) :
  1. rigid_scatter : rigid_drop_pack (dispersion de multiples instances avec collision et arrêt), rigid_chain_pendulum (pendule en chaîne avec contrainte de distance d'ancrage)
  2. cloth_rope : cloth_banner_wind (ancrage automatique du bord supérieur pour un tissu agité par le vent), rope_catenary_swing (prend en charge CURVE pour une sortie automatique vers le réseau de tuyaux)
  3. fluid_emission : fluid_fountain_sdf (émission de particules + collision + maillage de surface SDF), smoke_plume_volume (flottabilité + turbulences du vent + volume/maillage de prévisualisation)
• Modes de pont solveur : GN_NATIVE (noyau pur de nœuds par défaut), XPBD_ASSET_BRIDGE (pont vers Cloth Dynamics (Experimental) intégré de Blender 5.2), BULLET_BRIDGE (pont vers RigidBodyWorld), MANTAFLOW_BRIDGE (pont vers le modificateur FLUID natif)
• Formats d'exportation : NONE, STATIC_MESH, ALEMBIC (séquence d'animation .abc), OPENVDB (exportation adaptée au reçu/Volume)

---

3. Utilisation interactive du panneau N

• Emplacement du panneau : Vue 3D -> Panneau N -> Physics Nodes (VIEW_3D_PT_physics_nodes_workbench)
• Opérateurs principaux :
  • pnw.load_preset_defaults : Charger les paramètres par défaut d'un préréglage
  • pnw.build_workflow : Construire l'arbre de nœuds à trois couches et écrire l'état initial
  • pnw.update_parameters : Mettre à jour le workflow/paramètres en conservant les nœuds utilisateur et les connexions externes ; invalider automatiquement le cache obsolète en cas de modification du hachage des paramètres
  • pnw.bake_cache / pnw.invalidate_cache : Gérer la cuisson DISK (chemin court < 240 caractères pour éviter le dépassement MAX_PATH de Windows)
  • pnw.inspect_workflow : Compter les entités, les déplacements, la pénétration au sol et la cohérence du cache

---

4. Ordonnancement automatisé par CLI (physics_workflow_cli_v1)

Entrée : <REPO_ROOT>/tools/physics_workflow_cli_v1/cli.py. Lors de l'exécution dépendante de l'exécutable Blender, définissez d'abord la variable d'environnement BLENDER_PATH (ou BLENDERCTL_BLENDER).

1. Interroger le contrat et les préréglages

python tools/physics_workflow_cli_v1/cli.py describe

2. Construction d'une scène unique, cuisson, vérification à froid et exportation Alembic (run)

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

Exemple minimal de request.json :

{
  "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. Balayage de paramètres (sweep) et traitement par lot (batch)

• sweep : Injecte une liste de variantes de paramètres dans une requête de base, compare les déplacements/vitesses/stabilité en parallèle.
• batch : Exécute séquentiellement/en isolation plusieurs travaux de simulation .blend indépendants et produit un récapitulatif de sortie.

---

5. Liste essentielle des pièges à éviter pour Blender 5.2.1

1. Affectation des entrées du modificateur : Doit être effectuée via getattr(mod.properties.inputs, identifier).value = val (ne pas utiliser mod[id] = val), les métadonnées sont stockées dans obj[f"pnw_state_json__{mod.name}"].
2. Propriétés des prises d'entrée des nœuds Nodes : CollectionInfo["Separate Children"], InstanceOnPoints["Pick Instance"], CurveToMesh["Fill Caps"], PointsToVolume["Resolution Mode"], VolumeToMesh["Resolution Mode"] se trouvent dans node.inputs[...] et non dans les propriétés du nœud ; le premier port d'entrée de GeometryNodeSetShadeSmooth est nommé "Mesh".
3. Mots-clés d'exportation Alembic : bpy.ops.wm.alembic_export de Blender 5.2.1 n'a pas le paramètre visible_objects_only, il faut définir as_background_job=False pour garantir un écriture synchrone.
4. Coordonnées physiques locales et anti-rétrécissement PBD : La Simulation Zone fonctionne en coordonnées locales de l'objet, les points d'ancrage et le plan de sol doivent être soustraits de la position de l'Objet Self ; le flou PBD pour le tissu/la corde doit agir sur le déplacement relatif au repos (p_pred - pnw_rest_pos), et non directement sur les coordonnées absolues.