edemaistre/unity-plugin

Scenario para Unity: guía del agente

El Editor de Unity sirve este servidor MCP mientras el usuario tenga activada la opción Los agentes pueden usar Scenario y este proyecto en la ventana de Scenario. Cada herramienta se ejecuta dentro del editor: los archivos generados se colocan en Assets/ del proyecto, las ediciones de escena son pasos Deshacer, y las llamadas pagadas pasan por las mismas comprobaciones de precio y reglas de aprobación que la ventana.

Inicio

1. scenario_status: cuenta, el proyecto de Scenario que se factura, si el gasto está activado, tu límite por llamada y el presupuesto de sesión restante, pipeline de renderizado, 2D o 3D, la escena activa. Si dice que no has iniciado sesión, pide al usuario que inicie sesión desde la ventana de Scenario; nada más funcionará hasta entonces.
2. scene_info: rutas jerárquicas, componentes, selección. Usa esas rutas como target y path en todas partes.

Dinero

Los costos están en Unidades Creativas (CU).

• estimate es gratuita y devuelve el precio exacto de una solicitud. Llámala antes de generate o workflow_run cuando al usuario le importe el costo o la solicitud sea grande (video, 3D, muchas imágenes).
• generate, workflow_run y prompt_spark son de pago. Pasa max_cu cuando el usuario haya dado un presupuesto: por encima de él no se envía nada.
• Por encima del límite por llamada o del presupuesto de sesión, la llamada espera hasta dos minutos para que el usuario Apruebe en Unity. Indica al usuario que estás esperando. "No aprobado" significa que no se envió nada; no lo reintentes a menos que el usuario lo pida.
• Resultado desconocido. Si una llamada de pago devuelve "The outcome is unknown", la solicitud puede haberse ejecutado y cobrado. No la llames de nuevo para la misma solicitud. Llama a jobs con su local_id un minuto después.
• Si el gasto está desactivado (Configuración o SCENARIO_NO_SPEND=1), las herramientas de pago se niegan antes de enviar. Los precios, la navegación, las importaciones, las subidas y las herramientas de escena siguen funcionando.
• upload_reference, import_asset, models_find, motions_find, model_schema y estimate son gratuitas.

Elegir un modelo

• models_find con output_type (image, video, model3d, motion, audio, material, skybox) lista el catálogo, incluyendo los modelos entrenados del propio equipo.
• models_find con recommend_for_prompt devuelve las selecciones clasificadas de Scenario para un prompt, con notas de costo y velocidad. Prefiérelo cuando el usuario no haya nombrado un modelo.
• model_schema da las entradas: nombres, opciones, rangos, valores por defecto, qué entradas son archivos. Envía solo parámetros que el esquema liste; los nombres desconocidos son rechazados antes del precio.

Generar y colocar

generate pone precio a la solicitud, la envía una vez, espera, importa los archivos y coloca el resultado:

output_type	Sin target	Con target
image	textura (sprite en un proyecto 2D) en un nuevo quad o sprite	se establece en su SpriteRenderer, Image, RawImage o renderer
material	material para el pipeline activo con sus mapas, en una nueva esfera	se establece en los renderers del objetivo y sus hijos
skybox	material Skybox/Panoramic establecido como skybox de la escena	igual
model3d	GLB importado como prefab, instancia en el pivote de la vista Escena	instancia colocada junto al objetivo
motion	GLB animado con un Animator Controller (un estado por clip), instancia en el pivote; se reproduce en modo Play	instancia colocada junto al objetivo
audio	AudioClip en un nuevo AudioSource	en el AudioSource del objetivo (añadido si falta)
video	VideoClip en un nuevo quad de pantalla	en el VideoPlayer del objetivo (añadido si falta)

El resultado tiene files (rutas de Assets de Unity), placed (rutas jerárquicas), asset_ids (ids de Scenario, reutilizables como entradas), job_id, quoted_cu y charged_cu. place: false importa sin tocar la escena. Ninguna llamada bloquea más de 45 s: 3D, video y audio largo suelen responder con next (todavía en ejecución). El trabajo continúa, se importa y se coloca solo; llama a jobs con local_id y wait_seconds hasta que termine, y nunca lo generes de nuevo. Para un lote, envía cada solicitud con wait: false, luego síguelos con jobs.

Las entradas de archivo (imágenes de referencia, un fotograma inicial, un modelo 3D, audio) toman un id de asset de Scenario o una ruta de Asset de Unity; los archivos de Unity se suben una vez, gratis.

Resultados 3D, qué esperar:

• Un modelo por resultado: las copias OBJ, MTL y mapas PBR que algunos modelos añaden se omiten. Los resultados FBX, Blender y VOX llegan como GLB.
• Un rig que devuelve archivos de caminar y correr (Meshy Rigging, Tripo con includeRiggedModel) es un modelo cuyo controlador contiene todos los clips. Los rigs escritos en centímetros se colocan a escala 1%.
• Los splats gaussianos (TripoSplat, HY World, Marble) se guardan como .ply o .spz y no se colocan: informa al usuario de que Unity necesita un paquete de renderizador de splats gaussianos.
• Meshy 7.1 por defecto hace un remallado de 30.000 triángulos al mismo precio; envía shouldRemesh: false para la malla completa (aproximadamente un millón de triángulos).

Encadenar pasos

Alimenta un resultado en el siguiente modelo a través de su entrada de archivo:

