Panoramica

Steam supporta la creazione di classifiche persistenti con voci ordinate automaticamente. Le classifiche possono essere utilizzate per mostrare il punteggio degli amici e degli utenti di tutto il mondo all'interno del gioco e sulla pagina web della Comunità. Per ogni titolo di Steamworks possono essere create fino a 10.000 classifiche, ognuna delle quali può essere recuperata subito dopo l'inserimento del punteggio di un giocatore.

Il giocatore può fare parte una volta di ciascuna classifica. Non c'è limite al numero di giocatori che possono entrare nelle classifiche. Ciascuna voce contiene il punteggio per la classifica di riferimento (un valore int32) e, facoltativamente, fino a 64 valori int32 dei dati associati. I dati associati possono essere utilizzati per conservare informazioni specifiche sulla sessione di gioco che ha portato l'utente a entrare in classifica. Questi dati non vengono ordinati né analizzati da Steam, e vengono sostituiti alla creazione di una nuova voce della classifica per l'utente.

Tutte le funzioni delle classifiche sono incluse in ISteamUserGameStats.h. Due classifiche esemplificative sono state implementate nell'esempio di Steamworks. Puoi visualizzare e gestire le classifiche del tuo gioco anche dalla pagina Amministratore gioco su Steamworks.

Cenni preliminari

Tutte le funzioni asincrone delle classifiche restituiscono un handle al risultato della chiamata all'API di Steam. Puoi trovare maggiori informazioni su come ricevere questi risultati nella sezione "Risultati di chiamata" nella documentazione "Per iniziare".

Creazione di una classifica

Le classifiche sono diverse per ogni applicazione e possono essere configurate tramite l'API o nella pagina di amministrazione del gioco sul sito dei partner di Steamworks.

Creazione tramite il web

Puoi creare e gestire le classifiche del tuo appID dalla sezione Amministratore dell'applicazione in Steamworks, navigando su Statistiche e achievement > Classifiche.


Per definire una classifica è necessario compilare i campi di seguito:

• Nome: assegna un nome che possa avere un senso ai sensi dello sviluppo interno.
  
• Nome della Comunità: se la classifica verrà mostrata nell'hub della Comunità, inserisci qui il nome pubblico da visualizzare. Se non inserisci alcun nome, la classifica non viene visualizzata.
  
• Metodo di ordinamento: imposta il metodo di ordinamento dei dati della classifica. Per le classifiche basate sulla posizione, utilizza l'ordine crescente. Per le classifiche basate sul punteggio più alto, utilizza l'ordine decrescente.
  
• Tipo di visualizzazione: determina i tipi di dati da visualizzare con la classifica. Seleziona un'opzione tra valori numerici, secondi o millisecondi.
  
• Scritture: se impostato su "Affidabile", i punteggi della classifica non potranno essere definiti dai client, ma soltanto tramite l'API web SetLeaderboardScore. Valore predefinito: false.
  
• Letture: se impostato su "Amici", il gioco potrà leggere solo i punteggi degli amici dell'utente. Tutti i punteggi possono comunque essere letti dall'API web. Valore predefinito: false.

Creazione tramite l'API

Le classifiche del gioco possono essere create tramite la sezione Amministratore dell'applicazione di Steamworks o a livello di programmazione, effettuando la chiamata a ISteamUserStats::FindOrCreateLeaderboard. In Steam, tutte le classifiche dei titoli di Steamworks sono identificate da un nome univoco. Il nome della classifica viene utilizzato solo per l'identificazione nell'API di Steamworks e non viene mostrato agli utenti nella Comunità di Steam. Durante la creazione di una classifica, è necessario impostare alcuni parametri.

• Metodo di ordinamento: k_ELeaderboardSortMethodAscending (in prima posizione l'utente con il punteggio più basso) o k_ELeaderboardSortMethodDescending (in prima posizione l'utente con il punteggio più alto)
  
• Tipo di visualizzazione: ELeaderboardDisplayType viene utilizzato per descrivere il valore rappresentato dal punteggio di una classifica. Viene utilizzato dalla Comunità solo per strutturare i punteggi di una classifica quando viene visualizzata.

