Wiki

Plugin do Unreal Engine

Plugin uVersion para Unreal Engine: controle de versão nativo no editor, diff de Blueprint, auditoria Project Health e as duas regras que mais bloqueiam um envio.

Pré-requisitos

O projeto do Unreal deve estar DENTRO de um workspace uVersion Essa é a condição de ativação, e ela não está escrita em lugar nenhum do editor. O plugin procura uma pasta .uversion/ subindo a partir do projeto; se não encontra nenhuma, e se nenhum token de autenticação foi salvo antes, ele não se ativa de jeito nenhum e o Unreal fica sem controle de versão. Não é uma falha: é o que o impede de se impor nos seus projetos que não são versionados com uVersion. Abra o projeto a partir da pasta clonada pelo cliente desktop, não a partir de uma cópia colocada em outro lugar.

O cliente desktop é obrigatório na prática Um servidor uVersion é autoassinado por padrão. O editor do Unreal, por sua vez, não sabe o que fazer com um certificado autoassinado: ele não tem um repositório de impressões digitais e ninguém pode confirmar uma para ele. Resultado: em um servidor HTTPS, uma conexão direta a partir do Unreal falha no TLS, e o editor exibe uma notificação pedindo para iniciar o cliente desktop. O formulário de conexão existe, sim, na janela Revision Control Login, mas ele não passa desse muro: preenchê-lo contra um servidor autoassinado não leva a lugar nenhum. Só um arranjo funciona: o cliente desktop está rodando, você está conectado nele e o plugin passa por ele. Melhor saber disso logo do que perder uma hora com isso.

Instalação

O plugin uVersion é distribuído como binário pré-compilado, gerenciado pelo cliente desktop. Nada de compilar por sua conta, nada de arquivos de código para manipular. Ele nunca é versionado: não chega com o repositório e não deve ser enviado para dentro dele. Cada máquina instala o binário correspondente à SUA versão do Unreal e ao SEU sistema.

Versões do Unreal suportadas: 5.6 e superiores.

1. Abrir o workspace no cliente desktop

Instale o cliente desktop do uVersion, faça login e abra em seguida o workspace que contém o projeto do Unreal. Tudo acontece a partir do cliente: não há nenhum arquivo compactado para baixar, nem para descompactar no projeto manualmente.

2. Deixar o cliente detectar o projeto

O cliente procura seu .uproject (o arquivo que descreve um projeto do Unreal) sob a raiz do workspace, desde que não esteja enterrado a mais de três níveis. Assim que o encontra, uma barra Unreal aparece no topo da aba do workspace, e ele coloca o plugin correspondente à sua versão do Unreal em Plugins/uVersion/. O selo à esquerda traz o estado do plugin e seu número de versão: é ali também que as atualizações são lidas.

A barra Unreal do cliente desktop: à esquerda o selo verde Plugin 1.0.5, depois os botões Open Editor, Compile, Package, Publish Build, Sync e Status.

3. Abrir o projeto no Unreal

O plugin fica ativo imediatamente. Nada a marcar na janela Plugins do editor, nada a reiniciar: se estava faltando, é porque o cliente ainda não o colocou, não que ele ainda precise ser ativado.

Mais tarde: as atualizações

O cliente desktop verifica novas versões ao abrir o projeto e periodicamente depois. Atenção, a verificação automática não faz a mesma coisa nos dois casos:

Plugin ausente: ele é instalado sem perguntar nada a você. É o que torna a primeira inicialização transparente.
Plugin já presente, mas desatualizado (nova versão, ou mudança de versão do Unreal): o cliente apenas avisa você. Ele nunca substitui sozinho um plugin instalado. O selo do painel do Unreal passa então para Update ready.

Para aplicar a atualização: feche o editor do Unreal e clique no selo. Um plugin carregado não pode ser substituído no disco; se o editor ainda estiver aberto, o selo exibe Restart UE.

Primeira conexão

No caso normal, não há nada a conectar. O plugin se seleciona sozinho como provedor de controle de versão assim que detecta um workspace uVersion em torno do projeto, ou um token já salvo. Suas credenciais são retomadas do cliente desktop, sem redigitar. Basta abrir o projeto.

As três etapas abaixo só servem se essa seleção automática não tiver acontecido.

1. Abrir o menu Revision Control

Ele fica no canto inferior direito da barra de status do editor, não nos menus de cima. Ele abre para cima e traz as ações do Unreal, entre elas Submit Content, mais uma seção uVersion com a nossa entrada Audit Project (Project Health). Escolha Connect to Revision Control.

2. Escolher uVersion na lista Provider

