blender-physics-workflow

Habilidade de Fluxo de Trabalho de Nós de Física do Blender (Blender 5.2.1 LTS)

Esta habilidade é direcionada ao Blender 5.2.1 LTS (build verificado 9e2066aef7ef), fornecendo uma bancada interativa no painel N da visão 3D (Physics Nodes) e um ponto de entrada CLI externo isolado em <REPO_ROOT>/tools/physics_workflow_cli_v1/cli.py.

[!IMPORTANT] Concorrência e Limites de Segurança: O addon de fluxo de trabalho físico e a CLI são totalmente independentes de tools/blenderctl/, tools/geometry_nodes_workflow_addon/ e tools/uv_workflow_addon/; é estritamente proibido sobrescrever arquivos .blend de origem sem autorização ou ignorar a verificação SHA-256 e a invalidação de cache em disco.

---

I. Arquitetura Central de Nós: Wrapper + Core + 12 Subgrupos Editáveis

1. Camada Wrapper (PNW_Wrapper_<obj>_<mod>) : Grupo de nós externo montado diretamente no modificador, expondo a interface unificada da bancada de física e da CLI. Nós personalizados inseridos no Editor de Nós de Geometria (como User_Added_Realize) e novas interfaces (como User Custom Scale) são totalmente preservados em operações subsequentes de update / parameters / bake.
2. Camada Core (PNW_Core_<obj>_<mod>) : Contém 1 GeometryNodeSimulationInput/Output de nível raiz + GeometryNodeBake no final + GeometryNodeRepeatInput/Output interno (Substeps = 1..8, dt_sub = Delta Time / Substeps), garantindo uma ligação precisa de 1:1 entre bake_id e cache em disco; e converte automaticamente o ponto de ancoragem mundial para espaço local (Anchor - self_info.Location), o solo mundial para Ground Z local e realiza a transferência de material de malha gerada (GeometryNodeSetMaterial).
3. 12 Subgrupos Modulares Sem Estado (PN_*) :
   • Campos de Força: PN_Force_GravityDrag, PN_Force_WindTurbulence
   • Colisão: PN_Collide_GroundPlane, PN_Collide_MeshSurface (inclui máscara de limite de distância para evitar propagação infinita fora da malha finita)
   • Restrições: PN_Constraint_PinAnchor, PN_Constraint_DistanceChain
   • Solvers de Passo: PN_Solver_RigidScatterStep, PN_Solver_ClothRopeStep (baseado no deslocamento relativo de repouso p_pred - pnw_rest_pos com amortecimento PBD e acoplamento de velocidade, sem encolhimento ou colapso), PN_Solver_FluidParticleStep
   • Pós-processamento: PN_Post_InstanceRigid, PN_Post_FluidSDFMesh (PointsToSDFGrid -> GridToMesh), PN_Post_SmokeVolume (PointsToVolume + VolumeToMesh)

---

II. Três Domínios Suportados, 6 Presets e Ponte Explícita

• Identificador de Contrato: BLENDER_PHYSICS_WORKFLOW_CONTRACT_V1 (schema_version: 1.0)
• Três Domínios e Presets (PRESET_DEFINITIONS) :
  1. rigid_scatter: rigid_drop_pack (colisão e empacotamento de múltiplas instâncias), rigid_chain_pendulum (pêndulo de corrente com restrição de distância de ancoragem)
  2. cloth_rope: cloth_banner_wind (tecido随风 ancorado automaticamente na borda superior), rope_catenary_swing (suporta saída automática de CURVE para malha de tubo)
  3. fluid_emission: fluid_fountain_sdf (emissão de partículas + colisão + malha de superfície SDF), smoke_plume_volume (flutuação + vórtices de vento + volume/malha de pré-visualização)
• Modos de Ponte do Solver: GN_NATIVE (núcleo de nó puro padrão), XPBD_ASSET_BRIDGE (ponte para o Cloth Dynamics (Experimental) integrado do Blender 5.2), BULLET_BRIDGE (ponte para RigidBodyWorld), MANTAFLOW_BRIDGE (ponte para o modificador FLUID nativo).
• Formatos de Exportação: NONE, STATIC_MESH, ALEMBIC (sequência de animação .abc), OPENVDB (exportação adaptada para recibo/Volume).

---

III. Uso da Bancada Interativa no Painel N

• Localização do Painel: 3D Viewport -> N-Panel -> Physics Nodes (VIEW_3D_PT_physics_nodes_workbench)
• Operadores Principais:
  • pnw.load_preset_defaults: Carrega parâmetros padrão do preset
  • pnw.build_workflow: Constrói a árvore de nós de três camadas e escreve o estado inicial
  • pnw.update_parameters: Preserva nós do usuário e conexões externas ao atualizar o fluxo de trabalho/parâmetros; invalida automaticamente o cache antigo quando os parâmetros mudam (hash alterado)
  • pnw.bake_cache / pnw.invalidate_cache: Gerencia o cozimento DISK (caminho curto < 240 caracteres para evitar estouro do MAX_PATH do Windows)
  • pnw.inspect_workflow: Estatísticas de entidade, deslocamento, penetração no solo e consistência do cache

---

IV. Automação de Agendamento da CLI Overlay (physics_workflow_cli_v1)

Ponto de entrada: <REPO_ROOT>/tools/physics_workflow_cli_v1/cli.py. Ao executar dependendo do executável Blender, primeiro defina a variável de ambiente BLENDER_PATH (ou BLENDERCTL_BLENDER).

1. Consultar Contrato e Presets

python tools/physics_workflow_cli_v1/cli.py describe

2. Construção, Cozimento, Verificação de Reabertura a Frio e Exportação Alembic de Cena Única (run)

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

Exemplo 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. Varredura de Parâmetros (sweep) e Processamento em Lote (batch)

• sweep: Injeta uma lista de variações de parâmetros sobre uma solicitação base, comparando deslocamento/velocidade/estabilidade em paralelo.
• batch: Executa sequencialmente/isoladamente múltiplos trabalhos de simulação .blend independentes e gera um resumo consolidado.

---

V. Lista de Verificação de Armadilhas Críticas do Blender 5.2.1

1. Atribuição de Entrada do Modificador: Deve ser atribuída via getattr(mod.properties.inputs, identifier).value = val (não use mod[id] = val), os metadados são armazenados em obj[f"pnw_state_json__{mod.name}"].
2. Propriedades de Soquete de Entrada de Nós: CollectionInfo["Separate Children"], InstanceOnPoints["Pick Instance"], CurveToMesh["Fill Caps"], PointsToVolume["Resolution Mode"], VolumeToMesh["Resolution Mode"] estão todos em node.inputs[...], não em atributos do nó; o primeiro porto de entrada de GeometryNodeSetShadeSmooth é chamado "Mesh".
3. Palavras-chave de Exportação Alembic: O bpy.ops.wm.alembic_export do Blender 5.2.1 não tem o parâmetro visible_objects_only, é necessário definir explicitamente as_background_job=False para garantir a finalização síncrona.
4. Coordenadas Locais Físicas e Prevenção de Encolhimento PBD: A Simulation Zone opera internamente no sistema de coordenadas locais do objeto; pontos de ancoragem e solo devem subtrair a posição do Self Object; o amortecimento PBD de tecido/corda deve atuar sobre o deslocamento relativo de repouso (p_pred - pnw_rest_pos), não suavizar coordenadas absolutas diretamente.