Cliente desktop

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 incluem a CLI uversion e a tornam 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 updater do Tauri

Windows em frota: o MSI

Para implantar em muitas máquinas com uma ferramenta de gestão de parque (Intune, SCCM, diretiva de grupo...), use o MSI em vez do instalador NSIS: uVersion_latest_x64_en-US.msi (URL estável, sempre a versão mais recente, ~10 MB). Instalação silenciosa, por máquina:

msiexec /i uVersion_latest_x64_en-US.msi /qn /norestart

• Instala em C:\Program Files\uVersion (requer permissões de administrador). A CLI uversion.exe está incluída, mas a pasta não é adicionada ao PATH: se seus usuários precisarem dela em um terminal, faça a ferramenta de implantação adicioná-la.
• Sem atualização automática numa instalação MSI: o cliente permanece na versão implantada e as atualizações da frota são feitas reimplantando o próximo MSI. É proposital: o updater integrado instalaria uma segunda cópia, por usuário, ao lado da gerenciada.
• Desinstalação silenciosa: msiexec /x uVersion_latest_x64_en-US.msi /qn

No primeiro uso, cada usuário informa o endereço do servidor e valida a impressão digital do certificado, uma vez por usuário e por máquina (ver Impressão digital TLS).

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, depois arraste uVersion.app para /Applications. No primeiro início, o Gatekeeper valida a notarização automaticamente, sem nenhum aviso.

A CLI uversion vem embutida no app. No primeiro início, 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.

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

Linux

Um único formato para x86_64: o AppImage (uVersion_x.y.z_amd64.AppImage, ~85 MB). Portátil, ele embute suas dependências (libwebkit2gtk, libgtk, libsoup, etc.) e funciona em qualquer distribuição recente sem instalação no sistema. Pré-requisitos: Ubuntu 24.04 ou superior, Debian 13 ou superior, ou uma distribuição de uma geração equivalente. O binário exige uma biblioteca C de sistema recente, e o AppImage não abaixa esse piso: ele embute o ambiente gráfico, não a biblioteca C.

A via recomendada é o script de instalação. Sem sudo:

curl -fSL https://uversion.io/downloads/client/install.sh | sh

Ele não faz nada de mágico e, sobretudo, nada que peça permissões:

• ele se recusa a rodar como root, numa arquitetura que não seja x86_64, ou num sistema velho demais para executar o binário, dizendo qual dos três é o problema;
• ele baixa o AppImage em ~/Applications/uVersion.AppImage, verifica que o que chegou é de fato um executável Linux (caso contrário, um portal cativo ou uma página de erro seriam salvos e tornados executáveis, para falhar mais tarde de forma incompreensível), e então o coloca no lugar num único gesto, o que continua seguro mesmo se uma cópia já estiver rodando;
• ele inicia o aplicativo. É esse início que cria a entrada no menu de aplicativos, então é melhor deixá-lo fazer. Numa sessão remota sem interface gráfica, ele exibe em vez disso o comando exato a digitar a partir da sua própria área de trabalho.

Você também pode baixar o AppImage manualmente na página de download, torná-lo executável e iniciá-lo:

chmod +x uVersion_x.y.z_amd64.AppImage
./uVersion_x.y.z_amd64.AppImage

Não há pacote .deb para o cliente, e não haverá: um pacote instalado por dpkg só pode se atualizar passando de novo por dpkg, ou seja, por uma elevação de privilégios a cada versão, o que é impossível numa máquina sem permissões de administrador. O AppImage se substitui sozinho, sem senha. O servidor, por sua vez, mantém sim seu pacote .deb.

Nota: a CLI uversion vem embutida no AppImage. No primeiro início, 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). A entrada no menu de aplicativos é criada no primeiro início, pela mesma razão: um AppImage é um arquivo, não uma instalação.

Primeiro início

1. Informar o endereço do servidor e suas credenciais

No primeiro início, o cliente exibe a página de login, intitulada Welcome to uVersion. O campo Server address não espera uma URL completa: ele é dividido em três blocos, um prefixo https:// não modificável, a máquina e a porta (8443 por padrão). O esquema é imposto, o cliente não pode produzir um http://. Colar um endereço completo ou um host:port na caixa da máquina o distribui automaticamente entre os dois campos. Em seguida, informe Username e Password, e clique em Sign in.

2. Verificar a impressão digital do servidor, uma única vez

Como um servidor uVersion é autoassinado por padrão, a primeiríssima conexão a uma dada máquina exibe Verify server identity: compare a impressão digital SHA-256 com aquela que seu administrador lhe deu, depois clique em Trust this server. A pergunta só é feita uma vez por servidor, e se ela voltar sob o título vermelho Server identity changed, a impressão digital mudou: não aceite sem verificar. Ver Impressão digital TLS.

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

