Steamworks-dokumentaatio
Steam Cloud
Lyhyesti
Steam Cloud tallentaa pelitiedostot automaattisesti Steamin palvelimille. Näin pelaajat voivat kirjautua Steamiin ja palata tallennettuihin peleihin miltä tahansa tietokoneelta.
Integraation taso
Steamworksin verkkosivun vaatimat tiedostopolkujen määritykset. Lähetys, lataus, luettelointi ja poisto vaativat jotain ohjelmointirajapinnan kutsuja pelikoodista Steamworksiin. (Tämä on valinnainen toiminto.)

Yleiskatsaus Steam Cloud -pilvipalveluun

Steam Cloud tarjoaa pelillesi helpon ja läpinäkyvän tiedostojen etätallennusjärjestelmän. Auto-Cloudin asetuksissa määritetyt tai Cloud-ohjelmointirajapintaa käyttävällä levylle kirjoitetut (luodut, muokatut, poistetut jne.) tiedostot kopioidaan automaattisesti Steamin palvelimille pelin sulkemisen jälkeen.

Jos käyttäjä siirtyy toiselle tietokoneelle, tiedostot ladataan automaattisesti uudelle koneelle ennen pelin käynnistystä. Peli pääsee tiedostoihin lukemalla ne Cloud-ohjelmointirajapinnan avulla tai suoraan kovalevyltä. Vältä tekemästä laitekohtaisia määrityksiä, kuten videoasetuksia.

Steam-asiakasohjelma varmistaa, että tiedostot synkronoidaan kaikille käyttäjän tietokoneille.

Käyttäjä voi poistaa Cloud-synkronoinnin käytöstä kaikista peleistä valitsemalla Steamissä Asetukset > Cloud ja poistamalla valinnan kohdasta Ota Steam Cloud -synkronointi käyttöön sitä tukeville sovelluksille.

Cloud-synkronoinnin voi poistaa käytöstä myös yksittäisistä peleistä pelin ominaisuuksista.

Spacewar_Cloud_Properties.png

Huomioita ja parhaita käytäntöjä


On tärkeää muistaa, että Steam synkronoi käyttäjän pelin Steam Cloud -tiedostot ennen jokaista sessiota ja sen jälkeen. Session aikana muuttuneet yhteensopivat tiedostot lähetetään Cloudiin välittömästi pelin jälkeen. Jos peli tallentaa Steam Cloudiin hyvin suuria tai monia pieniä tiedostoja, tämä voi vaikuttaa selvästi kaistanleveyteen ja viivästyttää Steamin sulkemista tai pelin uudelleen käynnistystä.

Yleisesti ottaen pienemmät tiedostot toimivat paremmin. Kannattaa käyttää erillisiä tiedostoja, jos tietyn käyttäjän tallennettu pelitila voidaan jakaa luokkiin, kuten usein muuttuviin ja harvoin muuttuviin tiloihin. Näin muuttumatonta tilaa ei lähetetä joka session jälkeen uudelleen.

Tiedostokoon rajat


Steam Cloudin tiedostokokojen rajat voivat muuttua. Tässä tämänhetkiset rajat ja kynnykset:

KokoRaja
100 MtEnimmäiskoko ISteamRemoteStorage::FileWrite- tai ISteamRemoteStorage::FileWriteStreamWriteChunk-kutsulle
256 MtSaattaa aiheuttaa käyttäjän tilan tallennuspaikkavalinnan, joka ei ole optimaalinen, mikä saattaa heikentää lähetys- ja lataussuorituskykyä

Tallenna tiedostopolut

Kun päätät tiedostojen tallennuspaikan, varmista, että polku on uniikki nykyiselle Steam-käyttäjälle. Voit tarvittaessa hakea käyttäjän uniikin SteamID-tunnuksen ISteamUser::GetSteamID-jäsenfunktiolla. Saat käyttäjän AccountID-tunnuksen GetAccountID()-jäsenfunktion kautta, jolloin sinulla voi olla uniikki muuttuja, kun luot tallennuspolkua.

Alustojen välinen tallentaminen


If your game is supported on multiple platforms - or even if you plan to support this in the future - you should consider this when setting up Steam Cloud for your game.

