Dokumentacja Steamworks
Steam Cloud
W skrócie
Steam Cloud automatycznie przechowuje pliki z twojej gry na serwerach Steam, by twoi gracze mogli zalogować się do Steam i uzyskać dostęp do swoich zapisanych gier na dowolnym komputerze.
Poziom integracji
Wymagana jest konfiguracja ścieżek do plików na stronie Steamworks. Opcjonalnie niektóre wywołania API są wymagane z poziomu kodu gry do Steamworks w celu przesyłania, pobierania, wyliczania i usuwania plików.

Wprowadzenie do Steam Cloud

Usługa Steam Cloud zapewnia łatwy i przejrzysty system zdalnego przechowywania plików twojej gry. Pliki określone podczas konfigurowania Auto-Cloud lub zapisane na dysku (utworzone, zmodyfikowane, usunięte itd.) za pomocą API chmury zostaną automatycznie powielone na serwery Steam po opuszczeniu gry.

Jeśli użytkownik skorzysta z innego komputera, pliki zostaną automatycznie pobrane na niego przed uruchomieniem gry. Gra może następnie uzyskać dostęp do plików, odczytując je poprzez API chmury lub bezpośrednio z dysku, tak jak zwykle. Unikaj konfiguracji specyficznych dla danego komputera, np. ustawień wideo.

Klient Steam zapewnia, że pliki są zsynchronizowane na wszystkich komputerach, z których korzysta użytkownik.

Użytkownicy mogą globalnie wyłączyć synchronizację z chmurą w ustawieniach Steam w zakładce „Cloud” poprzez odznaczenie „Włącz synchronizację dla produktów Steam, które ją obsługują”.

Użytkownicy mogą również wyłączyć synchronizację z chmurą dla każdej gry oddzielnie w jej właściwościach.

Spacewar_Cloud_Properties.png

Uwagi i najlepsze praktyki


Należy pamiętać, iż Steam zsynchronizuje pliki Steam Cloud użytkownika dla twojej gry przed i po każdej sesji. Wszelkie pasujące pliki, które zmienią się podczas sesji, zostaną przesłane do pamięci w chmurze natychmiast po jej zakończeniu. Jeżeli twoja gra zapisuje w Steam Cloud bardzo duże pliki lub wiele małych, to może to wywołać istotny wpływ na przepływność łącza użytkownika i opóźnić możliwość wyłączenia Steam lub kolejnego uruchomienia gry.

Najogólniej lepiej pracować z mniejszymi plikami. Jeżeli zapisany stan gry danego użytkownika można podzielić na kilka kategorii (te, które zmieniają się często i te, które zmieniają się rzadko), to zalecamy skorzystanie z oddzielnych plików dla tych kategorii. W ten sposób pliki z niezmienionym stanem nie będą ponownie przesyłane po każdej sesji.

Limit rozmiarów plików


Bezwzględny limit rozmiarów plików w Steam Cloud może zmienić się po pewnym czasie. Oto obecne limity i granice:

RozmiarOgraniczenie
100 MBMaksymalny rozmiar do wywołania dla ISteamRemoteStorage::FileWrite lub ISteamRemoteStorage:;FileWriteStreamWriteChunk
256MBMoże poskutkować wyborem nieoptymalnego punktu końcowego pamięci w lokalizacji użytkownika, negatywnie wpływając na wydajność wysyłania/pobierania

Wstępna konfiguracja

Aby skonfigurować Steam Cloud, musisz ustawić opcje Limit bajtów na użytkownika i Limit plików na użytkownika na stronie Ustawienia Steam Cloud w panelu administratora aplikacji Steamworks.

Określenie tych limitów to wymóg w każdej grze posiadającej obsługę chmury oddzielnie dla każdej gry i każdego użytkownika. Zalecamy ustawić rozsądne wartości dla swojej gry.

UWAGA: Nie zapomnij kliknąć przycisku „Zapisz” na dole strony oraz opublikować zaktualizowanych ustawień. Po opublikowaniu ikona chmury będzie widoczna dla każdego posiadacza gry w kliencie Steam.

Jeśli twoja gra została już wydana, możesz zaznaczyć pole Włącz obsługę chmury tylko dla deweloperów. W tym przypadku tylko konta, które posiadają licencję „Egzemplarz producenta” dla twojej gry, będą widziały ikonę chmury oraz będą w stanie korzystać ze Steam Cloud. Jest to przydatne w celu bezpiecznego testowania integracji Steam Cloud bez powodowania zakłóceń u użytkowników. Nie ma to wpływu na niewydane gry, ponieważ nikt jeszcze ich nie posiada i nie będzie w stanie widzieć lub uzyskać dostępu do pamięci w chmurze dla konkretnego ID aplikacji.

Możliwe jest współdzielenie pamięci w chmurze pomiędzy dwoma ID aplikacji poprzez wypełnienie pola Współdzielone ID aplikacji w chmurze. Jest to najczęściej używane do współdzielenia zapisanych stanów gier między demem a pełną wersją gry. Wartość 0 wyłącza tę funkcję.

