Communitygithub.com

3D 게임 에셋

3D 게임에 기본 프리미티브 도형 대신 구체적이고 인식 가능한 GLB 에셋이 필요할 때 사용합니다. 전체 워크플로우를 소유합니다.

3D 게임 에셋란 무엇인가요?

이 스킬은 3D 게임 개발 워크플로우를 자동화하여, 게임 프롬프트에 명시된 엔티티(플레이어, 적, 수집품 등)를 기반으로 GLB 3D 모델을 생성하고 통합합니다. Tripo3D를 통한 빠른 텍스트-모델 생성 또는 Gemini로 참조 이미지를 생성한 후 Tripo로 이미지-모델을 생성하는 두 가지 경로를 지원하며, 사용자가 필요에 따라 선택할 수 있습니다. 생성된 에셋은 `asset_manifest.json`에 관리되며, Three.js의 `GLTFLoader`를 통해 게임 코드에 연결됩니다. 모든 GLB에 대해 기본 프리미티브 폴백을 유지하여 네트워크 오류 시에도 게임이 플레이 가능하도록 보장합니다. 저작권 문제를 피하기 위해 기존 캐릭터나 브랜드명을 사용하지 않고 독창적인 디자인으로 재작성합니다.

지원 대상~Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add 674345386/agent-skills

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

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

문서

3D 게임 에셋은(는) 무엇을 하나요?

3D 게임에 기본 프리미티브 도형뿐 아니라 구체적이고 인식 가능한 GLB 에셋이 필요할 때 이 스킬을 사용하세요. 이 스킬은 엔드-투-엔드 워크플로우(경로 선택, 소규모 에셋 세트 생성, asset_manifest.json 읽기/쓰기, 폴백과 함께 GLB를 게임에 연결)를 소유합니다.

필수 동작

  • 게임 프롬프트에 플레이어, 캐릭터, 적, 수집품, 탈것, 무기, 장애물, 보스, 마스코트, 핵심 소품 또는 환경 객체와 같은 명시적 또는 암시적 엔티티가 포함된 경우, 도구를 사용할 수 있을 때 GLB 생성은 필수 단계입니다.
  • 기본적으로 1-3개의 주요 에셋만 생성하세요. 플레이어/주인공을 최우선으로 하고, 그 다음 게임플레이에 중요한 적, 수집품, 탈것, 위험 요소 또는 핵심 소품을 생성하세요. 장식용 채우기 에셋은 생성하지 마세요.
  • 기본 Three.js 프리미티브 도형은 에셋이 준비되는 동안 임시 플레이스홀더로만 사용하고, GLB 로드에 실패했을 때 런타임 폴백으로 사용하세요.
  • 사용자가 명시적으로 요청하지 않는 한 기존 에셋을 다시 생성하지 마세요. asset_manifest.json에 로드 가능한 에셋이 이미 있으면 재사용하세요.
  • 저작권이 있는 캐릭터, 브랜드명, 로고, 유명인 유사성은 피하세요. 독창적인 디자인으로 다시 작성하세요.

경로 선택

빠른 경로에는 tripo를 사용하세요: Tripo3D 텍스트-모델로 직접 텍스트 프롬프트를 보냅니다. 일반 소품, 적, 수집품, 탈것, 장애물 및 빠른 반복에 가장 적합합니다.

시각적 제어가 중요할 때는 gemini_reference를 사용하세요: Gemini가 먼저 순수 흰색 배경의 참조 이미지를 생성한 다음, Tripo 이미지-모델이 GLB를 생성합니다. 사용자가 Gemini, Nano Banana, T-포즈, 흰색 배경, 참조 이미지, 이미지-모델, 캐릭터 시트, 스타일 일관성을 언급하거나 주요 캐릭터의 실루엣을 제어해야 할 때 이 경로를 선호하세요.

auto는 서버가 프롬프트에 따라 선택하도록 할 때만 사용하세요. 확실하지 않으면 직접 경로를 선택하고 명시적으로 전달하세요.

환경

