Documentazione di Steamworks
Steam Cloud
In breve
Steam Cloud memorizza automaticamente i file del tuo gioco sui server di Steam in modo che i tuoi giocatori possano accedere a Steam e ai loro giochi salvati da qualsiasi computer.
Livello di integrazione
Configurazione dei percorsi dei file richiesta sul sito web di Steamworks. In alternativa, le chiamate che è necessario effettuare all'API di Steamworks dal codice di gioco affinché questo possa enumerare, leggere, eliminare o modificare i file su Steam Cloud.

Panoramica su Steam Cloud

La funzionalità Steam Cloud offre un sistema di archiviazione di file remoti semplice e trasparente per il tuo gioco. I file specificati nella configurazione automatica del Cloud o scritti su disco (creati, modificati, eliminati, ecc.) utilizzando l'API del Cloud verranno automaticamente replicati ai server di Steam dopo l'uscita dal gioco.

Se l'utente cambia computer, i file vengono scaricati automaticamente sul nuovo computer prima dell'avvio del gioco. Il gioco può quindi accedere ai file leggendoli tramite l'API del cloud o direttamente dal disco come di consueto. Consigliamo di evitare configurazioni specifiche del computer come le impostazioni video.

Il client di Steam garantisce che i file mantengano la sincronizzazione su tutti i computer da cui l'utente può accedere.

Gli utenti possono disattivare globalmente la sincronizzazione del cloud dalle impostazioni di Steam, rimuovendo il segno di spunta dalla casella "Abilita la sincronizzazione di Steam Cloud per le applicazioni che lo supportano".

Gli utenti possono inoltre disattivare la sincronizzazione del cloud per ciascun gioco dalle relative proprietà.

Spacewar_Cloud_Properties.png

Note e pratiche consigliate


Ricorda che Steam sicronizzerà i file di Steam Cloud dell'utente per il tuo gioco prima e dopo ogni sessione. Qualunque file corrispondente che viene modificato durante la sessione verrà caricato sul Cloud subito dopo. Se il tuo gioco memorizza file molto grandi o un gran numero di file piccoli su Steam Cloud, questo potrebbe provocare un evidente impatto sulle prestazioni della rete internet dell'utente e anche rallentare lo spegnimento di Steam o il riavvio del gioco.

Come regola generale, file più piccoli sono da preferire. Se lo stato di salvataggio di un utente può essere diviso in diverse categorie (ci sono cose che potrebbero cambiare di frequente a fronte di altre che cambiano meno di frequente nel gioco) consigliamo di usare file separati per le varie categorie. In questo modo, gli stati non modificati non dovranno essere caricati nuovamente dopo ogni sessione.

Limiti delle dimensioni dei file


I limiti assoluti alle dimensioni dei file su Steam Cloud possono cambiare nel corso del tempo. Ecco alcuni dei limiti attuali:

DimensioniLimitazioni
100MBDimensione massima per una chiamata a ISteamRemoteStorage::FileWrite o ISteamRemoteStorage::FileWriteStreamWriteChunk
256MBPotrebbe risultare in una scelta non ottimale di memorizzazione per la posizione dell'utente, influenzando negativamente le prestazioni di upload e download

Percorsi file di salvataggio

Quando devi decidere dove scrivere i file di salvataggio, assicurati che il percorso sia univoco per l'utente di Steam corrente. Se necessario, puoi ottenere l'ID univoco di Steam tramite ISteamUser::GetSteamID. Da qui puoi accedere all'ID dell' account da GetAccountID(), il che ti permette di avere una variabile univoca durante la costruzione del percorso di salvataggio.

Salvataggi multipiattaforma


Se il tuo gioco è supportato su diverse piattaforme, o se pensi di aggiungere questa funzionalità in futuro, dovresti tenere in considerazione la cosa quando configuri Steam Cloud per il tuo gioco.

Se pensi di leggere/scrivere i file direttamente tramite l'interfaccia ISteamRemoteStorage, puoi controllare la sincronizzazione con la piattaforma tramite ISteamRemoteStorage::SetSyncPlatforms. L'impostazione predefinita per un nuovo file è la sincronizzazione con tutte le piattaforme.

