Documentação do Steamworks
Como depurar jogos para Windows no Steam Deck

Visão geral

Siga as instruções abaixo para saber como depurar os binários do seu jogo para Windows (executados via Proton) em um kit de deseenvolvimento do Steam Deck. Você precisará empacotar as bibliotecas de tempo de execução de depuração para Windows com o jogo ao enviá-lo para o kit de desenvolvimento e ter tanto o Visual Studio quanto as ferramentas de depuração remota em execução na sua máquina de desenvolvimento com Windows.
Este recurso ainda está em desenvolvimento. Deixe comentários ou relate problemas encontrados no fórum do Steam Deck para
desenvolvedores
.
OBSERVAÇÃO: os recursos de depuração remota são apenas compatíveis com o "Proton Experimental".

Configuração

Be sure to see Envio e execução de jogos no Steam Deck to upload and run your game on your developer kit. Não se esqueça de empacotar as bibliotecas de tempo de execução de depuração para Windows (detalhes abaixo).

Empacotamento das bibliotecas de tempo de execução de depuração para Windows:

As bibliotecas de tempo de execução de depuração para Windows não são distribuídas com o Proton. Você precisará empacotar tais DLLs com a versão compilada do jogo. Consulte https://docs.microsoft.com/pt-br/cpp/windows/preparing-a-test-machine-to-run-a-debug-executable para detalhes. Para o Visual Studio, uma configuração de implantação de depuração deve funcionar. Nas propriedades do projeto, seção "Avançado", há a opção "Copiar o Runtime do C++ para OutDir", que pode ser útil para projetos em C++.

Ferramentas de depuração remota do Visual Studio no Proton:

As ferramentas de depuração remota do Visual Studio não são distribuídas com o Proton. Ao enviar um título com o botão "Steam Play" assinalado, a ferramenta de kit de desenvolvimento copiará as ferramentas de depuração remota da máquina de desenvolvimento com Windows para o sistema do kit de desenvolvimento.

Atualmente, o kit de desenvolvimento buscará as ferramentas de depuração instaladas do Visual Studio 2019 e Visual Studio 2017. Para que as ferramentas de depuração remotas sejam disponibilizadas, ao instalar o Visual Studio, não deixe de incluir uma carga de trabalho de desenvolvimento, como "Desenvolvimento para desktop com C++".

VirtualBox_Win_10_05_08_2021_18_05_44.png

Uso

Exemplos com Vulkan

O projeto Vulkan Examples é um bom ponto de partida para se acostumar a depurar remotamente jogos enviados para o kit de desenvolvimento do Steam Deck.

Clone o projeto e altere o diretório atual:
git clone --recursive https://gitlab.steamos.cloud/jupiter/vulkan-examples.git cd vulkan-examples

O diretório "examples" do projeto contém várias amostras diferentes que usam Vulkan. Nesta documentação, usaremos a amostra imgui. Gere e compile o projeto:
cmake -G "Visual Studio 16 2019" -S . -Bbuild/windows cmake --build build/windows --config Debug --target imgui

Aviso: a compilação com cmake baixará recursos adicionais por meio da execução de um pequeno script, que exige que o Python esteja instalado na máquina usada para compilação.

Isso criará um diretório build/windows/bin/Debug que contém o executável imgui, as DLLs de depuração para Windows necessárias e os recursos de dados.

A partir desse ponto, você pode enviar o diretório "Debug" resultante.

Não se esqueça de assinalar a opção "This title requires Steam Play" (Este título requer Steam Play), já que a versão compilada não é nativa para Linux, e também selecionar "Start Visual Studio C++ debugger service on launch" (Iniciar o depurador do Visual Studio C++ na inicialização) para ativar um depurador remoto.

Se não for adequado anexar o depurador após o jogo já estar em execução e você deseja depurar a inicialização do título, use a opção "Wait for a debug client to attach" (Espere por um cliente de depuração para anexar) e consulte a seção "Anexação antecipada" neste documento.

devkit-tool-remote-debug-20211207.png

