edemaistre/unity-plugin

Scenario for Unity: guia do agente

O Unity Editor serve este servidor MCP enquanto o usuário tiver Agents can use Scenario and this project ativado na janela do Scenario. Cada ferramenta é executada dentro do editor: os arquivos gerados vão para Assets/ do projeto, as edições na cena são etapas de Undo, e as chamadas pagas seguem as mesmas regras de verificação de preço e aprovação que a janela.

Início

1. scenario_status: conta, o projeto Scenario que é faturado, se os gastos estão ativos, seu limite por chamada e o orçamento restante da sessão, pipeline de renderização, 2D ou 3D, a cena ativa. Se disser que não está conectado, peça ao usuário para fazer login na janela do Scenario; nada mais funciona até lá.
2. scene_info: caminhos da hierarquia, componentes, seleção. Use esses caminhos como target e path em todos os lugares.

Dinheiro

Os custos são em Creative Units (CU).

• estimate é gratuito e retorna o preço exato de uma solicitação. Chame-o antes de generate ou workflow_run quando o usuário se importar com o custo ou a solicitação for grande (vídeo, 3D, muitas imagens).
• generate, workflow_run e prompt_spark são pagos. Passe max_cu quando o usuário definiu um orçamento: acima dele nada é enviado.
• Acima do limite por chamada ou do orçamento da sessão, a chamada aguarda até dois minutos pela Aprovação do usuário no Unity. Informe ao usuário que está aguardando. "Não aprovado" significa que nada foi enviado; não tente novamente a menos que o usuário peça.
• Resultado desconhecido. Se uma chamada paga retornar "O resultado é desconhecido", a solicitação pode ter sido executada e cobrada. Nunca a chame novamente para a mesma solicitação. Chame jobs com seu local_id um minuto depois.
• Se os gastos estiverem desligados (Configurações ou SCENARIO_NO_SPEND=1), as ferramentas pagas recusam antes de enviar. Preços, navegação, importações, uploads e ferramentas de cena ainda funcionam.
• upload_reference, import_asset, models_find, motions_find, model_schema e estimate são gratuitos.

Escolher um modelo

• models_find com output_type (image, video, model3d, motion, audio, material, skybox) lista o catálogo, incluindo os modelos treinados da própria equipe.
• models_find com recommend_for_prompt retorna as escolhas classificadas do Scenario para um prompt, com notas de custo e velocidade. Prefira-o quando o usuário não nomeou um modelo.
• model_schema fornece as entradas: nomes, opções, intervalos, padrões, quais entradas são arquivos. Envie apenas parâmetros que o esquema lista; nomes desconhecidos são recusados antes da precificação.

Gerar e posicionar

generate precifica a solicitação, envia uma vez, aguarda, importa os arquivos e posiciona o resultado:

output_type	Sem target	Com target
image	textura (sprite em um projeto 2D) em um novo quad ou sprite	definida em seu SpriteRenderer, Image, RawImage ou renderer
material	material para o pipeline ativo com seus mapas, em uma nova esfera	definido nos renderizadores do alvo e de seus filhos
skybox	material Skybox/Panoramic definido como skybox da cena	o mesmo
model3d	GLB importado como prefab, instância no pivô da View da Cena	instância colocada ao lado do alvo
motion	GLB animado com um Animator Controller (um estado por clipe), instância no pivô; ele toca no Modo Play	instância colocada ao lado do alvo
audio	AudioClip em um novo AudioSource	no AudioSource do alvo (adicionado se ausente)
video	VideoClip em um novo quad de tela	no VideoPlayer do alvo (adicionado se ausente)

O resultado tem files (caminhos de ativos Unity), placed (caminhos da hierarquia), asset_ids (ids do Scenario, reutilizáveis como entradas), job_id, quoted_cu e charged_cu. place: false importa sem tocar na cena. Nenhuma chamada bloqueia por mais de 45 s: 3D, vídeo e áudio longo geralmente respondem com next (ainda em execução). O trabalho continua, importa e posiciona a si mesmo; chame jobs com local_id e wait_seconds até terminar, e nunca gere novamente. Para um lote, envie cada solicitação com wait: false, depois acompanhe-as com jobs.

Entradas de arquivo (imagens de referência, um quadro inicial, um modelo 3D, áudio) aceitam um id de ativo do Scenario ou um caminho de ativo Unity; os arquivos Unity são carregados uma vez, gratuitamente.

Resultados 3D, o que esperar:

• Um modelo por resultado: as cópias de OBJ, MTL e mapa PBR que alguns modelos adicionam são ignoradas. Resultados FBX, Blender e VOX chegam como GLB.
• Uma rig que retorna arquivos de caminhada e corrida (Meshy Rigging, Tripo com includeRiggedModel) é um modelo cujo controlador contém todos os clipes. Rigs escritas em centímetros são posicionadas em escala de 1%.
• Splats Gaussianos (TripoSplat, HY World, Marble) são salvos como .ply ou .spz e não são posicionados: informe ao usuário que o Unity precisa de um pacote de renderizador de splat Gaussiano.
• Meshy 7.1 padrão é uma remalhagem de 30.000 triângulos pelo mesmo preço; envie shouldRemesh: false para a malha completa (cerca de um milhão de triângulos).

Encadear etapas

Alimente um resultado no próximo modelo através de sua entrada de arquivo:

• Imagem para 3D: generate uma imagem, depois um modelo model3d (por exemplo, Meshy 7.1 Image to 3D) com o id do ativo da imagem.
• Imagem para material ou skybox: PATINA Image to Maps, HY World Image to Skybox.
• Imagem para vídeo: um modelo img2video com a imagem como quadro inicial.
• Limpeza: remoção de fundo, upscale, vetorização, pixelização.
• Textura 3D: retexturização (Meshy 7 Retexture, Tripo 3.0 Texturing, Tencent Texture Edit, Trellis 2, YVO3D), UV unwrap (Tripo Smart UV, Meshy, Tencent).
• Forma 3D: editar com um prompt (Claude Opus 5.5 3D, Astra 3D; apenas prompt, sem imagem de referência), retopologia (Tripo Retopology v3, Hunyuan Polygen), remalhar para uma contagem de polígonos (Meshy Remesh), refinar a partir de uma imagem (UltraShape).
• Rig e animar: riggar um personagem (Uthana, Meshy, Cartwheel, Tripo), riggar uma criatura (Tripo Rigging 2.5, rigType), uma animação de biblioteca (Meshy Animation: actionId, por exemplo 30 Casual Walk, 106 Confident Walk, 4 Attack, 22 FunnyDancing 01; motions_find pesquisa todos os 656 por nome ou categoria), uma animação a partir de um prompt (Cartwheel, Uthana) ou de um vídeo (Cartwheel, Uthana).
• Partes e estilo: dividir em partes (Tripo Segmentation v2, Hunyuan 3D Part, Hitem3D Split, Rodin Bang), estilizar (Tripo Stylization: LEGO, voxel, Voronoi; Hitem3D Multicolor).
• Entradas que o Scenario precisa embora o esquema diga opcional: animações Cartwheel precisam de characterModel (um modelo 3D) ou characterFile (uma imagem, muito mais caro); YVO3D precisa de referenceImage a menos que retexture seja falso. A ferramenta avisa antes da precificação.
• Passe um id de ativo GLB mesmo para modelos que leem apenas FBX (Tencent Texture Edit): o plugin envia a cópia FBX do Scenario dele, gratuitamente.
• Vídeo: upscale, adicionar som, reestilizar. Áudio: mudança de voz, isolamento de voz.

models_find com uma capability (img23d, img2video, 3d23d, video23d, video2audio, audio2audio) encontra alternativas.

Workflows

workflows_find (scope: team ou featured) retorna ids, descrições e entradas. workflow_run recebe inputs por nome, com as mesmas regras de dinheiro que generate; as saídas importam por seu tipo.

Ferramentas de cena

Desligadas quando o usuário desativa Agents can edit the scene; as ferramentas de leitura (scene_info, object_get, assets_find, console_logs, capture_view) continuam funcionando.

• object_create (vazio, primitivo ou prefab), object_set (nome, ativo, pai, transform, tag, layer, height em metros, ground para colocá-lo no chão abaixo), object_delete.
• component_add, component_set: caminhos serializados (m_Intensity) ou propriedades públicas (intensity); vetores como [x,y,z], cores como [r,g,b,a] ou #RRGGBB, referências como caminhos de ativo ou hierarquia. object_get com properties: true lista o que pode ser definido.
• material_assign, skybox_set, select, scene_save (uma cena sem título precisa de um caminho).
• assets_find com label: "Scenario" lista todos os ativos gerados no projeto.

Cada edição é uma etapa de Undo, para que o usuário possa reverter qualquer coisa que você fez.

Mundos caminháveis

De um prompt a um mundo em que um jogador pode andar:

1. terrain_create: chão com um collider. Modele-o com uma imagem de heightmap que você gera primeiro (um heightmap top-down em escala de cinza, branco é alto), nivele flat_areas onde os edifícios vão, e pinte layers com materiais gerados (o primeiro é a base; outros por min_height ou min_slope). edge_falloff cria uma ilha ou platô.
2. Gere as peças do cenário, depois object_set com height (metros) e ground: true para dimensionar cada uma e colocá-la no terreno. Alturas típicas: uma pessoa 1.8, uma porta 2.2, uma casa 6 a 9, um pinheiro 8 a 14, uma rocha 0.5 a 2.
3. scatter repete um modelo no chão (on: o terreno), com um intervalo de height, zonas keep_clear ao redor de caminhos e edifícios, e colliders.
4. Um personagem: gere-o, rigge-o, anime idle, walk, run e jump (motions_find para ids de biblioteca), depois make_playable com esses resultados. Ele constrói o controlador, dimensiona o personagem, combina velocidades com os clipes e configura a câmera de acompanhamento.
5. play com action: "walk" e waypoints (run, jump, wait) para testar: ele relata os pontos alcançados, quedas (uma queda maior que 4 m conta) e pulos. Uma caminhada mais longa que a chamada continua no Unity: a resposta diz running, e play com action: "status" e wait_seconds retorna o resultado quando termina. play com action: "stop" antes de editar novamente; edições feitas no Modo Play são perdidas. record: true (ou action: "record") escreve quadros PNG da câmera principal em uma taxa de quadros fixa.
6. scene_save.

Verifique seu trabalho

• capture_view renderiza a View da Cena ou uma câmera e retorna a imagem. Olhe para ela após posicionar resultados ou editar a cena. Com upload: true também retorna um id de ativo do Scenario, para que uma captura possa ser a referência para a próxima geração.
• console_logs com level: "error" após importações ou alterações de componentes.

Bons hábitos

• Uma solicitação por intenção. Pergunte antes de lotes ou de qualquer coisa acima do orçamento declarado pelo usuário.
• Reutilize asset_ids de resultados anteriores em vez de fazer upload do mesmo arquivo novamente.
• jobs lista solicitações recentes deste projeto Unity; verifique antes de reenviar qualquer coisa após um erro.
• Reporte o que você criou com seus caminhos Unity e os objetos posicionados.