Steamworks Belgeleri
Steam Cloud
Kısaca
Steam Cloud, oyununuza ait dosyaları Steam sunucularında saklayarak, oyuncularınızın Steam'e giriş yaptığı herhangi bir bilgisayarda kayıtlı oyunlarına erişebilmelerini sağlar.
Entegrasyon seviyesi
Dosya yollarının yapılandırması Steamworks internet sitesinde gereklidir. Alternatif olarak API'lar Steamworks'e sıralama, okuma, silme ve Steam Cloud'a yazma için yapılacak çağrıların oyun kodundan yapılmasını gerektirir.

Steam Cloud Genel Bakış

Steam Cloud, oyununuz için kolay ve şeffaf bir uzakta dosya depolama sistemidir. Auto-Cloud yapılandırmasında belirtilen dosyalar veya Cloud API kullanılarak diske yazılan (oluşturulan, değiştirilen, silinen, vb.) dosyalar, oyundan çıkıldıktan sonra otomatik olarak Steam sunucularına kopyalanır.

Eğer kullanıcı bilgisayar değiştirirse, yeni bilgisayarda oyun açılmadan evvel bu dosyalar otomatik olarak yeni bilgisayara indirilir. Ardından oyun bu dosyalara Cloud API aracılığıyla bunları okuyarak ya da doğrudan her zaman olduğu gibi diskten okuyarak erişebilir. Video ayarları gibi makineye özel yapılandırmalardan kaçının.

Steam istemcisi, kullanıcının diğer bilgisayarlardan da erişebileceği bu dosyaların senkronize bir biçimde tutulmasını sağlar.

Kullanıcılar Cloud eşitlemesini Steam ayarlarına giderek burada yer alan Cloud sekmesinden "Destekleyen uygulamalarda Steam Cloud eşitlemesini etkinleştir" kutucuğunun işaretini kaldırarak devre dışı bırakabilir.

Kullanıcılar Cloud senkronizasyonunu aynı zamanda belirli oyunlar için de oyunların özelliklerine giderek kapatabilir.

Spacewar_Cloud_Properties.png

Notlar ve En İyi Yöntemler


Steam, kullanıcıların oyununuza ait dosyalarını her oyuna girdiklerinde ve çıktıklarında Steam Cloud'la eşitler. Oyun esnasında değiştirilmiş ve oyun başlamadan önce yapılan eşitlemeyle eşleşen bütün dosyalar, oyun kapatıldıktan hemen sonra Steam Cloud'a yüklenir. Oyununuzun Steam Cloud'a yazdığı dosyaların boyutu büyükse veya sayıca çok fazla dosyadan oluşuyorsa bu, kullanıcının bant genişliğine olumsuz etki edebilir ve aynı zamanda Steam'i kapatma veya oyunu yeniden başlatma kabiliyetlerini geciktirebilir.

Genel olarak küçük dosyalar daha iyi olacaktır. Bir kullanıcının kayıt durumu farklı kategorilere (ör. sıklıkla değişen şeyler ve sık değişmeyen şeyler) ayrılabiliyorsa, bu kategoriler için farklı dosyalar kullanmanızı tavsiye ediyoruz. Bu sayede değiştirilmemiş durum her bir oyun oturumundan sonra tekrar yüklenmez.

Dosya Boyutu Sınırları


Steam Cloud'un nihai dosya boyutu sınırları zamanla değişebilir. İşte mevcut bazı sınırlar ve eşikler:

BoyutKısıtlama
100 MBISteamRemoteStorage::FileWrite or ISteamRemoteStorage::FileWriteStreamWriteChunk'a yapılacak çağrının azami boyutu
256 MBKullanıcının konumu için optimal olmayan depolama uç noktası seçimine neden olabilir ve indirme/yükleme performansını olumsuz etkileyebilir

Dosya Kaydetme Dizinleri

