edemaistre/unity-plugin

Scenario for Unity : guide de l'agent

L'éditeur Unity sert ce serveur MCP lorsque l'utilisateur a coché Agents can use Scenario and this project dans la fenêtre Scenario. Chaque outil s'exécute dans l'éditeur : les fichiers générés atterrissent dans Assets/ du projet, les modifications de scène sont des étapes d'annulation (Undo), et les appels payants passent par les mêmes vérifications de prix et règles d'approbation que la fenêtre.

Démarrage

1. scenario_status : compte, projet Scenario facturé, si les dépenses sont activées, votre limite par appel et le budget de session restant, pipeline de rendu, 2D ou 3D, la scène active. S'il indique déconnecté, demandez à l'utilisateur de se connecter depuis la fenêtre Scenario ; rien d'autre ne fonctionne avant.
2. scene_info : chemins de hiérarchie, composants, sélection. Utilisez ces chemins comme target et path partout.

Argent

Les coûts sont en Creative Units (CU).

• estimate est gratuit et renvoie le prix exact d'une requête. Appelez-le avant generate ou workflow_run lorsque l'utilisateur se soucie du coût ou que la requête est importante (vidéo, 3D, nombreuses images).
• generate, workflow_run et prompt_spark sont payants. Passez max_cu lorsque l'utilisateur a donné un budget : au-dessus, rien n'est envoyé.
• Au-dessus de la limite par appel ou du budget de session, l'appel attend jusqu'à deux minutes que l'utilisateur approuve dans Unity. Dites à l'utilisateur que vous attendez. « Not approved » signifie que rien n'a été envoyé ; ne réessayez pas sauf si l'utilisateur le demande.
• Résultat inconnu. Si un appel payant renvoie « The outcome is unknown », la requête a peut-être été exécutée et facturée. Ne rappelez jamais la même requête. Appelez jobs avec son local_id une minute plus tard.
• Si les dépenses sont désactivées (Paramètres ou SCENARIO_NO_SPEND=1), les outils payants refusent avant d'envoyer. La tarification, la navigation, les importations, les téléversements et les outils de scène fonctionnent encore.
• upload_reference, import_asset, models_find, motions_find, model_schema et estimate sont gratuits.

Choisir un modèle

• models_find avec output_type (image, video, model3d, motion, audio, material, skybox) liste le catalogue, y compris les modèles personnalisés de l'équipe.
• models_find avec recommend_for_prompt renvoie les choix classés par Scenario pour un prompt, avec des notes de coût et de vitesse. À privilégier lorsque l'utilisateur n'a pas nommé de modèle.
• model_schema donne les entrées : noms, options, plages, valeurs par défaut, quelles entrées sont des fichiers. N'envoyez que les paramètres listés par le schéma ; les noms inconnus sont refusés avant la tarification.

Générer et placer

generate tarife la requête, l'envoie une fois, attend, importe les fichiers et place le résultat :

output_type	Sans target	Avec target
image	texture (sprite dans un projet 2D) sur un nouveau quad ou sprite	appliquée sur son SpriteRenderer, Image, RawImage ou renderer
material	matériau pour le pipeline actif avec ses maps, sur une nouvelle sphère	appliqué sur les renderers de la cible et de ses enfants
skybox	matériau Skybox/Panoramic défini comme skybox de la scène	identique
model3d	GLB importé comme prefab, instance au pivot de la Scene View	instance placée à côté de la cible
motion	GLB animé avec un Animator Controller (un état par clip), instance au pivot ; il joue en mode Play	instance placée à côté de la cible
audio	AudioClip sur un nouvel AudioSource	sur l'AudioSource de la cible (ajouté si manquant)
video	VideoClip sur un nouveau quad d'écran	sur le VideoPlayer de la cible (ajouté si manquant)

