huayuehua15-netizen/unity-blender-mcp

Unity + Blender MCP 자율 제작 파이프라인

경로约定: 이 파일의 모든 scripts/, references/, assets/는 이 SKILL.md 파일이 위치한 디렉토리를 기준으로 합니다. 다른 호스트나 작업 디렉토리로 변경할 경우, 먼저 SKILL.md의 디렉토리를 절대 경로로 변환한 후 호출하십시오. 스크립트 실행 시 반드시 --python-exit-code 1을 포함: Blender는 기본적으로 비정상 종료 시에도 종료 코드가 0이므로, 이 인자를 누락하면 감사 실패도 성공으로 표시됩니다.

개요

이 스킬은 AI가 MCP(Model Context Protocol)를 통해 Blender와 Unity를 자율적으로 조작하여 에셋 우선(Asset-First) 방식으로 3D 게임 에셋을 생산합니다: 먼저 검색하여 재사용하고, 그다음 AI 생성, 마지막으로 처음부터 모델링하며, 각 에셋을 '엔진에 가져오기만 하면 바로 사용 가능한' 완제품으로 만듭니다.

핵심 원칙: 에셋 우선 의사결정 트리

'XX 모델/에셋이 필요하다'는 요청을 받으면 반드시 다음 순서대로 의사 결정하며, 처음부터 직접 만드는 것을 금지합니다:

1. MCP 내장 에셋 소스(가장 빠름, 다운로드 및 이동 불필요): Blender MCP의 search_sketchfab_models / search_polyhaven_assets(HDRI, PBR 텍스처, 사실적 모델); Unity MCP의 import_model(Sketchfab).
2. CC0 게임 에셋 사이트: Kenney, Quaternius, KayKit, Poly Haven, Poly Pizza — 스타일이 통일되어 있고 엔진에 바로 사용 가능하며, 상용에 위험이 없습니다.
3. 대형 마켓플레이스 무료 영역: Sketchfab(CC0/CC-BY이고 Downloadable 필터 적용), TurboSquid, CGTrader, Fab(Megascans), BlenderKit.
4. 중국 내 사이트: 3d66, 모지옥, 아이게이왕 등 — 에셋별로 라이선스와 포맷을 반드시 확인(.max 파일이 많아 Blender에서 열 수 없음, 03 참조).
5. 캐릭터/애니메이션: 뼈대와 애니메이션은 Mixamo(무료 자동 리깅 + 수천 개 동작), Quaternius 애니메이션 캐릭터 팩을 우선 사용.
6. AI 생성: Blender MCP의 Hyper3D Rodin / Hunyuan3D, Unity MCP의 Tripo/Meshy — 단일 명확한 오브젝트에만 사용하며, 전체 씬이나 지형에는 사용하지 않습니다.
7. Blender 자체 제작(최후의 수단): 위의 모든 방법으로 찾을 수 없거나, 정밀한 기능 구조/맞춤형 브랜드 에셋이 필요한 경우에만 bpy/모델링 워크플로우로 자체 제작합니다.

어떤 소스의 에셋이든 Unity에 가져오기 전에 반드시 Blender 감사 및 클리닝(5단계)을 거쳐야 합니다. 다운로드한 원본 FBX를 Unity에 직접 드래그하는 것을 금지합니다.

작업 전: MCP 연결 및 도구 발견(매 세션 필수)

MCP 도구 이름은 구현에 따라 다릅니다(Blender 측은 주로 ahujasid/blender-mcp; Unity 측은 주로 CoplayDev/unity-mcp 또는 Unity 공식 com.unity.ai.assistant). 도구 이름이 고정되어 있다고 가정하지 마십시오.

1. 먼저 현재 세션에 실제로 노출된 MCP 도구를 확인하고, 이를 references/00-mcp-connection.md의 '표준 기능 대조표'와 매핑합니다.
2. 연결 상태를 확인합니다:
   • Blender: 씬 확인 도구(예: get_scene_info)를 호출하여 Blender가 실행 중이고 플러그인이 연결되었는지 확인합니다.
   • Unity: 에디터 상태/콘솔 도구(예: manage_editor / read_console)를 호출하여 브리지가 실행 중인지 확인합니다.
3. 도구가 없거나 연결되지 않은 경우: 00의 문제 해결 표에 따라 처리하거나, 명령줄 배치 처리(blender --background --python, Unity batchmode)로 대체하며, 호출 성공인 척 하지 마십시오.
4. 첫 연결 시 프로젝트의 렌더 파이프라인(Built-in / URP / HDRP)과 Unity 버전을 확인합니다 — 머티리얼 셰이더, 마스크 채널 패키징 방식이 다릅니다.