If you plan to read/write files directly via the ISteamRemoteStorage interface, then you can control platform sync via ISteamRemoteStorage::SetSyncPlatforms. The default for a new file is to sync to all platforms.

If you plan to use Steam Auto-Cloud, there are some key things to know. First, the default for new files is to sync to only the OS setting on the associated Auto Cloud Root path. This means that if you set up distinct roots for each OS, all files will be partitioned by platform, and hence there will be no cross-platform save functionality.

To enable cross-platform saves, you should instead define a single Root path (likely for Windows), and then create Root Overrides for the other supported platforms. Files matching a given Root path which also has platform Root Overrides will sync to all platforms in both the origianal Root and all Overrides. See the Steam Auto-Cloud documentation for more details.

Määritys

Asenna Steam Cloud määrittämällä Tavukiintiö per käyttäjä ja Sallittu tiedostojen lukumäärä per käyttäjä Steam Cloud -asetuksissa Steamworksin sovellushallintapaneelissa.

Kiintiötä sovelletaan jokaiseen Cloudia käyttävään peliin jokaista käyttäjää ja peliä kohden. Arvot kannattaa asettaa järkevälle tasolle.

Huomaa! Muista klikata Tallenna-painiketta sivun alalaidassa ja julkaista päivitetyt asetukset. Julkaisun jälkeen Cloud-kuvake näkyy Steam-asiakasohjelmassa kaikille, jotka omistavat pelin.

Jos peli on jo julkaistu, voi valita Ota Cloud-tuki käyttöön ainoastaan kehittäjille. Vain kehittäjille -tilan ollessa käytössä Cloud-kuvake näkyy vain Steam-tileille, jotka omistavat pelin Developer Comp -lisenssin. Vain nämä tilit voivat siis käyttää Steam Cloudia. Se on hyvä tapa testata Steam Cloud -integraatiota vaikuttamatta julkiseen peliin. Se ei vaikuta mitenkään julkaisemattomiin peleihin, sillä kukaan ei omista peliä vielä, eikä sovellustunnuksen Cloud-tallennustilaa näe tai pääse käyttämään kukaan.

Cloud-tallennustilan voi jakaa kahden sovellustunnuksen kesken täyttämällä kentän Jaettu Cloud-sovellustunnus. Näin toimitaan useimmiten, kun jaetaan tallennetut pelit demon ja täysjulkaisun kesken. Arvo 0 poistaa toiminnon käytöstä.

Steam Cloud -ohjelmointirajapinta ja Steam Auto-Cloud

Steam tarjoaa kaksi tapaa hyödyntää Steam Cloudia. Lue lisätietoja niiden eroista ja valitse sovelluksellesi paras vaihtoehto.

Steam Cloud -ohjelmointirajapinta
Cloud-ohjelmointirajapinnan toimintojen avulla voit integroida Steam Cloudin suoraan peliin. Cloud-ohjelmointirajapinta erottelee Steam-käyttäjien tiedostot toisistaan ja tarjoaa Steam Cloudin paremman hallinnan.

Steam Cloud -ohjelmointirajapinta näkyy ISteamRemoteStorage-ohjelmointirajapinnan käyttöliittymän kautta. Esimerkkejä käytöstä löytyy Steamworks API Example Application (SpaceWar) -projektista.

Steam Auto-Cloud
Steam Auto-Cloud on tarkoitettu peleille, joihin ei integroida Steam Cloud -ohjelmointirajapintaa. Se on nopea ja helppo tapa päästä alkuun, mutta siitä puuttuu Steam Cloud -ohjelmointirajapinnan tarjoama joustavuus.

Jos haluat syvempää integraatiota Steam Cloudiin (esimerkiksi mahdollisuuden valita, mitkä tiedostot tallennetaan Cloudiin), käytä Cloud-ohjelmointirajapintaa. Muutoin voit käyttää Steam Auto-Cloudia.

Steam Auto-Cloud

Steam Auto-Cloud on vaihtoehto Steam Cloud -ohjelmointirajapinnalle. Sen avulla sovellukset voivat käyttää Steam Cloudia ilman, että sinun pitää kirjoittaa koodia tai muokata pelitiedostoja. Sinun täytyy vain määrittää tiedostoryhmät, jotka haluat tallennettavan jatkuvasti Cloudiin. Steam synkronoi automaattisesti tiedostoryhmät, kun sovellus käynnistetään tai suljetaan. Vältä tekemästä laitekohtaisia määrityksiä, kuten videoasetuksia.
Huomaa! steam_autocloud.vdf-tiedosto luodaan jokaiseen Steamworksin pilvipolussa määritettyyn sijaintiin. Steam käyttää tätä tiedostoa, ja pelit voivat jättää sen huomiotta.

