Wiki

Plugin Unreal Engine

Plugin uVersion per Unreal Engine: controllo di versione nativo nell'editor, diff Blueprint, audit Project Health e le due regole che più spesso bloccano un invio.

Prerequisiti

Il progetto Unreal deve trovarsi DENTRO un workspace uVersion È la condizione di attivazione, e non è scritta da nessuna parte nell'editor. Il plugin cerca una cartella .uversion/ risalendo dal progetto; se non ne trova nessuna, e se nessun token di autenticazione è stato salvato in precedenza, non si attiva affatto e Unreal resta senza controllo di versione. Non è un guasto: è ciò che gli impedisce di imporsi nei tuoi progetti che non sono versionati con uVersion. Apri il progetto dalla cartella clonata dal client desktop, non da una copia messa altrove.

Il client desktop è obbligatorio nella pratica Un server uVersion è autofirmato per impostazione predefinita. L'editor Unreal, dal canto suo, non sa cosa farsene di un certificato autofirmato: non ha un archivio di impronte e nessuno può confermargliene una. Di conseguenza, su un server HTTPS, una connessione diretta da Unreal fallisce al TLS, e l'editor mostra una notifica che chiede di avviare il client desktop. Il modulo di connessione esiste eccome nella finestra Revision Control Login, ma non supera questo muro: compilarlo contro un server autofirmato non porta da nessuna parte. Solo una configurazione funziona: il client desktop è in esecuzione, vi sei connesso, e il plugin passa da lui. Meglio saperlo subito che perderci un'ora.

Installazione

Il plugin uVersion è distribuito come binario precompilato, gestito dal client desktop. Nessuna compilazione a tuo carico, nessun file sorgente da manipolare. Non è mai versionato: non arriva con il repository, e non deve essere inviato al suo interno. Ogni postazione installa il binario che corrisponde alla SUA versione di Unreal e al SUO sistema.

Versioni di Unreal supportate: 5.6 e successive.

1. Aprire il workspace nel client desktop

Installa il client desktop di uVersion, accedi, poi apri il workspace che contiene il progetto Unreal. Tutto avviene dal client: non c'è nessun archivio da scaricare, né da decomprimere nel progetto a mano.

2. Lasciare che il client rilevi il progetto

Il client cerca il tuo .uproject (il file che descrive un progetto Unreal) sotto la radice del workspace, a condizione che non sia sepolto a più di tre livelli. Non appena lo trova, una barra Unreal compare in cima alla scheda del workspace, e mette il plugin corrispondente alla tua versione di Unreal in Plugins/uVersion/. Il badge a sinistra riporta lo stato del plugin e il suo numero di versione: è lì che si leggono anche gli aggiornamenti.

La barra Unreal del client desktop: a sinistra il badge verde Plugin 1.0.5, poi i pulsanti Open Editor, Compile, Package, Publish Build, Sync e Status.

3. Aprire il progetto in Unreal

Il plugin è attivo immediatamente. Niente da spuntare nella finestra Plugins dell'editor, niente da riavviare: se mancava, è perché il client non l'ha ancora messo, non perché resti da attivare.

Più avanti: gli aggiornamenti

Il client desktop controlla la presenza di nuove versioni all'apertura del progetto e periodicamente in seguito. Attenzione, la verifica automatica non fa la stessa cosa nei due casi:

Plugin assente: viene installato senza chiederti nulla. È ciò che rende trasparente il primo avvio.
Plugin già presente ma superato (nuova versione, o cambio di versione di Unreal): il client si limita ad avvisarti. Non sostituisce mai da solo un plugin installato. Il badge del pannello Unreal passa allora a Update ready.

Per applicare l'aggiornamento: chiudi l'editor Unreal, poi clicca sul badge. Un plugin caricato non può essere sostituito sul disco; se l'editor è ancora aperto, il badge mostra Restart UE.

Prima connessione

Nel caso normale, non c'è niente da connettere. Il plugin si seleziona da solo come provider di controllo di versione non appena rileva un workspace uVersion attorno al progetto, o un token già salvato. Le tue credenziali vengono riprese dal client desktop, senza reinserimento. Aprire il progetto basta.

I tre passaggi qui sotto servono solo se questa selezione automatica non è avvenuta.

1. Aprire il menu Revision Control

Si trova in basso a destra nella barra di stato dell'editor, non nei menu in alto. Si apre verso l'alto e riporta le azioni di Unreal, tra cui Submit Content, più una sezione uVersion con la nostra voce Audit Project (Project Health). Prendi Connect to Revision Control.

2. Scegliere uVersion nella lista Provider

