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. Bazı API'lar Steamworks'e yükleme, indirme, sıralama ve silme 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 eşitlemesini 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

İ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 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 etmenin en iyi yolu budur. 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 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'yı 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. Sizden sadece Cloud'da 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/
  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 Steam 3 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ı

Eğer uygulamanız çapraz platformu destekliyorsa ve her bir İS için farklı bir dizine gereksinim duyuyorsa, Kök geçersiz kılmaları işlevini kullanarak yukarıda belirttiğiniz kök yolları için bir geçersiz kılma belirleyebilirsiniz.

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 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 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 testcloudapppaths 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.

Dynamic Cloud Sync


Steam Cloud now supports dynamic sync - where changes appearing in the Cloud can be downloaded to the local machine during an application session. The current example is a suspended game session on the Steam Deck. For apps marked as supporting dynamic Cloud sync, Steam will synchronize files up to the Steam Cloud at the suspend time. Then, the user may run the game on another device, which will receive the updates from the Steam Deck session at launch. At exit, those changes will be uploaded to the Steam Cloud. Finally, when the Steam Deck device is awakened, Steam will synchronize the changes down to that device, and post a notification to the application that local files have changed. The application can then iterate those changes and take appropriate action. For instance, the game may be able to simply load the updated progress from disk and allow the user to pick up right where they left off on the other device.

Currently, the ability to flag an application as supporting dynamic Cloud sync is only available to Valve admins. Get in touch with your Valve contacts for more detail.

Note that this feature supports applications whether they use the ISteamRemoteStorage API to manage files, or AutoCloud.

For more details, see the ISteamRemoteStorage documentation, specifically ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount, and ISteamRemoteStorage::GetLocalFileChange.

See also ISteamRemoteStorage::BeginFileWriteBatch and ISteamRemoteStorage::EndFileWriteBatch - these wrappers should be used to provide hints to Steam which will help it safely sync up to the Steam Cloud at the time when the user initiates a system suspend.

Debugging

First, always ensure that you have published your changes on the Steam partner website and have waited up to 10 minutes or restarted your Steam client to receive the published changes.

If you run into issues with Steam Cloud you should check the log file located at %Steam Install%\logs\cloud_log.txt.

See Debugging the Steamworks API for additional information.