A janela Revision Control Login se abre. Abra Provider e escolha uVersion. Quando o workspace é reconhecido, a janela anuncia isso ela mesma em verde (Automatically configured from workspace) e os campos Workspace, Server URL e Username já estão preenchidos: não há nada a digitar.

A janela Revision Control Login do Unreal: a lista Provider aberta com uVersion selecionado, a mensagem verde de configuração automática e o botão Accept Settings.

3. Validar com Accept Settings

O botão Accept Settings, no rodapé da janela, aplica a escolha e fecha a janela. A barra de status exibe então Connected to seguido do nome do repositório e do seu nome de usuário. A escolha é memorizada: as próximas aberturas do projeto não passarão mais por aqui.

Reservar um asset e depois enviá-lo

O percurso completo a partir do editor, sobre um arquivo de conteúdo. O código, por sua vez, nunca parte daqui: veja O código passa pelo cliente desktop.

1. Olhar o estado do asset antes de começar

Cada miniatura do Content Browser traz um selo que diz em que pé está o asset: reservado por você, reservado por outra pessoa, ou desatualizado em relação ao servidor. A dica de ferramenta dá a frase completa, por exemplo File is out of date, sync to get the latest version. Nesse caso, sincronize primeiro (clique com o botão direito, Revision Control, Sync): começar a trabalhar sobre uma versão desatualizada é preparar um conflito.

Uma miniatura de asset do Content Browser com um selo amarelo, e sua dica de ferramenta indicando que o arquivo está desatualizado e precisa ser sincronizado.

2. Reservar o asset

Clique com o botão direito no asset, submenu Revision Control, depois Check Out. Está tudo lá: Sync, Check Out, Check In, History, Diff Against Depot, Revert, como com qualquer outro provedor do Unreal. Os artistas não têm nada de novo para aprender.

Na prática, muitas vezes você não terá nada a fazer: assim que modifica um asset, o plugin aplica o lock do lado do servidor sozinho, sem checkout manual.

O Content Browser do Unreal: clique com o botão direito em um asset, submenu Revision Control com Sync, Check Out, Mark For Add, Check In, History, Diff Against Depot e Revert, e os ícones de estado nas miniaturas.

3. Comparar antes de enviar

Diff Against Depot abre a ferramenta de comparação visual padrão do editor, inclusive sobre um Blueprint: as duas revisões são exibidas lado a lado, e os nós adicionados, removidos ou modificados ficam contornados. Funciona em qualquer commit do histórico, a partir de History.

A janela Blueprint Diff: duas revisões de um mesmo Blueprint lado a lado, os nós adicionados contornados em verde.

4. Enviar

Clique com o botão direito, Revision Control, Check In sobre a seleção, ou Submit Content no menu da barra de status para enviar tudo de uma vez. A janela lista os arquivos envolvidos, inclusive as exclusões, e exige uma descrição. No momento do envio, o plugin limpa os redirectors deixados pelas suas renomeações e executa as regras de validação ativas: uma regra em error interrompe o envio e nomeia os arquivos culpados.

A janela de envio do Unreal: a lista de arquivos a enviar com suas caixas marcadas, o campo de descrição da mudança e o botão Submit.

O que o plugin faz no Unreal

Project Health: auditar o projeto

O menu Revision Control da barra de status contém uma entrada Audit Project (Project Health). Ela percorre o registro de assets do projeto sem carregar um único asset, e produz um relatório de saúde: nomenclatura, estrutura de pastas, dependências, conteúdo órfão, custos. Funciona offline (o relatório é escrito em Saved/uVersionAudit) e o envia ao servidor quando você está conectado, onde ele alimenta a aba Project Health do cliente desktop.

Limpeza de redirectors

Quando você renomeia ou move um asset, o Unreal deixa para trás um redirector: um pequeno arquivo de encaminhamento que aponta o caminho antigo para o novo, para que os assets que referenciavam o nome antigo continuem funcionando. Eles se acumulam rápido e acabam tornando a árvore ilegível. O plugin os detecta e os limpa no momento do checkin, atualizando as referências em todos os assets afetados.

Validação antes do checkin

O plugin sabe executar uma série de verificações nos arquivos enviados: compilação de Blueprints, convenção de nomenclatura, tamanho das texturas, configurações de importação, dependências ausentes, dependências circulares, assets órfãos, duplicatas, complexidade dos materiais. Nove regras no total. Uma regra em error bloqueia o envio, uma regra em warning o autoriza após confirmação.

As nove regras são entregues desativadas Em um repositório novo, todas são criadas no estado inativo: nenhuma verificação roda enquanto um administrador não as tiver ativado, uma a uma, a partir da aba Rules do painel Admin. Se você esperava que um envio fosse recusado e ele passa sem dizer nada, comece verificando ali.

