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 via opzionale, alcune chiamate API richieste dal codice di gioco a Steamworks per il caricamento, il download, l'enumerazione e l'eliminazione.

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

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 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 fare clic 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 "Sviluppatore" 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 l'uno dall'altro 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 è Auto-Cloud di Steam.
Auto-Cloud di Steam è progettato per i giochi legacy in cui non è facile integrare l'API di Steam Cloud e offre un modo semplice e veloce per iniziare a usare il sistema pur mancando della potenza e della flessibilità offerta dall'API di Steam Cloud.

In genere è consigliabile usare l'API del Cloud laddove possibile, in quanto consente un maggiore grado di integrazione e personalizzazione e ti permette di offrire ai tuoi utenti di Steam un'esperienza della migliore qualità, pari a quella che si aspettano da Steam Cloud.

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.

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/
  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 [Tutti i sistemi operativi] nell'elenco a discesa 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 dell'Auto-Cloud per le applicazioni di Unity

Di seguito viene riportato un esempio di configurazione di Auto-Cloud per l'utilizzo con la piattaforma Unity e la proprietà Application.persistentDataPath in cui il 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 è stato 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 una licenza per sviluppatori per 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 testcloudapppaths 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.

Debug

In primo luogo, assicurati sempre di aver pubblicato le modifiche apportate sul sito web di Steam per i partner e di aver atteso 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.

Per ulteriori informazioni, consulta Debugging nell'API di Steamworks.