Wiki

Client desktop

Il client desktop di uVersion per Windows, macOS e Linux: installazione, workspace, schede, impostazioni.

Installazione

Il client desktop è un'applicazione nativa disponibile per Windows, macOS (Apple Silicon) e Linux. Gli installer per Windows, macOS e Linux includono anche la CLI uversion e la rendono accessibile. Scaricalo da /downloads.

Windows

Scarica uVersion_x.y.z_x64-setup.exe (installer NSIS firmato, ~25 MB). All'avvio, l'installer:

Installa il client in %LOCALAPPDATA%\uVersion (per utente, nessun privilegio di amministratore richiesto)
Aggiunge la cartella di installazione al PATH utente (la CLI uversion.exe è inclusa lì)
Crea un collegamento nel menu Start
Abilita l'aggiornamento automatico tramite l'updater di Tauri

macOS (Apple Silicon)

Scarica uVersion_x.y.z_macos-arm64.app.zip (~32 MB, firmato con Developer ID e autenticato da Apple). Fai doppio clic per decomprimere, poi trascina uVersion.app in /Applications. Al primo avvio, Gatekeeper convalida automaticamente l' autenticazione, senza alcun avviso.

La CLI uversion è inclusa nell'app. Al primo avvio, il client crea automaticamente un collegamento simbolico a ~/.local/bin/uversion e aggiunge ~/.local/bin al tuo PATH tramite ~/.zprofile: nessuna azione manuale richiesta. Apri un nuovo terminale e uversion è disponibile.

Nota: è supportato solo Apple Silicon (M1/M2/M3/M4). Nessun binario Intel.

Linux

Due formati per x86_64:

AppImage (uVersion_x.y.z_amd64.AppImage, ~76 MB): portatile, include tutte le dipendenze (libwebkit2gtk, libgtk, libsoup, ecc.). Funziona su qualsiasi distribuzione Linux senza installazione a livello di sistema:
```
chmod +x uVersion_x.y.z_amd64.AppImage
./uVersion_x.y.z_amd64.AppImage
```
Pacchetto .deb (uVersion_x.y.z_amd64.deb, ~5 MB): per Ubuntu / Debian / derivate. apt risolve le dipendenze di sistema:
```
sudo apt install ./uVersion_x.y.z_amd64.deb
```
L'app viene installata in /usr/bin/uVersion.

Nota: la CLI uversion è inclusa nei pacchetti Linux. Al primo avvio, il client copia il binario in ~/.local/bin/uversion e aggiunge ~/.local/bin al tuo PATH tramite ~/.profile (nessuna azione manuale richiesta).

Primo avvio

Al primo avvio, il client mostra la pagina di login. Inserisci:

Indirizzo del server: l'indirizzo del tuo studio (es. https://uversion.mygamestudio.com)
Nome utente e password

Una volta connesso, il client memorizza la tua sessione in modo sicuro. La CLI uversion e i plugin per editor (Unreal, Rider) riutilizzano automaticamente le stesse credenziali: non reinserisci la password da nessun'altra parte.

Workspace

Un workspace è una cartella locale collegata a un repository del server. Il client può gestire più workspace contemporaneamente, mostrati nella barra delle schede in alto. Ogni workspace memorizza i propri metadati in .uversion/ nella radice della cartella locale:

.uversion/config.toml: owner, repo_id, server URL, workspace UUID
.uversion/checkouts_<workspace_id>.json: lock che TU detieni in questo workspace
.uversion/changelists_<workspace_id>.json: changelist locali
.uversion/.last_sync: ultima revisione synced (per i sync incrementali)

Scheda Files

L'albero dei file con i filtri di stato (Synced, Modified, Local only, Locked…) e la barra di ricerca.

Vista ad albero dei file del workspace con il loro status. Filtri disponibili:

Search: ricerca per sottostringa nel path (senza distinzione tra maiuscole e minuscole)
Status filters: Synced, Modified, Local only, Server only, Locked, Deleted

La vista rimane fluida anche su progetti con decine di migliaia di file.

Selezione multipla + azioni

Seleziona più file (clic + shift, oppure spunta le caselle) poi:

Checkout: acquisisce i lock (idempotente; rifare il checkout di un file già locked è un no-op)
Sync: riscarica quelli selezionati (utile se un file è corrotto localmente)
Revert: rilascia il lock, ripristina la versione del server

Scheda Pending

File attualmente checked-out, locked da te O da un altro utente. Due sezioni:

Your locks: puoi fare checkin, revert o release singolarmente
Other users' locks: vedi chi detiene il lock, più un pulsante Request release che crea una scheda di richiesta nella bacheca Production (un badge request)

Gli amministratori vedono anche un pulsante Force unlock sui lock di terzi, che rilascia il lock senza il consenso del titolare. Ogni force unlock viene registrato nell'audit.

Scheda History

Un commit espanso con il suo elenco di file e il pulsante Get all del commit.

Elenco paginato dei commit del repository, con autore, data, messaggio e file modificati. Facendo clic su un commit si apre il dettaglio: l'elenco completo dei file del commit con le rispettive revisioni.

Un pulsante Get all su ogni commit scarica una copia locale di tutti i file a quella revisione (utile per recuperare uno stato stabile).

Production

L'area Production (una voce dedicata nella barra laterale) raccoglie il monitoraggio del progetto, per repository. Ha sostituito le vecchie schede Activity e Requests del Workspace: il Workspace ora si concentra sui file (Files, Pending, History).

My tasks

Le attività assegnate a te, in tutti i progetti.

L'elenco delle schede assegnate a te, aggregato su tutti i repository a cui hai accesso.

Board

Il kanban: colonne To Do / In Progress / Review / Done, schede con priorità, etichette, assegnatari, copertine.

Bacheca kanban per repository, con colonne configurabili (per impostazione predefinita To Do, In Progress, Review, Done). Ogni scheda porta una priorità (low / normal / high / urgent), etichette, assegnatari, una scadenza, commenti, link ad asset o commit, e un'immagine di copertina.

Le richieste sono schede della bacheca Le vecchie modification request (per esempio 'Request release' su un lock detenuto da qualcun altro, nella scheda Pending) ora sono schede della bacheca con un badge request. Non esiste più una scheda Requests separata.

Una scheda aperta: descrizione, assegnatari, scadenza, commenti, link asset/commit, copertina.

📷 Screenshot · production-request-cards

Schede di tipo request (badge) nella colonna Review.

Activity

Dashboard unificata:

KPI 24 h: commit, contributori attivi, lock attivi
Calendario delle attività: commit al giorno nell'arco di più mesi (heatmap)
Recent Checkins e Most Modified Directories
Commit History: commit paginati con filtri per utente e per percorso

Watchlist

Sorveglia percorsi (pattern glob) per essere notificato dei check-in che li toccano. Ogni voce indica il percorso sorvegliato e gli eventi seguiti.

Games

L'area Games elenca i build di playtest interni pubblicati per il progetto. Ogni build indica la sua versione, la sua configurazione (DebugGame / Development / Shipping), la sua piattaforma (Win64 / Mac / Linux), la sua dimensione e le sue note di versione, con un pulsante di download adatto alla piattaforma.

È il punto di accesso dei playtester: un account con il ruolo playtester vede solo questa pagina (né Workspace né Production), e accede solo ai build dei progetti che gli sono aperti.

Changelist locali

📷 Screenshot · client-changelists

File checked-out suddivisi in due changelist locali (per esempio 'default' e 'review').

Raggruppa i tuoi checked-out file in più commit indipendenti. Le changelist sono locali al tuo workspace (mai inviate al server). Utile per:

Separare un fix critico da un lavoro in corso
Preparare più invii in parallelo senza mescolare tutto
Tenere una changelist "default" per il WIP e una "review" per ciò che va in checkin

Settings

Preferenze globali del client (salvate in %APPDATA%/uversion/uVersion/config/config.toml):

Opzione	Descrizione
Default server URL	Precompilato nella pagina di login
Username	Precompilato nella pagina di login
Theme	System / Light / Dark
Show hidden files	Mostrare i file che iniziano con `.` nella scheda Files
Auto-sync interval	Disattivato / 5 min / 15 min / 30 min: attiva un sync incrementale automatico
Parallel uploads	Limite di concurrency (1-32, predefinito 16)
Default repos path	Cartella proposta per impostazione predefinita durante un clone