Reconciliação na inicialização

Ao abrir o projeto, o plugin compara o estado dos seus assets com o servidor. Ele percorre Content/ e os Content/ dos plugins do projeto, e reserva automaticamente todo asset encontrado modificável no disco que ainda não estava. A intenção é protegê-lo: um arquivo que você tinha começado a modificar não pode ser fisgado por um colega entre duas sessões.

Consequência a conhecer: você pode deter locks sem saber Essa reserva automática é silenciosa, e um lock uVersion nunca expira: ele se mantém até ser devolvido explicitamente, por um checkin, por um revert, ou pelo desbloqueio forçado de um administrador. Nenhum prazo o libera. Abrir o editor em um projeto onde estão largados alguns arquivos modificáveis basta, portanto, para bloquear esses arquivos para toda a equipe, sem que nada sinalize isso a você. Adquira o hábito de olhar a aba Pending do cliente desktop, a lista My Pending Changes, e devolver o que você não está trabalhando.

O código passa pelo cliente desktop, não pelo Unreal

O plugin recusa o envio dos arquivos de código: .cpp, .h, .hpp, .c e .cs. A tentativa para em uma janela bloqueante que nomeia os arquivos culpados. Não é um defeito: o cliente desktop compila antes de enviar e publica os binários de editor que seus colegas recuperam no sync. Um commit de código enviado a partir do editor passaria ao largo dos dois, e suspenderia a distribuição de binários para toda a equipe.

Então envie seu código a partir do cliente desktop. Os arquivos de conteúdo, por sua vez, continuam perfeitamente livres para partir a partir do Unreal.

A cilada: um único arquivo de código reservado também bloqueia seus envios de CONTEÚDO A regra não para nos arquivos que você envia. Enquanto você detiver a reserva de um arquivo de código, mesmo que um só, mesmo sem tê-lo tocado, mesmo ausente do seu envio, todo checkin a partir do Unreal é recusado, inclusive um envio de .uasset puro. A mensagem diz para você enviar seu código a partir do cliente desktop primeiro.

É o bloqueio mais comum, e cai de bom grado sobre alguém que não escreve código: basta que um arquivo-fonte tenha sido tornado modificável no disco para que a reconciliação na inicialização o tenha reservado sozinha. A razão é real: um asset salvo contra código não enviado quebra todos os que o sincronizam, já que seus binários não têm o código do qual ele depende.

O desbloqueio: abra a aba Pending do cliente desktop, a lista My Pending Changes, localize os arquivos de código, e faça um Checkin Selected se você os modificou, ou um Revert se você não os tocou. Seu envio de conteúdo volta a sair em seguida normalmente. Pode levar alguns segundos, o tempo de o editor atualizar a sua visão dos locks.

A aba Pending do cliente desktop: a lista My Pending Changes onde figuram dois arquivos .h ao lado de um .uasset, cada um com seu botão Revert, e mais abaixo a seção Other Users' Locks.

Problemas comuns

Nenhum menu uVersion: o editor ignora o controle de versão

O projeto provavelmente não está em um workspace uVersion. Verifique se existe uma pasta .uversion/ na raiz da pasta clonada, e se você está mesmo abrindo o projeto a partir dessa pasta e não a partir de uma cópia colocada em outro lugar.

« Failed to connect to source control »

Verifique se o cliente desktop está rodando e se você está conectado nele: é ele que detém suas credenciais e que sabe dialogar com um servidor autoassinado. Se a conta proprietária do workspace não estiver conectada no cliente, o plugin recusa trabalhar sob outra identidade, e isso é proposital.

Um envio é recusado embora eu não tenha tocado em nenhum código

Você detém a reserva de um arquivo de código. Veja O código passa pelo cliente desktop.

Quero um asset que outra pessoa bloqueou

Isso não se pede a partir do Unreal: o plugin não tem função de pedido de liberação. Passe pelo cliente desktop, aba Pending, seção Other Users' Locks, botão Request Release na linha do arquivo. O detentor recebe um pedido em forma de cartão no board Production.

O plugin não atualiza

É o comportamento esperado: a verificação automática instala um plugin ausente, mas se limita a sinalizar uma atualização. Feche o editor do Unreal (um plugin carregado não pode ser substituído), depois clique no selo Update ready na barra Unreal do cliente desktop para aplicá-la.

Uma regra de validação nunca dispara

As nove regras são entregues desativadas. Um administrador deve ativá-las por projeto a partir da aba Rules do painel Admin.