Oversigt over Steam Cloud

Steam Cloud giver et simpelt og overskueligt system til ekstern lagring af filer til dit spil. Filer, der er angivet i Auto-Cloud-konfigurationen eller er skrevet til disken (oprettet, ændret, slettet osv.) med Cloud-API'en, kopieres automatisk til Steam-serverne, når spillet forlades.

Hvis brugeren skifter til en anden computer, downloades filerne automatisk til den nye computer, inden spillet startes. Spillet kan derefter tilgå filerne ved at læse dem via Cloud-API'en eller læse dem direkte fra disken som sædvanligt. Undgå maskinspecifikke konfigurationer såsom videoindstillinger.

Steam-klienten sørger for, at filerne altid er synkroniserede på tværs af alle computere, som brugeren benytter.

Brugere kan slå Cloud-synkronisering fra globalt i Steam-indstillingerne under "Cloud" ved at fjerne markeringen i "Slå Steam Cloud-synkronisering til i applikationer, som understøtter det".

Brugere kan også slå Cloud-synkronisering fra for individuelle spil i egenskaberne i hvert spil.

Noter og anbefalede metoder

Det er vigtigt at huske, at Steam synkroniserer brugerens Steam Cloud-filer til dit spil før og efter hver spilsession. Alle matchende filer, som ændres under spilsessionen, uploades til Cloud-lagret med det samme, efter spillet er afsluttet. Hvis dit spil gemmer store filer eller mange små i Steam Cloud, kan dette påvirke brugerens internetbåndbredde betydeligt og kan også forårsage forsinkelse, hvis de prøver på at genstarte spillet eller lukke Steam.

Som en generel regel fungerer mindre filer bedst. Hvis den gemte tilstand for en given bruger kan deles op i forskellige kategorier – såsom ting, der ændres ofte, og ting, som ikke ændres ofte – så anbefaler vi at bruge adskilte filer til disse kategorier. På den måde vil tilstande, som ikke er ændret, ikke skulle uploades igen efter hver spilsession.

Maks. filstørrelse

Den absolutte grænse på filstørrelser til Steam Cloud kan ændres med tiden. Her er nogle af de aktuelle grænser og tærskler:

Størrelse	Restriktion
100 MB	Maks. størrelse for at kalde til ISteamRemoteStorage::FileWrite eller ISteamRemoteStorage::FileWriteStreamWriteChunk
256 MB	Kan resultere i lagring, som ikke er optimal, for brugerens valg af placering, og dermed negativt påvirke ydeevnen af upload og download

Stier til gemte filer

Når du skal vælge, hvor de gemte filer skal lagres, skal du sørge for, at stien er unik for den aktuelle Steam-bruger. Om nødvendigt kan brugerens entydige Steam-ID hentes via ISteamUser::GetSteamID. Derfra kan du tilgå brugerens accountID fra GetAccountID(), så du får en unik variabel, når du opretter lagringsstien.

Gemme spil på tværs af platforme

Hvis dit spil understøttes på flere platforme – eller du planlægger at understøtte dette i fremtiden – bør du tage det med i dine betragtninger, når du konfigurerer Steam Cloud for spillet.

Hvis du planlægger at læse/skrive filer direkte via grænsefladen ISteamRemoteStorage, kan du styre platformssynkroniseringen via ISteamRemoteStorage::SetSyncPlatforms. Som udgangspunkt synkroniseres nye filer til alle platforme.

Hvis du planlægger at bruge Steam Auto-Cloud, er der nogle vigtige ting, du skal vide. For det første er standarden for nye filer kun at synkronisere til OS-indstillingen på den tilhørende rodsti for Auto-Cloud. Dette betyder, at hvis du opsætter forskellige rødder for hvert OS, partitioneres alle filer efter platform, og derfor vil det ikke være muligt at gemme på tværs af platforme.

For at gøre det muligt for brugere at gemme spil på tværs af platforme skal du i stedet definere en enkelt rodsti (nok for Windows) og derefter oprette rodtilsidesættelser for de andre understøttede platforme. Filer, som matcher en given rodsti, som også har rodtilsidesættelser, vil blive synkroniseret til alle platforme i både den oprindelige rod og alle tilsidesættelser. Læs mere i dokumentationen om Steam Auto-Cloud.

Indledende opsætning

For at konfigurere Steam Cloud skal du konfigurere indstillingerne Byte-kvote per bruger og Antal filer tilladt per bruger på siden Steam Cloud-indstillinger i panelet "App-administrator" i Steamworks.

Denne kvote gennemtvinges på hvert Cloud-aktiverede spil for hver individuelle bruger for hvert individuelle spil. Vi anbefaler, at du angiver rimelige værdier for dit spil.

