Unreal Game Assets Creation Skill — 텍스트·사진 → 게임 레디 3D 에셋 자동 파이프라인

저장소: LaurentiuGabriel/unreal-game-assets-creation-skill
언어: Python · 94 ⭐ · 최종 업데이트 2026-08-10

개요

이 레포지토리는 Claude Code Skill 형식으로 배포된 텍스트-투-3D 에셋 자동 생성 파이프라인이다. 텍스트 프롬프트 하나 또는 사진 한 장을 입력하면 로컬 AI 서비스 체인을 순차적으로 실행하여 텍스처가 입혀진 게임 레디 3D 메시를 생성하고, 선택적으로 Unreal Engine 프로젝트에 직접 임포트한다.

"a vintage green steam locomotive, single centered object, plain white background, studio product render, full side view" — 제목 카드 이후 모든 프레임이 이 파이프라인의 실제 출력물이다(Fooocus 이미지 + Hunyuan3D-2 GLB 터닝테이블).

파이프라인 구조

텍스트 프롬프트
    │
    ▼ Stage 1 (선택적)
Fooocus SDXL (Fooocus-API REST)
    │  → image.png
    ▼ Stage 2 (핵심)
Hunyuan3D-2 (image-to-textured-mesh)
    │  → textured.glb + white.glb
    ▼ Stage 3 (선택적)
Blender headless (glTF → FBX 변환)
    │  → .fbx
    ▼ Stage 4 (선택적)
Unreal Engine (unreal-mcp StaticMesh import)
    └→ StaticMesh + Blueprint

이미 사진이 있다면 Stage 1을 건너뛰고 Stage 2부터 시작한다.

각 Stage 세부 설명

Stage 1 — 텍스트 → 이미지 (Fooocus SDXL)

scripts/fooocus_gen.py가 Fooocus-API REST 래퍼(localhost:8888)를 호출한다. 바닐라 Fooocus는 gradio_client로 자동화할 수 없는 구조(Gradio 3.41.2, 0 named endpoints)여서 REST API 래퍼가 별도 설치된다.

• 모델: juggernautXL_v8Rundiffusion (포토리얼)
• 최적 프롬프트 규칙: 단일 피사체, 흰 배경, 정면/3/4 뷰, 균일 조명 — Hunyuan3D-2 배경 제거가 명확한 대상을 요구하기 때문
• 속도: GPU 단독 사용 시 약 1–2분, Hunyuan3D 병행 로드 시 약 14분 (VRAM 부족으로 디스크 스왑 발생)

Stage 2 — 이미지 → 텍스처 3D GLB (Hunyuan3D-2)

scripts/hunyuan_gen.py가 Hunyuan3D-2 Gradio 서버(localhost:8080)에 gradio_client로 연결해 이미지-투-텍스처드메시 변환을 실행한다.

• API 엔드포인트: /generation_all(텍스처 포함) / /shape_generation(형상만)
• 주요 파라미터: steps=5(turbo default), octree=256(메시 해상도), rembg=True
• 출력: <name>_textured.glb + <name>_white.glb (텍스처 없는 화이트 메시)
• 소요 시간: GPU 단독 시 60–130초

Stage 3 — GLB → FBX 변환 (Blender headless)

scripts/glb_to_fbx.py를 Blender 4.x가 --background --python 모드로 실행한다. Unreal Engine의 StaticMeshTools.import_file은 .fbx/.obj만 수락하므로 이 변환 단계가 필요하다.

Stage 4 — Unreal Engine 임포트 (unreal-mcp)

StaticMeshTools.import_file로 FBX를 임포트한 뒤, 프로젝트 컨벤션에 따라 BP_TrainBase를 상속하는 레이서 Blueprint에 GLBBody StaticMeshComponent로 연결한다. Scale은 length-match 기준으로 조정하고(relativeRotation yaw -90, relativeLocation.z 보정으로 지면 안착), Blueprint를 컴파일·저장한 뒤 EditorAppToolset.CaptureViewport로 결과를 검증한다.

Claude Code Skill 통합 방식

SKILL.md          # Claude Code가 로드하는 스킬 명세 (name, description, 사용 조건)
scripts/
  fooocus_gen.py  # Stage 1: text → image
  hunyuan_gen.py  # Stage 2: image → textured GLB
  glb_to_fbx.py   # Stage 3: GLB → FBX

SKILL.md의 description 필드가 트리거 조건을 명세한다. ~/.claude/skills/text-to-3d-asset/ 또는 <project>/.claude/skills/에 디렉터리를 복사하면 Claude Code가 자동으로 검색·로드한다. 이후 "make me a 3D asset of a red double-decker bus" 같은 자연어 요청에 스킬이 자동 활성화된다.

하드웨어 제약 및 직렬화 원칙

이 파이프라인은 RTX 4070 Laptop (8 GB VRAM / 32 GB RAM) 에서 검증됐다. Fooocus(SDXL)와 Hunyuan3D-2를 동시에 로드하면 VRAM + RAM 고갈로 디스크 스왑이 발생하여 1분 처리가 14분으로 증가한다. 해결책은 Stage 전환 시 이전 서버를 종료 후 다음 서버를 실행하는 것이다. RTX 5090(Blackwell) 등 VRAM이 풍부한 환경에서는 이 제약이 완화될 수 있다.

ROOPS Continuum 적용 가능성 분석

1. 로봇 부품·환경 3D 에셋 자동 생성

현재 Isaac Sim / MuJoCo 시뮬레이션 환경은 사전 제작된 URDF/MJCF 메시에 의존한다. 이 파이프라인을 통해 텍스트 설명 → 즉석 3D 메시 → URDF 임포트 워크플로를 구성하면 새로운 도구·부품·작업 환경을 프로토타이핑하는 속도가 대폭 향상된다. 예: "a cylindrical gripper tool, single object, white background" 프롬프트 → .glb → Blender .obj 변환 → URDF link 삽입.

2. Claude Code Skill 아키텍처의 ROOPS 적용

SKILL.md + scripts/ 구조는 EOS의 services/ 아키텍처와 동형이다. ROOPS Continuum의 에이전트별 CLAUDE.md(역할 명세)가 Skill의 SKILL.md(사용 조건 명세)에 대응한다. EOS가 관리하는 .claude/skills/에 특화 파이프라인을 등록하면 사령관의 자연어 요청에 즉응하는 인프라 자동화가 가능하다.

3. Aegis(Blackwell RTX 5090) 기반 고성능 실행

Aegis의 RTX 5090 환경에서는 Stage 1–2를 병렬 실행할 수 있으며, 더 높은 해상도(octree=512+)의 메시 생성도 가능하다. Isaac Sim과 별도 프로세스로 분리하면 VRAM 경합을 최소화할 수 있다.

4. Thesis 및 연구 시각화 표준화

로봇 실험 결과물(MuJoCo trajectory, Isaac Sim contact 시뮬레이션)을 3D 터닝테이블 형식으로 렌더링하여 thesis에 첨부하는 시각화 루틴을 표준화할 수 있다. 본 논문에 삽입된 데모 GIF가 그 첫 번째 선례가 된다.

요약