La finestra Revision Control Login si apre. Espandi Provider e prendi uVersion. Quando il workspace è riconosciuto, la finestra lo annuncia da sé in verde (Automatically configured from workspace) e i campi Workspace, Server URL e Username sono già compilati: non c'è nulla da inserire.

La finestra Revision Control Login di Unreal: la lista Provider espansa con uVersion selezionato, il messaggio verde di configurazione automatica e il pulsante Accept Settings.

3. Confermare con Accept Settings

Il pulsante Accept Settings, in fondo alla finestra, applica la scelta e chiude la finestra. La barra di stato mostra allora Connected to seguito dal nome del repository e dal tuo nome utente. La scelta è memorizzata: le successive aperture del progetto non ripasseranno di qui.

Riservare un asset, poi inviarlo

Il percorso completo dall'editor, su un file di contenuto. Il codice, invece, non parte mai da qui: vedi Il codice passa dal client desktop.

1. Guardare lo stato dell'asset prima di iniziare

Ogni miniatura del Content Browser riporta un badge che dice a che punto è l'asset: riservato da te, riservato da qualcun altro, o non più aggiornato rispetto al server. Il tooltip dà la frase completa, per esempio File is out of date, sync to get the latest version. In tal caso, sincronizza prima (clic destro, Revision Control, Sync): iniziare a lavorare su una versione superata significa preparare un conflitto.

Una miniatura di asset del Content Browser con un badge giallo, e il suo tooltip che indica che il file non è più aggiornato e va sincronizzato.

2. Riservare l'asset

Clic destro sull'asset, sottomenu Revision Control, poi Check Out. C'è tutto: Sync, Check Out, Check In, History, Diff Against Depot, Revert, come con qualsiasi altro provider Unreal. Gli artisti non hanno nulla di nuovo da imparare.

In pratica spesso non avrai nulla da fare: non appena modifichi un asset, il plugin applica il lock lato server da solo, senza checkout manuale.

Il Content Browser di Unreal: clic destro su un asset, sottomenu Revision Control con Sync, Check Out, Mark For Add, Check In, History, Diff Against Depot e Revert, e le icone di stato sulle miniature.

3. Confrontare prima di inviare

Diff Against Depot apre lo strumento di confronto visivo standard dell'editor, anche su un Blueprint: le due revisioni sono mostrate affiancate, e i nodi aggiunti, rimossi o modificati sono cerchiati. Funziona su qualsiasi commit della cronologia, da History.

La finestra Blueprint Diff: due revisioni di uno stesso Blueprint affiancate, i nodi aggiunti cerchiati in verde.

4. Inviare

Clic destro, Revision Control, Check In sulla selezione, o Submit Content nel menu della barra di stato per inviare tutto in una volta. La finestra elenca i file interessati, comprese le eliminazioni, e richiede una descrizione. Al momento dell'invio, il plugin pulisce i redirector lasciati dalle tue rinomine e avvia le regole di validazione attive: una regola in error ferma l'invio e nomina i file colpevoli.

La finestra di invio di Unreal: la lista dei file da inviare con le caselle spuntate, il campo di descrizione della modifica e il pulsante Submit.

Cosa fa il plugin in Unreal

Project Health: auditare il progetto

Il menu Revision Control della barra di stato contiene una voce Audit Project (Project Health). Percorre il registro degli asset del progetto senza caricare un solo asset, e produce un rapporto di salute: denominazione, struttura delle cartelle, dipendenze, contenuto orfano, costi. Funziona offline (il rapporto è scritto sotto Saved/uVersionAudit) e lo invia al server quando sei connesso, dove alimenta la scheda Project Health del client desktop.

Pulizia dei redirector

Quando rinomini o sposti un asset, Unreal lascia dietro di sé un redirector: un piccolo file di rinvio che punta il vecchio percorso verso quello nuovo, così che gli asset che referenziavano il vecchio nome continuino a funzionare. Si accumulano in fretta e finiscono per rendere l'albero illeggibile. Il plugin li rileva e li pulisce al momento del checkin, aggiornando i riferimenti in tutti gli asset interessati.

Validazione prima del checkin

Il plugin sa eseguire una serie di controlli sui file inviati: compilazione dei Blueprint, convenzione di denominazione, dimensione delle texture, impostazioni di import, dipendenze mancanti, dipendenze circolari, asset orfani, duplicati, complessità dei materiali. Nove regole in tutto. Una regola in error blocca l'invio, una regola in warning lo autorizza dopo conferma.