Kayıt dosyalarınızı nereye yazacağınıza karar verirken dosya yolunun ilgili Steam kullanıcısı için benzersiz olduğundan emin olun. Gerekliyse, kullanıcının SteamID'sini ISteamUser::GetSteamID aracılığıyla alabilirsiniz. Buradan GetAccountID()'den kullanıcının accountID'sine erişebilirsiniz ve kayıt dizininizi oluştururken benzersiz bir değişkeniniz olabilir.

Çapraz Platform Oyun Kayıtları


Oyununuz birden fazla platformda destekleniyorsa ya da bunu gelecekte yapmayı düşünüyorsanız, oyununuz için Steam Cloud'u ayarlarken bunu göz önünde bulundurmalısınız.

Dosyaları ISteamRemoteStorage arayüzü aracılığıyla doğrudan yazmayı/okumayı planlıyorsanız platform senkronizasyonunu ISteamRemoteStorage::SetSyncPlatforms aracılığıyla kontrol edebilirsiniz. Yeni bir dosya varsayılan olarak tüm platformlar arasında senkronize eder.

Steam Auto-Cloud kullanmayı planlıyorsanız bilmeniz gereken bazı önemli şeyler var. İlk olarak, yeni dosyalar varsayılan olarak sadece Auto-Cloud kök yoluyla ilişkilendirilmiş işletim sistemleriyle senkronize eder. Bu, her işletim sistemi için farklı bir kök yolu ayarladığınız takdirde tüm dosyaların platforma göre bölümleneceği anlamına geleceğinden, farklı platformlar arasında kayıt işlevi de olmaz.

Çapraz platform kayıtlarını etkinleştirmek için tek bir kök yolu belirlemelisiniz (muhtemelen Windows için) ve ardından desteklenen diğer platformlar için kök geçersiz kılmaları oluşturmalısınız. Bir kök yoluyla eşleşen ve aynı zamanda platform kök geçersiz kılmalarına sahip olan dosyalar hem orijinal kökteki hem de tüm geçersiz kılmalardaki tüm platformlarla senkronize edilir. Daha detaylı bilgi için Steam Auto-Cloud belgesine bakın.

İlk Kurulum

Steam Cloud kurulumunu yapmak için öncelikle Steamworks Uygulama Yöneticisi paneline giderek orada yer alan Steam Cloud Ayarları sayfasından Kullanıcı başına bayt kotası ve Kullanıcı başına izin verilen dosya sayısı seçeneklerini ayarlamalısınız.

Bu kota, Cloud özelliğinin etkin olduğu bütün oyunlarda o oyun için kullanıcı başına uygulanır. Bu değerleri oyununuz için uygun olacak bir değere ayarlamanızı tavsiye ediyoruz.

NOT: Sayfanın en altında yer alan Kaydet butonuna basmayı ve güncellediğiniz ayarları yayınlamayı unutmayın. Yayınlandıktan sonra Cloud simgesi Steam istemcisinde oyununuza sahip olan herkese gösterilecektir.

Eğer oyununuz zaten yayınlanmışsa Cloud desteğini sadece geliştiriciler için etkinleştir kutucuğunu işaretleyebilirsiniz. Geliştiricilere özel modu etkinleştirdiğinizde sadece oyununuz için "Geliştirici Erişimi" lisansına sahip Steam hesapları Cloud simgesini görebilir ve Steam Cloud'u kullanabilir. Kullanıcıların tecrübelerini sekteye uğratmadan Steam Cloud'u test etmek için bu iyi bir yoldur. Oyuna henüz kimse sahip olmadığı ve bundan ötürü ilgili appID'nin bulut depolamasını kimse kullanamayacağı için bu özellik, yayınlanmamış oyunlarda herhangi bir etkiye neden olmayacaktır.

Paylaşılan Cloud APP ID'yi doldurarak Cloud depolama alanını iki app ID arasında paylaşabilirsiniz. Bu genellikle bir oyunun tam sürümü ile demo sürümündeki kayıtlı oyunları paylaşmak için kullanılabilir. 0 değeri girmek bu özelliği devre dışı bırakır.

