Steamworks Belgeleri
Steam Deck'te Windows oyunlarında hata ayıklamak

Genel Bakış

Steam Deck geliştirici kitinde oyununuzun Windows ikili dosyalarında (Proton üzerinden çalışan) nasıl hata ayıklayabileceğinizi öğrenmek için aşağıdaki talimatları izleyin. Oyunu geliştirici kitinize yüklerken Windows hata ayıklama runtime'ıyla (çalışma zamanı) bir araya getirmeniz gereklidir. Ayrıca Windows geliştirme kutunuzda Visual Studio ve uzaktan hata ayıklama araçları çalışıyor olmalıdır.
Bu özellik üzerinde hâlâ çalışılıyor. Geri bildirimlerinizi ve sorunlarınızı lütfen Steam Deck geliştirici forumlarına yazın.
NOT: Uzaktan hata ayıklama özellikleri sadece Proton Experimental'a özeldir.

Kurulum

Oyununuzu geliştirici kitinize nasıl yükleyip çalıştırabileceğinizi öğrenmek için steamdeck/devkits/loadgames belgelendirmesini okuduğunuzdan emin olun. Windows hata ayıklama runtime'ıyla bir araya getirdiğinizden emin olun (detaylar aşağıda).

Windows hata ayıklama runtime'ıyla oyunu bir araya getirmek:

Windows hata ayıklama runtime'ı Proton ile dağıtılmaz. Hata ayıklama runtime'ına ait DLL dosyalarını derlemenizle bir araya getirmeniz gereklidir. Detaylar için https://docs.microsoft.com/en-us/cpp/windows/preparing-a-test-machine-to-run-a-debug-executable adresini ziyaret edin. Visual Studio için hata ayıklama dağıtımı yapılandırması işe yarayacaktır. Proje özelliklerinde C++ projeleri için işe yarar olabilecek "Copy c++ Runtime to OutDir" adlı gelişmiş bir seçenek yer almaktadır.

Proton'daki Visual Studio uzaktan hata ayıklama araçları:

Visual Studio'nun uzaktan hata ayıklama araçları Proton ile dağıtılmaz. Steam Play butonu işaretli olan bir ürünü yüklediğinizde geliştirici kiti, uzaktan hata ayıklama araçlarını Windows geliştirme ana bilgisayarınızdan geliştirici kiti sistemine yükler.

An itibarıyla geliştirici kiti, Visual Studio 2019 ve Visual Studio 2017 sürümlerine ait yüklü hata ayıklama araçlarını arar. Uzaktan hata ayıklama araçlarını kullanabilmek için, Visual Studio'yu yüklerken "C++ ile masaüstü geliştirme" gibi bir geliştirme iş yükünü dâhil ettiğinizden emin olun.

VirtualBox_Win_10_05_08_2021_18_05_44.png

Kullanım

Vulkan Örnekleri

Vulkan Örnekler projesi, Steam Deck geliştirici kitine yüklenen oyunlarda uzaktan hata ayıklama yapmaya alışmak için iyi bir başlangıç noktasıdır.

Projeyi klonlayın ve mevcut dizini şu şekilde değiştirin:
git clone --recursive git@gitlab.steamos.cloud:jupiter/vulkan-examples.git cd vulkan-examples

Proje, örnekler dizininde bulunan birkaç farklı küçük Vulkan örneği içermektedir. Belgelendirme maksadıyla sadece imgui kullanacağız. Projeyi oluşturun ve derleyin:
cmake -G "Visual Studio 16 2019" -S . -Bbuild/windows cmake --build build/windows --config Debug --target imgui

Not: Cmake derlemesi ufak bir betik yürüterek ilave varlıklar indirir. Derleme ana bilgisayarında Python'a sahip olmalısınız.

Bu; imgui yürütülebilirini, gerekli Windows hata ayıklama DLL dosyalarını ve veri varlıklarını içeren build/windows/bin/Debug dizinini oluşturacak.

Bu noktada ortaya çıkan hata ayıklama dizinini yükleyebilirsiniz.

"This title requires Steam Play"i seçtiğinizden emin olun zira bu yerel bir Linux derlemesi olmayacak, ayrıca uzaktan hata ayıklayıcıyı etkinleştirmek için "Start Visual Studio C++ debugger service on launch"u da seçin.

Oyununuzu çalıştırdıktan sonra eklemek yeterli değilse ve oyununuza başlangıçta ve başlarken hata ayıklama uygulamak isterseniz "Wait for a debug client to attach (Hata ayıklama istemcisinin eklenmesini bekle)" seçeneğini kullanın ve bu makaledeki "early attach (erkenden ekle)" kısmını okuyun.

devkit-tool-remote-debug-20211207.png