생성 클라이언트는 이 스킬과 함께 scripts/game-assets-mcp.mjs(Node >= 20, 종속성 없음)에 번들로 제공됩니다. 기본 원격 에셋 API(http://54.81.110.182:3001)와 통신합니다.

  • GAME_ASSETS_API_URL - 에셋 API 기본 URL을 재정의하는 선택적 변수
  • GAME_ASSETS_API_TOKEN - 사용자별 액세스 토큰

토큰이 없고 서비스에 인증이 필요한 경우, 사용자에게 생성 전에 GAME_ASSETS_API_TOKEN을 설정하도록 요청하세요. GAME_ASSETS_API_URL은 사용자가 기본 서비스를 재정의해야 할 때만 요청하세요. Tripo 또는 Gemini API 키는 절대 묻지 마세요. 키는 서버에 있습니다.

도구 워크플로우

mcp__game_assets__*라는 이름의 MCP 도구를 세션에서 사용할 수 있으면 선호하세요. 그렇지 않으면 Bash를 통해 번들 클라이언트를 실행하세요. 두 가지 모두 동일한 두 가지 작업을 제공합니다.

  1. 현재 워크스페이스 경로를 모르면 pwd를 실행하세요.
  2. 3개 이상의 에셋을 계획 중이거나, 스레드에서 첫 번째 에셋 생성인 경우, 준비 상태를 확인하세요(<skill-dir>는 이 스킬의 디렉토리):
node <skill-dir>/scripts/game-assets-mcp.mjs readiness --cwd "$(pwd)"
  1. 1-3개의 에셋을 생성하세요(배치 최대 4개). 매개변수를 하나의 JSON 객체로 전달하세요:
node <skill-dir>/scripts/game-assets-mcp.mjs generate --cwd "$(pwd)" --params '{
  "gamePrompt": "...",
  "route": "tripo",
  "assets": [{ "id": "...", "role": "player", "name": "...", "prompt": "..." }]
}'
  • route: tripo, gemini_reference 또는 auto.
  • assets: 안정적인 케밥-케이스 id, role, name, prompt 및 선택적 assetKind를 가진 1-3개의 객체.
  • force: 사용자가 에셋 재생성을 명시적으로 요청한 경우에만 사용.
  • 명령어는 원격 작업을 폴링하는 동안 차단되고(일반적으로 배치당 1-3분) JSON 결과를 출력합니다. 종료 코드 1은 배치 실패를 의미합니다.
  1. 명령어가 반환된 후 cwd에서 asset_manifest.json을 읽으세요. 해당 파일을 진실의 원천으로 취급하세요.
  2. manifest.assets를 Three.js GLTFLoader와 함께 게임 코드에 연결하세요.
  3. 생성된 모든 에셋에 대해 로컬 프리미티브 폴백을 유지하세요. GLB 로드에 실패해도 게임을 플레이할 수 있어야 합니다.

예시 --params JSON:

{
  "cwd": "/absolute/path/to/project",
  "gamePrompt": "3D runner with an astronaut cat collecting crystals and dodging patrol robots",
  "route": "gemini_reference",
  "assets": [
    {
      "id": "astronaut-cat",
      "role": "player",
      "name": "우주 고양이",
      "assetKind": "character",
      "prompt": "original low-poly astronaut cat hero, round helmet, compact readable silhouette, blue and white suit, friendly arcade game character"
    },
    {
      "id": "energy-crystal",
      "role": "collectible",
      "name": "에너지 크리스탈",
      "assetKind": "prop",
      "prompt": "bright cyan faceted energy crystal pickup, clean silhouette, game collectible"
    }
  ]
}

런타임 통합 규칙

  • 로드된 모든 GLB를 THREE.Box3().setFromObject()로 정규화하세요: 대상 크기로 조정, 수평 중앙 정렬, 바닥을 y = 0에 배치, 안정적인 방향 오프셋 적용.
  • 시각적 요소와 게임플레이 히트박스를 분리하세요. 충돌은 원시 모델 경계나 메시 원점이 아닌 안정적인 게임플레이 치수를 사용해야 합니다.
  • manifest.assets에 rigged, rigType 또는 animations가 포함되어 있으면, 로드된 gltf.animations를 검사하여 네이티브 애니메이션이 존재한다고 주장하기 전에 확인하세요.
  • 네이티브 클립이 있으면 THREE.AnimationMixer를 만들고, idle, walk, run, jump와 같은 대소문자 구분 없는 하위 문자열로 클립을 매핑하고, 매 프레임마다 mixer.update(delta)를 호출하세요.
  • 네이티브 클립이 없으면 전체 그룹 바운스/틸트/회전 또는 명시적으로 레이블이 지정된 절차적 클립을 폴백 애니메이션으로 사용하세요.
  • 생성된 에셋, 사용된 경로, 런타임 애니메이션 소스를 설명하는 3D Asset Pipeline 또는 3D 素材流水线이라는 짧은 README.md 섹션을 추가하세요.

실패 처리

  • 에셋 API에 연결할 수 없음(준비 상태가 unreachable 보고): 원격 모델 생성이 불가능함을 설명하고, 사용자에게 기본 에셋 서비스, 네트워크 액세스, 필요한 경우 GAME_ASSETS_API_TOKEN을 확인하도록 요청하세요. 기본 서비스를 재정의할 때만 GAME_ASSETS_API_URL을 요청하세요. 프리미티브 폴백을 유지하고 플레이 가능한 게임을 계속 진행하세요.
  • gemini_reference 경로에서 서버에 Gemini 키 누락: 허용된다면 tripo로 전환하거나, 사용자에게 서버 운영자가 Gemini 키를 구성해야 한다고 알리세요.
  • Tripo 잔액 0: 루프에서 재시도하지 마세요. 폴백을 유지하고 README에 건너뛴 단계를 기록하세요.
  • 부분 성공: 성공한 생성 에셋을 사용하고 나머지는 폴백 지오메트리를 사용하세요.

관련 스킬