Abrir ou clonar um repositório

Conectar-se não abre nenhum projeto: a lista de repositórios é solicitada explicitamente. É a mesma janela que serve para clonar um projeto pela primeira vez e para reabrir um workspace já presente no disco.

1. Abrir a janela Open Repository

Enquanto nenhuma aba estiver aberta, o Workspace exibe No repository selected e um botão Open Repository. Assim que você tiver ao menos uma aba, a mesma tela é obtida pelo + da barra de abas. A janela lista, um cartão por projeto, os repositórios aos quais você tem acesso, com um botão Refresh para pedir a lista ao servidor novamente.

2. Clonar, ou reabrir um workspace existente

Cada cartão propõe a ação que corresponde ao seu estado:

• Clone: cria um workspace novo. O campo Workspace name do cartão nomeia a pasta criada e assume o nome do projeto se for deixado vazio. O seletor de pasta que se segue pede a pasta pai: a subpasta é criada pelo próprio uVersion.
• Clone New: o mesmo botão, renomeado quando já existe um workspace para este projeto. Clonar uma segunda vez é legítimo, por exemplo para manter dois estados do projeto lado a lado.
• Open: reabre um workspace já clonado nesta máquina, cujo caminho é lembrado sob o cartão. Switch to Open Tab aparece em seu lugar quando a aba já está aberta.
• Open Local Repository..., embaixo na janela: aponta para uma pasta que já contém um .uversion/, por exemplo depois de ter movido um workspace.

A caixa Download files after clone, embaixo, vem marcada por padrão e inicia o download logo após o clone. Desmarque-a para criar o workspace agora e trazer os arquivos mais tarde.

3. Acompanhar o download

A janela se fecha assim que o clone começa, e isso é proposital: a transferência pode durar horas e não deve bloquear você. O progresso continua no cabeçalho do cliente, a aba do workspace se abre sozinha no final, e uma queda de rede não perde nada, já que a transferência é retomada por si mesma.

Workspace

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

• .uversion/config.toml: o único arquivo realmente importante. Sua seção [workspace] carrega o proprietário do workspace (owner), seu identificador, seu nome, e last_synced_revision, a revisão com a qual você está sincronizado (não há arquivo .last_sync). É também ali que fica memorizado o caminho do motor Unreal.
• .uversion/checkouts_<workspace_id>.json: os bloqueios que VOCÊ detém neste workspace
• .uversion/changelists_<workspace_id>.json: suas changelists, ou seja, pacotes de arquivos reservados que você agrupa para enviá-los separadamente. Puramente local, nunca transmitido ao servidor.
• .uversion/pending_deletes_<workspace_id>.json: as exclusões aguardando envio
• .uversion/snapshots.json: o estado conhecido dos arquivos, que serve para identificar o que você modificou localmente

Aba Files

Visão em árvore dos arquivos do workspace com seu estado. Duas maneiras de reduzir a lista:

• O campo de busca, intitulado Search files...: filtra por um trecho do caminho, sem diferenciar maiúsculas e minúsculas.
• Os chips de status, logo abaixo. São contadores clicáveis, e um chip só aparece se seu contador ultrapassar zero: num workspace recém-sincronizado, você verá portanto apenas {n} synced, e a ausência dos demais é normal. Os seis chips possíveis são {n} synced, {n} modified, {n} local only, {n} server only, {n} locked e {n} deleted.

Busca e chips se combinam: a busca restringe primeiro, os chips filtram depois. A visão permanece fluida mesmo em projetos de várias dezenas de milhares de arquivos.

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

A barra de ações só existe se algo estiver selecionado. Enquanto a seleção estiver vazia, não há nenhum botão: é normal, não é um carregamento em curso. Selecione arquivos (clique + shift, ou as caixas de seleção) e a barra aparece, prefixada com o número retido ({n} file(s) selected). Os botões aparecem conforme o que a seleção permite:

Aba Pending

Arquivos atualmente em 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 possui o bloqueio + um botão Request release que cria um cartão de solicitação no board Production (uma insígnia request)

Os admins também veem um botão Force unlock nos bloqueios de terceiros, que faz release do bloqueio sem o consentimento do detentor. Todos os force unlock são auditados.

Aba History

Lista paginada dos commits do repositório, 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.

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

Production

A zona Production (uma entrada dedicada na barra lateral) reúne o acompanhamento de projeto, por repositório. O Workspace, por sua vez, se concentra nos arquivos (Files, Pending, History).

My tasks

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

Board

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

Dashboard

