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 gier, w których wolisz nie integrować API Steam Cloud. Jest to szybkie i proste rozwiązanie do rozpoczęcia pracy, ale nie posiada takiej samej elastyczności co Steam Cloud API.

Jeżeli wolisz głębszą integrację ze Steam Cloud (np. umożliwiając, które pliki zapisów mają być przechowywane w chmurze), to wykorzystaj API chmury. W przeciwnym wypadku użyj Steam Auto-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.
Uwaga: plik steam_autocloud.vdf zostanie utworzony w każdej lokalizacji określonej przez twoje ścieżki chmury w Steamworks. Ten plik jest używany przez Steam i może zostać zignorowany przez twoją grę.

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

Użycie tego ma sens w przypadku, jeżeli twoja aplikacja jest wieloplatformowa i wymaga różnych katalogów dla każdego systemu operacyjnego. Możesz użyć obejścia roota, by określić obejście ścieżek roota ustawionych powyżej.

Ś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 aplikacji Auto-Cloud z Unity, w której wartość właściwości Application.persistentDataPath jest różna dla różnych systemów operacyjnych. 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 testowaną przez ciebie aplikację.
  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

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.

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.