Wiki

Plugin Unreal Engine

Plugin uVersion pour Unreal Engine : contrôle de version natif dans l'éditeur, diff Blueprint, audit Project Health, et les deux règles qui bloquent le plus souvent un envoi.

Prérequis

Le projet Unreal doit se trouver DANS un workspace uVersion C'est la condition d'activation, et elle n'est écrite nulle part dans l'éditeur. Le plugin cherche un dossier .uversion/ en remontant depuis le projet ; s'il n'en trouve pas, et si aucun jeton d'authentification n'a été enregistré auparavant, il ne s'active pas du tout et Unreal reste sans contrôle de version. Ce n'est pas une panne : c'est ce qui l'empêche de s'imposer dans vos projets qui ne sont pas versionnés avec uVersion. Ouvrez le projet depuis le dossier cloné par le client desktop, pas depuis une copie posée ailleurs.

Le client desktop est obligatoire en pratique Un serveur uVersion est auto-signé par défaut. L'éditeur Unreal, lui, ne sait pas quoi faire d'un certificat auto-signé : il n'a pas de magasin d'empreintes et personne ne peut lui en confirmer une. Résultat, sur un serveur en HTTPS, une connexion directe depuis Unreal échoue au TLS, et l'éditeur affiche une notification demandant de démarrer le client desktop. Le formulaire de connexion existe bien dans la fenêtre Revision Control Login, mais il ne franchit pas ce mur : le remplir sur un serveur auto-signé ne mène nulle part. Un seul montage fonctionne : le client desktop tourne, vous y êtes connecté, et le plugin passe par lui. Autant le savoir tout de suite plutôt que d'y passer une heure.

Installation

Le plugin uVersion est distribué en binaire précompilé, géré par le client desktop. Pas de compilation à votre charge, pas de fichiers source à manipuler. Il n'est jamais versionné : il n'arrive pas avec le dépôt, et il ne doit pas être envoyé dedans. Chaque poste installe le binaire qui correspond à SA version d'Unreal et à SON système.

Versions Unreal supportées : 5.6 et supérieur.

1. Ouvrir le workspace dans le client desktop

Installez le client desktop uVersion, connectez-vous, puis ouvrez le workspace qui contient le projet Unreal. Tout se passe depuis le client : il n'y a aucune archive à télécharger, ni à décompresser dans le projet à la main.

2. Laisser le client détecter le projet

Le client cherche votre .uproject (le fichier qui décrit un projet Unreal) sous la racine du workspace, à condition qu'il ne soit pas enfoui à plus de trois niveaux. Dès qu'il le trouve, une barre Unreal apparaît en haut de l'onglet du workspace, et il pose le plugin correspondant à votre version d'Unreal dans Plugins/uVersion/. La pastille de gauche porte l'état du plugin et son numéro de version : c'est là que se lisent aussi les mises à jour.

La barre Unreal du client desktop : a gauche la pastille verte Plugin 1.0.5, puis les boutons Open Editor, Compile, Package, Publish Build, Sync et Status.

3. Ouvrir le projet dans Unreal

Le plugin est actif immédiatement. Rien à cocher dans la fenêtre Plugins de l'éditeur, rien à redémarrer : s'il manquait, c'est que le client ne l'a pas encore posé, pas qu'il reste à activer.

Plus tard : les mises à jour

Le client desktop vérifie les nouvelles versions à l'ouverture du projet et périodiquement ensuite. Attention, la vérification automatique ne fait pas la même chose dans les deux cas :

