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 synchronizowania konfiguracji specyficznych dla danego komputera, np. ustawień obrazu.

Klient Steam zapewnia, że pliki są synchronizowane 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ę ze Steam Cloud dla produktów, które ją obsługują”.

Użytkownicy mogą również wyłączyć synchronizację z chmurą oddzielnie dla każdej gry, przechodząc do właściwości danej gry.

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ędne limity rozmiarów plików w Steam Cloud mogą zmienić się w przyszłości. Oto obecne limity i granice:

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

Ścieżki plików z zapisami

Podczas podejmowania decyzji, gdzie zapisać pliki z zapisanym stanem gry, upewnij się, że ścieżka będzie unikalna dla obecnego użytkownika Steam. Jeżeli to konieczne, możesz uzyskać unikalne ID Steam użytkownika za pomocą ISteamUser::GetSteamID. Dzięki temu możesz poznać jego ID konta z użyciem funkcji GetAccountID(), co umożliwi ci użycie unikalnej zmiennej podczas tworzenia ścieżki zapisu.

Międzyplatformowa synchronizacja zapisów stanu gry

Jeśli twoja gra jest obsługiwana na wielu platformach lub masz takie plany na przyszłość, powinieneś wziąć to pod uwagę przy konfigurowaniu Steam Cloud dla swojej gry.

Jeśli planujesz odczytywać/zapisywać pliki bezpośrednio przez interfejs ISteamRemoteStorage, to możesz kontrolować synchronizację międzyplatformową za pomocą ISteamRemoteStorage::SetSyncPlatforms. Domyślnym zachowaniem dla nowego pliku jest synchronizacja ze wszystkimi platformami.

Jeśli planujesz korzystać ze Steam Auto-Cloud, musisz wiedzieć o kilku kluczowych kwestiach. Po pierwsze, domyślnym zachowaniem dla nowych plików jest synchronizacja tylko ustawienia dla systemu operacyjnego (SO) na powiązanej ścieżce roota dla Auto-Cloud. Oznacza to, że jeśli skonfigurujesz osobne rooty dla każdego systemu operacyjnego, wszystkie pliki zostaną podzielone według platformy i z tego powodu pliki nie będą zapisywane między platformami.

Aby umożliwić międzyplatformowe zapisywanie, powinieneś zdefiniować pojedynczą ścieżkę roota (prawdopodobnie dla systemu Windows), a następnie utworzyć obejścia roota dla innych obsługiwanych platform. Pliki pasujące do danej ścieżki roota, które mają również obejścia roota dla danej platformy, zostaną zsynchronizowane na wszystkich platformach zarówno w oryginalnym roocie, jak i we wszystkich obejściach. Więcej szczegółów znajdziesz w dokumentacji Steam Auto-Cloud.

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 ustawień Steam Cloud w panelu administratora aplikacji Steamworks.

Podanie tych wartości jest wymuszane dla każdej gry z 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 producentó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. Najczęściej używa się tego 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 ma takiej samej elastyczności co API Steam Cloud.

Jeżeli wolisz głębszą integrację ze Steam Cloud (np. pozwoli ci to określić, które pliki zapisów mają być przechowywane w chmurze), to wykorzystaj API Steam Cloud. W przeciwnym wypadku użyj Steam Auto-Cloud.

Steam Auto-Cloud

Steam Auto-Cloud to alternatywa dla API Steam Cloud, która pozwala aplikacjom na korzystanie ze Steam Cloud bez potrzeby pisania kodu lub modyfikowania gry w jakikolwiek sposób. Wymaga ono 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 synchronizowania konfiguracji specyficznych dla danego komputera, np. jakości obrazu.

Konfiguracja

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.
   

   Root	Obsługiwane SO	Odpowiadająca ścieżka
   Folder instalacyjny aplikacji	Wszystkie	[Instalacja Steam]\SteamApps\common\[Folder gry]\
   SteamCloudDocuments	Wszystkie	Ścieżka dla określonej platformy, np. dla systemu Linux: ~/.SteamCloud/[nazwa użytkownika]/[Folder gry]/
   WinMyDocuments	Windows	%USERPROFILE%\Dokumenty\
   WinAppDataLocal	Windows	%USERPROFILE%\AppData\Local\
   WinAppDataLocalLow	Windows	%USERPROFILE%\AppData\LocalLow\
   WinAppDataRoaming	Windows	%USERPROFILE%\AppData\Roaming\
   WinSavedGames	Windows	%USERPROFILE%\Zapisane gry\
   MacHome	macOS	~/
   MacAppSupport	macOS	~/Library/Application Support/
   MacDocuments	macOS	~/Documents/
   LinuxHome	Linux	~/
   LinuxXdgDataHome	Linux	$XDG\_DATA\_HOME/

   
   Uwaga dotycząca ścieżek %USERPROFILE% systemu Windows: odpowiadające ścieżki wymienione powyżej są lokalizacjami domyślnymi. Obecnie użytkownik może skonfigurować instalację systemu Windows tak, by te foldery znajdowały się w różnych lokalizacjach (niekoniecznie w %USERPROFILE%). Steam używa niezbędnych interfejsów API systemu Windows, by znaleźć bieżącą lokalizację tych folderów, niezależnie od tego, czy są one domyślne, czy niestandardowe.
   
   

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 ścieżce podkatalogu. Pozwala to na przechowywanie plików zapisanych gier oddzielnie dla każdego użytkownika Steam na tym samym komputerze. Możesz użyć ISteamUser::GetSteamID w swojej grze, by uzyskać ID Steam lub ID konta obecnego użytkownika i wykorzystać je do zapisywania i odczytywania.
   
   • {64BitSteamID} – użyj tej zmiennej w ścieżce Steam, by 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ć ID konta Steam3 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 wieloznacznika. Jeśli chcesz mieć wszystkie pliki w katalogu, po prostu 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 stanowczo zaleca się użycie specjalnych wartości ścieżki w polu „Podkatalog”.