표준 작업 사이클(모든 작업에서 준수)

현재 상태 확인(scene_info / 콘솔) → 스크린샷/데이터 기록 → 작은 단위로 단일 변경 실행
→ 스크린샷 또는 데이터로 검증 → 저장/기록 → 다음 단계 진행

• 읽기 후 쓰기: 변경 전에 항상 씬/오브젝트 정보를 먼저 가져옵니다. Blender 변경 전에는 bpy.ops.wm.save_as_mainfile로 백업합니다.
• 작은 단위 실행: Blender MCP의 execute_blender_code에는 타임아웃(약 180초)이 있으므로, 복잡한 작업은 여러 코드 블록으로 분할합니다. 각 블록은 자체 포함(자체 import bpy, 이름으로 오브젝트 재선택, 이전 블록의 메모리 변수에 의존하지 않음)되어야 합니다.
• 결과는 반드시 확인 가능: Blender에서 가져오기/배치/내보내기 후 get_viewport_screenshot으로 검증합니다. Unity에서는 각 단계마다 read_console로 오류를 확인하고, 계층/씬 쿼리로 결과를 확인합니다.
• 실패 시 무리하게 진행 금지: 동일 유형의 작업이 두 번 실패하면 방법이나 채널을 변경하고 현상을 기록하며, 동일한 호출을 반복적으로 재시도하지 마십시오.

세 가지 워크플로우

워크플로우 A: 기존 에셋 가져오기(가장 자주 사용됨)

references/04-asset-reuse-workflow.md를 읽고 9단계를 따릅니다: 요구 사항 명세 → 에셋 검색 → 후보 평가(라이선스 포함) → 다운로드 임시 저장 → Blender 감사 → 클리닝 및 표준화 → FBX 내보내기 → 품질 검사 렌더링 및 육안 검사 → Unity 가져오기 및 검수.

• 감사: scripts/blender_asset_audit.py(면 수/머티리얼/UV/변환/뼈대/애니메이션의 JSON 보고서 출력, 예산과 비교하여 유지/폐기 결정).
• 클리닝 + 내보내기: scripts/blender_prep_unity.py(변환 적용, 원점 재설정, 법선 재계산, 이름 통일, Unity 올바른 매개변수로 FBX 내보내기).
• 품질 검사 렌더링: scripts/blender_asset_qa_render.py(내보내기 후 자동으로 표준 조명/구도의 품질 이미지 생성, 텍스처, 금속성/거칠기, 법선, 형태 확인; --turntable N으로 여러 시점 출력 가능, 감사된 데이터와 육안 확인이 모두 통과해야 합격).
• 라이선스: CC0가 아닌 에셋은 항목별로 assets/asset-ledger.csv에 등록(라이선스 유형, 출처 URL, 저작자 표시 요구 사항).

워크플로우 B: 처음부터 에셋 만들기

references/05-model-from-scratch.md를 읽습니다: 참조 이미지/치수 → 로우 폴리 모델링 → 하이 폴리 디테일 → UV → 법선/PBR 베이킹 → 면 수 및 텍셀 예산 자체 점검 → A의 내보내기/가져오기 단계 수행. 먼저 AI 생성으로 대체 가능한지 판단하고, AI 생성 에셋도 감사 및 리토폴로지를 거쳐야 합니다.

워크플로우 C: Blender → Unity 엔진 내 설정

references/06-blender-to-unity.md를 읽습니다: 모델/머티리얼/애니메이션 임포트 설정 → LOD → 충돌 → 머티리얼 텍스처 채널 매핑(URP/HDRP 상이) → 프리팹 생성 → 씬 배치/라이트 베이킹 → 빌드.

• 배치 임포트 시 assets/unity/Editor/AssetPostprocessor.cs를 Unity 프로젝트의 Assets/Editor/에 넣습니다(디렉토리 게이트 포함, 지정된 임포트 디렉토리만 처리, 전체 프로젝트를 오염시키지 않음).

스크립트 및 에셋

