Unreal Engine 4.10 + Git LFS

unreal_git

Em tempos de inscrição para a GDS Summer Project 2016, bastante gente pareceu se interessar pelo uso da Unreal Engine. É por isso que esse guia existe, pra mostrar como fazer o versionamento do projeto utilizando o velho amigo Git, com a extensão LFS para o armazenamento de arquivos grandes.

A leitura talvez tenha ficado um pouco pesada, mas com sorte vocês só vão precisar seguir esse tutorial uma vez 🙂

Todos os membros da equipe devem

  • Instalar o git (https://git-scm.com/downloads)
    • Recomendo instalar o git bash com o terminal emulado, e não usando o cmd do Windows.
  • Instalar o git-lfs (https://github.com/github/git-lfs/releases/tag/v1.1.0)
    • O instalador do git-lfs não funciona muito bem. O destino da instalação é apenas o local do uninstaller, e o executável git-lfs.exe sempre vai ser colocado no desktop. Esse arquivo deve ser movido para o mesmo diretório onde o Git foi instalado.
    • Abra o git bash (instalado junto com o git) e digite ‘git lfs install‘ para concluir a instalação

 

Apenas um membro da equipe (preferencialmente o líder) deve

    • Criar um repositório para o projeto na nuvem. Considerações:
      • Quem quiser utilizar um servidor próprio, à vontade
      • GitHub permite apenas 2GB por repositório, pode ser muito pouco
      • GitLab permite até 10GB (https://gitlab.com)
    • Criar o projeto na Unreal
    • Abre o git bash na pasta raíz do projeto e digita
      • git init
      • git remote add origin https://gitlab.com/user/project.git
        Lembrando que esse último comando deve ser alterado com o endereço do repositório criado
    • No diretório raíz do projeto, criar um arquivo de texto chamado .gitignore (sem extensão) e adicione o seguinte conteúdo:
      /Binaries
      /DerivedDataCache
      /Intermediate
      /Saved
      *.sln
      *.sdf
      *.suo
      *.opensdf
      *.opendb

 

  • Com o git bash na pasta do projeto, digite
    • git add .
    • git commit -m "First commit or something else"
    • git push origin master
  • Esse último comando vai demorar um pouco… Ele está enviando para o servidor tudo o que não foi incluído no .gitignore e o upload normalmente é lento.
  • Agora dentro da Unreal, com o projeto aberto, no painel no topo da viewport existe um botão de Source Control. Clica nele, e seleciona “Add source control” e depois, “Git”. Ele proavelmente vai perguntar qual o diretório de instalação do git. Se for o caso, basta informar o caminho completo para o arquivo git.exe (é o mesmo lugar onde o git-lfs.exe foi colocado)

 

Os demais membros da equipe devem baixar o projeto da nuvem através de clone ou pull.

  • Clone: esse comando cria automaticamente uma nova pasta no diretório atual para salvar o projeto
    • git clone https://gitlab.com/user/project.git
  • Pull: esse comando copia os arquivos diretamente para o diretório atual
    • git remote add origin https://gitlab.com/user/project.git
    • git pull origin master

Se o projeto for um projeto C++ (e não Blueprint, é uma escolha feita na criação do projeto na Unreal), após baixar o projeto é necessário encontrar o arquivo .uproject, clicar com o botão direito e selecionar “Generate Visual Studio project files“.

O projeto não vai aparecer automaticamente na lista de projetos da Unreal. É necessário abrir a Engine e selecionar a opção “Browse” e selecionar o arquivo .uproject (a Unreal precisa compilar tudo de binário que não entrou para o git – isso pode demorar).

 

Ativando cache de credenciais

Para cada arquivo adicionado no LFS, você vai precisar digitar seu usuário e senha do git. Para evitar isso, é possível utilizar o wincred:

  • git config --global credential.helper wincred

Após a execução deste comando, o git vai pedir seu usuário e senha no próximo uso, mas o wincred vai salvar os seus dados e autorizar os comandos do git automaticamente.

Para cancelar o wincred, basta executar o seguinte comando:

  • git config --global credential.helper unset

 

Adicionando arquivos ao Git LFS

O Git LFS foi criado para fazer o armazenamento de arquivos binários grandes, caso em que o Git “regular” deixa a desejar. Bons arquivos a serem adicionados em LFS são texturas, meshes, áudio, arquivos comprimidos, etc. Talvez vocês achem que animações são bons candidatos a serem incluídos no LFS, mas na verdade arquivos de animação são bastante leves, e podem ficar no Git convencional.

  • É possível incluir arquivos no Git LFS por nome do arquivo, por extensão ou por diretório.
    • git lfs track "build.zip"
    • git lfs track "*.psd"
    • git lfs track "Assets/Textures/*"
      • Não inclui sub-diretórios automaticamente
  • Além do comando exemplificado, também é possível especificar esses arquivos editando diretamente o arquivo .gitattributes
  • Para listar os arquivos em LFS:
    • git lfs ls-files

 

Problemas com a Unreal

Todos os arquivos criados pela Unreal são binários com a extensão .uasset. O problema é que alguns arquivos UASSET são grandes, e outros são pequenos. Não podemos simplesmente adicionar “*.uasset” ao LFS, pois isso seria ineficiente. Infelizmente, não existe regra que diga “isso vai pra LFS, isso vai pra Git comum”; é preciso escolher para cada caso. Os melhores candidatos a entrarem para o LFS são os arquivos grandes que sofrem muitas alterações.

Recomendações:

  • git lfs track "*.umap"
    • Arquivos que guardam informações sobre o level criado (potencialmente pesado porque inclui informação de iluminação)
  • git lfs track Content/StarterContent/*/*.uasset
  • git lfs track Content/StarterContent/*/*/*.uasset
    • Esses últimos se aplicam só para quem criou o projeto com Starter Content (provavelmente a maioria dos casos)
    • Como o ‘git lfs track’ não aceita recursão em subdiretórios, cada nível de subdiretórios deve estar incluído no comando (por isso aqueles “/*/*” nos exemplos)

Uma opção é criar um diretório para manter os assets que se enquadram com o LFS e adicionar esse diretório, para automatizar a inclusão de novos arquivos.

 

Conflitos

O Git LFS não possui nenhuma ferramenta para resolução de conflitos. Quando ocorrer um conflito, a única coisa que se pode fazer é escolher um dos arquivos (“mine” (local) ou “theirs” (servidor)) para ser mantido, descartando alterações feitas no outro. Isso pode ser um problema quando alterarmos mapas, por exemplo. É necessário manter uma boa organização entre os desenvolvedores para evitar conflitos.

Recomendações:

  • Cada desenvolvedor criar um mapa próprio para teste. Assim, cada um faz os testes isoladamente, e evitando conflitos. Os mapas oficiais do jogo devem ficar separados destes, e apenas manipulados pelo(s) level designer(s);
  • Utilizar um modelo de branching que promova o isolamento de alterações

 

Bônus: Branching

Mesmo sabendo usar o git, às vezes a gente não sabe como aproveitar tudo o que ele tem pra oferecer. Aproveitando que estamos falando do assunto, vamos apresentar o Gitflow Workflow. Esse modelo de branching foi criado especificamente para projetos grandes com múltiplos desenvolvedores.

O modelo se utiliza de uma mistura de branches permanentes e temporários, mantendo o repositório sempre limpo e organizado. Além disso, o tutorial é bem explicado e cheio de imagens que ilustram muito bem os conceitos.