Documentazione di Steamworks
Come effettuare il debug dei giochi per Windows su Steam Deck

Introduzione

Le seguenti istruzioni ti insegneranno come effettuare il debug dei binari Windows del tuo gioco (in esecuzione tramite Proton) su un dev kit di Steam Deck. Il runtime di debug di Windows dovrà essere associato al tuo gioco quando lo carichi sul dev kit, mentre Visual Studio e gli strumenti di debugging remoto dovranno essere in esecuzione sul tuo ambiente di sviluppo Windows.
Questa funzionalità è ancora in fase di sviluppo. Per qualsiasi commento o problema, ti invitiamo a usare il forum degli sviluppatori di Steam Deck.
NOTA: le funzionalità di debugging remoto sono compatibili esclusivamente con Proton Experimental.

Configurazione

Per caricare ed eseguire il tuo gioco sul dev kit, consulta il seguente articolo: Come caricare ed eseguire i giochi su Steam Deck. Assicurati di associare il runtime di debug di Windows (ulteriori dettagli in basso).

Associare il runtime di debug di Windows

Il runtime di debug di Windows non viene distribuito con Proton. Dovrai associare i file DLL del runtime di debug alla tua build. Per ulteriori dettagli, visita questo link: https://docs.microsoft.com/it-it/cpp/windows/preparing-a-test-machine-to-run-a-debug-executable. Per Visual Studio, dovrebbe funzionare una configurazione di distribuzione delle versioni di debug. Le proprietà dei progetti contengono l'opzione avanzata "Copiare il runtime C++ in OutDir" che può essere utile per i progetti in C++.

Strumenti di debugging remoto di Visual Studio su Proton

Gli strumenti di debugging remoto di Visual Studio non sono inclusi con Proton. Quando carichi un titolo per cui è stata selezionata la casella "Steam Play", lo strumento del dev kit copierà gli strumenti di debugging remoto dal tuo ambiente di sviluppo Windows al sistema dev kit.

Al momento, il dev kit cercherà gli strumenti di debugging installati da Visual Studio 2019 e Visual Studio 2017. Per avere a disposizione gli strumenti di debugging remoto, assicurati di includere un carico di lavoro al momento dell'installazione di Visual Studio (ad esempio: "Sviluppo di applicazioni desktop con C++").

VirtualBox_Win_10_05_08_2021_18_05_44.png

Utilizzo

Esempi su Vulkan

Il progetto Vulkan Examples è un buon punto di partenza per abituarsi ad effettuare il debugging remoto per i giochi caricati sul dev kit di Steam Deck.

Clona il progetto e cambia la directory corrente:
git clone --recursive git@gitlab.steamos.cloud:jupiter/vulkan-examples.git cd vulkan-examples

La directory "examples" del progetto contiene diversi piccoli esempi su Vulkan. Qui ci limiteremo a usare imgui. Genera e compila il progetto:
cmake -G "Visual Studio 16 2019" -S . -Bbuild/windows cmake --build build/windows --config Debug --target imgui

Nota: CMake scaricherà alcune risorse aggiuntive tramite un piccolo script, la cui esecuzione richiede l'installazione di Python sul computer della build.

Verrà creata la directory build/windows/bin/Debug contenente l'eseguibile imgui, i file DLL di Windows richiesti per il debug e tutti i dati.

A questo punto potrai caricare la directory "Debug" risultante.

Assicurati di selezionare "Questo titolo richiede Steam Play" (poiché non si tratta di una build nativa di Linux) e "Avvia il debugger di Visual Studio C++ all'avvio" per abilitare il debugger remoto.

Se non è sufficiente collegarsi quando il gioco è già in esecuzione e se desideri effettuare il debug delle fasi di avvio e inizializzazione del tuo titolo, usa "Wait for a debug client to attach" (Attendi il collegamento di un client di debug) e consulta la sezione relativa al collegamento anticipato (early attach) in questo documento.

devkit-tool-remote-debug-20211207.png

Una volta completato il trasferimento, se ad esempio hai scelto il nome vulkan_examples_debug, dovresti trovare un nuovo gioco chiamato Devkit Game: vulkan_examples_debug nella Libreria dei giochi di Steam.

Lanciando quel gioco, si avvierà automaticamente anche un server msvsmon per il debugging remoto.

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

Ora potrai finalmente collegare un debugger al gioco in esecuzione.

Su Visual Studio, premi Ctrl+Alt+P per aprire la finestra Esegui debug > Collega a processo. Imposta l'IP e la porta del server msvsmon come connessione di destinazione e poi seleziona il processo imgui.exe.

Screenshot_2021-07-26_092207.png

Per una lista di istruzioni dettagliate, consulta la documentazione di Microsoft sul debugging.

Esempi su Unreal Engine 4

Crea un account Epic Games, se non ne hai già uno, quindi scarica e installa Unreal Engine 4.

Come esempio, useremo uno dei progetti di prova offerti da Unreal Editor. Crea un nuovo progetto e seleziona il modello"Puzzle".

Screenshot_2021-07-16_072803.png

Seleziona un nome e un percorso per il progetto.

Screenshot_2021-07-15_082533.png

Vai su Edit->Project settings->Packaging e seleziona "Debug" o "DebugGame" come configurazione della build. Ulteriori informazioni sono disponibili nella documentazione ufficiale. Selezionando "Include Debug Files", i file di debug saranno inclusi nel pacchetto del gioco.

Screenshot_2021-07-16_073647.png

Se non riesci a compilare una build nativa su Linux (ad esempio se il tuo gioco ha delle dipendenze esterne che non supportano Linux), puoi creare una build Windows utilizzando File->Package Project->Windows (64-bit). In questo modo verrà creata una build in una nuova directory chiamata "WindowsNoEditor".

Carica il tuo gioco compilato usando lo strumento SteamOS Devkit Client.

Screenshot_2021-07-16_074524.png

Ora la tua Libreria di Steam dovrebbe contenere un nuovo titolo dal nome Devkit Game: puzzle (o simile). Lanciando il gioco, si avvierà automaticamente anche un server msvsmon per il debugging remoto.

Ora potrai collegare il debugger al gioco in esecuzione.

Su Visual Studio, premi Ctrl+Alt+P per aprire la finestra Esegui debug > Collega a processo. Imposta l'IP e la porta del server msvsmon come connessione di destinazione e poi seleziona il processo puzzle.exe.

Per una lista di istruzioni dettagliate, consulta la documentazione di Microsoft sul debugging.

Avvio del processo di debugging remoto: supporto "early attach" (collegamento anticipato):


Il servizio di debug remoto può essere configurato in modo da attendere che l'utente ne effettui il collegamento prima di avviare il titolo. È così possibile impostare un punto di interruzione in WinMain o altri codici di inizializzazione.

Per prima cosa, installa sul PC di sviluppo questa estensione di Microsoft per Visual Studio: https://marketplace.visualstudio.com/items?itemName=vsdbgplat.MicrosoftChildProcessDebuggingPowerTool

child-process-debug-extension.png

Una volta installata l'estensione, abilita il debug dei processi figlio come spiegato nella documentazione: Debug > Other Debug Targets > Child Process Debugging Settings.

Spunta la casella "Wait for a debug client to attach" (Attendi il collegamento di un client di debug) nel dev kit, dopodiché carica il tuo titolo.

Avvia il tuo titolo normalmente.

Quando ti colleghi al processo remoto, collegati a steam.exe. Una volta effettuato il collegamento, Proton avvierà immediatamente il tuo titolo come processo figlio e l'estensione si attiverà, iniziando il debug del tuo gioco dal momento dell'avvio con i punti di interruzione attivati.