BEMÆRK: Husk at klikke på "Gem" nederst på siden og udgive de opdaterede indstillinger. Når de er udgivet, kan alle, der ejer dit spil, se Cloud-ikonet i Steam-klienten.

Hvis dit spil allerede er udgivet til offentligheden, kan du markere feltet Slå kun Cloud-support til for udviklere. Hvis udviklertilstanden er slået til, er det kun Steam-konti, som ejer en "Udviklerpakke"-licens til dit spil, som vil se Cloud-ikonet og kunne bruge Steam Cloud. Dette er nyttigt til sikker testning af Steam Cloud-integrationen uden at ødelægge offentlighedens brugeroplevelse. Det har ingen betydning for ikke-udgivne spil, eftersom ingen ejer spillene endnu. Ingen vil kunne se eller tilgå Cloud-lageret for det specifikke app-ID.

Du kan dele Cloud-lagerplads mellem to app-ID'er ved at udfylde feltet Delt Cloud-app-ID. Dette bruges oftest til at dele gemte spil mellem en demo og et komplet spil. Værdien 0 slår denne funktion fra.

Steam Cloud-API og Steam Auto-Cloud

Steam giver dig to forskellige metoder til at bruge Steam Cloud. Læs, hvordan de to metoder adskiller sig fra hinanden, og beslut, hvilken der er bedst til din applikation.

Den første er Steam Cloud-API'en.
Cloud-API'en har en række funktioner, som gør det muligt for dig at integrere Steam Cloud direkte i dit spil. Cloud-API'en isolerer individuelle Steam-brugeres filer fra hinanden og giver en højere grad af kontrol over Steam Cloud.

Steam Cloud-API'en er synlig via API-grænsefladen ISteamRemoteStorage, og du kan finde eksempler på brug i projektet Steamworks-API-eksempel på applikation (SpaceWar).

Den anden er Steam Auto-Cloud.
Steam Auto-Cloud er udviklet til spil, hvor du vælger ikke at integrere Steam Cloud-API'en. Denne metode giver en hurtig og nem måde at komme i gang på, men mangler den fleksibilitet, som Steam Cloud-API'en tilbyder.

Hvis du foretrækker en dybere integration med Steam Cloud (for eksempel hvis du vil tillade, at brugeren vælger, hvilke filer der gemmes i skyen), så bør du bruge Cloud-API'en. Ellers kan du bruge Steam Auto-Cloud.

Steam Auto-Cloud

Steam Auto-Cloud er et alternativ til Steam Cloud-API'en, som gør det muligt for apps at bruge Steam Cloud uden at skrive kode eller modificere spillet på nogen måde. Det kræver kun, at du angiver de filgrupper, der skal gemmes i skyen. Steam synkroniserer automatisk filgrupperne, når applikationen startes og afsluttes. Undgå maskinspecifikke konfigurationer såsom videokvalitet.

Opsætning

Når du er færdig med den indledende opsætning, åbnes sektionen Steam Auto-Cloud-konfiguration på siden Steam Cloud-indstillinger.

Rodstier beskriver filgrupper, som gemmes i Steam Cloud. Hver rodsti kan være så specifik som en enkelt fil eller så bred som alle filer i en given undermappe. Brug en ny sti for hver filgruppe, der skal synkroniseres.

En rodsti består af fem dele:

1. Rod

   Dette er en forudbestemt liste over stier, hvor gemte spil almindeligvis findes.
   

   Rod	Understøttede OS'er	Tilsvarende sti
   Applikationens installationsmappe	Alle	[Steam-installation]\SteamApps\common\[spilmappe]\
   SteamCloudDocuments	Alle	Platformsspecifik sti, for eksempel på Linux: ~/.SteamCloud/[brugernavn]/[spilmappe]/
   WinMyDocuments	Windows	%USERPROFILE%\Dokumenter\
   WinAppDataLocal	Windows	%USERPROFILE%\AppData\Local\
   WinAppDataLocalLow	Windows	%USERPROFILE%\AppData\LocalLow\
   WinAppDataRoaming	Windows	%USERPROFILE%\AppData\Roaming\
   WinSavedGames	Windows	%USERPROFILE%\Saved Games\
   MacHome	macOS	~/
   MacAppSupport	macOS	~/Library/Application Support/
   MacDocuments	macOS	~/Documents/
   LinuxHome	Linux	~/
   LinuxXdgDataHome	Linux	$XDG\_DATA\_HOME/

   
   Bemærk angående stier med %USERPROFILE%: De tilsvarende stier angivet ovenfor er standardlokationerne. Det er nu muligt for brugeren at konfigurere sin egen Windows-installation, så disse mapper befinder sig i andre lokationer (dvs. ikke nødvendigvis under %USERPROFILE%). Steam bruger de nødvendige Windows-API'er til at finde den nuværende lokation af mapperne, uanset om det er standardlokationen eller en brugerdefineret lokation.
   
   

