Wiki
Unreal-Engine-Plugin
uVersion-Plugin für Unreal Engine: native Versionskontrolle im Editor, Blueprint-Diff, Project-Health-Audit und die zwei Regeln, die eine Übermittlung am häufigsten blockieren.
Voraussetzungen
.uversion/-Ordner, indem es vom Projekt aus nach oben geht; findet es keinen, und wurde zuvor kein
Authentifizierungs-Token gespeichert, dann aktiviert es sich gar nicht und Unreal bleibt ohne Versionskontrolle.
Das ist kein Ausfall: Es hindert das Plugin daran, sich in Ihre Projekte zu drängen, die nicht mit
uVersion versioniert sind. Öffnen Sie das Projekt aus dem vom Desktop-Client geklonten Ordner, nicht aus einer
anderswo abgelegten Kopie.
Installation
Das uVersion-Plugin wird als vorkompilierte Binärdatei ausgeliefert und vom Desktop-Client verwaltet. Kein Kompilieren Ihrerseits, keine Quelldateien, mit denen Sie hantieren müssen. Es wird nie versioniert: Es kommt nicht mit dem Repository und darf nicht hinein übermittelt werden. Jede Maschine installiert die Binärdatei, die zu IHRER Unreal-Version und IHREM System passt.
Unterstützte Unreal-Versionen: 5.6 und höher.
1. Den Workspace im Desktop-Client öffnen
Installieren Sie den uVersion-Desktop-Client, melden Sie sich an und öffnen Sie dann den Workspace, der das Unreal-Projekt enthält. Alles läuft über den Client: Es gibt kein Archiv zum Herunterladen und keines, das Sie von Hand ins Projekt entpacken müssten.
2. Den Client das Projekt erkennen lassen
Der Client sucht Ihre .uproject (die Datei, die ein Unreal-Projekt beschreibt) unterhalb des Workspace-
Stamms, sofern sie nicht mehr als drei Ebenen tief vergraben ist. Sobald er sie findet, erscheint oben im Workspace-Tab eine Unreal-
Leiste, und er legt das zu Ihrer Unreal-Version passende Plugin in Plugins/uVersion/ ab. Das Badge links
trägt den Zustand des Plugins und seine Versionsnummer: Dort werden auch die Updates abgelesen.
3. Das Projekt in Unreal öffnen
Das Plugin ist sofort aktiv. Nichts anzuhaken im Plugins-Fenster des Editors, nichts neu zu starten: Wenn es fehlte, dann weil der Client es noch nicht abgelegt hat, nicht weil es noch zu aktivieren wäre.
Später: die Updates
Der Desktop-Client prüft beim Öffnen des Projekts und danach regelmäßig auf neue Versionen. Achtung, die automatische Prüfung tut in den beiden Fällen nicht dasselbe:
- Plugin fehlt: Es wird installiert, ohne Sie zu fragen. Das macht den ersten Start nahtlos.
-
Plugin bereits vorhanden, aber veraltet (neue Version oder Wechsel der Unreal-Version): Der Client
benachrichtigt Sie nur. Er ersetzt ein installiertes Plugin nie von selbst. Das Badge
des Unreal-Panels wechselt dann zu
Update ready.
Um das Update anzuwenden: Schließen Sie den Unreal-Editor und klicken Sie dann auf das Badge. Ein geladenes Plugin
kann auf der Festplatte nicht ersetzt werden; ist der Editor noch offen, zeigt das Badge
Restart UE.
Erste Verbindung
Im Normalfall gibt es nichts zu verbinden. Das Plugin wählt sich selbst als Versionskontroll-Provider, sobald es einen uVersion-Workspace rund um das Projekt erkennt oder ein bereits gespeichertes Token. Ihre Zugangsdaten werden vom Desktop-Client übernommen, ohne erneute Eingabe. Das Projekt zu öffnen genügt.
Die drei Schritte unten sind nur nötig, wenn diese automatische Auswahl nicht stattgefunden hat.
1. Das Menü Revision Control öffnen
Es befindet sich unten rechts in der Statusleiste des Editors, nicht in den oberen Menüs. Es
öffnet sich nach oben und trägt die Aktionen von Unreal, darunter Submit Content, plus einen
uVersion-Abschnitt mit unserem Eintrag Audit Project (Project Health). Nehmen Sie
Connect to Revision Control.
2. uVersion in der Provider-Liste wählen
Das Fenster Revision Control Login öffnet sich. Klappen Sie Provider auf und nehmen Sie uVersion. Ist der Workspace erkannt, meldet das Fenster es selbst in Grün (Automatically configured from workspace), und die Felder Workspace, Server URL und Username sind bereits ausgefüllt: Es gibt nichts einzugeben.
3. Mit Accept Settings bestätigen
Die Schaltfläche Accept Settings unten im Fenster wendet die Wahl an und schließt das Fenster. Die Statusleiste zeigt dann Connected to, gefolgt vom Namen des Repositorys und Ihrem Benutzernamen. Die Wahl wird gemerkt: Spätere Öffnungen des Projekts gehen nicht mehr hier durch.
Einen Asset auschecken, dann übermitteln
Der vollständige Weg aus dem Editor, an einer Content-Datei. Code hingegen geht nie von hier aus: siehe Code läuft über den Desktop-Client.
1. Vor dem Beginnen den Zustand des Assets ansehen
Jede Miniatur im Content Browser trägt ein Badge, das sagt, wie es um den Asset steht: von Ihnen ausgecheckt, von jemand anderem ausgecheckt oder gegenüber dem Server veraltet. Der Tooltip gibt den vollständigen Satz, zum Beispiel File is out of date, sync to get the latest version. In diesem Fall zuerst synchronisieren (Rechtsklick, Revision Control, Sync): An einer veralteten Version zu arbeiten heißt, einen Konflikt vorzubereiten.
2. Den Asset auschecken
Rechtsklick auf den Asset, Untermenü Revision Control, dann Check Out. Alles ist da: Sync, Check Out, Check In, History, Diff Against Depot, Revert, wie bei jedem anderen Unreal-Provider. Artists müssen nichts Neues lernen.
In der Praxis werden Sie oft nichts zu tun haben: Sobald Sie einen Asset ändern, setzt das Plugin die Sperre serverseitig von selbst, ohne manuellen Checkout.
3. Vor dem Übermitteln vergleichen
Diff Against Depot öffnet das standardmäßige visuelle Vergleichswerkzeug des Editors, auch bei einem Blueprint: Die beiden Revisionen werden nebeneinander angezeigt, und die hinzugefügten, entfernten oder geänderten Knoten sind umrandet. Funktioniert bei jedem Commit im Verlauf, aus History.
4. Übermitteln
Rechtsklick, Revision Control, Check In auf die Auswahl, oder Submit Content im Menü der Statusleiste, um alles auf einmal zu senden. Das Fenster listet die betroffenen Dateien auf, einschließlich der Löschungen, und verlangt eine Beschreibung. Beim Übermitteln räumt das Plugin die von Ihren Umbenennungen hinterlassenen Redirectors auf und führt die aktiven Validierungsregeln aus: Eine Regel im Zustand error hält die Übermittlung an und benennt die schuldigen Dateien.
Was das Plugin in Unreal leistet
Project Health: das Projekt auditieren
Das Menü Revision Control der Statusleiste enthält einen Eintrag
Audit Project (Project Health). Er durchläuft die Asset-Registry des Projekts,
ohne einen einzigen Asset zu laden, und erzeugt einen Gesundheitsbericht: Benennung, Ordnerstruktur,
Abhängigkeiten, verwaiste Inhalte, Kosten. Er funktioniert offline (der Bericht wird unter
Saved/uVersionAudit geschrieben) und sendet ihn an den Server, wenn Sie verbunden sind, wo er den
Project-Health-Tab des Desktop-Clients speist.
Redirector-Bereinigung
Wenn Sie einen Asset umbenennen oder verschieben, lässt Unreal einen Redirector zurück: eine kleine Weiterleitungsdatei, die den alten Pfad auf den neuen zeigt, damit Assets, die den alten Namen referenzierten, weiter funktionieren. Sie häufen sich schnell und machen den Baum am Ende unlesbar. Das Plugin erkennt sie und bereinigt sie beim Checkin und aktualisiert dabei die Referenzen in allen betroffenen Assets.
Validierung vor dem Checkin
Das Plugin kann eine Reihe von Prüfungen an den übermittelten Dateien ausführen: Blueprint-Kompilierung, Namens- konvention, Texturgröße, Import-Einstellungen, fehlende Abhängigkeiten, zirkuläre Abhängigkeiten, verwaiste Assets, Duplikate, Materialkomplexität. Neun Regeln insgesamt. Eine Regel im Zustand error blockiert die Übermittlung, eine Regel im Zustand warning erlaubt sie nach Bestätigung.
Abgleich beim Start
Beim Öffnen des Projekts vergleicht das Plugin den Zustand Ihrer Assets mit dem Server. Es durchläuft Content/
und die Content/ der Plugins des Projekts und checkt automatisch jeden auf der Festplatte
beschreibbar gefundenen Asset aus, der es nicht schon war. Die Absicht ist, Sie zu schützen: Eine Datei, die Sie zu ändern begonnen hatten,
kann zwischen zwei Sitzungen nicht von einem Teammitglied gegriffen werden.
Code läuft über den Desktop-Client, nicht über Unreal
Das Plugin verweigert die Übermittlung von Code-Dateien: .cpp, .h,
.hpp, .c und .cs. Der Versuch endet in einem blockierenden Fenster, das
die schuldigen Dateien benennt. Das ist kein Mangel: Der Desktop-Client kompiliert vor dem Senden und veröffentlicht die
Editor-Binärdateien, die Ihre Teammitglieder beim Sync erhalten. Ein aus dem Editor gesendeter Code-Commit würde an
beidem vorbeigehen und die Verteilung der Binärdateien für das ganze Team aussetzen.
Übermitteln Sie Ihren Code also aus dem Desktop-Client. Content-Dateien hingegen bleiben völlig frei, aus Unreal loszugehen.
.uasset-Übermittlung. Die Meldung sagt Ihnen, Ihren Code zuerst aus dem
Desktop-Client zu übermitteln.
Das ist die häufigste Blockade, und sie trifft gern jemanden, der gar keinen Code schreibt: Es genügt, dass eine Quelldatei auf der Festplatte beschreibbar gemacht wurde, damit der Abgleich beim Start sie von selbst ausgecheckt hat. Der Grund ist real: Ein gegen nicht übermittelten Code gespeicherter Asset zerstört jeden, der ihn synchronisiert, weil ihre Binärdateien den Code, von dem er abhängt, nicht haben.
Die Entsperrung: Öffnen Sie den Tab Pending des Desktop-Clients, die Liste My Pending Changes, machen Sie die Code-Dateien aus und führen Sie einen Checkin Selected aus, wenn Sie sie geändert haben, oder einen Revert, wenn Sie sie nicht berührt haben. Ihre Content-Übermittlung geht danach normal los. Es kann ein paar Sekunden dauern, bis der Editor seine Sicht auf die Sperren aktualisiert hat.
Häufige Probleme
Kein uVersion-Menü: der Editor ignoriert die Versionskontrolle
Das Projekt ist wahrscheinlich nicht in einem uVersion-Workspace. Prüfen Sie, ob ein .uversion/-Ordner
im Stamm des geklonten Ordners existiert und dass Sie das Projekt tatsächlich aus diesem Ordner öffnen und nicht aus einer anderswo
abgelegten Kopie.
« Failed to connect to source control »
Prüfen Sie, ob der Desktop-Client läuft und Sie darin angemeldet sind: Er hält Ihre Zugangsdaten und weiß, wie man mit einem selbstsignierten Server spricht. Ist das Konto, dem der Workspace gehört, nicht im Client angemeldet, verweigert das Plugin die Arbeit unter einer anderen Identität, und das ist so gewollt.
Eine Übermittlung wird abgelehnt, obwohl ich keinen Code berührt habe
Sie halten den Checkout einer Code-Datei. Siehe Code läuft über den Desktop-Client.
Ich will einen Asset, den jemand anderes gesperrt hat
Das wird nicht aus Unreal angefragt: Das Plugin hat keine Funktion zur Freigabeanfrage. Gehen Sie über den Desktop-Client, Tab Pending, Abschnitt Other Users' Locks, Schaltfläche Request Release in der Zeile der Datei. Der Halter erhält eine Anfrage als Karte im Production-Board.
Das Plugin aktualisiert sich nicht
Das ist das erwartete Verhalten: Die automatische Prüfung installiert ein fehlendes Plugin, aber sie
signalisiert ein Update nur. Schließen Sie den Unreal-Editor (ein geladenes Plugin kann nicht ersetzt werden), klicken Sie dann auf das
Badge Update ready in der Unreal-Leiste des Desktop-Clients, um es anzuwenden.
Eine Validierungsregel löst nie aus
Die neun Regeln werden deaktiviert ausgeliefert. Ein Administrator muss sie pro Projekt über den Tab Rules des Admin-Panels aktivieren.