API Steam Cloud i Steam Auto-Cloud

Steam zapewnia dwie różne metody korzystania z usługi Steam Cloud. Przeczytaj, czym się one różnią i wybierz tę, która będzie najlepsza dla twojej aplikacji.

Pierwsza to API Steam Cloud.

API chmury zawiera wiele funkcji, które pozwalają na bezpośrednią integrację Steam Cloud z twoją grą. API chmury odizolowuje pojedyncze pliki użytkowników Steam od siebie oraz zapewnia większy poziom kontroli nad usługą Steam Cloud.

API Steam Cloud jest dostępne poprzez interfejs ISteamRemoteStorage, a przykład zastosowania znajduje się tutaj.

Drugi sposób to Steam Auto-Cloud.

Steam Auto-Cloud został zaprojektowany dla starszych gier, których nie można łatwo zintegrować z API Steam Cloud. Dzięki niemu można szybko i łatwo zacząć, ale nie posiada on takich możliwości oraz elastyczności co API Steam Cloud.

Zaleca się korzystać z API Steam Cloud, kiedy to tylko możliwe, gdyż pozwala ono na głębszą integrację i dostosowywanie oraz umożliwia dostarczenie jak najlepszej jakości usług, której użytkownicy oczekują od Steam Cloud.

Steam Auto-Cloud

Steam Auto-Cloud jest alternatywą dla API Steam Cloud i pozwala aplikacjom na korzystanie ze Steam Cloud bez pisania kodu lub modyfikowania gry w jakikolwiek sposób. Wymaga to tylko określenia grup plików, które chcesz zachować w chmurze. Steam będzie automatycznie synchronizował grupy plików przy każdorazowym włączeniu i wyłączeniu aplikacji. Unikaj konfiguracji specyficznych dla danego komputera, np. jakości wideo.

Ustawienie

Gdy zakończysz konfigurację wstępną, na stronie ustawień Steam Cloud zostanie odblokowana sekcja konfiguracji dla Steam Auto-Cloud.

Ścieżki roota opisują grupy plików, które zostaną zachowane w usłudze Steam Cloud. Każda ścieżka roota może zostać określona zarówno jako pojedynczy plik, jak i wszystkie pliki w danym podfolderze. Użyj nowej ścieżki dla każdej grupy plików, którą chcesz zsynchronizować.

Ścieżka roota składa się z 5 części:
  1. Root

    Jest to ustalona lista ścieżek, w których zwykle znajdują się zapisywane gry.
    RootWspierane SOOdpowiadająca ścieżka
    Folder instalacyjny aplikacjiWszystkie[Instalacja Steam]\SteamApps\common\[Folder gry]\
    SteamCloudDocumentsWszystkieŚcieżka dla określonej platformy, np. dla systemu Linux: ~/.SteamCloud/[nazwa użytkownika]/[Folder gry]/
    WinMyDocumentsWindows%USERPROFILE%\Dokumenty\
    WinAppDataLocalWindows%USERPROFILE%\AppData\Local\
    WinAppDataLocalLowWindows%USERPROFILE%\AppData\LocalLow\
    WinAppDataRoamingWindows%USERPROFILE%\AppData\Roaming\
    WinSavedGamesWindows%USERPROFILE%\Zapisane gry\
    MacHomemacOS~/
    MacAppSupportmacOS~/Library/Application Support/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/
  2. Podkatalog

    Ścieżka podkatalogu plików w chmurze względem roota. Użyj „.”, jeśli nie ma podkatalogu.

    Wartości specjalne ścieżek w Auto-Cloud
    Auto-Cloud pozwala na użycie unikalnych identyfikatorów użytkownika Steam w podkatalogu ścieżki. Pozwala to na przechowywanie plików zapisanych gier dla każdego użytkownika Steam na jednym komputerze oddzielnie. Możesz użyć ISteamUser::GetSteamID w swojej grze, by uzyskać ID Steam lub ID konta użytkownika i wykorzystać je do zapisywania i odczytywania.
    • {64BitSteamID} — użyj tej zmiennej w ścieżce Steam, aby wstawić 64-bitowe ID Steam użytkownika. 64-bitowe ID Steam wygląda następująco: 76561198027391269
    • {Steam3AccountID} — użyj tej zmiennej w ścieżce Steam, aby wstawić 3-bitowe ID konta Steam użytkownika. ID konta wygląda następująco: 67125541.
    Przykład: SavesDir/{64BitSteamID}
  3. Wzorzec

    Wzorzec maski pliku do dopasowania. Możesz użyć * jako dzikiej karty. Jeśli potrzebujesz wszystkich plików w katalogu, użyj *.

    Przykład: *.sav
  4. SO

    Ustawia systemy operacyjne, z którymi lub do których te pliki będą synchronizowane. Jest to wymagane tylko w przypadku, kiedy pliki są specyficzne dla danego systemu operacyjnego, co, miejmy nadzieję, nie ma miejsca!
  5. Cykliczne

    Dołącz podkatalogi podczas szukania pasujących plików. Jest to przydatne dla podkatalogów z niedeterministycznymi nazwami, np. nazwy użytkowników niezwiązane ani ze Steam, ani z ID. Jeśli korzystasz z ID Steam, to zaleca się użycie specjalnych wartości ścieżki w polu „Podkatalog”.