Se pensi di usare la configurazione Auto-Cloud di Steam, ci sono alcuni aspetti da tenere a mente. Prima di tutto, l'impostazione predefinita per i nuovi file è la sincronizzazione solo con l'impostazione del sistema operativo associata al percorso radice di Auto Cloud. Questo significa che, se imposti percorsi radice diversi per ciascun sistema operativo, tutti i file saranno partizionati dalla piattaforma e quindi non sarà attiva alcuna funzionalità di salvataggio multipiattaforma.

Per abilitare i salvaggi multipiattaforma, dovresti invece definire un unico percorso radice (generalmente per Windows) e poi creare override delle radici per le altre piattaforme supportate. I file che corrispondono a un certo percorso e che hanno anche le override delle radici verranno sincronizzati su tutte le piattaforme sia nella radice originale che in tutte le override. Consulta la documentazione sull'Auto-Cloud di Steam per ulteriori informazioni.

Impostazione iniziale

Per l'impostazione iniziale di Steam Cloud è necessario definire i campi delle opzioni Quota di byte per utente e Numero di file consentiti per utente nel pannello Amministratore dell'applicazione di Steamworks alla pagina Impostazioni di Steam Cloud.

Tali valori vengono applicati a tutti i giochi abilitati per il Cloud, per ciascun utente e per ciascun gioco. Ti consigliamo di impostare valori ragionevoli per il tuo gioco.

NOTA: Non dimenticare di cliccare su Salva nella parte inferiore della pagina e di pubblicare le impostazioni aggiornate. Una volta pubblicate, l'icona del Cloud sarà visibile nel client di Steam di chiunque possieda il gioco.

Se hai già rilasciato pubblicamente il gioco, puoi selezionare la casella Abilita Steam Cloud soltanto per gli sviluppatori. Se abiliti questa modalità riservata agli sviluppatori, solo gli account di Steam che possiedono una licenza per i "pacchetti per sviluppatori" per il tuo titolo visualizzeranno l'icona di Steam Cloud e potranno utilizzarla. È utile per eseguire test di integrazione di Steam Cloud in modo sicuro, senza necessità di interrompere l'esperienza pubblica dell'utente. La modalità non ha effetto sui giochi non rilasciati: se nessuno possiede ancora il gioco, nessuno potrà visualizzare o accedere ai dati archiviati sul Cloud per l'appID specifico.

Compilando il campo AppID Cloud condiviso è possibile far sì che lo spazio di archiviazione del Cloud venga condiviso tra due appID. Questo campo viene comunemente usato per condividere i salvataggi di gioco tra una versione demo e il gioco completo. Il valore 0 disattiva questa funzione.

API di Steam Cloud e Auto-Cloud di Steam

Steam mette a tua disposizione due diversi metodi per utilizzare Steam Cloud. Valuta attentamente in cosa differiscono e determina la scelta più giusta per la tua applicazione.

Il primo metodo è l'API di Steam Cloud.
L'API del Cloud fornisce una serie di funzioni che consentono di integrare direttamente Steam Cloud nel gioco. L'API del Cloud isola i singoli file degli utenti di Steam e fornisce un maggiore livello di controllo su Steam Cloud.

L'API di Steam Cloud è visibile tramite l'interfaccia API ISteamRemoteStorage. Puoi trovarne esempi di utilizzo nel progetto Esempio di applicazione dell'API di Steamworks (SpaceWar).

Il secondo metodo è l'Auto-Cloud di Steam.
L'Auto-Cloud di Steam è stato progettato per i giochi in cui si è deciso di non integrare l'API di Steam Cloud e fornisce un modo veloce e semplice per iniziare, anche se difetta della flessibilità messa a disposizione dall'API di Steam Cloud.

Se preferisci avere una maggiore integrazione con Steam Cloud (ad esempio consentendo di scegliere quali file di salvataggio vengono memorizzati nel Cloud), consigliamo di usare l'API di Steam Cloud. In caso contrario, puoi usare Auto-Cloud di Steam.

Auto-Cloud di Steam

