Abrir projetos do Unreal Engine no Visual Studio

O Visual Studio 2022 versão 17.12 fornece suporte direto para projetos do Mecanismo Unreal.

Anteriormente, você precisava gerar um projeto do Microsoft Visual Studio antes de trabalhar com um projeto do Unreal Engine no Visual Studio. Esse processo foi complicado. E sempre que um novo ativo era adicionado de dentro do Editor do Mecanismo Unreal ou por outro membro da equipe, o projeto do Visual Studio tinha que ser regenerado para permanecer em sincronia com o projeto do Mecanismo Unreal.

Agora, com suporte direto para arquivos de projeto do Unreal Engine (.uproject), você pode trabalhar diretamente com projetos do Unreal Engine de dentro do Visual Studio. Essa integração permite a edição perfeita, a depuração e o gerenciamento de arquivos de projeto sem o processo demorado de gerar e regenerar um arquivo de projeto do Visual Studio.

Pré-requisitos

O seguinte deve ser instalado para trabalhar com projetos do Unreal Engine no Visual Studio:

• Visual Studio versão 17.12 Versão Prévia 2 ou posterior.
• Unreal Engine versão 4.27 ou Unreal Engine versão 5 e posterior.
• Ferramentas do Visual Studio para o Mecanismo Unreal. Consulte Instalar as Ferramentas do Visual Studio para o Unreal Engine para obter instruções de instalação.
• Baixe o jogo de exemplo do Lyra. Consulte a seção Downloading the Lyra Starter Game em Lyra Sample Game para obter instruções de download. Se você adquiriu por meio da instalação do código-fonte do Unreal Engine, essa versão não contém os ativos necessários para compilar e executar o jogo. Use as instruções de download para obter tudo o que você precisa por meio do instalador Epic.

Configuração do Unreal Engine 5.3 ou anterior

Para versões do Unreal Engine antes da 5.4, siga estas etapas para habilitar a integração do Unreal Engine .uproject com o Visual Studio. Essas etapas funcionam se você instalou o Unreal Engine do Iniciador da Epic Games ou o criou a partir do código-fonte.

1. Baixe o patch específico para sua versão do Unreal Engine do repositório Unreal Engine GitHub. Por exemplo, UnrealBuildTool-5.2.patch atualiza o Unreal Engine para a versão 5.2.
2. Abra uma janela do PowerShell ou do prompt de comando e navegue até o diretório raiz em que o Unreal Engine está instalado. Você precisará da elevação do administrador para aplicar o patch se o Unreal Engine estiver instalado em um diretório protegido, como C:\Program Files\Epic Games\UE_5.3.
3. Aplique o patch com o comando git apply <path to the downloaded patch file>. Por exemplo: git apply C:\Users\someuser\Downloads\UnrealBuiltTool-5.3.patch. Se isso falhar, tente git apply -v --ignore-whitespace --ignore-space-change <path to the downloaded patch file>.

Abrir um projeto nativo do Unreal Engine no Visual Studio

Há duas maneiras de abrir um projeto nativo do Unreal Engine no Visual Studio:

• Arquivo>Abrir>Pasta que é usado quando há apenas um projeto (.uproject) na pasta.
• Arquivo>Abrir>Projeto do Unreal Engine para selecionar um arquivo .uproject específico para abrir quando houver vários arquivos de projeto do Unreal Engine em uma pasta.

Neste exemplo, usamos o projeto de jogo Lyra para demonstrar a abertura de um projeto nativo do Unreal Engine no Visual Studio.

1. No Visual Studio, abra o menu Arquivo e selecione Abrir>Abrir Pasta.

2. Navegue até o diretório em que o projeto do jogo Lyra (LyraStarterGame.uproject) está instalado e escolha Selecionar Pasta.

3. Depois que a pasta é selecionada, os arquivos do projeto aparecem no Gerenciador de Soluções e as mensagens aparecem na janela de Saída sobre a configuração do espaço de trabalho.

   

   Há uma mensagem no topo do editor de que outros sistemas de build estão desabilitados porque um projeto do Unreal Engine está aberto. A janela **Saída** mostra algumas das últimas mensagens sobre o workspace do projeto que está sendo configurado. À direita está o gerenciador de soluções e mostra as pastas e arquivos no exemplo do jogo Lyra, como Plataformas, Plug-ins, Origem e assim por diante.

Uma mensagem mostra que o suporte ao projeto do Mecanismo Unreal é ativado e que outros sistemas de build, como CMake e MSBUILD, estão desabilitados. Você pode ignorar essa mensagem clicando no X no canto da mensagem.

Exibir o projeto no Gerenciador de Soluções

