Dokumentacja Steamworks
Jak debugować gry w systemie Windows na Steam Decku

Wprowadzenie

Wykonaj poniższe instrukcje, by dowiedzieć się, jak debugować pliki binarne swojej gry przeznaczonej na system Windows (działającej poprzez Protona) na zestawie deweloperskim Steam Deck. Podczas przesyłania gry do swojego zestawu deweloperskiego musisz załączyć biblioteki wykonawcze systemu Windows do swojej gry, a na twoim komputerze deweloperskim z systemem Windows musi być uruchomiony Visual Studio wraz z narzędziami zdalnego debugowania.
Ta funkcja jest nadal w fazie rozwoju. Prześlij nam wszelkie uwagi czy problemy na forum dla producentów tworzących na Steam Decka.
UWAGA: funkcje zdalnego debugowania są obsługiwane tylko w eksperymentalnym wydaniu Protona.

Konfiguracja

Be sure to see Jak przesyłać gry i uruchamiać je na Steam Decku to upload and run your game on your developer kit. Upewnij się, że dołączysz do niej biblioteki wykonawcze systemu Windows (szczegóły poniżej).

Dołączanie bibliotek wykonawczych systemu Windows:

Biblioteki wykonawcze systemu Windows nie są rozprowadzane wraz z Protonem. Musisz je dołączyć do swojej kompilacji samodzielnie. Zobacz https://docs.microsoft.com/en-us/cpp/windows/preparing-a-test-machine-to-run-a-debug-executable?view=msvc-160 celem uzyskania szczegółów. Dla programu Visual Studio powinna działać konfiguracja wdrażania debugowania. Właściwości projektu posiadają zaawansowaną opcję „Copy c++ Runtime to OutDir”, która może okazać się pomocna w przypadku projektów C++.

Narzędzia zdalnego debugowania programu Visual Studio w Protonie:

Narzędzia zdalnego debugowania programu Visual Studio nie są rozprowadzane wraz z Protonem. Gdy przesyłasz grę z zaznaczonym polem „Steam Play”, to narzędzie zestawu deweloperskiego skopiuje narzędzia zdalnego debugowania z twojego hosta deweloperskiego w systemie Windows na system zestawu deweloperskiego.

Obecnie zestaw deweloperski będzie szukał zainstalowanych narzędzi debugowania z programów Visual Studio 2019 i Visual Studio 2017. Aby te narzędzia były dostępne, podczas instalacji Visual Studio musisz załączyć pakiet roboczy programowania, np. „Programowanie aplikacji klasycznych w języku C++”.

VirtualBox_Win_10_05_08_2021_18_05_44.png

Użycie

Vulkan – przykłady

Projekt Vulkan Examples stanowi dobry punkt startowy, by przyzwyczaić się do zdalnego debugowania gier przesłanych na zestaw deweloperski Steam Deck.

Sklonuj projekt i zmień obecny katalog:
git clone --recursive https://gitlab.steamos.cloud/jupiter/vulkan-examples.git cd vulkan-examples

Projekt zawiera kilka różnych małych próbek Vulkana znajdujących się w katalogu „examples”. W tej dokumentacji skorzystamy z imgui w celach demonstracyjnych. Wygeneruj i skompiluj projekt:
cmake -G "Visual Studio 16 2019" -S . -Bbuild/windows cmake --build build/windows --config Debug --target imgui

Uwaga: proces kompilacji z użyciem Cmake pobiera dodatkowe zasoby poprzez uruchomienie niedużego skryptu; na twoim hoście z kompilacją będzie ci potrzebny Python.

Utworzy to katalog build/windows/bin/Debug zawierający plik wykonywalny imgui, wymagane biblioteki debugowania systemu Windows i zasoby danych.

W tym momencie możesz przesłać wynikowy katalog Debug.

Upewnij się, że zaznaczysz „This title requires Steam Play”, gdyż nie jest to natywna kompilacja Linuksa, oraz „Start Visual Studio C++ debugger service on launch”, by włączyć zdalnego debuggera.

Jeśli dołączenie po uruchomieniu twojej gry nie jest adekwatne do sytuacji i chcesz zdebugować uruchomienie oraz inicjalizację twojego tytułu, użyj opcji „Wait for a debug client to attach” i sprawdź sekcję dotyczącą wczesnego dołączenia (tzw. early attach) w tym dokumencie.