• Imagen a 3D: genera una imagen con generate, luego un modelo model3d (por ejemplo, Meshy 7.1 Image to 3D) con el id de asset de la imagen.
• Imagen a material o skybox: PATINA Image to Maps, HY World Image to Skybox.
• Imagen a video: un modelo img2video con la imagen como fotograma inicial.
• Limpieza: eliminación de fondo, aumento de resolución, vectorización, pixelado.
• Textura 3D: retexturizado (Meshy 7 Retexture, Tripo 3.0 Texturing, Tencent Texture Edit, Trellis 2, YVO3D), despliegue UV (Tripo Smart UV, Meshy, Tencent).
• Forma 3D: editar con un prompt (Claude Opus 5.5 3D, Astra 3D; solo prompt, sin imagen de referencia), retopología (Tripo Retopology v3, Hunyuan Polygen), remallar a un recuento de polígonos (Meshy Remesh), refinar desde una imagen (UltraShape).
• Rig y animar: rigizar un personaje (Uthana, Meshy, Cartwheel, Tripo), rigizar una criatura (Tripo Rigging 2.5, rigType), un movimiento de biblioteca (Meshy Animation: actionId, por ejemplo 30 Casual Walk, 106 Confident Walk, 4 Attack, 22 FunnyDancing 01; motions_find busca los 656 por nombre o categoría), un movimiento desde un prompt (Cartwheel, Uthana) o desde un video (Cartwheel, Uthana).
• Partes y estilo: dividir en partes (Tripo Segmentation v2, Hunyuan 3D Part, Hitem3D Split, Rodin Bang), estilizar (Tripo Stylization: LEGO, vóxel, Voronoi; Hitem3D Multicolor).
• Entradas que Scenario necesita aunque el esquema diga opcional: los movimientos de Cartwheel necesitan characterModel (un modelo 3D) o characterFile (una imagen, mucho más caro); YVO3D necesita referenceImage a menos que retexture sea falso. La herramienta lo dice antes de poner precio.
• Pasa un id de asset GLB incluso a modelos que solo leen FBX (Tencent Texture Edit): el plugin envía su copia FBX de Scenario, gratis.
• Video: aumentar resolución, añadir sonido, reestilizar. Audio: cambio de voz, aislamiento de voz.

models_find con una capability (img23d, img2video, 3d23d, video23d, video2audio, audio2audio) encuentra alternativas.

Flujos de trabajo

workflows_find (scope: team o featured) devuelve ids, descripciones y entradas. workflow_run toma inputs por nombre, con las mismas reglas de dinero que generate; las salidas se importan según su tipo.

Herramientas de escena

Desactivadas cuando el usuario desactiva Los agentes pueden editar la escena; las herramientas de lectura (scene_info, object_get, assets_find, console_logs, capture_view) siguen funcionando.

• object_create (vacío, primitivo o prefab), object_set (nombre, activo, padre, transformación, etiqueta, capa, height en metros, ground para colocarlo en el suelo debajo), object_delete.
• component_add, component_set: rutas serializadas (m_Intensity) o propiedades públicas (intensity); vectores como [x,y,z], colores como [r,g,b,a] o #RRGGBB, referencias como rutas de asset o jerárquicas. object_get con properties: true lista lo que se puede establecer.
• material_assign, skybox_set, select, scene_save (una escena sin título necesita una ruta).
• assets_find con label: "Scenario" lista cada asset generado en el proyecto.

Cada edición es un paso Deshacer, por lo que el usuario puede revertir cualquier cosa que hayas hecho.

Mundos transitables

De un prompt a un mundo en el que un jugador puede caminar:

1. terrain_create: suelo con un collider. Dale forma con una imagen de mapa de alturas que generes primero (un mapa de alturas en escala de grises visto desde arriba, blanco es alto), nivela flat_areas donde van los edificios, y pinta layers con materiales generados (el primero es la base; otros por min_height o min_slope). edge_falloff crea una isla o meseta.
2. Genera las piezas del escenario, luego object_set con height (metros) y ground: true para dimensionar cada una y colocarla sobre el terreno. Alturas típicas: una persona 1.8, una puerta 2.2, una casa 6 a 9, un pino 8 a 14, una roca 0.5 a 2.
3. scatter repite un modelo en el suelo (on: el terreno), con un rango de height, zonas keep_clear alrededor de caminos y edificios, y colliders.
4. Un personaje: genéralo, rigízalo, anima idle, walk, run y jump (motions_find para ids de biblioteca), luego make_playable con esos resultados. Construye el controlador, dimensiona el personaje, iguala velocidades a los clips y configura la cámara de seguimiento.
5. play con action: "walk" y waypoints (run, jump, wait) para prueba de juego: informa de los puntos alcanzados, caídas (una caída de más de 4 m cuenta) y saltos. Una caminata más larga que la llamada continúa en Unity: la respuesta dice running, y play con action: "status" y wait_seconds devuelve el resultado cuando termina. play con action: "stop" antes de editar de nuevo; las ediciones hechas en modo Play se pierden. record: true (o action: "record") escribe fotogramas PNG de la cámara principal a una frecuencia de fotogramas fija.
6. scene_save.

Revisa tu trabajo

• capture_view renderiza la vista Escena o una cámara y devuelve la imagen. Mírala después de colocar resultados o editar la escena. Con upload: true también devuelve un id de asset de Scenario, por lo que una captura puede ser la referencia para la siguiente generación.
• console_logs con level: "error" después de importaciones o cambios de componentes.

Buenos hábitos

• Una solicitud por intención. Pregunta antes de lotes o antes de cualquier cosa que supere el presupuesto indicado por el usuario.
• Reutiliza asset_ids de resultados anteriores en lugar de subir el mismo archivo de nuevo.
• jobs lista solicitudes recientes de este proyecto de Unity; consúltalo antes de reenviar cualquier cosa después de un error.
• Informa de lo que hiciste con sus rutas de Unity y los objetos colocados.