Steam Cloud API ve Steam Auto-Cloud

Steam, Steam Cloud'u kullanabileceğiniz iki farklı yöntem sunar. Bu yöntemlerin ayrıştığı noktaları okuyun ve hangisinin sizin uygulamanız için en uygun olacağına karar verin.

Steam Cloud API ile başlayalım.
Cloud API, Steam Cloud'u doğrudan oyununuza entegre edebilmenizi sağlayan bir dizi işlev içerir. Cloud API, Steam kullanıcılarının dosyalarını tekil olarak izole eder ve Steam Cloud üzerinde oldukça iyi bir kontrol imkânı sağlar.

Steam Cloud API'ı ISteamRemoteStorage API arayüzü aracılığıyla açığa çıkarılır. Örnek kullanımını Steamworks API Example Application (SpaceWar) projesinde bulabilirsiniz.

Diğeri de Steam Auto-Cloud.
Steam Auto-Cloud, Steam Cloud API'ını entegre etmek istemediğiniz oyunlarda kullanılmak için tasarlanmıştır. Başlamak için hızlı ve kolay bir yol sunar ancak Steam Cloud API'ı kadar esnekliğe sahip değildir.

Steam Cloud ile daha derin bir entegrasyon tercih ediyorsanız (bulutta hangi kayıt dosyalarının saklanacağı gibi) Cloud API'nı kullanmalısınız. Bunun haricinde Steam Auto-Cloud'u kullanabilirsiniz.

Steam Auto-Cloud

Steam Auto-Cloud, size Steam Cloud'u kod yazmadan ya da oyunu herhangi bir şekilde değiştirmeden kullanma imkânı sağlayan bir Steam Cloud API'ı alternatifidir. Sadece bulutta sürekli olmasını istediğiniz dosya gruplarını belirlemenizi gerektirir. Steam, dosya gruplarını uygulamaya her giriş ve çıkış yapıldığında otomatik olarak eşitleyecektir. Video kalitesi gibi makineye özel yapılandırmaları seçmekten kaçının.
Not: Steamworks Cloud dosya yollarınız tarafından belirtilen her konumda bir steam_autocloud.vdf dosyası oluşturulur. Bu dosya Steam tarafından kullanılacağı için oyununuz tarafından yok sayılabilir.

Kurulum

İlk Kurulum tamamlandıktan sonra Steam Cloud Ayarları sayfasında Steam Auto-Cloud yapılandırması kısmı açılacaktır.

Kök yolları, Steam Cloud'da sürekli olacak dosya gruplarını tanımlar. Her kök yolu tek bir dosyaya kadar spesifik olabileceği gibi bir alt klasörün altındaki bütün dosyaları kapsayacak kadar geniş de olabilir. Senkronize edilecek her dosya grubu için yeni bir dosya yolu kullanın.