Määritys

Kun Määritys on tehty, Steam Auto-Cloud -määritysosio avaa Steam Cloud -asetukset.

Juuripolut kertovat tiedostoryhmät, jotka tallennetaan Steam Cloudiin. Kukin juuripolku voidaan määrittää yksittäisenä tiedostona tai tietyn alihakemiston kaikissa tiedostoissa. Käytä uutta polkua jokaiselle synkronoitavalle tiedostoryhmälle.

Juuripolku koostuu viidestä osasta:
  1. Juuri

    Tämä on ennalta määritetty lista poluista, joissa pelitallenteet yleensä sijaitsevat.
    JuuriTuetut käyttöjärjestelmätVastaava polku
    Sovelluksen asennushakemistoKaikki[Steam Install]\SteamApps\common\[pelikansio]\
    SteamCloudDocumentsKaikkiAlustakohtainen polku, esim. Linuxissa: ~/.SteamCloud/[käyttäjänimi]/[pelikansio]/
    WinMyDocumentsWindows%USERPROFILE%\Omat tiedostot\
    WinAppDataLocalWindows%USERPROFILE%\AppData\Local\
    WinAppDataLocalLowWindows%USERPROFILE%\AppData\LocalLow\
    WinAppDataRoamingWindows%USERPROFILE%\AppData\Roaming\
    WinSavedGamesWindows%USERPROFILE%\Tallennetut pelit\
    MacHomemacOS~/
    MacAppSupportmacOS~/Library/Application Support/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/
  2. Alihakemisto

    Juureen liittyvä pilvipalvelun tiedostojen alihakemistopolku. Käytä ".", jos alihakemistoa ei ole.

    Auto-Cloudin erityiset polkuarvot
    Auto-Cloud mahdollistaa ainutlaatuisten Steam-käyttäjätunnusten hyödyntämisen alihakemistopolussa. Tämän ansiosta voit tallentaa kunkin Steam-käyttäjän tallennustiedostoja erikseen tietokoneelle. Voit käyttää ISteamUser::GetSteamID-jäsenfunktiota pelissä, jotta voit hakea nykyisten käyttäjien SteamID- tai AccountID-tunnuksen, jotta voit tallentaa ja lukea niihin tietoja.
    • {64BitSteamID} – Voit lisätä käyttäjien 64-bittisen SteamID-tunnuksen käyttämällä tätä muuttujaa Steam-polussa. 64-bittinen SteamID-tunnus näyttää tältä: 76561198027391269
    • {Steam3AccountID} – Voit lisätä käyttäjien 3-bittisen Steam-tilitunnuksen käyttämällä tätä muuttujaa Steam-polussa. Tilitunnus näyttää tältä: 67125541
    Esimerkki: SavesDir/{64BitSteamID}
  3. Malli

    Tiedostomaskimalli tiedostojen vastaavuuteen. Voit käyttää *-merkkiä yleismerkkinä. Jos haluat kaikki hakemiston tiedostot, käytä *-merkkiä.

    Esimerkki: *.sav
  4. Käyttöjärjestelmä

    Määrittää käyttöjärjestelmät, joihin/joista nämä tiedostot synkronoidaan. Tämä vaaditaan vain, jos tiedostot ovat käyttöjärjestelmäkohtaisia, mikä ei ole toivottavaa.
  5. Rekursio

    Sisällytä alikansiot, kun haet vastaavia tiedostoja. Tästä on hyötyä, jos alihakemistoissa on ei-deterministisiä nimiä, kuten muita kuin Steamin käyttäjänimiä tai tunnuksia. Jos se käyttää SteamID-tunnusta, erityisten polkujen arvojen käyttäminen Alihakemisto-kentässä on suositeltavaa.

Juuren ohitukset

Jos sovellus on järjestelmäriippumaton ja vaatii eri hakemistot eri käyttöjärjestelmille. Voit käyttää juuren ohitus -toimintoa määrittääksesi ohituksen juuripoluille, jotka määritit yllä.