devkit-tool-remote-debug-20211207.png

Jeżeli przykładowo wybrana przez ciebie nazwa to vulkan_examples_debug, to po zakończeniu transferu w bibliotece Steam powinna się znaleźć nowa gra o nazwie Devkit Game: vulkan_examples_debug.

Uruchamiając grę, automatycznie uruchomi się również serwer msvsmon do zdalnego debugowania.

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

Teraz będziesz w stanie dołączyć debugger do uruchomionej gry.

W programie Visual Studio wciśnij Ctrl+Alt+P, by otworzyć Debugowanie > Dołącz do procesu. W polu „Adres docelowy połączenia” wpisz adres IP i port serwera msvsmon, a następnie wybierz proces imgui.exe.

Screenshot_2021-07-26_092207.png

Szczegółowe informacje krok po kroku znajdziesz również w dokumentacji debugowania firmy Microsoft.

Unreal Engine 4 – przykłady

Utwórz konto Epic Games, jeśli go jeszcze nie posiadasz, a następnie pobierz i zainstaluj Unreal Engine 4.

Wykorzystamy jeden z przykładowych projektów oferowanych przez Unreal Engine Editor. Utwórz nowy projekt i wybierz szablon „Puzzle”.

Screenshot_2021-07-16_072803.png

Wybierz nazwę i lokalizację projektu.

Screenshot_2021-07-15_082533.png

Przejdź do Edit -> Project settings -> Packaging i wybierz "Debug" lub "DebugGame" jako konfigurację kompilacji. Więcej informacji znajdziesz w oficjalnej dokumentacji. Jeśli zaznaczysz „Include Debug Files”, to pliki debugowania zostaną dołączone do pakietu gry.

Screenshot_2021-07-16_073647.png

Jeżeli nie jesteś w stanie skompilować natywnej kompilacji Linuksa, np. w przypadku, gdy twoja gra posiada zewnętrzne zależności nieobsługujące Linuksa, to możesz rozpocząć kompilowanie dla systemu Windows, używając File -> Package Project -> Windows (64-bit). Utworzy to kompilację w nowym katalogu o nazwie „WindowsNoEditor”.

Prześlij swoją skompilowaną grę, używając programu SteamOS Devkit Client.

Screenshot_2021-07-16_074524.png

W bibliotece Steam powinna się znajdować nowa gra o nazwie podobnej do Devkit Game: puzzle. Uruchamiając grę, automatycznie uruchomi się również serwer msvsmon do zdalnego debugowania.

W ramach ostatniego kroku możesz teraz dołączyć debugger do uruchomionej gry.

W programie Visual Studio wciśnij Ctrl+Alt+P, by otworzyć Debugowanie > Dołącz do procesu. W polu „Adres docelowy połączenia” wpisz adres IP i port serwera msvsmon, a następnie wybierz proces puzzle.exe.

Szczegółowe informacje krok po kroku znajdziesz również w dokumentacji debugowania firmy Microsoft.

Rozpoczęcie procesu zdalnego debugowania: obsługa „early attach”:


Usługa zdalnego debugowania może zostać skonfigurowana tak, by czekać na dołączenie przez użytkownika przed uruchomieniem tytułu. Umożliwia to ustawienie punktu przerwania w WinMain lub innym kodzie inicjalizacyjnym.

Wymaga to od ciebie wcześniejszej instalacji rozszerzenia firmy Microsoft w programie Visual Studio na twoim hoście deweloperskim: https://marketplace.visualstudio.com/items?itemName=vsdbgplat.MicrosoftChildProcessDebuggingPowerTool.

child-process-debug-extension.png

Po zainstalowaniu rozszerzenia włącz debugowanie procesów podrzędnych zgodnie z dokumentacją (Debug > Other Debug Targets > Child Process Debugging Settings).

Zaznacz „Wait for a debug client to attach” w swoim narzędziu devkitowym i prześlij swój tytuł.

Uruchom swój tytuł w normalny sposób.

Podczas dołączania do zdalnego procesu dołącz do steam.exe – gdy już to zrobisz, Proton natychmiast uruchomi twój tytuł jako proces podrzędny, a rozszerzenie uruchomi się i zacznie debugować twój tytuł od uruchomienia z włączonymi punktami przerwania.