Wiki

Cliente desktop

O cliente desktop do uVersion para Windows, macOS e Linux: instalação, workspace, abas, configurações.

Instalação

O cliente desktop é um aplicativo nativo disponível para Windows, macOS (Apple Silicon) e Linux. Os instaladores de Windows, macOS e Linux também trazem embutida a CLI uversion e a deixam acessível. Baixe em /downloads.

Windows

Baixe uVersion_x.y.z_x64-setup.exe (instalador NSIS assinado, ~25 MB). Ao ser executado, o instalador:

Instala o cliente em %LOCALAPPDATA%\uVersion (por usuário, sem necessidade de administrador)
Adiciona a pasta de instalação ao PATH do usuário (a CLI uversion.exe vem embutida ali)
Cria um atalho no menu Iniciar
Ativa a atualização automática via atualizador do Tauri

macOS (Apple Silicon)

Baixe uVersion_x.y.z_macos-arm64.app.zip (~32 MB, assinado com Developer ID e notarizado pela Apple). Dê um duplo clique para descompactar e arraste uVersion.app para /Applications. Na primeira inicialização, o Gatekeeper valida automaticamente a notarização, sem nenhum aviso.

A CLI uversion vem embutida no app. Na primeira inicialização, o cliente cria automaticamente um link simbólico para ~/.local/bin/uversion e adiciona ~/.local/bin ao seu PATH via ~/.zprofile: nenhuma ação manual é necessária. Abra um novo terminal e uversion estará disponível.

Observação: apenas Apple Silicon (M1/M2/M3/M4) é suportado. Não há binário para Intel.

Linux

Dois formatos para x86_64:

AppImage (uVersion_x.y.z_amd64.AppImage, ~76 MB): portátil, traz embutidas todas as dependências (libwebkit2gtk, libgtk, libsoup, etc.). Funciona em qualquer distribuição Linux sem instalação no sistema:
```
chmod +x uVersion_x.y.z_amd64.AppImage
./uVersion_x.y.z_amd64.AppImage
```
Pacote .deb (uVersion_x.y.z_amd64.deb, ~5 MB): para Ubuntu / Debian / derivados. O apt resolve as dependências do sistema:
```
sudo apt install ./uVersion_x.y.z_amd64.deb
```
O app é instalado em /usr/bin/uVersion.

Observação: a CLI uversion vem embutida nos pacotes Linux. Na primeira inicialização, o cliente copia o binário para ~/.local/bin/uversion e adiciona ~/.local/bin ao seu PATH via ~/.profile (nenhuma ação manual é necessária).

Primeira inicialização

Na primeira inicialização, o cliente exibe a página de login. Informe:

