blender-physics-workflow

Blender Physics Nodes Workflow Skill (Blender 5.2.1 LTS)

본 스킬은 Blender 5.2.1 LTS(검증된 빌드 9e2066aef7ef)를 대상으로 하며, 대화형 3D 뷰포트 N-패널 작업대(Physics Nodes) 및 격리된 외부 배치 CLI 진입점 <REPO_ROOT>/tools/physics_workflow_cli_v1/cli.py를 제공합니다.

[!IMPORTANT] 동시성 및 안전 경계: 물리 워크플로우 애드온과 CLI는 tools/blenderctl/, tools/geometry_nodes_workflow_addon/ 및 tools/uv_workflow_addon/과 완전히 독립적으로 실행됩니다. 소스 .blend 파일의 무단 덮어쓰기 또는 SHA-256 검증과 디스크 캐시 무효화 검사를 건너뛰는 행위는 엄격히 금지됩니다.

---

1. 핵심 노드 아키텍처: Wrapper + Core + 12개의 편집 가능한 하위 그룹

1. Wrapper 계층 (PNW_Wrapper_<obj>_<mod>) : 수정자에 직접 연결된 최상위 노드 그룹으로, 물리 작업대와 CLI에 통일된 인터페이스를 제공합니다. 지오메트리 노드 편집기에서 삽입된 사용자 정의 노드(예: User_Added_Realize)와 새 인터페이스(예: User Custom Scale)는 이후 update / parameters / bake 작업 중에 완전히 보존됩니다.
2. Core 계층 (PNW_Core_<obj>_<mod>) : 1개의 루트 레벨 GeometryNodeSimulationInput/Output + 꼬리의 GeometryNodeBake + 내부 GeometryNodeRepeatInput/Output(Substeps = 1..8, dt_sub = Delta Time / Substeps)을 포함하여 단일 bake_id와 디스크 캐시가 정확히 1:1로 바인딩되도록 보장합니다. 또한 월드 앵커포인트를 로컬 공간으로 변환하고(Anchor - self_info.Location), 월드 그라운드를 로컬 Ground Z로 변환하며, 생성된 메쉬 재질 전달(GeometryNodeSetMaterial)을 자동으로 수행합니다.
3. 12개의 모듈형 무상태 하위 그룹 (PN_*) :
   • 힘장: PN_Force_GravityDrag, PN_Force_WindTurbulence
   • 충돌: PN_Collide_GroundPlane, PN_Collide_MeshSurface(거리 임계값 마스킹 포함, 유한 메쉬 외부로의 무한 확장 방지)
   • 제약: PN_Constraint_PinAnchor, PN_Constraint_DistanceChain
   • 단계별 솔버: PN_Solver_RigidScatterStep, PN_Solver_ClothRopeStep(p_pred - pnw_rest_pos 기반 상대 정적 변위 PBD 블러(blur) 및 속도 결합, 수축 또는 붕괴 없음), PN_Solver_FluidParticleStep
   • 후처리: PN_Post_InstanceRigid, PN_Post_FluidSDFMesh(PointsToSDFGrid -> GridToMesh), PN_Post_SmokeVolume(PointsToVolume + VolumeToMesh)

---

2. 지원되는 3개 도메인, 6개 사전 설정 및 명시적 브리지

• 계약 식별자: BLENDER_PHYSICS_WORKFLOW_CONTRACT_V1 (schema_version: 1.0)
• 3개 도메인 및 사전 설정 (PRESET_DEFINITIONS) :
  1. rigid_scatter: rigid_drop_pack(다중 인스턴스 낙하 충돌 및 안착), rigid_chain_pendulum(앵커 거리 제약 체인 진자)
  2. cloth_rope: cloth_banner_wind(상단 가장자리 자동 고정 바람 천), rope_catenary_swing(CURVE 자동 파이프 메쉬 출력 지원)
  3. fluid_emission: fluid_fountain_sdf(입자 방출 + 충돌 + SDF 표면화 메쉬), smoke_plume_volume(부력 + 바람 소용돌이 + 볼륨/미리보기 메쉬)