Quando a transferência for concluída, se o nome for, por exemplo, vulkan_examples_debug, você verá um novo jogo chamado Devkit Game: vulkan_examples_debug na Biblioteca Steam.

Ao iniciar o jogo, um servidor msvsmon para depuração remota será automaticamente iniciado em conjunto.

Screenshot_from_2021-07-14_10-05-21.png

O último passo é anexar um depurador ao jogo em execução.

No Visual Studio, pressione Ctrl+Alt+P ou selecione a opção Depurar > Anexar ao Processo. Em "Destino da conexão", defina o endereço IP e a porta do servidor msvsmon, e selecione o processo imgui.exe.

Screenshot_2021-07-26_092207.png

Para ver um guia passo a passo detalhado, consulte a documentação sobre depuração da Microsoft.

Exemplos com Unreal Engine 4

Crie uma conta da Epic Games, se ainda não tiver uma, e então baixe e instale a Unreal Engine 4.

Como exemplo, usaremos um dos projetos de amostra oferecidos pelo editor da Unreal Engine. Crie um novo projeto e use o modelo "Puzzle" (Quebra-Cabeça).

Screenshot_2021-07-16_072803.png

Dê um nome ao projeto e escolha onde ele será salvo.

Screenshot_2021-07-15_082533.png

Abra o menu "Edit" -> "Project settings" -> "Packaging" ("Editar" -> "Configurações do Projeto" -> "Empacotamento") e, na seção "Project" (Projeto), escolha "Debug" "DebugGame" como a "Build Configuration" (Configuração de compilação). Mais informações estão disponíveis na documentação oficial (em inglês). Ao assinalar a opção "Include Debug Files", (Incluir arquivos de depuração), os arquivos de depuração serão incluídos no jogo empacotado.

Screenshot_2021-07-16_073647.png

Caso não seja possível gerar uma versão nativa para Linux (ex.: o jogo tem dependências externas sem versão para Linux), gere uma versão para Windows pelo menu "File" -> "Package Project" -> "Windows (64-bit)" ("Arquivo" -> "Empacotar projeto" -> "Windows (64-bit)"). Isso gerará uma versão do jogo em um novo diretório, chamado "WindowsNoEditor".

Envie o jogo compilado usando o SteamOS Devkit Client.

Screenshot_2021-07-16_074524.png

Deve aparecer um novo jogo na Biblioteca Steam com um nome parecido com Devkit Game: puzzle. Ao iniciar o jogo, um servidor msvsmon para depuração remota será automaticamente iniciado em conjunto.

O último passo é anexar um depurador ao jogo em execução.

No Visual Studio, pressione Ctrl+Alt+P ou selecione a opção Depurar > Anexar ao Processo. Em "Destino da conexão", defina o endereço IP e a porta do servidor msvsmon, e selecione o processo puzzle.exe.

Para ver um guia passo a passo detalhado, consulte a documentação sobre depuração da Microsoft.

Início do processo de depuração remota: uso de "anexação antecipada":


O serviço de depuração remota pode ser configurado para esperar que o usuário realize a anexação do depurador antes de iniciar o título. Isso permite que você defina um ponto de parada no WinMain ou em outro código de inicialização.

This requires that you first install a Microsoft extension in Visual Studio on your development host: https://marketplace.visualstudio.com/items?itemName=vsdbgplat.MicrosoftChildProcessDebuggingPowerTool

child-process-debug-extension.png

Once the extension is installed, enable child process debugging per the documentation (Debug > Other Debug Targets > Child Process Debugging Settings)

Assinale a opção "Wait for a debug client to attach" (Aguardar a anexação de um cliente de depuração) na ferramenta do kit de desenvolvimento e envie o título para o Steam Deck.

Inicie o seu título normalmente.

Na lista de processos remotos para anexar, escolha steam.exe. Uma vez anexado, o Proton imediatamente iniciará o título como um processo secundário, a extensão será iniciada e começará a depurar o seu título desde a sua inicialização, com os seus pontos de parada ativados.