A janela do Gerenciador de Soluções mostra muitos dos arquivos e pastas que fazem parte do projeto do Mecanismo Unreal, como as pastas Platforms, Pluginse Source. Você também pode ver o arquivo .uproject do Unreal Engine. A pasta Engine contém o diretório de fontes do Unreal Engine.

O Solution Explorer está filtrado para se concentrar no código-fonte. Por padrão, as pastas Content são filtradas, que contêm ativos binários, como texturas, modelos e assim por diante. Você pode abrir esses assets no Unreal Engine Editor. Em geral, os arquivos binários não são exibidos no Gerenciador de Soluções do Visual Studio.

Você não precisa regenerar o projeto para exibir ou editar novos ativos adicionados fora do Visual Studio.

Página de configuração do Unreal Engine

O Visual Studio fornece uma página de configuração de projeto do Unreal Engine. Esta página mostra o status dos recursos do Mecanismo Unreal e permite que você acesse mais recursos.

Para acessar esta página no menu principal do Visual Studio, escolha Project>Configurar Ferramentas para o Unreal Engine:

A página de configuração tem um indicador de status vermelho/verde e um botão de atualização para opções como Status Geral de Configuração, Status da Ferramenta de Build do Unreal, Alvos do Unreal Engine, Suporte ao Blueprint, Status da Ferramenta de Integração do Visual Studio e assim por diante.

Status da ferramenta de build do Unreal

Para garantir que você tenha a versão mais recente da Unreal Build Tool (UBT), selecione o ícone de atualização para Status da Unreal Build Tool.

Neste exemplo, aparece uma mensagem informando que a Ferramenta de Build do Unreal não está usando a versão mais recente disponível para o Gerador de Workspace. Escolha Atualizar para atualizar a Unreal Build Tool para a versão mais recente:

O Status da Ferramenta de Build do Unreal exibe a mensagem: a instalação atual da Ferramenta de Build do Unreal não está usando a versão mais recente disponível para o Gerador de Workspace. Agora você pode atualizá-lo para usar todos os recursos disponíveis que o Visual Studio tem a oferecer. Há um botão de atualização acima da mensagem.

Na janela Saída, as mensagens são exibidas ao preparar a Unreal Engine Build Tool. Uma mensagem informando que o Workspace está pronto será exibida, após a qual você poderá começar a adicionar e editar arquivos.

Alvos do Unreal Engine

Quando você cria um projeto no Unreal Engine, há diferentes configurações de build, chamadas alvos, que você pode escolher.

A opção Alvos do Unreal Engine é onde você gera esses alvos. Escolha o ícone de atualização para atualizar a lista de destinos do Mecanismo Unreal e abrir a janela em que você pode selecionar as configurações de destino que deseja criar:

Há três menus suspensos de opções de configuração e um botão **Adicionar** e um botão **Gerar Alvos**. O botão atualizar próximo à parte superior também está realçado.

Para obter mais informações sobre combinações de alvos, consulte a documentação do Unreal Engine Descrições da Configuração de Build.

Neste exemplo, LyraClient, DebugGame e Win64 são selecionados nas listas suspensas.

1. Escolha Adicionar para adicioná-los à lista de configurações a serem geradas.
2. Escolha Gerar Alvos para criar as configurações selecionadas para cada configuração cuja caixa esteja marcada.

Depois que os destinos forem gerados, você poderá selecioná-los conforme descrito em Escolha a configuração de build. Observe os erros na janela de saída quando você gera destinos porque algumas combinações podem não ter suporte.

Você pode remover destinos desmarcando os que não deseja e selecionando o botão Gerar Destinos. Quando você seleciona Gerar Destinos, os destinos que não estão selecionados são removidos, embora eles não desapareçam dessa lista até que você recarregue o projeto.

Editar propriedades de destino

Para editar as propriedades de destino do Mecanismo Unreal, clique com o botão direito do mouse no arquivo de destino em negrito no Gerenciador de Soluções e escolha Editar propriedades de destino do Mecanismo Unreal.

Por exemplo, se LyraEditor.Target.cs for o destino de inicialização (nesse caso, o nome dele está em negrito no Gerenciador de Soluções), clique com o botão direito do mouse nele e escolha Editar estas propriedades de destino do Unreal Engine. Isso abre o arquivo UETargetProperties.json no editor.

Um menu é exibido e, na parte inferior, está a opção de editar esse alvo do Unreal Engine. Selecionar essa opção abre UETargetProperties.json no editor.

Em seguida, você pode alterar as propriedades de destino, como argumentos de linha de comando.

Editar configurações do projeto

Para editar as configurações de projeto do Mecanismo Unreal, clique com o botão direito do mouse no arquivo .uproject no Gerenciador de Soluções e escolha Editar configurações de projeto do Mecanismo Unreal.

