polywright-blender은(는) 무엇을 하나요?
Blender는 모든 OS에서 무료로 사용할 수 있으며, 마지막 버튼 하나까지 스크립팅 가능한 작업 도구입니다. 에이전트는 라이브 세션의 스크린샷이 아닌, 복사본에 대해 짧은 텍스트 보고서와 함께 헤드리스로 구동하는 것이 가장 좋습니다. 허브로 돌아가기: ../polywright/SKILL.md 깊이: references/bpy-api-traps.md, references/bpy-recipes.md, references/bpy-recipes-scenes.md 및 references/bpy-recipes-physics.md (각 레시피는 테스트 스위트에서 실행됨), references/mcp-bridges.md, references/tools-by-os.md.
1단계: Blender 확인
python ../polywright/scripts/pw.py doctor 명령어로 Blender를 찾고(POLYWRIGHT_BLENDER, PATH, Windows, macOS, Linux의 설치 폴더) 버전을 출력합니다. 현재 LTS (5.2, 2028년 7월까지 지원)를 대상으로 합니다. 스크립트의 첫 번째 주석에 버전을 기록하세요. 아래 API 정보는 5.2 기준입니다.
2단계: 헤드리스로 스크립트 실행
python ../polywright/scripts/pw.py bpy build.py [--blend in.blend] [--timeout 1800] -- <script args>
pw.py의 자체 옵션은 스크립트 이름 앞이나 뒤에 올 수 있습니다. -- 뒤의 모든 것은 스크립트로 전달됩니다.
이 명령어는 blender --background --factory-startup --python-exit-code 3 --python build.py -- args를 실행하고, Blender의 로그 노이즈를 제거하고 ok, 스크립트의 자체 출력 줄 및 역추적을 반환합니다. --python-exit-code 없이 Blender 내부의 Python 오류는 여전히 0으로 종료됩니다: 그렇지 않으면 종료 코드만으로 성공을 판단하지 마십시오. 필요한 숫자 (크기, 개수, 검사)에 대해 자체 [pw] 줄을 출력하세요.
스크립트 규칙:
bpy.ops.wm.read_factory_settings(use_empty=True)또는 명시적인.blend파일로 시작하십시오. 사용자의 시작 파일에 절대 의존하지 마십시오.bpy.ops보다bpy.data와bmesh를 선호하십시오. 연산자가 필요한 경우 먼저 활성 객체와 선택을 설정하거나with bpy.context.temp_override(...)를 사용하십시오.- 뷰포트 연산자는 헤드리스 모드에서 실패합니다(
view3d.*,screen.screenshot,render.opengl): 직접 바운드에서 카메라를 프레임하십시오(pw.py render가 하는 것처럼). - 이름을 추측하는 대신 열거형 항목을 읽으십시오:
m.bl_rna.properties["solver"].enum_items. - 실제 크기는 미터 단위입니다. 측정 전에 변환을 적용하십시오. glTF 가져오기는 쿼터니언 모드로 제공되며 축 수정이 부모에 있습니다: 변환을 유지하면서 부모를 지우고, 적용한 다음 측정하십시오.
- 모든 출력 경로를 절대 경로(
os.path.abspath)로 작성하고 파일이 존재하는지 출력하십시오: 상대render.filepath는 성공을 보고했지만 아무것도 표시되지 않는 파일을 작성했습니다 (L-004). - 각 마일스톤마다
work/에 번호가 매겨진.blend파일을 저장하십시오. 긴 라이브 세션을 유지하는 대신 해당 파일에서 다시 시작하십시오. - 렌더링하기 전에 시뮬레이션을 베이크하고, 캐시 폴더를
.blend파일 옆에 두십시오 (기본값은 임시이며 종료 시 손실됨). 베이크 진행 상황은 stdout을 넘치게 하고pw.py bpy는 중간을 자릅니다: 결과를 JSON 파일에 쓰십시오. - 역추적이 발생하면 두 번 재시도하십시오. 그런 다음 세 번째 추측 대신 API(트랩 파일, 내성 검사, 공식 MCP의 문서 검색)를 조회하십시오.
3단계: 트랩 (짧은 목록; 전체 목록은 트랩 파일 참조)
| 작성 (이전) | 5.x에서 사용 |
|---|---|
bpy.ops.import_scene.obj, import_mesh.stl, import_mesh.ply, wm.collada_* | wm.obj_import, wm.stl_import, wm.ply_import; Collada는 사라짐 |
BLENDER_EEVEE_NEXT | BLENDER_EEVEE |
import bgl | gpu 모듈 |
Principled Specular, Subsurface, Transmission, Emission, Clearcoat | Specular IOR Level, Subsurface Weight, Transmission Weight, Emission Color, Coat Weight |
action.fcurves | 슬롯형 액션: 레이어, 스트립, 채널백 |
Geometry Nodes에서 mod["Socket_2"] = x | mod.properties.inputs.Socket_2.value = x |
import_image.to_plane | image.import_as_mesh_planes |
Workbench shading.show_shadow | shading.show_shadows |
obj.select = True, scene.objects.active, mesh.use_auto_smooth, scene.node_tree (2.7x 서적) | select_set, view_layer.objects.active, shade_auto_smooth 또는 set_sharp_from_angle, scene.compositing_node_group |
transform_apply(scale=True) 단독 | 위치와 회전도 적용: location=False, rotation=False 전달 |
4단계: 일반 작업
pw.py는 이미 검사, 렌더링, 변환, LOD, 인쇄 가능 및 유니온을 수행합니다. 다른 모든 작업에 대해서는 references/bpy-recipes.md에서 레시피를 가져오십시오: 크기 조정된 참조 이미지, 모디파이어 및 적용, Manifold 솔버와 EXACT 폴백을 사용한 불리언, 복셀 리메시, QuadriFlow, Smart UV 및 라이트맵 UV, 하이에서 로우로의 노멀 및 AO 베이크, 5.x 소켓이 있는 재질, 턴테이블 스틸, 비디오를 위한 뎁스 및 노멀 패스, 엔진별 내보내기, 그리고 설명에서 설계된 프로프(선반, 스윕, 미러, L-003). 장면: references/bpy-recipes-scenes.md: Geometry Nodes 분산, 역뎁스, 마스크, 하나의 렌더링에서 Mist와 노멀, 재질 오버라이드로 클레이, Line Art, Blender 자체 FFmpeg를 통한 MP4. 물리 및 리그: references/bpy-recipes-physics.md: 강체 및 천 베이크, Rigify 리그가 게임 뼈대가 아닌 이유, 수동으로 아마추어에 바인딩, 볼륨 리메시. 페어런팅, F-모디파이어 모션 및 드라이버: references/bpy-recipes-motion.md. 미러 이미지 부품이 있는 모델의 시트: 측면 카메라를 10~15도 올리십시오. 그렇지 않으면 한 부품이 다른 부품을 숨깁니다 (L-005).
5단계: 라이브 세션 (MCP)
두 개의 서버가 존재합니다: Blender Lab의 공식 MCP (v1.0.3, Blender 5.1+, 장면 분석 및 API 문서 검색)와 커뮤니티 mcp-for-blender (이전 blender-mcp; 자산 검색 및 생성기 훅). 둘 다 모델이 보내는 모든 Python을 샌드박스 없이 포트 9876에서 실행합니다. 하나만 사용하고 둘 다 사용하지 마십시오. 사용자가 Blender를 보고 라이브 편집을 원할 때만 사용하십시오. 다운로드한 파일의 텍스트를 해당 코드에 붙여넣지 마십시오. 설정 및 실패 모드: references/mcp-bridges.md. 라이브 세션에서 편집기 바인딩 연산자를 context.temp_override(window=w, area=a, region=r)로 래핑하십시오. 모달 연산자와 bpy.app.timers는 거기서만 실행되며 -b 아래에서는 절대 실행되지 않습니다.
기타 도구
Blender 없이 메시 검사 및 복구: trimesh + manifold3d (+ PyMeshLab). 웹 전달: gltf-transform 또는 gltfpack. 솔리드: OpenSCAD, build123d, CadQuery, FreeCAD. 슬라이서에는 CLI가 있습니다. 버전 및 각 OS에서 실행되는 항목: references/tools-by-os.md. macOS에서 Blender 5.x 및 bpy 휠은 Apple Silicon 전용입니다. bpy 휠은 정확히 Blender가 번들로 제공하는 Python (5.2의 경우 3.13)이 필요합니다.
유지 관리
Evergreen 유닛, 등급 moderate (4개월마다 Blender 릴리스, 각각 확인). 컴패니언: RESEARCH.md, CHANGELOG.md, LEARNINGS.md, TESTS.md
evals/evals.json 포함, MAINTENANCE.md, evergreen.json에 상태 저장. 사용할 때마다 evergreen.json을 읽고, 기한이 되면 새로 고침하십시오.