Le résultat a files (chemins d'actifs Unity), placed (chemins de hiérarchie), asset_ids (IDs Scenario, réutilisables comme entrées), job_id, quoted_cu et charged_cu. place: false importe sans toucher à la scène. Aucun appel ne bloque plus de 45 s : la 3D, la vidéo et l'audio long répondent généralement avec next (encore en cours). Le travail continue, s'importe et se place tout seul ; appelez jobs avec local_id et wait_seconds jusqu'à ce qu'il soit terminé, et ne le générez plus jamais. Pour un lot, envoyez chaque requête avec wait: false, puis suivez-les avec jobs.

Les entrées fichier (images de référence, image de départ, modèle 3D, audio) prennent un ID d'actif Scenario ou un chemin d'actif Unity ; les fichiers Unity sont téléversés une fois, gratuitement.

Résultats 3D, à quoi s'attendre :

• Un modèle par résultat : les copies OBJ, MTL et PBR-map que certains modèles ajoutent sont ignorées. Les résultats FBX, Blender et VOX arrivent en GLB.
• Un rig qui renvoie des fichiers walk et run (Meshy Rigging, Tripo avec includeRiggedModel) est un modèle dont le contrôleur contient tous les clips. Les rigs écrits en centimètres sont placés à l'échelle 1%.
• Les splats gaussiens (TripoSplat, HY World, Marble) sont sauvegardés en .ply ou .spz et ne sont pas placés : dites à l'utilisateur qu'Unity a besoin d'un package de rendu de splats gaussiens.
• Meshy 7.1 utilise par défaut un remaillage à 30 000 triangles au même prix ; envoyez shouldRemesh: false pour le maillage complet (environ un million de triangles).

Enchaîner les étapes

Nourrissez un résultat dans le modèle suivant via son entrée fichier :

• Image vers 3D : generate une image, puis un modèle model3d (par exemple Meshy 7.1 Image to 3D) avec l'ID d'actif de l'image.
• Image vers matériau ou skybox : PATINA Image to Maps, HY World Image to Skybox.
• Image vers vidéo : un modèle img2video avec l'image comme image de départ.
• Nettoyage : suppression d'arrière-plan, upscale, vectorisation, pixellisation.
• Texture 3D : retexturation (Meshy 7 Retexture, Tripo 3.0 Texturing, Tencent Texture Edit, Trellis 2, YVO3D), dépliage UV (Tripo Smart UV, Meshy, Tencent).
• Forme 3D : édition par prompt (Claude Opus 5.5 3D, Astra 3D ; prompt uniquement, pas d'image de référence), retopologie (Tripo Retopology v3, Hunyuan Polygen), remaillage vers un nombre de polygones (Meshy Remesh), raffinement à partir d'une image (UltraShape).
• Rigger et animer : rigger un personnage (Uthana, Meshy, Cartwheel, Tripo), rigger une créature (Tripo Rigging 2.5, rigType), une animation de bibliothèque (Meshy Animation : actionId, par exemple 30 Casual Walk, 106 Confident Walk, 4 Attack, 22 FunnyDancing 01 ; motions_find recherche les 656 par nom ou catégorie), une animation à partir d'un prompt (Cartwheel, Uthana) ou d'une vidéo (Cartwheel, Uthana).
• Parties et style : diviser en parties (Tripo Segmentation v2, Hunyuan 3D Part, Hitem3D Split, Rodin Bang), styliser (Tripo Stylization : LEGO, voxel, Voronoi ; Hitem3D Multicolor).
• Entrées dont Scenario a besoin même si le schéma les dit optionnelles : les animations Cartwheel nécessitent characterModel (un modèle 3D) ou characterFile (une image, bien plus chère) ; YVO3D nécessite referenceImage sauf si retexture est faux. L'outil le dit avant la tarification.
• Passez un ID d'actif GLB même aux modèles qui ne lisent que du FBX (Tencent Texture Edit) : le plugin envoie la copie FBX de Scenario, gratuitement.
• Vidéo : upscale, ajout de son, restylisation. Audio : changement de voix, isolation vocale.

models_find avec une capability (img23d, img2video, 3d23d, video23d, video2audio, audio2audio) trouve des alternatives.

Workflows

workflows_find (scope : team ou featured) renvoie les IDs, descriptions et entrées. workflow_run prend des inputs par nom, avec les mêmes règles d'argent que generate ; les sorties s'importent selon leur type.

Outils de scène

Désactivés lorsque l'utilisateur désactive Agents can edit the scene ; les outils de lecture (scene_info, object_get, assets_find, console_logs, capture_view) continuent de fonctionner.

• object_create (vide, primitive ou prefab), object_set (nom, actif, parent, transform, tag, layer, height en mètres, ground pour le poser sur le sol en dessous), object_delete.
• component_add, component_set : chemins sérialisés (m_Intensity) ou propriétés publiques (intensity) ; vecteurs en [x,y,z], couleurs en [r,g,b,a] ou #RRGGBB, références en chemins d'actifs ou de hiérarchie. object_get avec properties: true liste ce qui peut être défini.
• material_assign, skybox_set, select, scene_save (une scène sans titre nécessite un chemin).
• assets_find avec label: "Scenario" liste tous les actifs générés dans le projet.

Chaque édition est une étape d'annulation (Undo), donc l'utilisateur peut annuler tout ce que vous avez fait.

Mondes praticables

D'un simple prompt à un monde dans lequel un joueur peut se déplacer :

1. terrain_create : sol avec un collider. Façonnez-le avec une image de heightmap que vous générez d'abord (heightmap en niveaux de gris vue de dessus, le blanc est haut), nivelez les flat_areas où vont les bâtiments, et peignez les layers avec des matériaux générés (le premier est la base ; les autres par min_height ou min_slope). edge_falloff crée une île ou un plateau.
2. Générez les éléments de décor, puis object_set avec height (mètres) et ground: true pour dimensionner chacun et le poser sur le terrain. Hauteurs typiques : une personne 1.8, une porte 2.2, une maison 6 à 9, un pin 8 à 14, un rocher 0.5 à 2.
3. scatter répète un modèle sur le sol (on : le terrain), avec une plage de height, des zones keep_clear autour des chemins et bâtiments, et des colliders.
4. Un personnage : générez-le, riggez-le, animez idle, walk, run et jump (motions_find pour les IDs de bibliothèque), puis make_playable avec ces résultats. Il construit le contrôleur, dimensionne le personnage, fait correspondre les vitesses aux clips et configure la caméra de suivi.
5. play avec action: "walk" et des waypoints (run, jump, wait) pour faire un test de jeu : il rapporte les points atteints, les chutes (une chute de plus de 4 m compte) et les sauts. Une marche plus longue que l'appel continue dans Unity : la réponse dit running, et play avec action: "status" et wait_seconds renvoie le résultat lorsqu'il se termine. play avec action: "stop" avant de modifier à nouveau ; les modifications faites en mode Play sont perdues. record: true (ou action: "record") écrit des images PNG de la caméra principale à une fréquence d'images fixe.
6. scene_save.

Vérifier votre travail

• capture_view rend la Scene View ou une caméra et renvoie l'image. Regardez-la après avoir placé des résultats ou modifié la scène. Avec upload: true, il renvoie également un ID d'actif Scenario, donc une capture peut servir de référence pour la génération suivante.
• console_logs avec level: "error" après les importations ou les modifications de composants.

Bonnes habitudes

• Une seule intention par requête. Demandez avant les lots ou avant tout ce qui dépasse le budget indiqué par l'utilisateur.
• Réutilisez les asset_ids des résultats précédents au lieu de téléverser le même fichier.
• jobs liste les requêtes récentes de ce projet Unity ; vérifiez-le avant de renvoyer quoi que ce soit après une erreur.
• Rapportez ce que vous avez créé avec ses chemins Unity et les objets placés.