Auto-Cloud di Steam è un'alternativa all'API di Steam Cloud che consente di utilizzare questo sistema di archiviazione per le applicazioni senza dover scrivere altro codice o modificare il gioco in alcun modo. È necessario solo specificare i gruppi di file che si desidera archiviare nel Cloud. Steam si occuperà della sincronizzazione automatica di tali gruppi all'avvio e alla chiusura dell'applicazione. Consigliamo di evitare configurazioni specifiche del computer come la qualità del video.
Nota: il file steam_autocloud.vdf sarà creato in ogni posizione specificata dai tuoi percorsi Cloud di Steamworks. Questo file è usato da Steam e può essere ignorato dal tuo gioco.

Configurazione

Dopo aver completato la Impostazione iniziale, nella pagina Impostazioni di Steam Cloud verrà sbloccata la sezione per la configurazione di Auto-Cloud di Steam.

I percorsi radice descrivono i gruppi di file che saranno memorizzati in Steam Cloud. Ogni percorso radice può essere rappresentato da un singolo file o da tutti i file presenti in una data sottocartella. Utilizza un nuovo percorso per ogni gruppo di file da sincronizzare.

Un percorso radice è composto da 5 parti:
  1. Radice

    Si tratta di un elenco predeterminato di percorsi in cui i salvataggi di gioco vengono comunemente posizionati.
    RadiceSistemi operativi supportatiPercorso corrispondente
    Directory di installazione dell'applicazioneTutti[Steam Install]\SteamApps\common\[cartella del gioco]\
    SteamCloudDocumentsTuttiPercorso specifico della piattaforma, ad esempio su Linux: ~/.SteamCloud/[nome utente]/[cartella del gioco]/
    WinMyDocumentsWindows%USERPROFILE%\Documenti\
    WinAppDataLocalWindows%USERPROFILE%\AppData\Local\
    WinAppDataLocalLowWindows%USERPROFILE%\AppData\LocalLow\
    WinAppDataRoamingWindows%USERPROFILE%\AppData\Roaming\
    WinSavedGamesWindows%USERPROFILE%\Giochi salvati\
    MacHomemacOS~/
    MacAppSupportmacOS~/Libreria/Supporto applicazioni/
    MacDocumentsmacOS~/Documents/
    LinuxHomeLinux~/
    LinuxXdgDataHomeLinux$XDG\_DATA\_HOME/

    Una nota sui percorsi Windows %USERPROFILE%: i percorsi corrispondenti elencati qui sopra sono quelli predefiniti. Ora è possibile configurare la propria installazione di Windows, così che quelle cartelle possano essere in posizioni diverse (non necessariamente sotto %USERPROFILE%). Steam usa le necessarie API di Windows per trovare la posizione attuale di queste cartelle, che sia questa predefinita o personalizzata.

  2. Sottocartella

    Percorso sottodirectory ai file memorizzati nel cloud relativi alla radice. In assenza di sottodirectory, utilizza '.'.

    Valori speciali del percorso di Auto-Cloud
    Auto-Cloud consente di utilizzare identificatori univoci per gli utenti di Steam nel percorso Subdirectory. In questo modo è possibile archiviare separatamente sul computer i file di salvataggio di ogni utente di Steam. Usando ISteamUser::GetSteamID nel gioco puoi ottenere l'attuale ID di Steam o l'ID dell'account dell'utente su cui salvare e da cui leggere i salvataggi.
    • {64BitSteamID}: utilizza questa variabile nel percorso di Steam per immettere l'ID di Steam a 64 bit di un utente. Un ID di Steam a 64 bit presenta questa forma: 76561198027391269.
    • {Steam3AccountID}: utilizza questa variabile nel percorso di Steam per immettere l'ID dell'account 3 di Steam di un utente. Un ID dell'account presenta questa forma: 67125541.
    Esempio: SavesDir/{64BitSteamID}
  3. Modello

    Modello della maschera di file da abbinare. Puoi utilizzare * come carattere jolly. Se desideri selezionare tutti i file nella directory, utilizza solo *.

    Esempio: *.sav
  4. Sistema operativo

    Imposta i sistemi operativi in cui e da cui questi file verranno sincronizzati. Questa operazione è necessaria solo se i file sono specifici del sistema operativo (è auspicabile il contrario).
  5. Ricorsivo

    Include le sottodirectory durante la ricerca dei file corrispondenti. È utile per le sottodirectory con nomi non deterministici, come i nomi degli utenti (o gli ID) non appartenenti a Steam. Se è in uso un ID di Steam, consigliamo vivamente di utilizzare i valori del percorso speciale nel campo della sottodirectory.