Pannello Unreal

📷 Screenshot · client-unreal-panel

Il pannello Unreal con i suoi pulsanti di azione: Open Editor, Compile, Package Game e la sua scelta di config, Publish Build, Stop.

Quando il client rileva un progetto Unreal nel workspace (presenza di un file .uproject), appare un pannello dedicato. Pilota il motore direttamente dal client: aprire l'editor, compilare, creare il pacchetto, senza passare da un IDE. La maggior parte delle azioni riguarda solo i progetti C++ (un progetto Blueprint puro non ha bisogno di compilare).

Engine path

La versione di Unreal viene rilevata automaticamente dall'EngineAssociation del .uproject (registro di Windows, LauncherInstalled.dat o build da sorgente). Puoi sovrascriverla manualmente se il rilevamento fallisce. Questo percorso è necessario per tutte le azioni seguenti.

Open Editor

Avvia l'editor di Unreal (UnrealEditor) sul progetto del workspace. Il pulsante è idempotente: l'editor può impiegare diverse decine di secondi per mostrare la sua finestra (soprattutto su macOS / Linux), quindi un secondo clic in quel lasso di tempo non apre una seconda istanza. Il pulsante mostra «Opening…» mentre l'editor si avvia. Per un progetto C++ mai compilato in locale, aprire l'editor avvia prima una generazione dei file di progetto e poi una compilazione (vedi Azioni automatiche).

Compile

📷 Screenshot · client-compile-console

La console integrata che mostra l'output di compilazione di Unreal Build Tool in tempo reale.

Compila il progetto (Unreal Build Tool). L'output viene mostrato in tempo reale in una console integrata. Un progetto C++ deve essere compilato affinché l'editor possa aprirlo e per riflettere le modifiche al codice.

Generate Project Files

Rigenera i file di progetto dell'IDE (Visual Studio, Rider). Utile dopo aver aggiunto o rimosso file sorgente, o dopo un clone. Si trova nel menu «…» (altre azioni) del pannello.

Package Game

Crea il pacchetto del gioco tramite RunUAT BuildCookRun e archivia il risultato in Packages/{config}/ nella radice del workspace. Tre configurazioni a scelta:

Config	Uso
`DebugGame`	Build di debug (simboli completi, non ottimizzato).
`Development`	Build di sviluppo (predefinito): ottimizzato ma con gli strumenti di dev.
`Shipping`	Build di distribuzione: ottimizzato, senza gli strumenti di dev.

La cartella Packages/ è ignorata per impostazione predefinita (.uversionignore): i pacchetti non vengono versionati, si distribuiscono tramite Publish Build.

Publish Build

Pubblica un build pacchettizzato come versione di playtest interna. Diventa scaricabile dal tuo team dalla pagina Games del client (ruolo playtester o accesso al build concesso). Il client scansiona Packages/{config}/, invia i file (deduplicati lato server) e poi registra il manifest.

Open project folder

Apre la cartella del workspace nell'esplora file del sistema (Esplora risorse di Windows, Finder o xdg-open su Linux).

Stop

Interrompe in modo pulito tutti i build in corso: compilazione e creazione del pacchetto. Il pulsante indica quanti build sono stati fermati (una compilazione automatica avviata in background può essere conteggiata).

Azioni automatiche

Oltre ai pulsanti, il client avvia da solo alcune azioni di Unreal, affinché un progetto C++ rimanga sempre aggiornato e compilabile:

Prima di un check-in: se dei file di codice sono cambiati, il progetto viene compilato prima. Se la compilazione fallisce, il check-in viene bloccato (non si invia codice che non compila).
Dopo un sync: se il sync ha scaricato del codice, il client rigenera i file di progetto e poi ricompila.
Al primo avvio dopo un clone (progetto C++): generazione dei file di progetto e poi compilazione, prima di poter aprire l'editor.

Questi build automatici si serializzano sul lock del motore (Unreal Build Tool -WaitMutex): non si rifiutano a vicenda, si concatenano. Anche il pulsante Stop li interrompe.