MCP와 Hugging Face Spaces를 활용한 게임 자산 생성기

이 프로젝트는 AI 기반 생성 기능을 활용하여 게임 에셋 제작을 간소화하는 혁신적인 도구입니다. 신속한 프로토타입을 원하는 게임 개발자든, 생성 모델을 탐구하는 AI 애호가든, 이 도구를 사용하면 텍스트 프롬프트에서 2D 및 3D 게임 에셋을 손쉽게 제작할 수 있습니다. "gokaygokay/Flux-2D-Game-Assets-LoRA" , "gokaygokay/Flux-Game-Assets-LoRA-v2" , 그리고 세 가지 3D 모델 생성 공간 ( InstantMesh , Hunyuan3D-2 또는 Hunyuan3D-2mini-Turbo , 계정으로 복제해야 함) 중 하나를 기반으로 하는 Hugging Face Spaces의 AI 모델을 통합하고, Claude Desktop 과 같은 AI 도우미와의 원활한 상호작용을 위해 모델 컨텍스트 프로토콜(MCP)을 사용합니다.

목차

1. 프로젝트 개요

2. 특징

3. 작동 원리

4. 필수 조건

5. 설치

6. 용법

7. 구성

8. 파일 관리

9. MCP 통합

10. 문제 해결

11. 고급의

12. 기여하다

13. 특허

프로젝트 개요

게임 에셋 생성기 (버전 0.3.0 )는 AI를 활용하여 게임 에셋 생성을 간소화합니다. 텍스트 프롬프트에서 2D 에셋 (예: 픽셀 아트 스프라이트)과 3D 에셋 (예: OBJ 및 GLB 모델)을 생성할 수 있으며, Hugging Face Spaces 및 Model Context Protocol(MCP) 과 통합됩니다. 이번 릴리스에서는 InstantMesh , Hunyuan3D-2 , Hunyuan3D-2mini-Turbo 등 다양한 3D 모델 생성 공간을 지원하여 유연성과 향상된 성능을 제공합니다. Node.js 와 MCP TypeScript SDK(v1.7.0) 로 구축된 이 제품은 에셋 생성을 위한 강력한 크로스 플랫폼 솔루션을 제공합니다.

특징

• 2D 자산 생성 : 텍스트 프롬프트에서 픽셀 아트, 스프라이트 또는 기타 2D 자산을 생성합니다(예: "픽셀 아트 검").

• 3D 자산 생성 : 텍스트 설명에서 3D 모델(OBJ 및 GLB 형식)을 생성하고, 이미지를 자동으로 모델로 변환합니다.

• 다중 3D 모델 공간 : 다양한 3D 생성 워크플로를 위해 InstantMesh , Hunyuan3D-2 , Hunyuan3D-2mini-Turbo 지원합니다.

• MCP 통합 : Claude Desktop 과 같은 MCP 호환 클라이언트를 통해 도구와 원활하게 상호 작용합니다.