2. Undermappe

   Undermappestien til filerne i skyen i forhold til roden. Brug ".", hvis der ikke er en undermappe.
   
   Særlige stiværdier i Auto-Cloud
   Auto-Cloud giver mulighed for at bruge unikke ID'er for Steam-brugere i Undermappe-stien. På denne måde kan du lagre gemte filer separat for hver Steam-bruger på computeren. Du kan bruge ISteamUser::GetSteamID i dit spil for at få den aktuelle brugers SteamID eller AccountIDsave til at gemme til og læse fra.
   
   • {64BitSteamID} – Brug denne variabel i Steam-stien til at indsætte brugerens 64-bit Steam-ID. Et 64-bit Steam-ID ser således ud: 76561198027391269
     
   • {Steam3AccountID} – Brug denne variabel i Steam-stien til at indsætte brugerens Steam3-konto-ID. Et konto-ID ser således ud: 67125541
     
   Eksempel: SavesDir/{64BitSteamID}
   

3. Mønster

   Filmaskemønster, der skal matches. Du kan bruge * som jokertegn. Hvis du vil have alle filer i mappen, skal du bruge *.
   
   Eksempel: *.sav
   

4. OS

   Angiver de operativsystemer, som disse filer vil blive synkroniseret fra/til. Dette er kun nødvendigt, hvis filerne er OS-specifikke, hvilket forhåbentligt ikke er tilfældet!
   

5. Rekursiv

   Medtag undermapper, når du søger efter matchende filer. Dette er nyttigt i forbindelse med undermapper med ikke-deterministiske navne såsom brugernavne eller ID'er, der ikke er fra Steam. Hvis der anvendes et Steam-ID, anbefaler vi kraftigt at bruge de særlige stiværdier i feltet "Undermappe".

Tilsidesættelse af rod

Hvis din applikation understøtter flere platforme og kræver forskellige mapper for hvert operativsystem, kan du bruge rodtilsidesættelsesfunktionen til at angive en tilsidesættelse af de rodstier, du har angivet ovenfor.

Rodstierne, som er angivet ovenfor, kan tilsidesættes for at svare til en anden sti på et andet OS. Hvis du bruger rodtilsidesættelser, skal du angive [Alle operativsystemer] i Rod-OS-rullemenuen ovenfor.

En rodtilsidesættelse består af fem dele.

1. Oprindelig rod

   Dette svarer til en af de rødder, du har angivet ovenfor.
   

2. OS

   Det operativsystem, som tilsidesættelsen skal gælde for.
   

3. Ny rod

   Den nye placering, som den oprindelige rod er tilknyttet på det angivne OS.
   

4. Tilføj/erstat sti

   Dette giver dig mulighed for at tilføje en undermappesti, som indsættes mellem den nye rod og den oprindelige undermappe.
   

5. Erstat sti

   Hvis dette er slået til, erstatter stien angivet i "Tilføj/erstat sti" den oprindelige undermappe fuldstændigt.

Eksempel: Konfiguration af Auto-Cloud til Unity-applikationer

Følgende er et eksempel på konfiguration af Auto-Cloud til brug med Unity og egenskaben Application.persistentDataPath, hvor værdien er forskellig for hvert OS. Windows-versionen er konfigureret som rodstien med firmaet i Unity angivet til DefaultCompany og projektet AutocloudSample. På macOS og Linux/SteamOS angives de alternative stier fra Application.persistentDataPath i feltet "Tilføj/erstat sti", og "Erstat sti" markeres.

Med disse indstillinger vil Auto-Cloud-filerne blive synkroniseret mellem de tre mapper som vist i eksemplerne.

Testning inden udgivelse

Hvis du tilføjer Steam Auto-Cloud til et spil, som allerede er udgivet, og du har slået udviklertilstanden til under den indledende opsætning, skal du udføre nogle ekstra trin for at teste funktionaliteten.

1. Log på Steam med en konto, som ejer appen, du tester.
   
2. Åbn Steam-konsollen ved at navigere til steam://open/console i din browser.
   
3. Indtast testappcloudpaths <AppId> i konsollen med det app-ID, som du vil teste. Eksempel: testappcloudpaths 480
   
4. Indtast set_spew_level 4 4 i konsollen.
   
5. Start din app fra Steam.
   