O arquivo ProjectSettings.json é aberto no editor. Em seguida, você pode alterar as configurações do projeto, como quais arquivos de projeto e arquivos de mecanismo excluir da exibição do Solution Explorer, quais caminhos de inclusão compartilhados excluir do IntelliSense e assim por diante. Você pode usar essas configurações para excluir arquivos que você não precisa para acelerar o IntelliSense.

Um menu é exibido e, na parte inferior, está a opção de editar as configurações de projeto do Mecanismo Unreal. Selecionar essa opção abre o arquivo '.uproject' no editor.

Escolher a configuração de build

Para escolher uma configuração de build, escolha o alvo desejado na lista suspensa de Configuração:

O menu suspenso de configuração contém os itens: DebugGame – Win64 e Desenvolvimento – Win64.

Se o destino que você deseja criar não estiver na lista, adicione-o conforme descrito em Destinos do Mecanismo Unreal.

Edição e depuração no Visual Studio

Você pode editar, compilar e depurar seu projeto do Unreal Engine no Visual Studio. Para saber como adicionar módulos, classes e plugins do Unreal Engine no Visual Studio, consulte Adicionar classes, módulos e plugins do Unreal Engine no Visual Studio.

Você pode definir pontos de interrupção em seu código e, em seguida, executar o jogo no Editor do Unreal Engine. Quando um ponto de interrupção é atingido, você pode depurar o código no Visual Studio.

Por padrão, o Visual Studio gera apenas um alvo: desenvolvimento – Win64. Este alvo é compilado e inicia o Unreal Editor com seu projeto de jogo carregado.

Se você abriu a pasta para o projeto de exemplo de jogo do Lyra no Visual Studio, experimente a depuração seguindo estas etapas:

1. No Visual Studio, abra LyraGameplayAbility_RangedWeapon.cpp. Pesquise esse arquivo no painel Pesquisa do Gerenciador de Soluções ou localize-o em Games>LyraStarterGame>Source>LyraGame>Weapons>LyraGameplayAbility_RangedWeapon.cpp.
2. Em LyraGameplayAbility_RangedWeapon.cpp, vá para a linha 477. Procure a função: void ULyraGameplayAbility_RangedWeapon::OnTargetDataReadyCallback.
3. Coloque um ponto de interrupção na função pressionando F9.
4. Execute o jogo de exemplo no Visual Studio escolhendo Depurar>Iniciar Depuração. Dê algum tempo ao Editor do Unreal Engine para carregar o jogo.
5. No Unreal Engine Editor, escolha o botão Jogar na barra de ferramentas (ou pressione Alt+p) para iniciar o jogo.
6. No jogo Lyra, use as teclas w, a, s, d para mover o jogador à esquerda até o portal de Eliminação . Posicione o jogador sobre o portal de entrada para carregar o jogo.
7. Depois que o jogo estiver em execução, clique com o botão do mouse para disparar e você verá o ponto de interrupção no Visual Studio:

Problemas e soluções comuns

• O mecanismo e o código do jogo devem estar na mesma unidade. Se não estiverem, confira O código-fonte do jogo e o código-fonte do mecanismo estão em unidades diferentes.
• Não há suporte para vários arquivos .uproject na mesma pasta. Para abrir um arquivo .uproject específico quando há vários arquivos de projeto na mesma pasta, use Arquivo>Abrir>Projeto do Unreal Engine.
• Se você abrir um projeto do Unreal Engine usando Arquivo>Abrir>Projeto do Unreal Engine, o projeto não aparecerá na lista Arquivo>Projetos e Soluções Recentes no Visual Studio. Se você abrir o projeto do Unreal Engine usando Arquivo>Abrir Pasta, o projeto do Unreal Engine aberto aparecerá na lista de projetos recém-abertos.
• Algumas extensões podem não funcionar com um projeto aberto como um projeto do Unreal Engine.
• A janela de propriedade está vazia para arquivos de origem. No momento, isso é intencional.
• Há um arquivo de solução do Visual Studio no modo de exibição de pasta. O Mecanismo Unreal gera esse arquivo, mas ele não é usado pelo Visual Studio e você pode ignorá-lo.

O código-fonte do jogo e o código-fonte do mecanismo estão em unidades diferentes

Se o código-fonte do Mecanismo Unreal e o código-fonte do jogo estiverem em unidades diferentes, um erro será exibido quando você abrir o projeto de código do jogo. Por exemplo: se o jogo estiver localizado em C:\Users\MyUser\MyGame, o Mecanismo Unreal deverá estar localizado em algum lugar na unidade C:\; caso contrário, o suporte ao projeto do Mecanismo Unreal no Visual Studio não está disponível:

Recomendamos uma das seguintes soluções:

Solução nº 1: mover o código-fonte do jogo e do mecanismo para a mesma unidade

A solução mais fácil é mover o projeto do jogo para a mesma unidade lógica em que o Unreal Engine reside usando o Windows File Explorer.

Se você estiver movendo o código-fonte do Unreal Engine que foi instalado via Epic Games Launcher, desinstale o mecanismo e reinstale-o no mesmo disco em que está o jogo. Dessa forma, os arquivos de configuração do mecanismo refletem o novo local.

Quando tiver o código-fonte do jogo e o código-fonte do mecanismo na mesma unidade, você poderá abrir o .uproject no Visual Studio.

Solução nº 2: criar um link simbólico para o Unreal Engine e alterar a propriedade de associação do mecanismo

Se não for viável mover o código-fonte do mecanismo e o código-fonte do jogo para a mesma unidade, você poderá criar um link simbólico para a origem do Unreal Engine e alterar a propriedade EngineAssociation no arquivo .uproject para corresponder.

Para este exemplo, suponha que o Unreal Engine está localizado em C:\Program Files\Epic Games\UE_5.4 e seu jogo está localizado em Q:\src\game.

1. Abra um prompt de comando (não uma janela do PowerShell).
2. Navegue até a unidade onde o código-fonte do jogo está localizada. Por exemplo, cd /d Q:\.
3. Crie um link simbólico que aponte para o Unreal Engine. O comando mklink usa um parâmetro de link que especifica o nome do link simbólico, que é como o local do diretório é exibido para o sistema de arquivos. O parâmetro de destino é aquele ao qual você está conectando. Por exemplo, mklink /d "Q:\UE-Link" "C:\Program Files\Epic Games\UE_5.4" cria um link simbólico chamado Q:\UE-Link que aponta para o diretório Unreal Engine na unidade C:.
4. Abra o arquivo .uproject do jogo e altere a propriedade EngineAssociation para ser a pasta symlink que você criou. Por exemplo, "EngineAssociation": "Q:\\UE-Link".

Agora, você pode abrir .uproject no Visual Studio porque o código-fonte do jogo e o código-fonte do mecanismo estão na mesma unidade. O symlink cuidará do redirecionamento das referências de arquivo para o mecanismo.

Solução nº 3: criar um link simbólico para o Mecanismo Unreal e alterar arquivos de configuração

Essa solução é frágil porque altera um arquivo de configuração e a alteração pode ser revertida na próxima vez que você atualizar o Unreal Engine.

Para este exemplo, suponha que o Mecanismo Unreal esteja localizado em C:\Program Files\Epic Games\UE_5.4 e seu jogo esteja localizado em Q:\src\Game

1. Abra um prompt de comando (não uma janela do PowerShell).
2. Navegue até a unidade onde o código-fonte do jogo está localizada. Por exemplo, cd /d Q:\.
3. Crie um link simbólico que aponte para o Unreal Engine. O comando mklink usa um parâmetro de link que especifica o nome do link simbólico, que é como o local do diretório é exibido para o sistema de arquivos. O parâmetro de destino é ao que você está vinculando. Por exemplo, mklink /d "Q:\UE-Link" "C:\Program Files\Epic Games\UE_5.4" cria um link simbólico chamado Q:\UE-Link que aponta para o diretório Unreal Engine na unidade C:.
4. Abra C:\ProgramData\Epic\UnrealEngineLauncher\LauncherInstalled.dat em um editor.
5. Substitua o valor de InstallLocation pelo caminho do symlink que você criou. Este exemplo é para UE 5.4 instalado na unidade C:, e o symlink está na unidade Q:.

Antes:

{
    "InstallationList": [
        {
            "InstallLocation": "C:\\Program Files\\Epic Games\\UE_5.3",
            ...
            "AppName": "UE_5.4"
        },
}

Depois:

{
    "InstallationList": [
        {
            "InstallLocation": "Q:\\UE-Link",
            ...
            "AppName": "UE_5.4"
        },
}

Agora, você pode abrir .uproject no Visual Studio porque o código-fonte do jogo e o código-fonte do mecanismo estão na mesma unidade. O symlink cuidará do redirecionamento das referências de arquivo para o mecanismo.

Conteúdo relacionado

Ferramentas do Visual Studio para Unreal Engine
Adicionar classes, módulos e plug-ins do Mecanismo Unreal no Visual Studio
Início Rápido: Ferramentas do Visual Studio para o Unreal Engine
Exibir Blueprints do Unreal Engine no Visual Studio
Ver o log do Unreal Engine no Visual Studio
Exibir macros do Unreal Engine no Visual Studio