Obejścia roota

Jeśli twoja aplikacja jest wieloplatformowa i wymaga różnych katalogów dla każdego systemu operacyjnego, możesz użyć funkcji obejść roota, by określić obejście dla ś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ć opcję „[Wszystkie systemy operacyjne]” w wymienionej wyżej liście rozwijanej „SO”.

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 lokalizacja, 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ę

   Zaznaczenie tej opcji 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 na silniku Unity

Poniżej przedstawiono przykład konfiguracji Auto-Cloud z aplikacją napisaną w Unity oraz właściwości Application.persistentDataPath, której wartość 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 wychodzące z Application.persistentDataPath są ustawione w polu „Dodaj/zastąp ścieżkę”, a opcja „Zastąp ścieżkę” jest zaznaczona.

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

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 testappcloudpaths 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 tylko dla producentów oraz opublikować zmiany po zakończeniu testowania.

Dynamiczna synchronizacja z chmurą

Steam Cloud od teraz obsługuje dynamiczną synchronizację – zmiany pojawiające się w chmurze mogą być pobrane na urządzenie lokalne podczas sesji aplikacji. Obecnym przykładem użycia tej funkcji jest wstrzymana sesja gry na Steam Decku. W przypadku aplikacji oznaczonych jako obsługujące dynamiczną synchronizację z chmurą, Steam zsynchronizuje pliki ze Steam Cloud w momencie wstrzymania. Następnie gracz może uruchomić grę na innym urządzeniu, które wtedy otrzyma aktualizację z sesji Steam Decka. Po wyjściu te zmiany zostaną przesłane do Steam Cloud. Na koniec, kiedy Steam Deck zostanie wybudzony, Steam zsynchronizuje zmiany na tym urządzeniu i wywoła odpowiednie powiadomienie informujące o tym, że pliki lokalne zostały zmienione. Aplikacja może następnie wykonać odpowiednie działania na tych zmianach – przykładowo gra może po prostu wczytać zaktualizowany postęp z dysku i umożliwić użytkownikowi kontynuowanie od tego samego miejsca, do którego doszedł na innym urządzeniu.

Sprawdź nasz post z ogłoszeniem, w którym znajduje się jeszcze więcej informacji na temat powodów zaistnienia tej funkcji oraz tego, jak z niej korzystać.

Pamiętaj o tym, że ta funkcja obsługuje aplikacje niezależnie od tego, czy do zarządzania plikami korzystają z API ISteamRemoteStorage, czy ze Steam Auto-Cloud.

Aby dowiedzieć się więcej, sprawdź dokumentację ISteamRemoteStorage, a w szczególności ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount oraz ISteamRemoteStorage::GetLocalFileChange.

Zobacz również ISteamRemoteStorage::BeginFileWriteBatch oraz ISteamRemoteStorage::EndFileWriteBatch – te funkcje opakowujące powinny zostać użyte do dania Steam wskazówek, by pomóc bezpiecznie zsynchronizować dane ze Steam Cloud, gdy użytkownik zainicjuje wstrzymanie systemu.

Testowanie przed opublikowaniem

Możesz lokalnie włączyć dynamiczną synchronizację z chmurą dla swojej aplikacji, by przetestować swoje kompilacje – jest to zalecane w przypadku gry, która została już wydana, ponieważ włączenie dynamicznej synchronizacji z chmurą dla wszystkich użytkowników może doprowadzić do utraty danych podczas korzystania z kompilacji, które nie obsługują nowych metod API i wywołań zwrotnych.

Aby przetestować lokalnie na komputerze:

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. Możesz również uruchomić Steam z wiersza poleceń poprzez steam -console i bezpośrednio przejść do sekcji konsoli.
   
3. Wpisz w konsoli @cloud_testdynamicsyncapp <ID aplikacji> z danym ID aplikacji, którą testujesz. Przykład: @cloud_testdynamicsyncapp 480.
   
4. Uruchom swoją aplikację z poziomu Steam.
   
5. Graj, aż osiągniesz pożądany postęp.
   
6. W konsoli Steam wpisz prepare_for_suspend. Steam wstrzyma proces gry i prześle wszelkie zmienione pliki do Steam Cloud.
   
7. Opcjonalnie: zagraj w grę na innym urządzeniu, osiągając kolejne postępy, a następnie zamknij grę i pozwól, by klient Steam przesłał postęp do Steam Cloud.
   
8. Wróć do pierwszego urządzenia i w konsoli Steam wpisz resume_suspended_games. To działanie zsynchronizuje wszystkie potrzebne pliki ze Steam Cloud oraz wyśle odpowiednie wywołania zwrotne API dla twojej gry, a następnie wznowi proces twojej gry.

Aby przetestować lokalnie na Steam Decku:

1. Podłącz swojego Steam Decka do zestawu deweloperskiego.
   
2. Aby móc użyć konsoli CEF, sprawdź ten link.
   
3. W konsoli JavaScript wpisz SteamClient.Console.ExecCommand("@cloud_testdynamicsyncapp <AppId>"), by włączyć testowanie. Później możesz wpisać SteamClient.Console.ExecCommand("@cloud_testdynamicsyncapp 0"), by je wyłączyć.

Debugowanie

Po pierwsze, zawsze upewnij się, że zmiany zostały opublikowane na stronie partnerskiej Steamworks i że odczekasz nawet 10 minut lub zrestartujesz swojego klienta Steam, by 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, by dowiedzieć się więcej.