Yllä määritetyt juuripolut voidaan ohittaa, jotta ne vastaavat eri polkua toisessa käyttöjärjestelmässä. Jos käytät juuren ohitusta, sinun tulee määrittää juurten käyttöjärjestelmän pudotusvalikosta [Kaikki käyttöjärjestelmät].

Juuren ohitus koostuu viidestä osasta.
  1. Alkuperäinen juuri

    Tämä vastaa yhtä edellä määritetyistä juurista.
  2. Käyttöjärjestelmä

    Käyttöjärjestelmä, johon ohitusta sovelletaan.
  3. Uusi juuri

    Uusi sijainti, johon alkuperäinen juuri linkittää määritetyssä käyttöjärjestelmässä.
  4. Lisää tai korvaa polku

    Tämän avulla voit halutessasi lisätä alihakemistopolun, joka lisätään uuden juuren ja alkuperäisen alihakemiston väliin.
  5. Korvaa polku

    Jos tämä on valittuna, Lisää tai korvaa polku -kentässä määritelty polku korvaa alkuperäisen alihakemiston kokonaan.

Esimerkki: Auto-Cloudin määrittäminen Unity-sovelluksille

Tässä on esimerkki Auto-Cloud määrittämisestä Unityn käyttöön ja Application.persistentDataPath-ominaisuus, jossa eri käyttöjärjestelmissä on eri arvo. Windows-versio on määritetty juuripoluksi. Siinä yritykseksi Unityssä on määritetty DefaultCompany ja projektiksi AutocloudSample. MacOS:lle ja Linux/SteamOS:lle Application.persistentDataPath-ominaisuuden vaihtoehtoiset polut on määritetty Lisää tai korvaa polku -kentässä ja Korvaa polku -valintaruutu on valittuna.

Näillä asetuksilla Auto-Cloud-tiedostot synkronoidaan kolmen kansion välillä, kuten Esikatselu-esimerkistä näkyy.

Cloud_Unity_Auto-Cloud_Example.png

Julkaisua edeltävä testaus

Jos lisäät Steam Auto-Cloudin jo julkaistuun peliin, johon olet ottanut kehittäjätilan käyttöön Määritys -vaiheessa, sinun pitää suorittaa ylimääräisiä vaiheita, jotta voit testata toimintoa.
  1. Kirjaudu Steamiin tunnuksella, joka omistaa testattavan sovelluksen.
  2. Avaa Steam-konsoli siirtymällä selaimella osoitteeseen: steam://open/console.
  3. Syötä konsoliin testappcloudpaths <AppId>, ja korvaa AppID-kohta testattavan sovelluksen sovellustunnuksella. Esimerkiksi testappcloudpaths 480.
  4. Anna komentoriville: set_spew_level 4 4.
  5. Käynnistä sovellus Steamistä.
  6. Tarkista aktiivisuus konsolista. Jos tiedostot näkyvät jo Auto-Cloud-poluissa, niiden latauksen pitäisi olla käynnissä. Jos näin ei ole, käynnistä synkronointi tallentamalla joitakin tiedostoja sovelluksestasi ja sulkemalla se sitten.
  7. Testaa tiedostojen latauksen onnistuminen Steamin Auto-Cloudista siirtymällä toiselle PC:lle ja toistamalla edellä olevat vaiheet.
  8. Suorita testaus kaikilla tuetuilla käyttöjärjestelmillä.
  9. Lopeta testaus määrittämällä arvot testappcloudpaths 0 ja set_spew_level 0 0. Käynnistä Steam-sovellus uudelleen, jos haluat konsoli-välilehden pois näkyvistä.

Muista ottaa kehittäjätila pois käytöstä ja julkaista muutokset, kun testaus on suoritettu loppuun.

Dynaaminen Cloud-synkronointi


