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를 통해 번들 클라이언트를 실행하세요. 두 가지 모두 동일한 두 가지 작업을 제공합니다.
- 현재 워크스페이스 경로를 모르면
pwd를 실행하세요. - 3개 이상의 에셋을 계획 중이거나, 스레드에서 첫 번째 에셋 생성인 경우, 준비 상태를 확인하세요(
<skill-dir>는 이 스킬의 디렉토리):
node <skill-dir>/scripts/game-assets-mcp.mjs readiness --cwd "$(pwd)"
- 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은 배치 실패를 의미합니다.
- 명령어가 반환된 후
cwd에서asset_manifest.json을 읽으세요. 해당 파일을 진실의 원천으로 취급하세요. manifest.assets를 Three.jsGLTFLoader와 함께 게임 코드에 연결하세요.- 생성된 모든 에셋에 대해 로컬 프리미티브 폴백을 유지하세요. 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에 건너뛴 단계를 기록하세요.
- 부분 성공: 성공한 생성 에셋을 사용하고 나머지는 폴백 지오메트리를 사용하세요.