Wiki

Regole di validazione

Controlli di validazione degli asset eseguiti al check-in dall'editor Unreal : le 9 regole integrate, le severità error / warning / info, la configurazione JSON, export / import / reset, e il limite da conoscere.

Introduzione

Le regole di validazione sono controlli sugli asset di Unreal eseguiti al momento del check-in dall'editor Unreal : denominazione, dimensione delle texture, dipendenze mancanti, ecc. Servono a far rispettare automaticamente le convenzioni dello studio, prima che i contenuti entrino nel repository (il progetto versionato sul server). Si configurano per repository.

Dove si applicano davvero le regole

La validazione è fatta dall'editor Unreal, non dal server Le regole configurate qui vengono scaricate ed eseguite dal plugin uVersion per Unreal Engine, nel momento in cui invii dall'editor. Il server, dal canto suo, non consulta mai le regole quando registra un commit. Conseguenza da conoscere prima di farci affidamento : un invio effettuato dal client desktop, dalla riga di comando (uversion checkin) o dal plugin Rider aggira integralmente la politica di validazione, senza errori e senza lasciare traccia.

Non è un errore di configurazione da parte tua : è il funzionamento attuale. Le regole riguardano asset di Unreal (.uasset, .umap) e la loro ispezione richiede l'editor aperto, con il progetto caricato. Trattale quindi come una protezione per gli artisti che lavorano nell'editor, e non come una barriera che nessuno può superare.

Due conseguenze pratiche :

Se una convenzione deve essere garantita e non solo incoraggiata, prevedi un controllo in più (revisione, verifica lato build) : le regole da sole non la assicurano.
Se una regola «non scatta mai» per qualcuno, verifica prima da dove invia. Un artista che invia dal client desktop non vedrà alcuna validazione, qualunque sia la configurazione.

Accesso e ruoli

La scheda Regole è accessibile al super admin e al project_admin sui repository che amministra.

Popolamento automatico, ma tutte disattivate Le 9 regole predefinite vengono create automaticamente alla creazione di un repository (e, in mancanza, la prima volta che si apre la scheda Rules di un repository che non ne ha nessuna). Vengono popolate disattivate : su un repository nuovo, nessuna validazione viene eseguita finché un amministratore non ha attivato le regole che desidera. Parti da un insieme completo, da attivare e regolare.

Severità

La severità decide cosa succede nell'editor Unreal quando una regola attivata fallisce.

Severità	Effetto al check-in dall'editor Unreal
`error`	Blocca il check-in : la finestra di validazione si apre, il pulsante Proceed è disattivato e solo OK resta cliccabile. Bisogna correggere l'asset.
`warning`	Non impedisce di inviare, ma non passa in silenzio : la finestra di validazione si apre comunque, elenca gli avvisi, e l'utente deve cliccare Proceed per continuare.
`info`	Puramente informativo : non apre la finestra da solo e non interrompe nulla.

La finestra Pre-Checkin Validation nell'editor Unreal, con l'elenco dei rilievi e il pulsante Proceed.

Le 9 regole integrate

Regola	Predefinito	Cosa verifica
`blueprint_compilation`	error	I Blueprint compilano senza errori prima del check-in.
`naming_convention`	warning	Prefissi di denominazione (stile Allar UE5) : `T_` texture, `M_` materiali, `BP_` blueprint, `SM_` static mesh, `WBP_` widget, ecc.
`max_texture_size`	warning	Dimensione massima delle texture : per impostazione predefinita 4096 × 4096, potenza di 2 richiesta.
`material_complexity`	warning	Complessità dei materiali : per impostazione predefinita max 256 istruzioni, 16 campioni di texture.
`import_settings`	warning	Impostazioni di importazione conformi (texture, mesh).
`missing_dependency`	error	Nessuna dipendenza mancante (ignora per impostazione predefinita il contenuto del motore).
`circular_dependency`	error	Nessuna dipendenza circolare (profondità di ricerca 20 per impostazione predefinita).
`unreferenced_asset`	info	Segnala gli asset non referenziati (esclude mappe e widget per impostazione predefinita).
`duplicate_asset`	warning	Rileva gli asset duplicati (ignora i `.umap` per impostazione predefinita).