Steam Cloud tukee nyt dynaamista synkronointia. Siinä Cloudissa näkyvät muutokset voidaan ladata paikalliselle koneelle, kun sovellus on käynnissä. Esimerkiksi, kun pelisessio on keskeytetty Steam Deckillä. Dynaamista Cloud-synkronointia tukevissa sovelluksissa Steam synkronoi tiedostot Steam Cloudiin sovelluksille, kun peli keskeytetään. Käyttäjä voi silloin pyörittää peliä toisella laitteella, joka saa pelin käynnistyessä Steam Deck -istunnon päivitykset. Muutokset lähetetään Steam Cloudiin, kun peli suljetaan. Kun Steam Deck -laite on jälleen käytössä, Steam synkronoi muutokset laitteelle ja julkaisee sovellukseen ilmoituksen, että paikalliset tiedostot ovat muuttuneet. Sovellus voi sitten iteroida kyseiset muutokset ja tehdä tarvittavat toimet. Peli voi esimerkiksi ladata päivitetyn edistymisen levyltä ja antaa käyttäjän jatkaa siitä, mihin hän jäi toisella laitteella.

Lue blogijulkaisu aiheesta ja lisätietoa toiminnon olemassaolosta ja sen käytöstä.

Huomaa, että tämä toiminto tukee sovelluksia, jos ne käyttävät tiedostojen hallinnointiin ISteamRemoteStorage-ohjelmointirajapintaa tai Auto-Cloudia.

Lisätietoja löytyy ISteamRemoteStorage-dokumentaatiosta, erityisesti seuraavista: ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount ja ISteamRemoteStorage::GetLocalFileChange.

Katso myös ISteamRemoteStorage::BeginFileWriteBatch ja ISteamRemoteStorage::EndFileWriteBatch – näitä paketoijia pitäisi käyttää tarjoamaan Steamille vihjeitä, jotka auttavat sitä synkronoimaan turvallisesti Steam Cloudiin, kun käyttäjä laittaa järjestelmän lepotilaan.

Julkaisua edeltävä testaus


Koontiversioista testataksesi voit ottaa dynaamisen Cloud-synkronoinnin sovelluksellesi käyttöön paikallisesti. Tätä suositellaan jo julkaistuille peleille, sillä dynaamisen Cloud-synkronoinnin käyttöön ottaminen kaikille käyttäjille voi johtaa tietojen menetykseen, kun pyöritetään koontiversioista, jotka eivät käsittele uusia ohjelmointirajapintametodeja ja takaisinkutsuja.

Testaa paikallisesti tietokoneelta:

  1. Kirjaudu Steamiin tunnuksella, joka omistaa testattavan sovelluksen.
  2. Avaa Steam-konsoli siirtymällä selaimella osoitteeseen: steam://open/console. (Voit käyttää Steamiä myös komentorivillä steam -console ja navigoida sitten suoraan konsoliosioon.)
  3. Syötä @cloud_testdynamicsyncapp <AppId> konsoliin testattavan sovellustunnuksen kanssa. Esimerkiksi: @cloud_testdynamicsyncapp 480
  4. Käynnistä sovellus Steamistä.
  5. Etene pelissä haluttuun pisteeseen.
  6. Syötä Steam-konsolissa prepare_for_suspend. Steam keskeyttää pelin etenemisen ja lähettää muuttuneet tiedostot Steam Cloudiin.
  7. Valinnaisesti voit pelata peli toisella laitteella, edetä ja poistua ja antaa Steam-asiakasohjelman latauksen edetä Steam Cloudiin.
  8. Syötä alkuperäisellä laitteella Steam-konsolissa resume_suspended_games. Tämä synkronoi vaadittavat tiedostot Steam Cloudista, julkaisee olennaiset ohjelmointirajapinnan kutsut peliin ja vapauttaa pelin etenemisen.

Testaa paikallisesti Steam Deckillä:

  1. Yhdistä Steam Deck kehittäjäpakettiin
  2. Lue lisää CEF-konsolin käytöstä täältä.
  3. Syötä JS-konsolissa SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppId>”) ja ota testaus käyttöön. Syöttämällä SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”) se otetaan pois käytöstä.

Vianmääritys

Varmista aina ensin, että olet julkaissut muutokset Steam-kumppanuussivulla ja olet odottanut 10 minuuttia tai käynnistänyt Steam-asiakasohjelman uudelleen, jotta julkaistut muutokset näkyvät siinä.

Jos sinulla on ongelmia Steam Cloudin kanssa, tarkista lokitiedosto, joka löytyy kansiosta: %Steam Install%\logs\cloud_log.txt.

Lisätietoja löytyy Debugging the Steamworks API -dokumentaatiosta.