flujo-de-trabajo-fisica-blender

Habilidad de Flujo de Trabajo de Física con Nodos de Blender (Blender 5.2.1 LTS)

Esta habilidad está dirigida a Blender 5.2.1 LTS (build verificado 9e2066aef7ef) y proporciona un banco de trabajo interactivo en el panel N de la vista 3D (Physics Nodes), así como un punto de entrada CLI externo aislado <REPO_ROOT>/tools/physics_workflow_cli_v1/cli.py.

[!IMPORTANTE] Concurrencia y Límites de Seguridad: El complemento de flujo de trabajo de física y la CLI son completamente independientes de tools/blenderctl/, tools/geometry_nodes_workflow_addon/ y tools/uv_workflow_addon/; está estrictamente prohibido sobrescribir archivos .blend de origen sin autorización o saltarse la comprobación SHA-256 y la invalidación de la caché en disco.

---

I. Arquitectura Central de Nodos: Wrapper + Core + 12 Subgrupos Editables

1. Capa Wrapper (PNW_Wrapper_<obj>_<mod>): Grupo de nodos externo montado directamente en el modificador, expone una interfaz unificada para el banco de trabajo de física y la CLI. Los nodos personalizados insertados en el Editor de Geometry Nodes (como User_Added_Realize) y las nuevas interfaces (como User Custom Scale) se conservan intactos en operaciones posteriores de update / parameters / bake.
2. Capa Core (PNW_Core_<obj>_<mod>): Contiene 1 GeometryNodeSimulationInput/Output raíz + un GeometryNodeBake al final + GeometryNodeRepeatInput/Output interno (Substeps = 1..8, dt_sub = Delta Time / Substeps), asegurando un enlace 1:1 preciso entre un único bake_id y la caché en disco; además, realiza automáticamente la conversión del punto de anclaje mundial a espacio local (Anchor - self_info.Location), el plano de tierra mundial a Ground Z local y la transferencia de material de malla generada (GeometryNodeSetMaterial).
3. 12 Subgrupos Modulares sin Estado (PN_*):
   • Campos de fuerza: PN_Force_GravityDrag, PN_Force_WindTurbulence
   • Colisiones: PN_Collide_GroundPlane, PN_Collide_MeshSurface (con umbral de distancia para evitar extensión infinita más allá de la malla finita)
   • Restricciones: PN_Constraint_PinAnchor, PN_Constraint_DistanceChain
   • Solver de pasos: PN_Solver_RigidScatterStep, PN_Solver_ClothRopeStep (basado en desplazamiento relativo de reposo p_pred - pnw_rest_pos con difuminación PBD y acoplamiento de velocidad, sin contracción ni colapso), PN_Solver_FluidParticleStep
   • Post-procesado: PN_Post_InstanceRigid, PN_Post_FluidSDFMesh (PointsToSDFGrid -> GridToMesh), PN_Post_SmokeVolume (PointsToVolume + VolumeToMesh)

---

II. Tres Dominios Soportados, 6 Ajustes Predefinidos y Puente Explícito

• Identificador de Contrato: BLENDER_PHYSICS_WORKFLOW_CONTRACT_V1 (schema_version: 1.0)
• Tres Dominios y Ajustes (PRESET_DEFINITIONS):
  1. rigid_scatter: rigid_drop_pack (colisiones y asentamiento de múltiples instancias), rigid_chain_pendulum (péndulo de cadena con restricción de distancia de anclaje)
  2. cloth_rope: cloth_banner_wind (tela con anclaje automático en el borde superior al viento), rope_catenary_swing (soporta salida de red desde CURVE automática)
  3. fluid_emission: fluid_fountain_sdf (emisión de partículas + colisiones + mallado de superficie SDF), smoke_plume_volume (flotabilidad + vórtice de viento + malla de volumen/vista previa)
