edemaistre/unity-plugin

Scenario for Unity: 에이전트 가이드

Unity 에디터는 사용자가 Scenario 창에서 에이전트가 Scenario와 이 프로젝트를 사용할 수 있음을 켠 상태에서 이 MCP 서버를 제공합니다. 모든 도구는 에디터 내에서 실행됩니다. 생성된 파일은 프로젝트의 Assets/에 저장되고, 씬 편집은 실행 취소 단계로 기록되며, 유료 호출은 창과 동일한 가격 확인 및 승인 규칙을 따릅니다.

시작

1. scenario_status: 계정, 비용이 청구되는 Scenario 프로젝트, 지출 활성화 여부, 호출당 한도 및 남은 세션 예산, 렌더 파이프라인, 2D 또는 3D 모드, 활성 씬 정보를 반환합니다. 로그아웃 상태라고 표시되면 사용자에게 Scenario 창에서 로그인하도록 요청하세요. 그렇지 않으면 다른 모든 기능이 작동하지 않습니다.
2. scene_info: 계층 구조 경로, 컴포넌트, 선택 항목을 반환합니다. 해당 경로를 모든 곳에서 target 및 path로 사용하세요.

비용

비용은 Creative Units(CU)으로 계산됩니다.

• estimate는 무료이며 요청의 정확한 가격을 반환합니다. 사용자가 비용을 중요시하거나 요청이 큰 경우(비디오, 3D, 여러 이미지) generate 또는 workflow_run 전에 호출하세요.
• generate, workflow_run 및 prompt_spark는 유료입니다. 사용자가 예산을 지정한 경우 max_cu를 전달하세요. 이를 초과하면 아무것도 전송되지 않습니다.
• 호출당 한도 또는 세션 예산을 초과하면 Unity에서 사용자의 승인을 위해 최대 2분 동안 호출이 대기됩니다. 사용자에게 기다리고 있다고 알리세요. "승인되지 않음"은 아무것도 전송되지 않았음을 의미하며, 사용자가 요청하지 않는 한 재시도하지 마세요.
• 알 수 없는 결과. 유료 호출이 "결과를 알 수 없습니다"를 반환하면 요청이 실행되어 청구되었을 수 있습니다. 동일한 요청에 대해 다시 호출하지 마세요. 1분 후에 해당 local_id로 jobs를 호출하세요.
• 지출이 꺼져 있으면(설정 또는 SCENARIO_NO_SPEND=1) 유료 도구는 전송 전에 거부합니다. 가격 책정, 검색, 가져오기, 업로드 및 씬 도구는 계속 작동합니다.
• upload_reference, import_asset, models_find, motions_find, model_schema 및 estimate는 무료입니다.

모델 선택

• models_find에 output_type(image, video, model3d, motion, audio, material, skybox)을 지정하면 카탈로그(팀의 자체 학습 모델 포함)가 나열됩니다.
• models_find에 recommend_for_prompt를 지정하면 프롬프트에 대한 Scenario의 순위별 선택 항목과 비용 및 속도 정보를 반환합니다. 사용자가 모델을 지정하지 않은 경우 이를 선호하세요.
• model_schema는 입력(이름, 옵션, 범위, 기본값, 파일 입력 여부)을 제공합니다. 스키마에 나열된 매개변수만 전송하세요. 알 수 없는 이름은 가격 책정 전에 거부됩니다.

생성 및 배치

generate는 요청 가격을 책정하고, 한 번 전송하고, 대기한 후, 파일을 가져와 결과를 배치합니다.

output_type	target 없음	target 있음
image	새로운 쿼드 또는 스프라이트에 텍스처(2D 프로젝트에서는 스프라이트) 설정	SpriteRenderer, Image, RawImage 또는 renderer에 설정
material	활성 파이프라인용 머티리얼과 맵을 새로운 구체에 설정	대상 및 그 자식의 renderer에 설정
skybox	Skybox/Panoramic 머티리얼을 씬 스카이박스로 설정	동일
model3d	GLB를 프리팹으로 가져와 Scene 뷰 피벗에 인스턴스 생성	대상 옆에 인스턴스 배치
motion	Animator Controller(클립당 하나의 상태)가 있는 애니메이션 GLB를 피벗에 인스턴스 생성; Play 모드에서 재생됨	대상 옆에 인스턴스 배치
audio	새로운 AudioSource에 AudioClip 설정	대상의 AudioSource(없으면 추가)에 설정
video	새로운 화면 쿼드에 VideoClip 설정	대상의 VideoPlayer(없으면 추가)에 설정