Override delle radici

Se la tua applicazione è multipiattaforma e richiede directory differenti per ciascun sistema operativo, puoi utilizzare questa funzionalità per specificare un override dei percorsi radice impostati in precedenza.

È possibile sostituire i percorsi radice già specificati con i diversi percorsi corrispondenti per un altro sistema operativo. Se utilizzi la funzione di override delle radici, dovrai specificare [All OSes] (Tutti i sistemi operativi) nell'elenco a discesa [Root OS] (Sistema operativo radice).

L'override delle radici è costituito da 5 parti.
  1. Radice originale

    Corrisponde a una delle radici precedentemente impostate.
  2. Sistema operativo

    Il sistema operativo a cui applicare l'override.
  3. Nuova radice

    La nuova posizione in cui viene mappata la radice originale nel sistema operativo specificato.
  4. Aggiungi/sostituisci percorso

    Consente di aggiungere facoltativamente un percorso di sottodirectory che viene inserito tra la nuova radice e la sottodirectory originale.
  5. Sostituisci percorso

    Se attivato, il percorso specificato in Aggiungi/sostituisci percorso sostituisce completamente la sottodirectory originale.

Esempio: configurazione di Auto-Cloud per le applicazioni Unity

Di seguito viene riportato un esempio di configurazione di Auto-Cloud per l'utilizzo con la piattaforma Unity e la proprietà Application.persistentDataPath, il cui valore è diverso a seconda del sistema operativo. La versione di Windows è configurata come percorso radice, l'azienda in Unity è impostata su DefaultCompany e il progetto è denominato Autocloudsample. Su macOS e su Linux/SteamOS, nel campo Aggiungi/sostituisci percorso sono impostati i percorsi alternativi da Application.persistentDataPath e la casella di controllo Sostituisci percorso è selezionata.

Con queste impostazioni, i file di Auto-Cloud verranno sincronizzati tra le tre cartelle, come mostrato negli esempi di anteprima.

Cloud_Unity_Auto-Cloud_Example.png

Test precedenti al rilascio

Se desideri aggiungere Auto-Cloud di Steam a un gioco già rilasciato e hai abilitato la modalità riservata agli sviluppatori durante la Impostazione iniziale, è necessario completare alcuni passaggi aggiuntivi per eseguire dei test di funzionalità.
  1. Accedi a Steam con un account che possiede l'applicazione in cui vuoi eseguire il test.
  2. Apri la console di Steam navigando a steam://open/console dal tuo browser.
  3. Immetti testappcloudpaths <AppId> nella console con l'appID per cui desideri eseguire il test. Esempio: testappcloudpaths 480
  4. Immetti set_spew_level 4 4 nella console.
  5. Avvia l'applicazione da Steam.
  6. Verifica la normale attività della console. Se i file sono già presenti nei percorsi di Auto-Cloud, dovresti visualizzarne il caricamento. In caso contrario, salva alcuni file dall'applicazione e quindi chiudila per attivare la sincronizzazione.
  7. Spostati su un altro computer e ripeti i passaggi sopra elencati per eseguire il test del download dei file da Auto-Cloud di Steam.
  8. Assicurati di eseguire test per tutti i sistemi operativi supportati.
  9. Imposta testappcloudpaths 0 e set_spew_level 0 0 per terminare il test. Per eliminare la scheda della console puoi riavviare il client di Steam.

Non dimenticare di disattivare la modalità riservata agli sviluppatori e di pubblicare le modifiche al completamento del test.

Sincronizzazione dinamica del Cloud


