Steamworks-dokumentation
Steam Cloud
Kort opsummering
Steam Cloud gemmer automatisk filer fra dit spil på Steams servere, så spillere kan logge på Steam og tilgå deres gemte filer fra en hvilken som helst computer.
Integrering
Konfiguration af filstier kræves på Steamworks-siden. Det er muligt, at der kræves visse API-kald fra spilkoden til Steamworks for at uploade, downloade, optælle og slette.

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.

Spacewar_Cloud_Properties.png

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ørrelseRestriktion
100 MBMaks. størrelse for at kalde til ISteamRemoteStorage::FileWrite eller ISteamRemoteStorage::FileWriteStreamWriteChunk
256 MBKan resultere i lagring, som ikke er optimal, for brugerens valg af placering, og dermed negativt påvirke ydeevnen af upload og download

Indledende opsætning

For at opsætte Steam Cloud skal du indstille 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 to forskellige metoder til brug af 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.
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 clouden), 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 Cloud. Steam synkroniserer automatisk filgrupperne, når applikationen startes og afsluttes. Undgå maskinspecifikke konfigurationer såsom videokvalitet.
Bemærk: Filen steam_autocloud.vdf bliver oprettet på hver placering angivet af dine Cloud-stier for Steamworks. Denne fil bruges af Steam og kan ignoreres af dit spil.

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.
    RodUnderstøttede OS'erTilsvarende sti
    Applikationens installationsmappeAlle[Steam Install]\SteamApps\common\[Game Folder]\
    SteamCloudDocumentsAllePlatformsspecifik sti, for eksempel på Linux: ~/.SteamCloud/[brugernavn]/[spilmappe]/
    WinMyDocumentsWindows%USERPROFILE%\Dokumenter\
    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. 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 Steam 3-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 kan spilles på tværs af platforme og kræver forskellige mapper for hvert OS. Du kan 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.

Cloud_Unity_Auto-Cloud_Example.png

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

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 Fejlfinding i Steamworks-API'en for additional information.