결과에는 files(Unity 에셋 경로), placed(계층 구조 경로), asset_ids(Scenario ID, 입력으로 재사용 가능), job_id, quoted_cu 및 charged_cu가 포함됩니다. place: false는 씬을 건드리지 않고 가져오기만 합니다. 어떤 호출도 45초 이상 차단되지 않습니다. 3D, 비디오 및 긴 오디오는 일반적으로 next(계속 실행 중)로 응답합니다. 작업은 계속 진행되고, 자체적으로 가져오고 배치됩니다. local_id와 wait_seconds로 jobs를 호출하여 완료될 때까지 기다리세요. 절대 같은 항목을 다시 생성하지 마세요. 배치의 경우 각 요청을 wait: false로 보낸 다음 jobs로 후속 조치하세요.

파일 입력(참조 이미지, 시작 프레임, 3D 모델, 오디오)은 Scenario 에셋 ID 또는 Unity 에셋 경로를 사용합니다. Unity 파일은 한 번만 업로드되며 무료입니다.

3D 결과, 예상 사항:

• 결과당 하나의 모델: 일부 모델이 추가하는 OBJ, MTL 및 PBR 맵 복사본은 건너뜁니다. FBX, Blender 및 VOX 결과는 GLB로 도착합니다.
• 걷기 및 달리기 파일을 반환하는 리그(Meshy Rigging, includeRiggedModel이 있는 Tripo)는 모든 클립을 보유하는 컨트롤러가 있는 하나의 모델입니다. 센티미터 단위로 작성된 리그는 1% 크기로 배치됩니다.
• 가우시안 스플랫(TripoSplat, HY World, Marble)은 .ply 또는 .spz로 저장되며 배치되지 않습니다. 사용자에게 Unity에 가우시안 스플랫 렌더러 패키지가 필요하다고 알리세요.
• Meshy 7.1은 동일한 가격에 기본적으로 30,000 삼각형 리메쉬를 사용합니다. 전체 메시(약 백만 삼각형)를 원하면 shouldRemesh: false를 전송하세요.

단계 연결

한 결과를 파일 입력을 통해 다음 모델에 공급하세요.

• 이미지를 3D로: generate로 이미지를 생성하고, 이미지의 에셋 ID로 model3d 모델(예: Meshy 7.1 Image to 3D)을 생성하세요.
• 이미지를 머티리얼 또는 스카이박스로: PATINA Image to Maps, HY World Image to Skybox.
• 이미지를 비디오로: 이미지를 시작 프레임으로 하는 img2video 모델.
• 정리: 배경 제거, 업스케일, 벡터화, 픽셀화.
• 3D 텍스처: 재질 변경(Meshy 7 Retexture, Tripo 3.0 Texturing, Tencent Texture Edit, Trellis 2, YVO3D), UV 언랩(Tripo Smart UV, Meshy, Tencent).
• 3D 형태: 프롬프트로 편집(Claude Opus 5.5 3D, Astra 3D; 프롬프트만, 참조 이미지 없음), 리토폴로지(Tripo Retopology v3, Hunyuan Polygen), 폴리카운트로 리메쉬(Meshy Remesh), 이미지로 정밀화(UltraShape).
• 리깅 및 애니메이션: 캐릭터 리깅(Uthana, Meshy, Cartwheel, Tripo), 크리처 리깅(Tripo Rigging 2.5, rigType), 라이브러리 모션(Meshy Animation: actionId, 예: 30 Casual Walk, 106 Confident Walk, 4 Attack, 22 FunnyDancing 01; motions_find는 이름이나 카테고리로 656개 모두 검색), 프롬프트 기반 모션(Cartwheel, Uthana) 또는 비디오 기반 모션(Cartwheel, Uthana).
• 부품 및 스타일: 부품 분할(Tripo Segmentation v2, Hunyuan 3D Part, Hitem3D Split, Rodin Bang), 스타일화(Tripo Stylization: LEGO, voxel, Voronoi; Hitem3D Multicolor).
• 스키마가 선택 사항이라고 표시하지만 Scenario가 필요로 하는 입력: Cartwheel 모션은 characterModel(3D 모델) 또는 characterFile(이미지, 훨씬 비쌈)이 필요합니다. YVO3D는 retexture가 false가 아닌 한 referenceImage가 필요합니다. 도구는 가격 책정 전에 이를 알려줍니다.
• FBX만 읽는 모델(Tencent Texture Edit)에도 GLB 에셋 ID를 전달하세요. 플러그인이 Scenario의 FBX 복사본을 무료로 전송합니다.
• 비디오: 업스케일, 사운드 추가, 스타일 변경. 오디오: 음성 변경, 음성 분리.