Obejścia roota

Jeśli twoja aplikacja jest wieloplatfromowa i wymaga różnych katalogów dla każdego systemu operacyjnego, korzystając z funkcjonalności Root Overrides, możesz określić obejście wcześniej ustawionych ścieżek.

Ścieżki roota określone powyżej można obejść, by odpowiadały innej ścieżce na innym systemie operacyjnym. Jeżeli korzystasz z obejścia roota, musisz wybrać wszystkie systemy operacyjne w powyższej liście rozwijanej.

Obejście roota składa się z 5 części.
  1. Oryginalny root

    Odpowiada to jednemu z rootów ustawionych powyżej.
  2. SO

    System operacyjny, do którego zostanie zastosowane obejście.
  3. Nowy root

    Nowa lokacja, do której oryginalny root będzie przekierowywał na określonym systemie operacyjnym.
  4. Dodaj/zastąp ścieżkę

    To ustawienie pozwala na opcjonalnie dodanie ścieżki podkatalogu, która jest wstawiana między nowym rootem a oryginalnym podkatalogiem.
  5. Zastąp ścieżkę

    Włączenie spowoduje, że ścieżka określona w polu „Dodaj/zastąp ścieżkę” całkowicie zastąpi oryginalny podkatalog.

Przykład: konfiguracja Auto-Cloud dla aplikacji Unity

Poniżej przedstawiono przykład konfiguracji Auto-Cloud do użycia z Unity, w której wartość właściwości Application.persistentDataPath jest różna dla każdego systemu operacyjnego. Wersja dla systemu Windows jest skonfigurowana jako ścieżka roota, gdzie nazwa firmy w Unity to DefaultCompany, a projekt nazywa się AutocloudSample. W przypadku systemów macOS i Linux/SteamOS alternatywne ścieżki określone w Application.persistentDataPath są ustawione w polu „Dodaj/zastąp ścieżkę”, a opcja „Zastąp ścieżkę” jest włączona.

Dzięki tym ustawieniom pliki w Auto-Cloud będą zsynchronizowane między trzema folderami, jak pokazano w przykładzie.

Cloud_Unity_Auto-Cloud_Example.png

Testowanie przed opublikowaniem

Jeśli dodajesz Steam Auto-Cloud do już wydanej gry, a podczas wstępnej konfiguracji włączono tryb tylko dla producentów, musisz wykonać dodatkowe kroki, aby przetestować funkcjonalność.
  1. Zaloguj się do Steam za pomocą konta, które posiada licencję o nazwie „Egzemplarz producenta” dla testowanej przez ciebie aplikacji.
  2. Uruchom konsolę Steam, przechodząc do steam://open/console w twojej przeglądarce.
  3. Wpisz w konsoli testappcloudpaths <AppId> z danym ID aplikacji, którą testujesz. Przykład: testappcloudpaths 480.
  4. Wpisz w konsoli set_spew_level 4 4.
  5. Uruchom swoją aplikację z poziomu Steam.
  6. Sprawdź aktywność w konsoli. Jeśli istnieją już pliki w ścieżkach Auto-Cloud, zobaczysz w konsoli, że są przesyłane. W przeciwnym wypadku zapisz niektóre pliki w swojej aplikacji, a następnie zamknij ją, aby rozpocząć synchronizację.
  7. Przejdź do innego komputera i powtórz powyższe kroki, by przetestować pobieranie plików ze Steam Auto-Cloud.
  8. Upewnij się, że przetestujesz tę funkcjonalność na wszystkich obsługiwanych systemach operacyjnych.
  9. Wpisz testcloudapppaths 0 i set_spew_level 0 0, by zakończyć testowanie. Możesz zrestartować klienta Steam, by pozbyć się zakładki z konsolą.

Nie zapomnij wyłączyć trybu dla producentów oraz opublikować zmiany po zakończeniu testowania.

Debugowanie

Po pierwsze, zawsze upewnij się, że zmiany zostały opublikowane na stronie partnerskiej Steamworks i odczekałeś(-aś) 10 minut lub zrestartowałeś(-aś) swojego klienta Steam, aby je zobaczyć.

Jeśli masz problemy ze Steam Cloud, sprawdź plik dziennika znajdujący się w katalogu %Instalacja Steam%\logs\cloud_log.txt.

Przejdź tutaj, aby uzyskać więcej informacji.