• Modos de Puente de Solver: GN_NATIVE (núcleo de nodos puro predeterminado), XPBD_ASSET_BRIDGE (puente con Cloth Dynamics (Experimental) integrado de Blender 5.2), BULLET_BRIDGE (puente con RigidBodyWorld), MANTAFLOW_BRIDGE (puente con el modificador FLUID nativo).
• Formatos de Exportación: NONE, STATIC_MESH, ALEMBIC (secuencia de animación .abc), OPENVDB (exportación adaptada para recibos/Volumen).

---

III. Uso del Banco de Trabajo Interactivo del Panel N

• Ubicación del Panel: Vista 3D -> Panel N -> Nodos de Física (VIEW_3D_PT_physics_nodes_workbench)
• Operadores Principales:
  • pnw.load_preset_defaults: Carga los parámetros predeterminados del ajuste.
  • pnw.build_workflow: Construye el árbol de nodos de tres capas y escribe el estado inicial.
  • pnw.update_parameters: Conserva los nodos de usuario y las conexiones externas mientras actualiza el flujo de trabajo/parámetros; invalida automáticamente la caché antigua cuando cambia el hash de los parámetros.
  • pnw.bake_cache / pnw.invalidate_cache: Gestiona el horneado en DISK (ruta corta < 240 caracteres para evitar el desbordamiento de MAX_PATH en Windows).
  • pnw.inspect_workflow: Estadísticas de número de entidades, desplazamiento, penetración en el suelo y consistencia de la caché.

---

IV. Automatización de Programación CLI Overlay (physics_workflow_cli_v1)

Entrada: <REPO_ROOT>/tools/physics_workflow_cli_v1/cli.py. Al ejecutar dependiendo del ejecutable de Blender, primero configure la variable de entorno BLENDER_PATH (o BLENDERCTL_BLENDER).

1. Consultar Contrato y Ajustes

python tools/physics_workflow_cli_v1/cli.py describe

2. Construcción de Escena Única, Horneado, Verificación de Reapertura en Frío y Exportación Alembic (run)

$env:BLENDER_PATH = "<ruta-a-blender-5.2.1>"
python tools/physics_workflow_cli_v1/cli.py run `
  --request "ruta/al/request.json" `
  --jobs-dir "./jobs/mi-trabajo" `
  --timeout-seconds 300

Ejemplo mínimo 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. Barrido de Parámetros (sweep) y Procesamiento por Lotes (batch)

• sweep: Inyecta variantes de parámetros en la solicitud base y compara desplazamiento/velocidad/estabilidad en paralelo.
• batch: Ejecuta de forma secuencial/aislada múltiples trabajos de simulación .blend independientes y genera un resumen de recibos.

---

V. Lista de Verificación Clave para Evitar Problemas en Blender 5.2.1

1. Asignación de Entradas del Modificador: Se debe asignar mediante getattr(mod.properties.inputs, identifier).value = val (no usar mod[id] = val), los metadatos se almacenan en obj[f"pnw_state_json__{mod.name}"].
2. Propiedades de Toma de Entrada "Output" de Nodes: CollectionInfo["Separate Children"], InstanceOnPoints["Pick Instance"], CurveToMesh["Fill Caps"], PointsToVolume["Resolution Mode"], VolumeToMesh["Resolution Mode"] se encuentran en node.inputs[...], no en las propiedades del nodo; el primer puerto de entrada de GeometryNodeSetShadeSmooth se llama "Mesh".
3. Palabras Clave de Exportación Alembic: Blender 5.2.1 bpy.ops.wm.alembic_export no tiene el parámetro visible_objects_only, se debe establecer explícitamente as_background_job=False para garantizar la escritura sincrónica en disco.
4. Coordenadas Locales de Física y Prevención de Contracción PBD: La Simulation Zone opera en el sistema de coordenadas local del objeto, los puntos de anclaje y el suelo deben restar la posición del Self Object; la difuminación PBD de tela/cuerda debe actuar sobre el desplazamiento relativo de reposo (p_pred - pnw_rest_pos), no se puede suavizar directamente coordenadas absolutas.