Attivare e configurare

1. Aprire la scheda Rules

Nel pannello di amministrazione, scegli prima il repository nel selettore della riga PROJECT, poi apri la scheda Rules di quella stessa riga : le regole riguardano un solo repository alla volta. Le 9 regole vengono visualizzate, una per riga, con un chevron per espandere, un interruttore, il nome della regola, la sua severità e la sua descrizione.

L'elenco delle 9 regole di validazione : su ogni riga il chevron, l'interruttore di attivazione, il nome della regola, la sua severità e il menu a discesa Error / Warning / Info a destra.

2. Attivare la regola

Clicca sull'interruttore a sinistra del nome. Il salvataggio è immediato : non c'è un pulsante di salvataggio per questa azione. È il passaggio che si dimentica : su un repository nuovo, tutti gli interruttori sono spenti, e una regola spenta non dice nulla a nessuno, qualunque sia la sua severità.

3. Scegliere la severità

Il menu a discesa a destra della riga propone Error, Warning e Info, con salvataggio immediato anche qui. Solo error blocca davvero il check-in : vedi Severità.

4. Regolare i parametri (JSON)

Clicca sul chevron a inizio riga per espandere la regola. Il campo Configuration (JSON) contiene i suoi parametri ; modificali, poi clicca su Save Config. Un JSON non valido blocca il salvataggio e mostra il dettaglio dell'errore sotto il campo (Invalid JSON: ...), la regola resta allora nel suo stato precedente.

Una regola espansa sul suo editor Configuration (JSON) : il testo dei parametri nell'area di inserimento e il pulsante Save Config in basso a destra.

Esempio : abbassare max_texture_size a 2048 per un progetto mobile, o portare naming_convention a error per imporla in modo rigoroso.

Export, import, reset

Tre pulsanti occupano la barra degli strumenti, in alto a destra nella scheda Rules :

Export : scarica un file rules.json contenente lo stato di tutte le regole (attivazione, severità, config).
Import : ricarica un rules.json e applica ogni voce alle regole corrispondenti (le chiavi sconosciute vengono ignorate).
Reset to Defaults : ripristina tutte le regole ai loro valori predefiniti. Le configurazioni personalizzate vengono perse (viene chiesta conferma).

L'export / import serve a replicare una politica di validazione da un repository all'altro, o a versionarla offline.

rules.json nel repository

Un rules.json committato non viene applicato da chiunque Un file .uversion/rules.json committato viene applicato alla politica del repository solo se l'autore del commit possiede l'autorizzazione denominata manage_rules (una «capacità», cioè un'autorizzazione legata a un ruolo e valida su tutto il server). Altrimenti il file viene memorizzato ma le regole non cambiano. È una salvaguardia : un collaboratore con diritto di scrittura su quel percorso non può disattivare la validazione committando un file.

Errori comuni

Un check-in è bloccato nell'editor Unreal

Una regola in error è fallita : la finestra di validazione elenca i rilievi e il pulsante Proceed resta disattivato. Correggi l'asset, o (se la regola è troppo rigida per il tuo contesto) abbassa la sua severità a warning, o disattivala.

Reset cancella le mie impostazioni

Reset to Defaults è distruttivo per le tue configurazioni personalizzate. Fai un Export prima se vuoi poter tornare indietro.

Una regola sembra non fare nulla

Tre verifiche, in quest'ordine :

Da dove invia la persona? Dal client desktop, dalla riga di comando o dal plugin Rider, nessuna regola viene valutata (vedi Dove si applicano davvero le regole).
La regola è attivata? Su un repository nuovo, all'inizio sono tutte disattivate.
La sua severità è quella giusta? Solo error blocca il check-in ; info non interrompe nulla.