Blender 실시간 리깅
사용자가 이미 보고 있는 Blender 인스턴스를 구동합니다. 헤드리스 배치나 앱 종료는 없습니다. '완료'라고 주장하려면 반드시 평가된 디펩스그래프에서 읽은 수치로 뒷받침해야 합니다. 렌더링은 기본적으로 비활성화되어 있으며 소유자가 요청할 때만 수행됩니다.
리포지토리 문서 (깊이가 필요할 때마다 읽지 말고 참조):
docs/MCP_BRIDGE.md— 프로토콜, 실행 모드, 함정, 뷰포트 포커스docs/RIGGING_PLAYBOOK.md— 전체 리깅 방법 및 내보내기/복원 레시피docs/VERIFICATION.md— 메트릭 임계값 및 스니펫docs/RENDERING.md— 소유자 요청 렌더 경로reference/roblox-avatar.md— R15 바디 계약, 제자리 걷기 IK, FBX 검증reference/blender-5x-api.md— 슬롯 액션, 측정된 5.4 API, glTF 시간 원점reference/glb-qa.md— 렌더링 없는 GLB 게이트, 기준선, 부정 테스트 증거docs/CASE_STUDY_KNIGHT.md— 측정된 R15 아바타 + 걷기 루프 (리포지토리 루트)
이 스킬이 andypratama3/blender-mcp에서 설치된 경우, 리포지토리 루트는 이 파일에서 세 단계 위입니다 (skills/blender-live-rigging/SKILL.md).
엄격한 규칙
- 라이브 GUI 전용.
bpy.app.background == False를 확인합니다. 사용자가 작업하는 동안 Blender를 절대 종료하지 마십시오. 포트 충돌로 재시작해야 하는 경우 먼저.blend를 저장하고 동일한 파일을 다시 여십시오. - 소유자가 요청하지 않으면 렌더링하지 않습니다. 기본 검증은 수치입니다: 정점 좌표, 너비, 면적, 비율. 소유자가 명시적으로 렌더링을 요청하면 라이브 세션에서 수행합니다 (요청 시 렌더 참조).
- 편집하는 내용으로 뷰포트 포커스를 맞춥니다. 변경 전후에: 오브젝트/본을 선택하고, 하나를 활성화한 다음
view3d.view_axis+view3d.view_selected를 실행합니다. 에셋 평면에 맞는 축을 선택합니다 (평평한 XZ 에셋의 경우FRONT). - 평가된 메시를 사용합니다. 원본은 절대 사용하지 마십시오:
obj.evaluated_get(depsgraph).to_mesh(). scene.frame_set(f)로 드라이버 평가를 강제합니다.view_layer.update()만으로는 충분하지 않습니다.- 각 마일스톤마다
bpy.ops.wm.save_as_mainfile(filepath=..., compress=True)로 증분 저장합니다. 결과물은 프로젝트 폴더 내에 보관합니다. execute한 번 = 이를 증명하는 메트릭을 반환하는 하나의 원자적이고 멱등한 단계입니다.- 본이 아닌 메시에서 바닥에 닿는 것을 측정합니다. 본 꼬리는 밑창 위 0.4 스터드에 위치할 수 있으므로, 본-꼬리 게이트는 통과하지만 부츠가 땅에 잠길 수 있습니다. 평가된 메시의 가장 낮은 월드 정점을 사용합니다.
1. 연결
브릿지는 공식 애드온 bl_ext.blenderlab.mcp이며 127.0.0.1:9876에서 실행됩니다.
lsof -nP -iTCP:9876 -sTCP:LISTEN # 실행 전에 반드시 비어 있어야 함
open -a Blender --args --online-mode "/abs/path/file.blend" # macOS
sleep 8 && lsof -nP -iTCP:9876 -sTCP:LISTEN
--online-mode는 필수입니다 (자동 시작에는 bpy.app.online_access가 필요함). --factory-startup은 절대 사용하지 마십시오 (확장 기능을 비활성화합니다). 그런 다음:
python3 scripts/blender_mcp.py 'import bpy
result = {"gui": not bpy.app.background, "file": bpy.data.filepath}'
2. 에셋 검사
glTF를 가져오고, matrix_world를 메시 데이터에 베이크하고, 빈 부모를 제거하고, 중복을 용접하고 (remove_doubles(1e-5)), 연결된 쉘을 세고, ASCII 실루엣을 출력하여 평면, 피벗 및 움직이는 부품을 찾습니다:
blender -b --factory-startup --python scripts/inspect_glb.py -- "/path/asset.glb"
3. 리그 토폴로지 결정
기계적 에셋의 경우: 강체 부품, 강체 가중치, 부품당 하나의 본. 가위/플라이어 형태의 경우 부품을 대각선으로 쌍을 이룹니다 (왼쪽 손잡이 + 오른쪽 턱 반) 그래야 손잡이와 턱이 함께 열립니다. 중간선 분할은 턱이 손잡이가 열릴 때 닫히게 만듭니다.
힌지 피벗을 손잡이가 만나는 곳에 배치하고, 시임 절단도 거기에 배치하며, rotation_euler.x가 정확히 월드 힌지 축이 되도록 본을 정렬합니다:
d = (Vector(b.tail) - Vector(b.head)).normalized()
b.align_roll(Vector((d.z, 0.0, -d.x))) # local X == world Y
4. 메시 준비
use_fill=True로 모든 강체 부품 경계에서 양분하고, 캡을 ~0.0004만큼 오프셋하여 Z-파이팅을 제거하고, 캡 면만 뒤집습니다 (glTF 커스텀 분할 법선 유지), 결합 전에 부품별로 버텍스 그룹을 할당한 다음 ARMATURE 수정자로 부모 지정합니다.
5. 컨트롤과 애니메이션
하나의 커스텀 프로퍼티 (open, 0–1)가 간단한 드라이버 표현식을 통해 모든 본을 구동하며, LIMIT_ROTATION을 안전장치로 추가합니다. rotation_euler를 구동하기 전에 rotation_mode = "XYZ"로 설정합니다. 루프 액션을 위해 본이 아닌 프로퍼티에 키프레임을 설정하고, BEZIER + AUTO_CLAMPED를 사용합니다.
6. 검증 (성공을 주장하기 전에 게이트)
| 메트릭 | 임계값 |
|---|---|
| 소스 메시 대비 휴식 편차 | < 1e-5 |
| 루프 시임 (마지막 프레임 vs 첫 번째) | 0 |
| 열림/닫힘 면적비 | 0.99–1.01 |
| 손잡이와 턱이 모두 바깥쪽으로 움직임 | > 0 |
| 가중치가 적용된 정점 | 100% |
| 비-매니폴드/제로 면적 면 | 0 |
| 가장 낮은 변형 정점 vs 바닥 | ≥ −0.006, 스탠스 발 0 ± 0.006 |
scripts/verify_rig_glb.py는 별도의 Blender 프로세스에서 내보낸 GLB를 다시 가져와서 (라이브 세션을 방해하지 않음) 프레임 1/15/30/60에서 노드/스킨/애니메이션 개수와 너비를 출력합니다.
운동(locomotion)의 경우, 손으로 관절 각도를 키프레임하는 대신 발목 타겟에 대한 두-본 IK로 다리를 해결한 다음, 모든 프레임을 측정합니다:
low = min((ev.matrix_world @ v.co).z for v in ev.to_mesh().vertices) # 프레임당
본 게이트와 메시 게이트가 일치하지 않으면 메시 게이트가 옳습니다.
6d. 렌더링 없는 GLB QA
python3 scripts/glb_qa.py export/model.glb --loop --max-tris 20000
python3 scripts/glb_qa.py export/tool.glb --manifold
표준 라이브러리만 사용, Blender 없음: GLB 컨테이너를 직접 읽고 헤더 길이, 액세서 바운드, 가중치 합, 가중치 없는 정점, 조인트 인덱스, 바인드 포즈 개수, 키프레임 순서, 쿼터니언 노름, 루프 클로저, NaN 및 (--manifold 포함) 경계 엣지를 검사합니다. 실패 시 Exit 1을 반환합니다. verify_rig_glb.py는 여전히 움직이는 부품 너비 측정을 담당합니다. 게이트, 기준선 및 이들이 잡아낸 다섯 개의 의도적으로 망가진 파일: reference/glb-qa.md.
6b. 다중 파일 프로젝트 스크립트 라이브 실행
자체 모듈을 가져오는 스크립트는 라이브 세션 내에서 경로로 로드해야 합니다:
import importlib.util, sys
spec = importlib.util.spec_from_file_location("walk_cycle", "/abs/project/walk_cycle.py")
mod = importlib.util.module_from_spec(spec)
sys.modules["walk_cycle"] = mod # 그렇지 않으면 dataclasses/imports에서 중복으로 간주
spec.loader.exec_module(mod)
result = mod.main(save=True) # 측정된 게이트의 딕셔너리 반환
헤드리스 실행을 위해 __main__을 유지하고 (blender -b file.blend --python walk_cycle.py -- --save), 브릿지에서 main()을 호출하여 하나의 스크립트가 두 경로를 모두 제공하도록 합니다.
6c. Blender 5.x에서의 액션 (슬롯)
Action.fcurves, Action.groups 및 Action.id_root는 5.4에 존재하지 않습니다. channelbag 탐색을 다시 입력하는 대신 헬퍼를 사용하고, 슬롯을 명시적으로 바인딩하십시오:
# 라이브 세션 (cwd = 이 스킬 폴더); `result`로 감사 결과 반환
python3 scripts/blender_mcp.py "import sys; sys.path.insert(0, 'scripts')
import action_compat
result = action_compat.audit()"
# 헤드리스; 슬롯이 바인딩되지 않으면 exit 1
blender -b file.blend --python scripts/action_compat.py
from action_compat import iter_fcurves, ensure_fcurve, assign_action
slot = assign_action(obj, action) # 할당만으로는 action_slot이 None으로 남음
ensure_fcurve(action, slot, 'pose.bones["Head"].rotation_euler', 1, group_name="HeadTwist")
측정된 실패 모드: 이미 슬롯이 있는 액션을 다른 ID에 할당하면 animation_data.action_slot is None이 되고 리그가 아무 오류 없이 휴식 상태에 머뭅니다 (머리가 애니메이션된 3.92 대신 4.0). 게이트: action_compat.py는 모든 애니메이션된 오브젝트에 대해 slot_assigned: true 및 slot_fcurves > 0을 보고합니다. 또한 channelbag.fcurves.new(..., group_name=...), 절대 action_group=를 사용하지 마십시오.
세부 사항 및 나머지 측정된 API: reference/blender-5x-api.md.
7. glTF 내보내기
glTF에는 드라이버, 커스텀 프로퍼티 또는 제약 조건이 없습니다. 베이크하십시오:
- 소스 액션 이름을 변경합니다 (
*_src) 그래야 베이크된 액션이 깨끗한 이름을 얻습니다. - 커스텀 셰이프 위젯 오브젝트를 연결 해제합니다. 그렇지 않으면 빈 노드가 됩니다.
- 액션을 지우고,
pose_bone.driver_remove(...)를 수행하고, 포즈 극단에서rotation_euler[0]에 키프레임을 설정합니다. export_skins=True,export_animations=True,export_animation_mode="ACTIONS",export_yup=True로 내보냅니다.- 복원: 액션을 재할당하고, 베이크를 삭제하고, 위젯을 다시 연결하고, 드라이버를 다시 추가하고,
frame_set(1)을 수행하고, 저장합니다.
"지원되지 않는 제약 조건으로 인해 애니메이션을 베이킹합니다" 경고는 예상됩니다.
요청 시 렌더 (소유자 전용)
트리거: 소유자가 명시적으로 렌더를 말하거나, 미리보기 이미지/비디오를 요청합니다. 스스로 렌더링하지 말고, 검증으로 렌더링하지 마십시오.
Blender 5.4는 EEVEE를 BLENDER_EEVEE로 노출합니다 (BLENDER_EEVEE_NEXT가 아님). 따라서 버전별 이름을 하드코딩하는 대신 열거형에서 선택하십시오. glTF 장면에는 카메라와 조명이 없습니다 — 먼저 Render_Setup 컬렉션에 생성하십시오.
import bpy, math, os
scene = bpy.context.scene
engines = [i.identifier for i in bpy.types.RenderSettings.bl_rna.properties["engine"].enum_items]
scene.render.engine = next(e for e in ("BLENDER_EEVEE", "BLENDER_EEVEE_NEXT") if e in engines)
if scene.camera is None:
cam_data = bpy.data.cameras.new("Preview_Cam")
cam_data.type = "ORTHO"
cam_data.ortho_scale = 1.0
cam = bpy.data.objects.new("Preview_Cam", cam_data)
scene.collection.objects.link(cam)
cam.location = (0.0, -2.0, -0.055)
cam.rotation_euler = (math.radians(90), 0.0, 0.0)
scene.camera = cam
if not any(o.type == "LIGHT" for o in bpy.data.objects):
light_data = bpy.data.lights.new("Preview_Key", "AREA")
light_data.energy = 300
light_data.size = 2.0
light = bpy.data.objects.new("Preview_Key", light_data)
scene.collection.objects.link(light)
light.location = (1.5, -2.0, 1.5)
light.rotation_euler = (math.radians(55), 0.0, math.radians(35))
scene.render.resolution_x = 1920
scene.render.resolution_y = 1080
scene.render.resolution_percentage = 100
scene.render.image_settings.file_format = "PNG"
scene.render.filepath = "/abs/project/render/preview.png"
bpy.ops.render.render(write_still=True)
result = {"image": scene.render.filepath,
"size": os.path.getsize(scene.render.filepath),
"engine": scene.render.engine, "camera": scene.camera.name}
이 경로에 대한 규칙: 먼저 .blend를 저장하고, <project>/render/ 안에 쓰고, 절대 경로와 파일 크기를 보고하고, 클라이언트 타임아웃을 늘리며, 저장되지 않은 변경 사항이 있는 파일의 헤드리스 렌더를 절대 시작하지 마십시오.
Blender 5.4 함정
| 증상 | 원인 | 해결책 |
|---|---|---|
| 드라이버가 아무것도 변경하지 않음 | 디펩스그래프가 평가되지 않음 | scene.frame_set(f) |
Action.fcurves 누락 | 슬롯 액션 | act.layers[0].strips[0].channelbags[*].fcurves 또는 scripts/action_compat.py |
| 리그가 움직이지 않음, 오류 없음 | 할당된 액션에 이 ID에 바인딩된 슬롯이 없음 | assign_action() / animation_data.action_slot 설정 |
fcurves.new(action_group=...) TypeError | 5.4 키워드는 group_name | cb.fcurves.new(path, index, group_name="...") |
asset.mark() 폴 실패 | 연산자가 Outliner 선택을 읽음 | obj.asset_mark() API |
| 프로퍼티 키프레임 무시됨 | 잘못된 데이터 경로 | '["open"]' |
.001 액션 접미사 | 이름 충돌 | 먼저 소스 액션 이름 변경 |
| GLB의 위젯 | 오브젝트가 여전히 장면 컬렉션에 있음 | 내보내기 중에 연결 해제 |
Unrecognized command | --factory-startup / 확장 기능 꺼짐 | 온라인으로 재실행 |
| 자동 시작 무음 | 포트 사용 중 | 포트 해제, 재실행 (재시도 없음) |
| 렌더 열거형 오류 | 잘못된 엔진 이름 | 열거형에서 BLENDER_EEVEE 선택 |
enum "OCTAHEDRAL" not found | 아마추어 표시는 데이터, 오브젝트가 아님 | rig.data.display_type = "OCTAHEDRAL" |
bpy.context.window가 None임 | 백그라운드 빌드에 창 없음 | window_manager.windows로 보호 |
| FBX 재가져오기로 캐릭터가 뜸 | 임포터가 루트를 연결된 본으로 표시하고 변환을 드롭 | 왕복이 아닌 scripts/inspect_fbx.py로 파일 검증 |
결과물
.blend— 권위 있는 리그, 휴식 프레임에 저장,README_RIG텍스트 블록 포함..glb— 스킨 + 애니메이션, 재가져오기로 검증.- 프로젝트 폴더의
README.md— 피벗, 본, 프로퍼티, 각도, 숫자 포함.