Le nove regole sono consegnate disattivate Su un repository nuovo, sono tutte create allo stato inattivo: nessun controllo gira finché un amministratore non le ha attivate, una per una, dalla scheda Rules del pannello Admin. Se ti aspettavi che un invio venisse rifiutato e passa senza dire niente, comincia col verificare lì.

Riconciliazione all'avvio

All'apertura del progetto, il plugin confronta lo stato dei tuoi asset con il server. Percorre Content/ e i Content/ dei plugin del progetto, e riserva automaticamente ogni asset trovato modificabile sul disco che non lo era già. L'intento è proteggerti: un file che avevi iniziato a modificare non può essere afferrato da un collega tra due sessioni.

Conseguenza da conoscere: puoi detenere lock senza saperlo Questa riserva automatica è silenziosa, e un lock uVersion non scade mai: si mantiene finché non viene reso esplicitamente, con un checkin, con un revert, o con lo sblocco forzato di un amministratore. Nessuna scadenza lo libera. Aprire l'editor su un progetto dove restano in giro qualche file modificabile basta dunque a bloccare quei file per tutta la squadra, senza che nulla te lo segnali. Prendi l'abitudine di guardare la scheda Pending del client desktop, la lista My Pending Changes, e di rendere ciò su cui non stai lavorando.

Il codice passa dal client desktop, non da Unreal

Il plugin rifiuta l'invio dei file di codice: .cpp, .h, .hpp, .c e .cs. Il tentativo si ferma su una finestra bloccante che nomina i file colpevoli. Non è un difetto: il client desktop compila prima di inviare e pubblica i binari di editor che i tuoi colleghi recuperano al sync. Un commit di codice partito dall'editor mancherebbe entrambi, e sospenderebbe la distribuzione dei binari per tutta la squadra.

Invia quindi il tuo codice dal client desktop. I file di contenuto, invece, restano perfettamente liberi di partire da Unreal.

La trappola: un solo file di codice riservato blocca anche i tuoi invii di CONTENUTO La regola non si ferma ai file che invii. Finché detieni la riserva di un file di codice, anche uno solo, anche senza averlo toccato, anche assente dal tuo invio, ogni checkin da Unreal è rifiutato, compreso un invio di .uasset puro. Il messaggio ti dice di inviare il tuo codice dal client desktop prima.

È il blocco più comune, e cade volentieri su chi non scrive codice: basta che un file sorgente sia stato reso modificabile sul disco perché la riconciliazione all'avvio l'abbia riservato da sola. Il motivo è reale: un asset salvato contro codice non inviato rompe tutti quelli che lo sincronizzano, dato che i loro binari non hanno il codice da cui dipende.

Lo sblocco: apri la scheda Pending del client desktop, la lista My Pending Changes, individua i file di codice, e fai un Checkin Selected se li hai modificati, o un Revert se non li hai toccati. Il tuo invio di contenuto riparte poi normalmente. Può volerci qualche secondo, il tempo che l'editor aggiorni la sua vista dei lock.

La scheda Pending del client desktop: la lista My Pending Changes dove figurano due file .h accanto a un .uasset, ciascuno con il suo pulsante Revert, e più in basso la sezione Other Users' Locks.

Problemi comuni

Nessun menu uVersion: l'editor ignora il controllo di versione

Il progetto probabilmente non è in un workspace uVersion. Verifica che una cartella .uversion/ esista alla radice della cartella clonata, e che tu stia aprendo il progetto proprio da quella cartella e non da una copia messa altrove.

« Failed to connect to source control »

Verifica che il client desktop sia in esecuzione e che tu vi sia connesso: è lui a detenere le tue credenziali e a saper dialogare con un server autofirmato. Se l'account proprietario del workspace non è connesso nel client, il plugin rifiuta di lavorare sotto un'altra identità, ed è voluto.

Un invio è rifiutato anche se non ho toccato alcun codice

Detieni la riserva di un file di codice. Vedi Il codice passa dal client desktop.

Voglio un asset che qualcun altro ha bloccato

Questo non si richiede da Unreal: il plugin non ha una funzione di richiesta di rilascio. Passa dal client desktop, scheda Pending, sezione Other Users' Locks, pulsante Request Release sulla riga del file. Il detentore riceve una richiesta sotto forma di card nel board Production.

Il plugin non si aggiorna

È il comportamento previsto: la verifica automatica installa un plugin mancante, ma si limita a segnalare un aggiornamento. Chiudi l'editor Unreal (un plugin caricato non può essere sostituito), poi clicca sul badge Update ready nella barra Unreal del client desktop per applicarlo.

Una regola di validazione non scatta mai

Le nove regole sono consegnate disattivate. Un amministratore deve attivarle per progetto dalla scheda Rules del pannello Admin.