6. Kontrollér, om der er aktivitet i konsollen. Hvis der i forvejen er filer i Auto-Cloud-stierne, burde du se, at de bliver uploadet. Eller gem nogle filer fra din app, og luk den for at udløse synkroniseringen.
   
7. Gå til en anden PC, og gentag trinene ovenfor for at teste download af filerne fra Steam Auto-Cloud.
   
8. Sørg for at teste det på alle understøttede operativsystemer.
   
9. Indstil testappcloudpaths 0 og set_spew_level 0 0 for at afslutte testningen. Du kan genstarte Steam-klienten for at få konsolfanen væk.

Glem ikke at slå udviklertilstanden fra og udgive ændringerne, når du er færdig med at teste.

Dynamisk Cloud-synkronisering

Steam Cloud understøtter dynamisk synkronisering, hvor ændringerne, der vises i skyen, kan downloades til den lokale maskine under en programsession. Det aktuelle eksempel er en afbrudt spilsession på Steam Deck. For apps, der er mærket med understøttelse af dynamisk Cloud-synkronisering, synkroniserer Steam filer op til Steam Cloud på afbrydelsestidspunktet. Derefter kan brugeren køre spillet på en anden enhed, som modtager opdateringerne fra Steam Deck-sessionen ved opstart. Når spillet afsluttes, uploades ændringerne til Steam Cloud. Når Steam Deck-enheden vækkes igen, synkroniserer Steam ændringerne til den pågældende enhed og sender en notifikation til applikationen om, at lokale filer er blevet ændret. Applikationen kan så lave iterationer på ændringerne og handle derefter. For eksempel kan spillet måske blot indlæse det opdaterede fremskridt fra disken og lade brugeren fortsætte, hvor vedkommende slap, på en anden enhed.

Læs vores blogindlæg for at få endnu mere at vide om, hvorfor denne funktion eksisterer, og hvordan man bruger den.

Bemærk, at denne funktion understøtter applikationer, uanset om de bruger API'en ISteamRemoteStorage til at administrere filer eller Auto-Cloud.

Se dokumentationen om ISteamRemoteStorage for nærmere oplysninger, særligt ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount og ISteamRemoteStorage::GetLocalFileChange.

Se også ISteamRemoteStorage::BeginFileWriteBatch og ISteamRemoteStorage::EndFileWriteBatch – brug disse wrappere til at give hints til Steam, som hjælper det med at synkronisere korrekt til Steam Cloud, når brugeren midlertidigt stopper systemet.

Testning inden udgivelse

Du kan aktivere dynamisk Cloud-synkronisering for din app for at teste dine builds. Dette anbefales for spil, som allerede er udgivet, da det kan medføre datatab, hvis dynamisk Cloud-synkronisering aktiveres for alle brugere, og man kører builds, som ikke kan håndtere de nye API-metoder og tilbagekald.

Lokal testning fra en PC:

1. Log på Steam med en konto, som ejer appen, du tester.
   
2. Åbn Steam-konsollen ved at navigere til steam://open/console i din browser. (Du kan også køre Steam med kommandolinjen steam -console og derefter navigere til sektionen "Konsol" direkte).
   
3. Indtast @cloud_testdynamicsyncapp <AppId> i konsollen med det app-ID, som du vil teste. Eksempel: @cloud_testdynamicsyncapp 480
   
4. Start din app fra Steam.
   
5. Spil dig frem til det ønskede punkt i spillet.
   
6. Indtast prepare_for_suspend i Steam-konsollen. Steam afbryder dine spilfremskridt og uploader filer, der er blevet ændret, til Steam Cloud.
   
7. Valgfrit: Spil spillet på en anden enhed, så du får flere fremskridt, og afslut og lad den Steam-klient uploade fremskridt til Steam Cloud.
   
8. Tilbage på den oprindelige enhed skal du indtaste resume_suspended_games i Steam-konsollen. Dette synkroniserer de nødvendige filer fra Steam Cloud, sender de relevante API-kald til spillet og stopper afbrydelsen af dine spilfremskridt.

Lokal testning fra Steam Deck:

1. Opret forbindelse fra din Steam Deck til en Devkit
   
2. Brug CEF Console. Se her.
   
3. I JS-konsollen skal du indtaste SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppId>”) for at aktivere testning. Du kan indtaste SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”) for at deaktivere det.

Fejlfinding

Først skal du sørge for, at du har udgivet dine ændringer på Steams partnerwebsted. Vent ca. 10 minutter, eller genstart Steam-klienten for at få de udgivne ændringer.

Hvis du løber ind i problemer med Steam Cloud, skal du tjekke logfilen i %Steam Install%\logs\cloud_log.txt.

Se Fejlfinding i Steamworks-API'en for at få yderligere oplysninger.