• 파일 관리 : 리소스 URI(예: asset://{type}/{id} )를 사용하여 로컬 assets 디렉토리에 자산을 자동으로 저장하고 구성합니다.

• 강력한 입력 검증 : 안전하고 안정적인 입력 처리를 위해 Zod를 사용합니다.

• 다중 클라이언트 지원 : SSE 전송을 통해 여러 개의 동시 연결을 처리합니다.

• 보안 원격 액세스 : 안전한 원격 통신을 위한 선택적 HTTPS 지원.

• 확장 가능한 백엔드 : 새로운 모델이나 기능을 쉽게 통합할 수 있는 모듈식 디자인.

• 크로스 플랫폼 : Node.js를 사용하여 Windows, macOS, Linux와 호환됩니다.

• 구성 가능한 3D 생성 : 환경 변수를 통해 추론 단계, 안내 척도, 터보 모드와 같은 매개변수를 사용자 정의합니다.

작동 원리

게임 자산 생성기는 자동화된 파이프라인을 통해 텍스트 프롬프트를 게임에 사용할 수 있는 자산으로 변환합니다.

1. 사용자 입력 : 텍스트 프롬프트를 제출하세요(예: "픽셀 아트 검" 또는 "아이소메트릭 3D 성").

2. MCP 서버 : 프롬프트를 적절한 도구( generate_2d_asset 또는 generate_3d_asset )로 라우팅합니다.

3. AI 모델 상호작용 :

   • 2D 자산 : "gokaygokay/Flux-2D-Game-Assets-LoRA" 사용한 Hugging Face Inference API를 활용합니다(50단계).

   • 3D 자산 :

     • "gokaygokay/Flux-Game-Assets-LoRA-v2" 사용하여 초기 이미지를 생성합니다(30단계).

     • 다음 중 하나를 사용하여 이미지를 3D 모델로 변환합니다.

       • InstantMesh : 다단계 프로세스( /preprocess , /generate_mvs , /make3d ).

       • Hunyuan3D-2 : 단일 단계 프로세스( /generation_all ).

       • Hunyuan3D-2mini-Turbo : 구성 가능한 터보 모드를 갖춘 단일 단계 프로세스( /generation_all ).

4. 파일 출력 : assets 디렉토리에 자산(2D의 경우 PNG, 3D의 경우 OBJ/GLB)을 저장합니다.

5. 응답 : 즉시 사용할 수 있는 리소스 URI(예: asset://3d_model/filename.glb )를 반환합니다.

워크플로 다이어그램

지엑스피1

최적의 품질을 위해 프롬프트는 자동으로 "매우 자세하고 완전한 객체이며 잘리지 않았으며 흰색 단색 배경"으로 향상됩니다.

필수 조건

• Node.js : 버전 16 이상( npm 포함).

• Git : 저장소를 복제합니다.

• 인터넷 접속 : Hugging Face API 연결에 필요합니다.

• Hugging Face 계정 : API 접근에 필요합니다. huggingface.co/settings/tokens 에서 토큰을 받으세요.

• NPM 패키지 :

  • @gradio/client : Hugging Face Spaces와 상호작용합니다.

  • @huggingface/inference : 직접적인 모델 추론을 위해.

  • @modelcontextprotocol/sdk : MCP 서버를 구현합니다.

  • dotenv : 환경 변수를 로드합니다.

  • express : SSE 전송을 활성화합니다.

  • zod : 입력 검증을 보장합니다.

  • sharp : 이미지 처리를 처리합니다.

• 선택 사항 : 향상된 상호작용을 위해 Claude Desktop (또는 다른 MCP 클라이언트)을 사용합니다.

설치

1. 저장소 복제 :

   git clone https://github.com/yourusername/game-asset-mcp.git cd game-asset-mcp

2. 종속성 설치 :

   npm install

3. 환경 구성 :

   • 예제 .env 파일을 복사하세요.

     cp .env.example .env

   • Hugging Face API 토큰 과 복제된 MODEL_SPACE를 사용하여 .env 편집하세요. 자세한 내용은 구성을 참조하세요.

4. 서버 실행 :

   • 로컬(stdio 전송) :

     npm start

   • 사용자 정의 작업 디렉토리 :

     node src/index.js /path/to/directory

   • 원격(SSE 전송) :

     node src/index.js --sse

   • HTTPS를 통한 원격 :

     node src/index.js --sse --https

     ssl/key.pem 및 ssl/cert.pem 필요합니다( ssl/README.md 참조).

참고 : ES 모듈을 사용합니다( package.json 에 "type": "module" ). Node.js 16 이상이 설치되어 있는지 확인하세요( node --version ).

용법

MCP 클라이언트 (예: Claude Desktop)를 통해 또는 프로그래밍 방식으로 서버와 상호 작용합니다.

• 2D 자산 생성 :

  • 명령어 : generate_2d_asset prompt:"pixel art sword"

  • 출력 : PNG 파일(예: 2d_asset_generate_2d_asset_1698765432.png )을 저장하고 해당 URI를 반환합니다.

• 3D 자산 생성 :

  • 명령어 : generate_3d_asset prompt:"isometric 3D castle"

  • 출력 : OBJ/GLB 파일과 중간 이미지를 저장하고 해당 URI를 반환합니다. 장기 실행 작업에 대한 작업 ID를 제공합니다.

프롬프트 예제

• 자연스러운 상호작용 :

  • generate_2d_sprite prompt:"pixel art sword"

  • generate_3d_model prompt:"isometric 3D castle"

클로드 데스크톱과 함께

구성 후( 구성 참조) 인터페이스에 직접 명령을 입력합니다.

구성

.env 파일을 통해 서버를 사용자 정의합니다.

필수 설정

• HF_TOKEN : Hugging Face API 토큰.

  HF_TOKEN=your_hf_token

• MODEL_SPACE : 복제된 3D 모델 공간(예: your-username/InstantMesh ).

  • 다음 중 하나를 복제하세요.

    • 인스턴트메시

    • 헌원3D-2

    • 훈위안3D-2미니 터보 GXP10

선택적 3D 모델 설정

공간별 기본값

• 인스턴트메시 :

  • 단계: 30-75 (기본값: 75)

  • 시드: 기본 42

• 헌원3D-2 :

  • 단계: 20-50 (기본값: 20)

  • 안내 척도: 기본 5.5

  • Octree 해상도: 256 , 384 , 512 (기본값: 256 )

  • 시드: 기본 1234

• Hunyuan3D-2mini-Turbo :

  • 단계: 1-100(기본값: Turbo 의 경우 5, Fast 의 경우 10, Standard 의 경우 20)

  • 지침 척도: 기본 5.0

  • Octree 해상도: 16-512(기본값: 256)

  • 시드: 기본 1234

전송 설정

• PORT : SSE 전송 포트(기본값: 3000).

  PORT=3000

클로드 데스크탑 설정

구성 파일을 편집하세요:

• MacOS : ~/Library/Application Support/Claude/claude_desktop_config.json

• 윈도우 : %APPDATA%\Claude\claude_desktop_config.json

편집 후 Claude Desktop을 다시 시작하세요.

파일 관리

• 저장 위치 : 자산은 작업 디렉토리 내의 ./assets 에 저장됩니다.

• 명명 규칙 : 파일은 접두사, 도구 이름, 타임스탬프 및 고유 ID를 사용합니다(예: 2d_asset_generate_2d_asset_1698765432_abcd1234.png ).

• 사용자 정의 : 사용자 정의 디렉토리 설정:

  node src/index.js /path/to/custom/directory

• 리소스 액세스 : MCP URI(예: asset://2d_asset/filename.png )를 사용하여 자산을 나열하거나 읽습니다.

MCP 통합

MCP(모델 컨텍스트 프로토콜)를 통해 이 도구는 AI 클라이언트에게 안전하게 서비스를 제공할 수 있습니다.

• 도구 : generate_2d_asset , generate_3d_asset .

• 리소스 : asset:// URI를 통해 관리됩니다.

• 프롬프트 : generate_2d_sprite , generate_3d_model .

• 호환성 : Claude Desktop 및 기타 MCP 클라이언트와 호환됩니다.

문제 해결

• API 오류 : 네트워크 연결이나 속도 제한을 확인하세요. ./logs/server.log 를 검토하세요.

• 인증 문제 : .env 에서 HF_TOKEN 및 MODEL_SPACE 확인하세요.

• ES 모듈 오류 : Node.js 16 이상을 확인하세요( node --version ).

• 로그 : 자세한 로그를 검사합니다.

  tail -f ./logs/server.log

고급의

API 엔드포인트 및 통합

• 2D 자산 생성 : "gokaygokay/Flux-2D-Game-Assets-LoRA" 사용합니다(50단계).

• 3D 자산 이미지 생성 : "gokaygokay/Flux-Game-Assets-LoRA-v2" 사용합니다(30단계).

• 3D 모델 변환 :

  • InstantMesh : 다단계( /check_input_image , /preprocess , /generate_mvs , /make3d ).

  • Hunyuan3D-2 : 단일 단계( /generation_all ).

  • Hunyuan3D-2mini-Turbo : 터보 모드가 있는 단일 단계( /generation_all ).

버전 관리

• 현재 버전 : 0.3.0(Hunyuan3D-2mini-Turbo 지원 추가).

• MCP SDK 버전 : 1.7.0.

• 형식 : MAJOR.MINOR.PATCH(SemVer).

백엔드 아키텍처

• 코어 파일 : src/index.js .

• 종속성 : package.json 참조하세요.

• 보안 : Zod 검증, 경로 횡단 방지, HTTPS 지원, 속도 제한.

• 성능 : 비동기 처리, 백오프를 통한 재시도, GPU 할당량 처리.

기여하다

여러분의 참여를 환영합니다! 참여 방법:

1. 저장소 포크 : GitHub에 사본을 만듭니다.

2. 변경하기 : 기능을 추가하고, 버그를 수정하고, 문서를 개선합니다.

3. 풀 리퀘스트 제출 : 변경 사항을 자세히 설명하세요.

4. 열린 문제 : 버그를 보고하거나 개선 사항을 제안하세요.

표준 코딩 규칙을 따르고 해당되는 경우 테스트를 포함합니다.

특허

MIT 라이선스 에 따라 라이선스가 부여되었습니다. 자세한 내용은 LICENSE 파일을 참조하세요.