Se scegli di creare classifiche solo tramite la pagina Amministratore dell'applicazione, puoi utilizzare ISteamUserStats::FindLeaderboard per recuperare un handle per la tua classifica. I metodi FindLeaderboard e FindOrCreateLeaderboard sono asincroni e restituiscono l'handle della classifica specificata tramite il risultato della chiamata a ISteamUserStats::LeaderboardFindResult_t.

Dopo aver creato una classifica, puoi modificare il metodo di ordinamento e il tipo di visualizzazione tramite la sezione Amministratore gioco. Quando viene eseguita la chiamata a FindOrCreateLeaderboard per una classifica esistente, i parametri del metodo di ordinamento e del tipo di visualizzazione vengono ignorati.

Caricamento di un punteggio

Per caricare il punteggio di una classifica è sufficiente effettuare la chiamata a ISteamUserStats::UploadLeaderboardScore passando l'handle della classifica di interesse (recuperato tramite FindLeaderboard), il punteggio dell'utente e, facoltativamente, qualsiasi dato associato generato al momento dell'impostazione del nuovo punteggio. Se il punteggio dell'utente in classifica viene aggiornato, i dati associati passati a ISteamUserStats::UploadLeaderboardScore sostituiranno tutti i dati precedentemente conservati in memoria. È possibile scegliere tra due metodi di aggiornamento durante il caricamento del punteggio di un utente in una classifica:

• ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest: Steam confronterà il nuovo punteggio dell'utente con quello già memorizzato in classifica per conservare quello migliore (il punteggio più basso per le classifiche con ordinamento crescente o il punteggio più alto per le classifiche con ordinamento decrescente).
  
• ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate: Steam sostituirà sempre il punteggio dell'utente di una classifica con il nuovo punteggio.
  
• ISteamUserStats::UploadLeaderboardScore è una chiamata asincrona. Il risultato del caricamento viene restituito nel risultato della chiamata a LeaderboardScoreUploaded_t. Il risultato contiene un contrassegno che indica se il punteggio dell'utente è cambiato e le sue posizioni globali precedente e corrente. Una volta caricate, le classifiche di Steamworks vengono aggiornate immediatamente per riflettere il nuovo punteggio. Il nuovo ordinamento delle voci può essere recuperato tramite DownloadLeaderboardEntries.

Inclusione di contenuti generati dagli utenti come allegato

Dopo aver caricato un punteggio, è possibile allegare contenuti generati dagli utenti alla voce della classifica. Per eseguire l'operazione è sufficiente chiamare ISteamUserStats::AttachLeaderboardUGC. Questi contenuti possono essere rappresentati dal replay dell'utente che ottiene il punteggio o da un fantasma contro cui gareggiare. L'handle allegato sarà disponibile quando la voce viene recuperata e può essere scaricata dagli altri utenti. Per creare e scaricare contenuti generati dagli utenti, consulta la documentazione relativa a Steam Cloud.

Una volta allegato, il contenuto sarà disponibile anche se il relativo file del Cloud viene modificato o eliminato dall'utente.

Recupero delle voci della classifica

La chiamata a ISteamUserStats::DownloadLeaderboardEntries viene sfruttata per recuperare le voci della classifica con l'handle recuperato tramite ISteamUserStats::FindLeaderboard.

Dopo aver recuperato tutte le voci scaricate da GetDownloadedLeaderboardEntry, i dati saranno liberati e la chiamata a SteamLeaderboardEntries_t in LeaderboardScoresDownloaded_t non sarà più valida.

Recupero delle informazioni sulle classifiche

Con l'handle della classifica restituito da FindLeaderboard è possibile recuperare le informazioni sulla classifica con le seguenti chiamate:

ISteamUserStats::GetLeaderboardName
ISteamUserStats::GetLeaderboardEntryCount
ISteamUserStats::GetLeaderboardSortMethod
ISteamUserStats::GetLeaderboardDisplayType