Community이미지github.com

blender-live-rigging

사용자의 열린 Blender 앱에서 공식 Blender MCP 소켓 브릿지를 통해 3D 에셋을 실시간으로 리깅, 편집, 검증 및 내보냅니다. 아마추어, 스키닝, 기계/힌지 리그, 드라이버, 커스텀 프로퍼티 컨트롤, 평가 메시 검증, 베이크된 glTF 내보내기 및 소유자가 명시적으로 요청할 때만 렌더링을 지원합니다.

blender-live-rigging란 무엇인가요?

이 스킬은 사용자가 이미 열어놓은 Blender 인스턴스를 직접 제어하여 3D 에셋을 실시간으로 리깅, 편집, 검증 및 내보낼 수 있게 해줍니다. 헤드리스 배치나 앱 종료 없이 라이브 GUI에서 작업하며, 모든 '완료' 주장은 평가된 디펩스그래프(depsgraph)에서 읽은 수치로 뒷받침되어야 합니다. 렌더링은 기본적으로 비활성화되어 있으며 소유자가 명시적으로 요청할 때만 수행됩니다. 이 스킬은 Claude Code, Cursor, Codex 등의 AI 에이전트에서 사용할 수 있으며, Blender의 공식 MCP 브릿지(`bl_ext.blenderlab.mcp`)를 통해 `127.0.0.1:9876` 소켓으로 연결합니다. 리깅 방법, 검증 기준, glTF 내보내기, Blender 5.x 슬롯 액션 호환성 등이 상세한 문서와 함께 제공되어 AI 에이전트가 체계적이고 정확한 리깅 작업을 수행할 수 있도록 지원합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/andypratama3/blender-mcp/tree/HEAD/skills/blender-live-rigging

Installed? Explore more 이미지 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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).

엄격한 규칙

  1. 라이브 GUI 전용. bpy.app.background == False를 확인합니다. 사용자가 작업하는 동안 Blender를 절대 종료하지 마십시오. 포트 충돌로 재시작해야 하는 경우 먼저 .blend를 저장하고 동일한 파일을 다시 여십시오.
  2. 소유자가 요청하지 않으면 렌더링하지 않습니다. 기본 검증은 수치입니다: 정점 좌표, 너비, 면적, 비율. 소유자가 명시적으로 렌더링을 요청하면 라이브 세션에서 수행합니다 (요청 시 렌더 참조).
  3. 편집하는 내용으로 뷰포트 포커스를 맞춥니다. 변경 전후에: 오브젝트/본을 선택하고, 하나를 활성화한 다음 view3d.view_axis + view3d.view_selected를 실행합니다. 에셋 평면에 맞는 축을 선택합니다 (평평한 XZ 에셋의 경우 FRONT).
  4. 평가된 메시를 사용합니다. 원본은 절대 사용하지 마십시오: obj.evaluated_get(depsgraph).to_mesh().
  5. scene.frame_set(f)로 드라이버 평가를 강제합니다. view_layer.update()만으로는 충분하지 않습니다.
  6. 각 마일스톤마다 bpy.ops.wm.save_as_mainfile(filepath=..., compress=True)로 증분 저장합니다. 결과물은 프로젝트 폴더 내에 보관합니다.
  7. execute 한 번 = 이를 증명하는 메트릭을 반환하는 하나의 원자적이고 멱등한 단계입니다.
  8. 본이 아닌 메시에서 바닥에 닿는 것을 측정합니다. 본 꼬리는 밑창 위 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에는 드라이버, 커스텀 프로퍼티 또는 제약 조건이 없습니다. 베이크하십시오:

  1. 소스 액션 이름을 변경합니다 (*_src) 그래야 베이크된 액션이 깨끗한 이름을 얻습니다.
  2. 커스텀 셰이프 위젯 오브젝트를 연결 해제합니다. 그렇지 않으면 빈 노드가 됩니다.
  3. 액션을 지우고, pose_bone.driver_remove(...)를 수행하고, 포즈 극단에서 rotation_euler[0]에 키프레임을 설정합니다.
  4. export_skins=True, export_animations=True, export_animation_mode="ACTIONS", export_yup=True로 내보냅니다.
  5. 복원: 액션을 재할당하고, 베이크를 삭제하고, 위젯을 다시 연결하고, 드라이버를 다시 추가하고, 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=...) TypeError5.4 키워드는 group_namecb.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 — 피벗, 본, 프로퍼티, 각도, 숫자 포함.

관련 스킬