• 솔버 브리지 모드: GN_NATIVE(기본 순수 노드 코어), XPBD_ASSET_BRIDGE(Blender 5.2 내장 Cloth Dynamics (Experimental) 브리지), BULLET_BRIDGE(RigidBodyWorld 브리지), MANTAFLOW_BRIDGE(네이티브 FLUID 수정자 브리지)
• 내보내기 형식: NONE, STATIC_MESH, ALEMBIC(.abc 애니메이션 시퀀스), OPENVDB(영수증/볼륨 적응형 내보내기)

---

3. 대화형 N-패널 작업대 사용

• 패널 위치: 3D 뷰포트 -> N-패널 -> Physics Nodes(VIEW_3D_PT_physics_nodes_workbench)
• 핵심 작업 연산자:
  • pnw.load_preset_defaults: 사전 설정 기본 매개변수 로드
  • pnw.build_workflow: 3계층 노드 트리 구축 및 초기 상태 기록
  • pnw.update_parameters: 사용자 노드 및 외부 연결을 유지하면서 워크플로우/매개변수 업데이트, 매개변수 해시 변경 시 이전 캐시 자동 무효화
  • pnw.bake_cache / pnw.invalidate_cache: DISK 베이크 관리(Windows MAX_PATH 초과를 방지하기 위해 짧은 경로 < 240 문자)
  • pnw.inspect_workflow: 엔티티 수, 변위, 접지 관통 및 캐시 일관성 통계

---

4. CLI 오버레이 자동화 스케줄링 (physics_workflow_cli_v1)

진입점: <REPO_ROOT>/tools/physics_workflow_cli_v1/cli.py. 실행 시 Blender 실행 파일에 의존하므로 먼저 환경 변수 BLENDER_PATH(또는 BLENDERCTL_BLENDER)를 설정하십시오.

4.1. 계약 및 사전 설정 조회

python tools/physics_workflow_cli_v1/cli.py describe

4.2. 단일 씬 빌드, 베이크, 콜드 재오픈 검증 및 Alembic 내보내기 (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

최소 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
  }
}

4.3. 매개변수 스윕 (sweep) 및 배치 처리 (batch)

• sweep: 기본 요청에 매개변수 변형 목록을 주입하고 변위/속도/안정성을 병렬로 비교합니다.
• batch: 여러 개의 독립적인 .blend 시뮬레이션 작업을 순차적으로/격리하여 실행하고 요약 영수증을 출력합니다.

---

5. Blender 5.2.1 주요 주의 사항 체크리스트

1. 수정자 입력 할당: mod[id] = val을 사용하지 말고 반드시 getattr(mod.properties.inputs, identifier).value = val을 통해 할당해야 합니다. 메타데이터는 obj[f"pnw_state_json__{mod.name}"]에 저장됩니다.
2. Nodes 입력 소켓 속성: CollectionInfo["Separate Children"], InstanceOnPoints["Pick Instance"], CurveToMesh["Fill Caps"], PointsToVolume["Resolution Mode"], VolumeToMesh["Resolution Mode"]는 모두 노드 속성이 아닌 node.inputs[...]에 있습니다. GeometryNodeSetShadeSmooth의 첫 번째 입력 포트 이름은 "Mesh"입니다.
3. Alembic 내보내기 키워드: Blender 5.2.1 bpy.ops.wm.alembic_export에는 visible_objects_only 매개변수가 없습니다. 동기식 디스크 쓰기를 보장하려면 as_background_job=False를 명시적으로 설정해야 합니다.
4. 물리 로컬 좌표 및 PBD 수축 방지: Simulation Zone은 오브젝트 로컬 좌표계 내에서 실행되며, 앵커 포인트와 지면은 Self Object 위치를 차감해야 합니다. 천/로프 PBD 블러는 반드시 상대 정적 변위 (p_pred - pnw_rest_pos)에 적용되어야 하며, 절대 좌표를 직접 평활화해서는 안 됩니다.