Endereço do servidor: o endereço do seu estúdio (ex.: https://uversion.mygamestudio.com)
Nome de usuário e senha

Depois de conectado, o cliente memoriza sua sessão de forma segura. A CLI uversion e os plugins de editor (Unreal, Rider) reutilizam automaticamente as mesmas credenciais: você não digita a senha novamente em nenhum outro lugar.

Workspace

Um workspace é uma pasta local vinculada a um repository do servidor. O cliente pode gerenciar vários workspaces ao mesmo tempo, exibidos na barra de abas no topo. Cada workspace armazena seus metadados em .uversion/ na raiz da pasta local:

.uversion/config.toml: owner, repo_id, server URL, workspace UUID
.uversion/checkouts_<workspace_id>.json: locks que VOCÊ mantém neste workspace
.uversion/changelists_<workspace_id>.json: changelists locais
.uversion/.last_sync: última revisão synced (para syncs incrementais)

Aba Files

A árvore de arquivos com os filtros de status (Synced, Modified, Local only, Locked…) e a barra de busca.

Visão em árvore dos arquivos do workspace com seu status. Filtros disponíveis:

Search: busca por substring no path (sem diferenciar maiúsculas e minúsculas)
Status filters: Synced, Modified, Local only, Server only, Locked, Deleted

A visão permanece fluida mesmo em projetos com dezenas de milhares de arquivos.

Seleção múltipla + ações

Selecione vários arquivos (clique + shift, ou marque as caixas de seleção) e depois:

Checkout: adquire os locks (idempotente; refazer o checkout de um arquivo já locked é um no-op)
Sync: baixa novamente os selecionados (útil se um arquivo estiver corrompido localmente)
Revert: libera o lock, restaura a versão do servidor

Aba Pending

Arquivos atualmente checked-out, locked por você OU por outro usuário. Duas seções:

Your locks: você pode fazer checkin, revert ou release individualmente
Other users' locks: você vê quem detém o lock, além de um botão Request release que cria um cartão de solicitação no quadro Production (um selo request)

Os administradores também veem um botão Force unlock nos locks de terceiros, que libera o lock sem o consentimento do detentor. Todos os force unlock são auditados.

Aba History

Um commit expandido com sua lista de arquivos e o botão Get all do commit.

Lista paginada dos commits do repository, com autor, data, mensagem e arquivos modificados. Clicar em um commit abre o detalhe: a lista completa dos arquivos do commit com suas revisões.

Um botão Get all em cada commit baixa uma cópia local de todos os arquivos naquela revisão (útil para recuperar um estado estável).

Production

A área Production (uma entrada dedicada na barra lateral) reúne o acompanhamento do projeto, por repository. Ela substituiu as antigas abas Activity e Requests do Workspace: o Workspace agora se concentra nos arquivos (Files, Pending, History).

My tasks

As tarefas atribuídas a você, em todos os projetos.

A lista de cartões atribuídos a você, agregada em todos os repositorys aos quais você tem acesso.

Board

O kanban: colunas To Do / In Progress / Review / Done, cartões com prioridade, rótulos, responsáveis, capas.

Quadro kanban por repository, com colunas configuráveis (por padrão To Do, In Progress, Review, Done). Cada cartão carrega uma prioridade (low / normal / high / urgent), rótulos, responsáveis, um prazo, comentários, links para assets ou commits, e uma imagem de capa.

As solicitações são cartões do quadro As antigas modification requests (por exemplo 'Request release' em um lock que outra pessoa detém, na aba Pending) agora são cartões do quadro com um selo request. Não há mais uma aba Requests separada.

Um cartão aberto: descrição, responsáveis, prazo, comentários, links asset/commit, capa.

📷 Screenshot · production-request-cards

Cartões do tipo request (selo) na coluna Review.

Activity

Painel unificado:

KPIs de 24 h: commits, contribuidores ativos, locks ativos
Calendário de atividade: commits por dia ao longo de vários meses (heatmap)
Recent Checkins e Most Modified Directories
Commit History: commits paginados com filtros por usuário e por caminho

Watchlist

Vigie caminhos (padrões glob) para ser notificado dos check-ins que os tocam. Cada entrada indica o caminho vigiado e os eventos acompanhados.

Games

A área Games lista os builds de playtest internos publicados para o projeto. Cada build indica sua versão, sua configuração (DebugGame / Development / Shipping), sua plataforma (Win64 / Mac / Linux), seu tamanho e suas notas de versão, com um botão de download adaptado à plataforma.

É o ponto de acesso dos playtesters: uma conta com o papel playtester vê apenas esta página (nem Workspace nem Production), e acessa apenas os builds dos projetos que lhe são abertos.

Changelists locais

📷 Screenshot · client-changelists

Arquivos checked-out distribuídos em duas changelists locais (por exemplo 'default' e 'review').

Agrupe seus checked-out files em vários commits independentes. As changelists são locais ao seu workspace (nunca são enviadas ao servidor). Útil para:

Separar um fix crítico de um trabalho em andamento
Preparar vários envios em paralelo sem misturar tudo
Manter uma changelist "default" para o WIP e uma "review" para o que vai para checkin

Settings

Preferências globais do cliente (salvas em %APPDATA%/uversion/uVersion/config/config.toml):

Opção	Descrição
Default server URL	Pré-preenchido na página de login
Username	Pré-preenchido na página de login
Theme	System / Light / Dark
Show hidden files	Exibir os arquivos que começam com `.` na aba Files
Auto-sync interval	Desativado / 5 min / 15 min / 30 min: dispara um sync incremental automático
Parallel uploads	Limite de concurrency (1-32, padrão 16)
Default repos path	Pasta proposta por padrão ao fazer um clone

Painel do Unreal

📷 Screenshot · client-unreal-panel

O painel do Unreal com seus botões de ação: Open Editor, Compile, Package Game e sua escolha de config, Publish Build, Stop.

Quando o cliente detecta um projeto Unreal no workspace (presença de um arquivo .uproject), um painel dedicado aparece. Ele controla o motor diretamente pelo cliente: abrir o editor, compilar, empacotar, sem passar por uma IDE. A maioria das ações diz respeito apenas a projetos C++ (um projeto Blueprint puro não precisa compilar).

Engine path

A versão do Unreal é detectada automaticamente a partir do EngineAssociation do .uproject (registro do Windows, LauncherInstalled.dat ou build de código-fonte). Você pode sobrescrevê-la manualmente se a detecção falhar. Esse caminho é necessário para todas as ações abaixo.

Open Editor

Inicia o editor do Unreal (UnrealEditor) no projeto do workspace. O botão é idempotente: o editor pode levar várias dezenas de segundos para exibir sua janela (especialmente no macOS / Linux), então um segundo clique nesse período não abre uma segunda instância. O botão mostra «Opening…» enquanto o editor inicia. Para um projeto C++ nunca compilado localmente, abrir o editor primeiro dispara uma geração dos arquivos de projeto e depois uma compilação (veja Ações automáticas).

Compile

📷 Screenshot · client-compile-console

O console integrado exibindo a saída de compilação do Unreal Build Tool em tempo real.

Compila o projeto (Unreal Build Tool). A saída é exibida em tempo real em um console integrado. Um projeto C++ precisa ser compilado para que o editor possa abri-lo e para refletir as alterações de código.

Generate Project Files

Regenera os arquivos de projeto da IDE (Visual Studio, Rider). Útil após adicionar ou remover arquivos de código-fonte, ou após um clone. Fica no menu «…» (mais ações) do painel.

Package Game

Empacota o jogo via RunUAT BuildCookRun e arquiva o resultado em Packages/{config}/ na raiz do workspace. Três configurações à escolha:

Config	Uso
`DebugGame`	Build de depuração (símbolos completos, não otimizado).
`Development`	Build de desenvolvimento (padrão): otimizado, mas com as ferramentas de dev.
`Shipping`	Build de distribuição: otimizado, sem as ferramentas de dev.

A pasta Packages/ é ignorada por padrão (.uversionignore): os empacotados não são versionados, eles são distribuídos via Publish Build.

Publish Build

Publica um build empacotado como versão de playtest interno. Ele passa a ser baixável pela sua equipe na página Games do cliente (papel playtester ou acesso ao build concedido). O cliente escaneia Packages/{config}/, envia os arquivos (deduplicados no servidor) e então registra o manifesto.

Open project folder

Abre a pasta do workspace no explorador de arquivos do sistema (Explorador do Windows, Finder ou xdg-open no Linux).

Stop

Interrompe de forma limpa todos os builds em andamento: compilação e empacotamento. O botão indica quantos builds foram parados (uma compilação automática iniciada em segundo plano pode ser contabilizada).

Ações automáticas

Além dos botões, o cliente dispara sozinho certas ações do Unreal, para que um projeto C++ permaneça sempre atualizado e compilável:

Antes de um check-in: se arquivos de código mudaram, o projeto é compilado primeiro. Se a compilação falhar, o check-in é bloqueado (não se envia código que não compila).
Depois de um sync: se o sync baixou código, o cliente regenera os arquivos de projeto e depois recompila.
No primeiro lançamento após um clone (projeto C++): geração dos arquivos de projeto e depois compilação, antes de poder abrir o editor.

Esses builds automáticos são serializados no bloqueio do motor (Unreal Build Tool -WaitMutex): eles não se recusam entre si, eles se encadeiam. O botão Stop também os interrompe.