Örneğin vulkan_examples_debug adını seçtiyseniz aktarım tamamladıktan sonra Steam oyun kütüphanesinde Devkit Game: vulkan_examples_debug adlı yeni bir oyun göreceksiniz.

Oyunu başlattığınızda, uzaktan hata ayıklama için bir msvsmon sunucusu da otomatik olarak başlayacaktır.

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

Artık çalışan oyuna bir hata ayıklayıcı eklemeye hazırsınız.

Visual Studio'da Debug > Attach to Process'i (Hata Ayıklama > İşleme Ekle) açmak için Ctrl+Alt+P tuşlarına basın. Connection (Bağlantı) hedefinde msvsmon sunucusunun IP ve bağlantı noktasını seçin, ardından imgui.exe işlemini seçin.

Screenshot_2021-07-26_092207.png

Daha detaylı talimatlar için Microsoft hata ayıklayıcısı belgelendirmesindeki adımları takip edin.

Unreal Engine 4 örnekleri

Hesabınız yoksa bir Epic Games hesabı oluşturun, ardından Unreal Engine 4'ü indirin ve yükleyin.

Örnek olarak Unreal Editor'ın sunduğu örnek projelerden birini kullanacağız. Yeni bir proje oluşturun ve "Puzzle" (Bulmaca) şablonunu seçin.

Screenshot_2021-07-16_072803.png

Bir proje adı ve konumu seçin.

Screenshot_2021-07-15_082533.png

Edit->Project settings->Packaging (Düzenle > Proje ayarları > Paketleme) kısmına gidin ve derleme yapılandırması olarak "Debug" (hata ayıklama) veya "DebugGame" (oyun hata ayıklaması) seçeneklerinden birini seçin. Daha fazla bilgiye resmî belgelendirmeden ulaşabilirsiniz. "Include Debug Files" (Hata Ayıklama Dosyalarını Dâhil Et) kutusunu işaretlerseniz hata ayıklama dosyaları paketlenen oyuna dâhil edilir.

Screenshot_2021-07-16_073647.png

Yerel bir Linux derlemesi derleyemiyorsanız (ör. oyununuzun Linux'u desteklemeyen haricî gereksinimleri varsa) Dosya -> Projeyi Paketle -> Windows (64 bit) seçeneğini kullanarak bir Windows derlemesi başlatabilirsiniz. Bu, "WindowsNoEditor" adlı yeni bir dizinde bir derleme oluşturur.

Derlenmiş oyununuzu SteamOS geliştirici kiti istemcisini kullanarak yükleyin.

Screenshot_2021-07-16_074524.png

Steam kütüphanenizde Devkit Game: puzzle adına benzer bir ada sahip yeni bir girdi göreceksiniz. Oyunu başlattığınızda, uzaktan hata ayıklama için bir msvsmon sunucusu da otomatik olarak başlayacaktır.

Son adım olarak artık çalışan oyuna bir hata ayıklayıcı eklemeye hazırsınız.

Visual Studio'da Debug > Attach to Process'i (Hata Ayıklama > İşleme Ekle) açmak için Ctrl+Alt+P tuşlarına basın. Connection (Bağlantı) hedefinde msvsmon sunucusunun IP ve bağlantı noktasını seçin, ardından puzzle.exe işlemini seçin.

Daha detaylı talimatlar için Microsoft hata ayıklayıcısı belgelendirmesindeki adımları takip edin.

Başlangıçta uzaktan hata ayıklama işlemi: "Early attach (erkenden ekle)" desteği:


Uzaktan hata ayıklama hizmeti, oyunu başlatmadan önce kullanıcının ekleme yapmasını bekleyecek şekilde yapılandırılabilir. Bu, WinMain veya diğer başlangıçta devreye girecek kodlarda bir kesme noktası ayarlamanıza olanak tanır.

Bunun için ilk olarak geliştirme bilgisayarınıza Visual Studio'da bir Microsoft uzantısı eklemelisiniz: https://marketplace.visualstudio.com/items?itemName=vsdbgplat.MicrosoftChildProcessDebuggingPowerTool

child-process-debug-extension.png

Uzantı yüklendikten sonra belgelendirmede açıklandığı şekilde (Hata Ayıklama > Diğer Hata Ayıklama Hedefleri > Alt İşlem Hata Ayıklama Ayarları) alt işlem hata ayıklamasını etkinleştirin.

Geliştirici kitinizden "Wait for a debug client to attach (Hata ayıklama istemcisinin eklenmesini bekle)" seçeneğini işaretleyin ve oyununuzu yükleyin.

Oyununuzu normal bir şekilde çalıştırın.

Uzak işlemi steam.exe'ye ekleyin. Ekledikten sonra Proton, oyununuzu hemen alt işlem olarak başlatacak ve uzantı, kesme noktaları etkin bir şekilde devreye girerek başlangıçtan itibaren oyununuzda hata ayıklamaya başlayacaktır.