Steam Cloud ora supporta la sincronizzazione dinamica, grazie alla quale le modifiche apportate sul Cloud possono essere scaricate sul computer locale mentre l'applicazione è in esecuzione. L'esempio corrente riguarda una sessione di gioco sospesa su Steam Deck. Per le applicazioni contrassegnate come dotate di supporto alla sincronizzazione dinamica del Cloud, Steam sincronizzerà i file su Steam Cloud mentre l'applicazione è sospesa. A quel punto, l'utente può avviare il gioco su un altro dispositivo e ne riceverà i dati aggiornati dalla sessione su Steam Deck. Alla chiusura dell'applicazione, le modifiche verranno caricate su Steam Cloud. Infine, quando il dispositivo Steam Deck esce dalla modalità sospensione, sincronizzerà le modifiche e segnalerà all'applicazione che i file locali sono cambiati. A quel punto l'applicazione può iterare quei cambiamenti ed effettuare le azioni appropriate. Ad esempio, il gioco potrebbe essere in grado di caricare i progressi più recenti dal disco e consentire all'utente di riprendere da dove aveva interrotto sull'altro dispositivo.

Dai un'occhiata al nostro annuncio per trovare maggiori informazioni sul motivo dell'esistenza di questa funzionalità e su come utilizzarla.

Nota: questa funzionalità supporta sia le applicazioni che usano l'API ISteamRemoteStorage per gestire i file sia quelle che usano Auto-Cloud.

Per ulteriori dettagli, consulta la documentazione su ISteamRemoteStorage, in particolare ISteamRemoteStorage::RemoteStorageLocalFileChange_t, ISteamRemoteStorage::GetLocalFileChangeCount e ISteamRemoteStorage::GetLocalFileChange.

Vedi anche ISteamRemoteStorage::BeginFileWriteBatch e ISteamRemoteStorage::EndFileWriteBatch. Questi wrapper dovrebbero essere usati per aiutare Steam a sincronizzare in maniera sicura i dati su Steam Cloud quando l'utente sospende il sistema.

Test precedenti al rilascio


Puoi abilitare localmente la Sincronizzazione dinamica del Cloud per testare le build della tua applicazione; questa funzionalità è consigliata per un gioco già rilasciato, poiché l'abilitazione della Sincronizzazione dinamica del Cloud per tutti gli utenti potrebbe causare una perdita dei dati durante l'esecuzione di build che non gestiscono i nuovi metodi e callback dell'API.

Per testare localmente da un PC:

  1. Accedi a Steam con un account che possiede l'applicazione che vuoi testare.
  2. Apri la console di Steam navigando a steam://open/console dal tuo browser. (Puoi anche eseguire Steam con steam -console nella riga di comando e quindi andare direttamente alla Console).
  3. Immetti @cloud_testdynamicsyncapp <AppId> nella console con l'appID per cui desideri eseguire il test. Esempio: @cloud_testdynamicsyncapp 480
  4. Avvia l'applicazione da Steam.
  5. Procedi all'interno del gioco fino al punto desiderato
  6. Nella console di Steam, immetti prepare_for_suspend. Steam sospenderà il processo del gioco e caricherà gli eventuali file modificati su Steam Cloud.
  7. Facoltativo: gioca al titolo su un altro dispositivo, aumentando i progressi, quindi esci e lascia che quel client di Steam carichi i progressi sullo Steam Cloud.
  8. Torna al dispositivo originale e, nella console di Steam, immetti resume_suspended_games. Questa operazione sincronizzerà tutti i file necessari dallo Steam Cloud, pubblicherà le chiamate API pertinenti sul tuo gioco e quindi riattiverà il processo del gioco.

Per testare localmente da Steam Deck:

  1. Connetti il tuo Steam Deck a un dev kit
  2. Per usare la console CEF, consulta questa pagina
  3. Nella console JS, inserisci SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp <AppId>”) per abilitare il testing. Inserisci SteamClient.Console.ExecCommand(“@cloud_testdynamicsyncapp 0”) per disabilitarlo.

Debug

Per prima cosa, accertati di aver pubblicato le tue modifiche sul sito web di Steam per i partner e di avere atteso fino a 10 minuti o riavviato il client di Steam per ricevere le modifiche pubblicate.

In caso di problemi con Steam Cloud, è necessario controllare il file di registro alla posizione %Steam Install%\logs\cloud_log.txt.

Vedi Debugging nell'API di Steamworks per maggiori informazioni.