Bir kök yolu 5 parçadan oluşur:
  1. Kök

    Aşağıda bir oyunun kayıt dosyalarının yaygın olarak saklandığı yerlerin yollarının bir listesi vardır.
    KökDesteklenen İS'lerKarşılık Gelen Yol
    Uygulama Yükleme DiziniHepsi[Steam Install]\SteamApps\common\[Oyun Klasörü]\
    SteamCloudDocumentsHepsiPlatforma özgü yol, ör. Linux'da: ~/.SteamCloud/[kullanıcı adı]/[Oyun Klasörü]/
    WinMyDocumentsWindows%USERPROFILE%\My Documents\
    WinAppDataLocalWindows%USERPROFILE%\AppData\Local\
    WinAppDataLocalLowWindows%USERPROFILE%\AppData\LocalLow\
    WinAppDataRoamingWindows%USERPROFILE%\AppData\Roaming\
    WinSavedGamesWindows%USERPROFILE%\Saved Games\
    MacHomemacOS~/
    MacAppSupportmacOS~/Library/Application Support/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/

    Windows %USERPROFILE% dosya yollarına dair bir not: Yukarıda verilen dosya yolları varsayılan konumlardır. Kullanıcılar, artık bu klasörleri farklı konumlara alacak şekilde Windows kurulumlarında değişiklik yapabilmektedir (yani %USERPROFILE% konumunda olmaları şart değildir). Steam, ister varsayılan isterse farklı konumda olan bu klasörlerin güncel konumlarını bulmak için gerekli Windows API'larını kullanır.

  2. Alt dizin

    Buluta alınan dosyaların kökle ilişkili alt dizin yolu. Eğer alt dizin yoksa "." kullanın.

    Auto-Cloud özel yol değerleri
    Auto-Cloud, alt dizin içinde yer alan benzersiz Steam kullanıcı tanımlayıcılarının kullanılabilmesini sağlar. Bu sayede her Steam kullanıcısının bilgisayarında ayrıca yer alan kayıt dosyalarını saklayabilme olanağı elde edersiniz. Oyununuzdaki mevcut kullanıcıların SteamID veya HesapID'lerini alıp saklamak ve okumak için ISteamUser::GetSteamID'yi kullanabilirsiniz.
    • {64BitSteamID} - Kullanıcıların 64 bitlik Steam ID'lerini eklemek için bu değişkeni Steam yolunda kullanın. 64 bitlik bir Steam ID'si şöyle görünür: 76561198027391269
    • {Steam3AccountID} - Kullanıcıların Steam3 hesap ID'lerini eklemek için bu değişkeni Steam yolunda kullanın. Hesap ID'si şöyle görünür: 67125541
    Örnek: SavesDir/{64BitSteamID}
  3. Örüntü

    Eşleşecek dosya maskesi örüntüsü. * işaretini joker olarak kullanabilirsiniz. Eğer dizindeki bütün dosyaları istiyorsanız * işaretini kullanmanız yeterlidir.

    Örnek: *.sav
  4. İşletim Sistemi

    Bu dosyaların eşitleneceği işletim sistemlerini belirler. Bu sadece eğer dosyalar İS'ye özelse gereklidir ama umuyoruz dosyalarınız İS'ye özel değildir!
  5. Rekürsif

    Eşleşen dosyaları ararken alt klasörleri de dahil et. Bu, Steam dışı kullanıcı adları ya da ID'ler gibi gerekirci olmayan adlara sahip alt dizinler için kullanışlıdır. Eğer bu bir Steam ID kullanıyorsa "Alt Dizin" alanında özel yol değerleri kullanmanızı şiddetle tavsiye ediyoruz.

Kök Geçersiz Kılmaları

Uygulamanız çapraz platform destekliyse ve her bir işletim sistemi için farklı dizinler gerektiriyorsa kök geçersiz kılma işlevini kullanarak yukarıda belirlediğiniz kök yolları için bir geçersiz kılma belirtebilirsiniz.