Plugin absent : il est installé sans rien vous demander. C'est ce qui rend le premier démarrage transparent.
Plugin déjà présent mais dépassé (nouvelle version, ou changement de version d'Unreal) : le client se contente de vous prévenir. Il ne remplace jamais un plugin installé tout seul. La pastille du panneau Unreal passe alors à Update ready.

Pour appliquer la mise à jour : fermez l'éditeur Unreal, puis cliquez sur la pastille. Un plugin chargé ne peut pas être remplacé sur le disque ; si l'éditeur est encore ouvert, la pastille affiche Restart UE.

Première connexion

Dans le cas normal, il n'y a rien à connecter. Le plugin se sélectionne lui-même comme fournisseur de contrôle de version dès qu'il détecte un workspace uVersion autour du projet, ou un jeton déjà enregistré. Vos identifiants sont repris du client desktop, sans ressaisie. Ouvrir le projet suffit.

Les trois étapes ci-dessous ne servent que si cette sélection automatique ne s'est pas faite.

1. Ouvrir le menu Revision Control

Il se trouve en bas à droite de la barre d'état de l'éditeur, pas dans les menus du haut. Il s'ouvre vers le haut et porte les actions d'Unreal, dont Submit Content, plus une section uVersion avec notre entrée Audit Project (Project Health). Prenez Connect to Revision Control.

2. Choisir uVersion dans la liste Provider

La fenêtre Revision Control Login s'ouvre. Déroulez Provider et prenez uVersion. Quand le workspace est reconnu, la fenêtre l'annonce elle-même en vert (Automatically configured from workspace) et les champs Workspace, Server URL et Username sont déjà remplis : il n'y a rien à saisir.

La fenetre Revision Control Login d'Unreal : la liste Provider deroulee avec uVersion selectionne, le message vert de configuration automatique, et le bouton Accept Settings.

3. Valider avec Accept Settings

Le bouton Accept Settings, en bas de la fenêtre, applique le choix et ferme la fenêtre. La barre d'état affiche alors Connected to suivi du nom du dépôt et de votre identifiant. Le choix est mémorisé : les ouvertures suivantes du projet ne repasseront pas par là.

Réserver un asset, puis l'envoyer

Le parcours complet depuis l'éditeur, sur un fichier de contenu. Le code, lui, ne part jamais d'ici : voir Le code passe par le client desktop.

1. Regarder l'état de l'asset avant de commencer

Chaque vignette du Content Browser porte une pastille qui dit où en est l'asset : réservé par vous, réservé par quelqu'un d'autre, ou plus à jour par rapport au serveur. L'infobulle donne la phrase complète, par exemple File is out of date, sync to get the latest version. Dans ce cas, synchronisez d'abord (clic droit, Revision Control, Sync) : commencer à travailler sur une version dépassée, c'est préparer un conflit.

Une vignette d'asset du Content Browser avec une pastille jaune, et son infobulle indiquant que le fichier n'est plus a jour et doit etre synchronise.

2. Réserver l'asset

Clic droit sur l'asset, sous-menu Revision Control, puis Check Out. Tout y est : Sync, Check Out, Check In, History, Diff Against Depot, Revert, comme avec n'importe quel autre fournisseur Unreal. Les artistes n'ont rien de nouveau à apprendre.

En pratique vous n'aurez souvent rien à faire : dès que vous modifiez un asset, le plugin pose le verrou côté serveur tout seul, sans checkout manuel.

Le Content Browser d'Unreal : clic droit sur un asset, sous-menu Revision Control avec Sync, Check Out, Mark For Add, Check In, History, Diff Against Depot et Revert, et les icones d'etat sur les vignettes.

3. Comparer avant d'envoyer

Diff Against Depot ouvre l'outil de comparaison visuel standard de l'éditeur, y compris sur un Blueprint : les deux révisions sont affichées côte à côte, et les nœuds ajoutés, retirés ou modifiés sont entourés. Fonctionne sur n'importe quel commit de l'historique, depuis History.

La fenetre Blueprint Diff : deux revisions d'un meme Blueprint cote a cote, les noeuds ajoutes entoures en vert.

4. Envoyer

Clic droit, Revision Control, Check In sur la sélection, ou Submit Content dans le menu de la barre d'état pour tout envoyer d'un coup. La fenêtre liste les fichiers concernés, y compris les suppressions, et réclame une description. Au moment de l'envoi, le plugin nettoie les redirectors laissés par vos renommages et lance les règles de validation actives : une règle en error arrête l'envoi et nomme les fichiers en cause.

La fenetre d envoi d Unreal : la liste des fichiers a envoyer avec leurs cases cochees, le champ de description du changement, et le bouton Submit.

Ce que le plugin fait dans Unreal

Project Health : auditer le projet

Le menu Revision Control de la barre d'état contient une entrée Audit Project (Project Health). Elle parcourt le registre d'assets du projet sans charger un seul asset, et produit un rapport de santé : nommage, structure des dossiers, dépendances, contenu orphelin, coûts. Elle fonctionne hors ligne (le rapport est écrit sous Saved/uVersionAudit) et l'envoie au serveur quand vous êtes connecté, où il alimente l'onglet Project Health du client desktop.

Nettoyage des redirectors

Quand vous renommez ou déplacez un asset, Unreal laisse derrière lui un redirector : un petit fichier de renvoi qui pointe l'ancien chemin vers le nouveau, pour que les assets qui référencaient l'ancien nom continuent de fonctionner. Ils s'accumulent vite et finissent par rendre l'arborescence illisible. Le plugin les détecte et les nettoie au moment du checkin, en mettant à jour les références dans tous les assets concernés.

Validation pré-checkin

Le plugin sait lancer une série de vérifications sur les fichiers envoyés : compilation des Blueprints, convention de nommage, taille des textures, réglages d'import, dépendances manquantes, dépendances circulaires, assets orphelins, doublons, complexité des matériaux. Neuf règles au total. Une règle en error bloque l'envoi, une règle en warning l'autorise après confirmation.

Les neuf règles sont livrées désactivées Sur un dépôt neuf, elles sont toutes créées à l'état inactif : aucune vérification ne tourne tant qu'un administrateur ne les a pas activées, une par une, depuis l'onglet Rules du panneau Admin. Si vous vous attendiez à ce qu'un envoi soit refusé et qu'il passe sans rien dire, commencez par vérifier là.

Réconciliation au démarrage

À l'ouverture du projet, le plugin compare l'état de vos assets avec le serveur. Il parcourt Content/ et les Content/ des plugins du projet, et réserve automatiquement tout asset trouvé modifiable sur le disque et qui ne l'était pas déjà. L'intention est de vous protéger : un fichier que vous aviez commencé à modifier ne peut pas être attrapé par un coéquipier entre deux sessions.

Conséquence à connaître : vous pouvez détenir des verrous sans le savoir Cette réservation automatique est silencieuse, et un verrou uVersion n'expire jamais : il tient jusqu'à ce qu'il soit rendu explicitement, par un checkin, par un revert, ou par le déverrouillage forcé d'un administrateur. Aucun délai ne le libère. Ouvrir l'éditeur sur un projet où traînent quelques fichiers modifiables suffit donc à bloquer ces fichiers pour toute l'équipe, sans que rien ne vous le signale. Prenez l'habitude de regarder l'onglet Pending du client desktop, liste My Pending Changes, et de rendre ce que vous ne travaillez pas.

Le code passe par le client desktop, pas par Unreal

Le plugin refuse l'envoi des fichiers de code : .cpp, .h, .hpp, .c et .cs. La tentative s'arrête sur une fenêtre bloquante qui nomme les fichiers en cause. Ce n'est pas un défaut : le client desktop compile avant d'envoyer et publie les binaires d'éditeur que vos coéquipiers récupèrent au sync. Un commit de code parti depuis l'éditeur passerait à côté des deux, et suspendrait la distribution de binaires pour toute l'équipe.

Envoyez donc votre code depuis le client desktop. Les fichiers de contenu, eux, restent parfaitement libres de partir depuis Unreal.

Le piège : un seul fichier de code réservé bloque aussi vos envois de CONTENU La règle ne s'arrête pas aux fichiers que vous envoyez. Tant que vous détenez la réservation d'un fichier de code, même un seul, même sans y avoir touché, même absent de votre envoi, tout checkin depuis Unreal est refusé, y compris un envoi de .uasset pur. Le message vous dit d'envoyer votre code depuis le client desktop d'abord.

C'est le blocage le plus courant, et il tombe volontiers sur quelqu'un qui n'écrit pas de code : il suffit qu'un fichier source ait été rendu modifiable sur le disque pour que la réconciliation au démarrage l'ait réservé toute seule. La raison est réelle : un asset enregistré contre du code non envoyé casse tous ceux qui le synchronisent, leurs binaires n'ayant pas le code dont il dépend.

Le déblocage : ouvrez l'onglet Pending du client desktop, liste My Pending Changes, repérez les fichiers de code, et faites un Checkin Selected si vous les avez modifiés, ou un Revert si vous n'y avez pas touché. Votre envoi de contenu repart ensuite normalement. Il peut falloir quelques secondes, le temps que l'éditeur rafraîchisse sa vue des verrous.

L onglet Pending du client desktop : la liste My Pending Changes ou figurent deux fichiers .h aux cotes d un .uasset, chacun avec son bouton Revert, et plus bas la section Other Users' Locks.

Problèmes courants

Aucun menu uVersion : l'éditeur ignore le contrôle de version

Le projet n'est probablement pas dans un workspace uVersion. Vérifiez qu'un dossier .uversion/ existe à la racine du dossier cloné, et que vous ouvrez bien le projet depuis ce dossier et non depuis une copie posée ailleurs.

« Failed to connect to source control »

Vérifiez que le client desktop est lancé et que vous y êtes connecté : c'est lui qui détient vos identifiants et qui sait dialoguer avec un serveur auto-signé. Si le compte propriétaire du workspace n'est pas connecté dans le client, le plugin refuse de travailler sous une autre identité, et c'est voulu.

Un envoi est refusé alors que je n'ai touché à aucun code

Vous détenez la réservation d'un fichier de code. Voir Le code passe par le client desktop.

Je veux un asset que quelqu'un d'autre a verrouillé

Cela ne se demande pas depuis Unreal : le plugin n'a pas de fonction de demande de libération. Passez par le client desktop, onglet Pending, section Other Users' Locks, bouton Request Release sur la ligne du fichier. Le détenteur reçoit une demande sous forme de carte dans le board Production.

Le plugin ne se met pas à jour

C'est le comportement attendu : la vérification automatique installe un plugin manquant, mais elle se contente de signaler une mise à jour. Fermez l'éditeur Unreal (un plugin chargé ne peut pas être remplacé), puis cliquez sur la pastille Update ready dans la barre Unreal du client desktop pour l'appliquer.

Une règle de validation ne se déclenche jamais

Les neuf règles sont livrées désactivées. Un administrateur doit les activer par projet depuis l'onglet Rules du panneau Admin.