capability(img23d, img2video, 3d23d, video23d, video2audio, audio2audio)와 함께 models_find를 사용하면 대안을 찾을 수 있습니다.

워크플로우

workflows_find(scope: team 또는 featured)는 ID, 설명 및 입력을 반환합니다. workflow_run은 inputs를 이름으로 받으며, generate와 동일한 비용 규칙을 따릅니다. 출력은 종류에 따라 가져옵니다.

씬 도구

사용자가 에이전트가 씬을 편집할 수 있음을 끄면 비활성화됩니다. 읽기 도구(scene_info, object_get, assets_find, console_logs, capture_view)는 계속 작동합니다.

• object_create(빈 오브젝트, 원시 도형 또는 프리팹), object_set(이름, 활성화, 부모, 변환, 태그, 레이어, 미터 단위 height, 아래 지면에 배치하는 ground), object_delete.
• component_add, component_set: 직렬화된 경로(m_Intensity) 또는 공용 속성(intensity); 벡터는 [x,y,z], 색상은 [r,g,b,a] 또는 #RRGGBB, 참조는 에셋 또는 계층 구조 경로. object_get에 properties: true를 지정하면 설정 가능한 항목이 나열됩니다.
• material_assign, skybox_set, select, scene_save(제목 없는 씬은 경로 필요).
• assets_find에 label: "Scenario"를 지정하면 프로젝트의 모든 생성된 에셋이 나열됩니다.

각 편집은 하나의 실행 취소 단계이므로 사용자가 수행한 모든 작업을 되돌릴 수 있습니다.

걷기 가능한 월드

하나의 프롬프트로 플레이어가 걸어 다닐 수 있는 월드로:

1. terrain_create: 충돌체가 있는 지형. 먼저 생성한 높이 맵 이미지(위에서 아래로 본 회색조 높이 맵, 흰색이 높음)로 모양을 만들고, 건물이 들어갈 flat_areas를 평평하게 하고, 생성된 머티리얼로 layers를 페인트합니다(첫 번째는 베이스, 나머지는 min_height 또는 min_slope 기준). edge_falloff는 섬이나 고원을 만듭니다.
2. 세트 피스를 생성한 다음 height(미터)와 ground: true로 object_set하여 각각의 크기를 지정하고 지형 위에 배치합니다. 일반적인 높이: 사람 1.8, 문 2.2, 집 69, 소나무 814, 바위 0.5~2.
3. scatter는 지면에 모델을 반복 배치합니다(on: 지형). height 범위, 경로와 건물 주변의 keep_clear 영역, 충돌체를 지원합니다.
4. 캐릭터: 생성하고, 리깅하고, 대기, 걷기, 달리기, 점프 애니메이션을 적용한 후(motions_find로 라이브러리 ID 검색) make_playable로 해당 결과를 처리합니다. 컨트롤러를 빌드하고, 캐릭터 크기를 조정하고, 속도를 클립에 맞추고, 추적 카메라를 설정합니다.
5. play에 action: "walk"와 웨이포인트(run, jump, wait)를 사용하여 플레이테스트합니다. 도달한 지점, 낙하(4m 이상 드롭 카운트) 및 점프를 보고합니다. 호출 시간보다 긴 걷기는 Unity에서 계속 실행됩니다. 응답은 running이라고 말하고, action: "status" 및 wait_seconds와 함께 play를 호출하면 종료 시 결과를 반환합니다. 다시 편집하기 전에 action: "stop"과 함께 play를 호출하세요. Play 모드에서 수행된 편집은 손실됩니다. record: true(또는 action: "record")는 고정 프레임 속도로 메인 카메라의 PNG 프레임을 기록합니다.
6. scene_save.

작업 확인

• capture_view는 Scene 뷰 또는 카메라를 렌더링하고 이미지를 반환합니다. 결과를 배치하거나 씬을 편집한 후에 확인하세요. upload: true를 사용하면 Scenario 에셋 ID도 반환하므로 캡처를 다음 생성을 위한 참조로 사용할 수 있습니다.
• console_logs를 가져오기 또는 컴포넌트 변경 후 level: "error"로 호출하세요.

좋은 습관

• 의도당 하나의 요청. 배치 또는 사용자가 명시한 예산을 초과하는 모든 작업 전에 물어보세요.
• 동일한 파일을 다시 업로드하는 대신 이전 결과의 asset_ids를 재사용하세요.
• jobs는 이 Unity 프로젝트의 최근 요청을 나열합니다. 오류 후 다시 보내기 전에 확인하세요.
• 생성한 내용을 Unity 경로 및 배치된 오브젝트와 함께 보고하세요.