파일	용도	실행 방법
scripts/blender_asset_audit.py	현재 씬 또는 지정된 모델 파일을 감사하고 JSON 체크리스트 보고서 출력	MCP: 코드 붙여넣기 실행; 또는 blender --background --python scripts/blender_asset_audit.py -- 모델 경로
scripts/blender_prep_unity.py	선택된 에셋을 클리닝하고 Unity 표준 FBX로 내보내기(선택적 애니메이션 베이킹 포함)	MCP: 코드 붙여넣기 후 prep_and_export() 호출; 또는 명령줄 -- 출력 경로
scripts/blender_asset_qa_render.py	에셋 품질 검사 렌더링: 자동 구도 잡기, HDRI/3점 조명, AgX, 중립 배경으로 품질 이미지 생성, --turntable N 다중 시점 지원	blender --background --python ... -- 모델 경로 출력.png [--hdri 경로] [--turntable 3]; MCP는 현재 씬 렌더링 코드 붙여넣기
assets/unity/Editor/AssetPostprocessor.cs	Unity 측 임포트 후처리: 텍스처를 접미사에 따라 sRGB/법선/마스크로 설정, 모델 통일 스케일/법선/메시 설정	Unity 프로젝트 Assets/Editor/에 복사
assets/asset-ledger.csv	에셋 라이선스 대장 템플릿	CC0가 아닌 각 에셋당 한 행 등록

참조 문서 색인(필요 시 로드)

• references/00-mcp-connection.md: MCP 연결/도구 발견/안전 철칙/MCP 없을 때 명령줄 대체
• references/01-blender-mcp-playbook.md: Blender MCP 도구 표 + bpy 일반 코드 스니펫 라이브러리(가져오기/클리닝/머티리얼/LOD/내보내기/스크린샷)
• references/02-unity-mcp-playbook.md: Unity MCP 도구 표 + 씬/오브젝트/에셋/머티리얼/스크립트/빌드 작업
• references/03-asset-libraries.md: 에셋 라이브러리大全(라이선스/포맷/선정/검색 키워드/3d66 등 중국 내 사이트의 함정)
• references/04-asset-reuse-workflow.md: 에셋 재사용 9단계 프로세스 및 검수 체크리스트
• references/05-model-from-scratch.md: 언제 자체 제작할지, Blender 게임 에셋 생성 파이프라인, AI 생성 에셋 처리
• references/06-blender-to-unity.md: Blender→Unity 표준 파이프라인(축/비율/FBX 매개변수/머티리얼 채널/LOD/충돌/Humanoid)
• references/07-troubleshooting.md: 증상→원인→수정 대조표(분홍 머티리얼/스케일/법선/넘어짐/충돌 없음/T-포즈/발 미끄러짐 등)

안전 철칙

• 사용자의 기존 Blender 씬/Unity 씬을 수정하기 전에 별도로 백업을 저장합니다. 가져오기, 클리닝은 항상 별도의 Blender 씬과 Unity의 Assets/Imports/ 임시 디렉토리 내에서 완료하고, 검수를 통과한 후에만 공식 디렉토리로 이동합니다.
• 사용자의 소스 파일을 삭제하거나 덮어쓰지 않습니다. 다운로드한 원본은 임시 영역에 보관하고, 클리닝 결과물은 별도로 저장합니다.
• execute_blender_code와 Unity의 execute_code는 임의의 코드를 실행할 수 있으므로, 현재 작업과 관련 없는 작업은 금지합니다. 위험한 작업(삭제, 일괄 이름 변경, 덮어쓰기 내보내기)은 먼저 영향을 받는 오브젝트를 나열한 후 실행합니다.
• 라이선스가 명확하지 않은 경우(특히 NC, 학습용 전용, 3d66 무료 품목, 유료 회원 품목)는 절대 상업 프로젝트에 사용하지 않습니다. 차라리 CC0 소스로 변경하거나 자체 제작합니다.
• 모든 머티리얼/텍스처/모델 명명은 규칙을 따릅니다(SM_/SK_/T_BC/N/RMA/M/M_/MI_). 중국어 파일 이름과 중국어 텍스처 경로는 내보내기 전에 모두 영어로 변환합니다.

완료 정의(에셋 수준 DoD)

Unity에 전달되는 각 에셋은 다음을 충족해야 합니다:

• 라이선스가 등록됨(CC0도 출처 기록), 상업적 사용에 문제 없음
• 감사 보고서: 면 수가 예산에 부합, UV 존재, N-gon 문제 없음, 변환이 적용됨
• 씬 내 스케일이 올바름(인물 약 1.7m, 주변 오브젝트와 비율이 현실적), 방향이 올바름
• 머티리얼이 분홍색이 아니고 텍스처가 누락되지 않음(텍스처가 패키지에 포함/프로젝트 내에 있음), URP/HDRP 채널이 올바름
• 적절한 충돌체가 있음, 캐릭터/애니메이션 오브젝트에 Avatar가 할당되고 동작이 정상임
• 프리팹이 생성되었고, LOD가 요구에 따라 구성되었으며, 콘솔에 오류가 없음
• 주요 시점의 품질 이미지가 blender_asset_qa_render.py로 출력되고 육안 검사를 통과함(텍스처/법선/금속성 거칠기/형태), 그런 후 사용자에게 전달하여 확인