Yukarıdaki kök yolları başka bir işletim sistemindeki başka bir yola yönlendirilmek üzere geçersiz kılınabilir. Eğer kök geçersiz kılmasını kullanırsanız, yukarıdaki açılır "Kök İS" menüsünden [Bütün İS'ler] seçeneğini seçmelisiniz.

Bir kök geçersiz kılması 5 parçadan oluşur.
  1. Orijinal Kök

    Bu, yukarıda belirttiğiniz köklerden birine karşılık gelir.
  2. İşletim Sistemi

    Geçersiz kılmanın uygulanacağı işletim sistemi.
  3. Yeni Kök

    Orijinal kökün belirtilen işletim sisteminde atanacağı yeni yer.
  4. Yol Ekle/Değiştir

    Bu size, hem yeni hem de orijinal kök alt dizinleri arasına bir alt dizin ekleme imkânı verir.
  5. Yolu Değiştir

    Etkinleştirildiği zaman Yol Ekle/Değiştir'de belirtilen yolun orijinal alt dizinin tamamen yerini almasına neden olur.

Örnek: Auto-Cloud'u Unity Uygulamaları için Yapılandırmak

Aşağıda Auto-Cloud'un Unity ile kullanılabilmesi için gerekli kurulumunu ve her İS'ye göre değişiklik gösteren Application.persistentDataPath değerinin kurulumunu anlatan bir örnek yer almaktadır. Windows sürümünde kök yolu Unity'deki DefaultCompany olarak ayarlanmış "company" olarak belirlenmiş ve "Project" de AutocloudSample olarak adlandırılmış biçimde yapılandırılmıştır. macOS ve Linux/SteamOS'te ise Application.persistentDataPath'teki alternatif yollar, Yol Ekle/Değiştir kısmından (Yolu Değiştir kutucuğu işaretli olacak) belirlenir.

Bu ayarlar sayesinde Auto-Cloud dosyaları önizleme örneklerinde gösterildiği gibi üç klasör arasında eşitlenir.

Cloud_Unity_Auto-Cloud_Example.png

Yayın Öncesi Testi

Eğer Steam Auto-Cloud'u hâlihazırda yayınlanmış bir oyuna ekleyecekseniz ve İlk Kurulum esnasında geliştirici modunu açtıysanız bu işlevselliği test etmek için tamamlamanız gereken birkaç adım var.
  1. Test edeceğiniz uygulamaya sahip olan bir Steam hesabıyla giriş yapın.
  2. Tarayıcınıza steam://open/console yazarak Steam konsolunu açın.
  3. Test etmek istediğiniz uygulamanın App ID'sini şu komutun uygun yerine ekleyerek testappcloudpaths <AppId> komutunu girin. Ör.: testappcloudpaths 480
  4. Konsola set_spew_level 4 4 girin.
  5. Uygulamanızı Steam'den başlatın.
  6. Etkinlik için konsolu kontrol edin, eğer dosyalar zaten Auto-Cloud yollarında mevcutsa bu dosyaları yükleniyor olarak göreceksiniz. Aksi bir durum söz konusuysa eşitlemeyi tekrar tetiklemek için uygulamanızın bazı dosyalarını kaydedin ve uygulamayı kapatın.
  7. Steam Auto-Cloud'dan dosya indirmeyi test etmek için farklı bir bilgisayar başına geçin ve yukarıdaki adımları tekrar edin.
  8. Desteklenen bütün işletim sistemlerinde denediğinizden emin olun.
  9. Testi sonlandırmak için testappcloudpaths 0 ve set_spew_level 0 0 ayarlamasını yapın. Konsol sekmesinden kurtulmak için Steam istemcisini yeniden başlatın.

Test işleminiz sona erdiğinde geliştirici modunu devre dışı bırakmayı ve değişiklikleri yayınlamayı unutmayın.

Dinamik Bulut Senkronizasyonu


Steam Cloud artık dinamik senkronizasyonu destekliyor. Bu özellik sayesinde Cloud'da beliren değişiklikler bir uygulama oturumu esnasında yerel makineye indirilebilir. Mevcut örnekte Steam Deck'te askıya alınmış bir oyun oturumu yer almaktadır. Dinamik bulut senkronizasyonu desteğine sahip olarak işaretlenmiş uygulamalar, askıya alındıklarında dosyaları Steam Cloud'la senkronize eder. Ardından kullanıcı, oyunu başka bir aygıtta çalıştırabilir ve oyunu başlatırken bu aygıta Steam Deck'teki güncellemeler gönderilir. Çıkarken de oturum esnasında meydana gelen değişiklikler Steam Cloud'a yüklenir. Son olarak, Steam Deck aygıtı uyandırıldığında Steam, bu değişiklikleri Deck'e senkronize eder ve uygulamaya yerel dosyaların değiştiğine dair bir bildirim gönderir. Ardından uygulama da bu değişiklikleri alarak gerekli eylemleri gerçekleştirir. Örneğin, oyun güncellenmiş ilerlemeyi diskten yükleyerek kullanıcının başka bir aygıtta kaldığı yerden devam etmesine olanak tanıyabilir.

Daha fazla bilgi için bu özelliğin neden mevcut olduğunu ve nasıl kullanabileceğinizi anlatan duyuru gönderimizi okuyabilirsiniz.

Bu özelliğin, dosyaları yönetmek için ISteamRemoteStorage API'ını veya Auto-Cloud'u kullanan uygulamaları desteklediğini aklınızda bulundurun.

Daha fazla bilgi için ISteamRemoteStorage belgesine, spesifik olarak da ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount ve ISteamRemoteStorage::GetLocalFileChange'e bakın.

Ayrıca ISteamRemoteStorage::BeginFileWriteBatch ve ISteamRemoteStorage::EndFileWriteBatch'e de bakın. Bu sarmalayıcılar Steam'e, kullanıcı sistemi askıya alma işlemi başlattığında dosyaları Steam Cloud'a güvenli bir şekilde senkronize etmesini sağlayacak ipuçlarını sağlamak için kullanılmalıdır.

Yayın Öncesi Testi


Derlemelerinizi test etmek için uygulamanız için dinamik bulut senkronizasyonunu yerel olarak etkinleştirebilirsiniz. Bu, yayınlanmış oyunlar için tavsiye edilir zira tüm oyuncular için dinamik bulut senkronizasyonunu etkinleştirmek yeni API yöntemlerini ve geri dönüşleri işleyemeyen derlemelerde veri kaybına neden olabilir.

Bilgisayardan yerel olarak test etmek için:

  1. Test edeceğiniz uygulamaya sahip olan bir Steam hesabıyla giriş yapın.
  2. Tarayıcınıza steam://open/console yazarak Steam konsolunu açın (steam -console komut satırıyla da Steam'i çalıştırabilir ve ardından doğrudan "Konsol" kısmına gidebilirsiniz).
  3. Test ettiğiniz uygulamanın AppID'siyle birlikte konsola @cloud_testdynamicsyncapp<AppId>'i girin. Ör. @cloud_testdynamicsyncapp 480
  4. Uygulamanızı Steam'den başlatın.
  5. Oyunda istediğiniz yere kadar ilerleyin.
  6. Steam konsoluna prepare_for_suspend girin. Steam oyun işleminizi askıya alır ve değiştirilmiş dosyaları Steam Cloud'a yükler.
  7. İsteğe bağlı: Oyunu farklı bir aygıtta oynayın ve ilerleme kaydedin, ardından oyundan çıkın ve Steam istemcisinin ilerlemeyi Steam Cloud'a yüklemesine izin verin.
  8. Orijinal aygıttan Steam konsoluna resume_suspended_games girin. Bu, gerekli tüm dosyaları Steam Cloud'tan senkronize eder, oyununuzla ilgili API çağrılarını yayınlar, ardından oyun işleminizi askıdan indirir.

Bir Steam Deck'ten yerel olarak test etmek için:

  1. Geliştirici kitiyle Steam Deck'inize bağlanın.
  2. CEF konsolunu kullanmak için buraya bakın.
  3. Testi etkinleştirmek için JS konsoluna SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppId>”) girin. Bunu devre dışı bırakmak için SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”) satırını girebilirsiniz.

Hata Ayıklama

Öncelikle Steam partner sitesinde yaptığınız değişiklikleri yayınladığınızdan ve yayınlanan değişiklikleri almak için 10 dakika kadar beklediğinizden veya Steam istemcisini yeniden başlattığınızdan emin olun.

Eğer Steam Cloud ile ilgili sorunlarla karşılaşırsanız %Steam Install%\logs\cloud_log.txt dizininde yer alan kayıt dosyasını kontrol edin.

Daha fazla bilgi için Debugging the Steamworks API belgesine bakın.