A cabine do produtor: uma faixa de saúde do projeto (bloqueadores abertos, relatórios de playtest em espera), as zonas que concentram os problemas, os commits da semana, o peso do projeto e a última build publicada, cada bloco remetendo ao board ou a Games.

Abaixo, a linha do tempo em calendário: marcos, playtests (pontuais ou recorrentes), releases e prazos de cartões. Um playtest recorrente gera automaticamente seu cartão de board a cada ocorrência.

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 zona Games lista as builds de playtest internas publicadas 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 as builds dos projetos que lhe são abertos.

Changelists locais

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

• Separar um fix crítico de um trabalho em curso
• 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):

Painel Unreal

Quando o cliente detecta um projeto Unreal no workspace, uma barra de ações dedicada aparece no topo à direita do Workspace. Ela pilota o motor diretamente a partir do cliente: abrir o editor, compilar, empacotar, sem passar por um IDE. A maioria das ações só diz respeito aos projetos C++ (um projeto Blueprint puro não precisa compilar).

A pastilha de estado do plugin

Bem à esquerda da barra, uma pastilha indica em que ponto está o plugin Unreal para este projeto. Ela é clicável:

Caminho do motor

O caminho de instalação do Unreal é resolvido automaticamente a partir do EngineAssociation do .uproject (registro do Windows, LauncherInstalled.dat, ou build de fontes). Esse caminho é exigido para todas as ações abaixo, e a resolução automática falha em particular num motor compilado a partir das fontes. Aqui é onde ajustá-lo à mão.

1. Abrir o menu das ações secundárias

Não há nem campo de entrada, nem botão Browse, nem botão Auto-detect visível na barra. O único ponto de entrada é o botão em forma de engrenagem, bem à direita da barra Unreal, acompanhado de uma pequena seta e cuja dica diz More actions. Nada em sua aparência fala do motor, e é por isso que não o encontram.

2. Escolher Set Engine Path...

A entrada Set Engine Path... é a última do menu. Seu subtítulo exibe o caminho atual, ou Not configured se não houver nenhum: é a forma mais rápida de saber se o problema vem dali. Um seletor de pasta se abre, e o caminho escolhido é salvo no .uversion/config.toml do workspace.

Open Editor

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

Compile

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

Sync e Status

Esses dois botões vivem na mesma barra, e não na aba Files:

• Sync: atualiza todo o workspace a partir do servidor. Sua dica indica o número de arquivos em espera quando há algum. É o verdadeiro «sync» do cliente, a não confundir com o botão Download da aba Files, que só traz a seleção.
• Status: atualiza o estado do lado do servidor, bloqueios dos outros usuários incluídos, e reajusta o contador do botão Sync.

O menu More actions

As ações mais raras são agrupadas atrás do botão em forma de engrenagem, à direita da barra (captura acima):

• Generate Project Files: regenera os arquivos de projeto da IDE (Visual Studio, Rider). Útil depois de ter adicionado ou removido arquivos de código-fonte, ou depois de um clone.
• Publish Editor Binaries: compila, depois publica os binários de editor correspondentes ao último commit de código. Seus colegas os recuperam no sync em vez de recompilar cada um do seu lado. Ausente no Linux.
• Force Sync: rebaixa sobrescrevendo seus arquivos locais. Sinalizado em vermelho no menu, com a menção overwrites local, e precedido de uma confirmação. A reservar para os workspaces que se aceita perder.
• Set Engine Path...: o ajuste do caminho do motor, descrito acima.

Package

O botão se chama Package; «Package Game» é apenas sua dica, substituída por Set Engine Path first quando o caminho do motor falta, ficando o botão então desativado. Ele empacota o jogo via RunUAT BuildCookRun e arquiva o resultado em Packages/{config}/ na raiz do workspace. Três configurações à escolha:

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

Publish Build

Publica uma build empacotada como versão de playtest interna. Ela se torna baixável pela sua equipe a partir da página Games do cliente (papel playtester ou acesso à build concedido). O cliente escaneia Packages/{config}/, envia os arquivos (deduplicados do lado do servidor) e depois 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 todas as builds em curso: compilação e empacotamento. O botão indica quantas builds foram paradas (uma compilação automática iniciada em segundo plano pode ser contada junto).

Ações automáticas

Além dos botões, o cliente dispara certas ações Unreal por conta própria, 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 submete 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 início após um clone (projeto C++): geração dos arquivos de projeto e depois compilação, antes de poder abrir o editor.

Essas builds automáticas se serializam sobre o bloqueio do motor (Unreal Build Tool -WaitMutex): elas não se recusam entre si, elas se encadeiam. O botão Stop também as interrompe.