Panoramica

Le statistiche e gli achievement di Steam sono un modo semplice per fornire dati persistenti e sempre accessibili sugli obiettivi di gioco e per monitorare le statistiche dei tuoi utenti. I dati degli utenti vengono associati al loro account di Steam e ciascun utente può organizzare e mostrare achievement e statistiche nel proprio profilo della Comunità di Steam.

Utilità

Oltre a consentire agli utenti di ottenere ricompense di grande valore, gli achievement forniscono un'ulteriore dimensione agli obiettivi di gioco. Sono utili per incoraggiare e premiare il lavoro di squadra e l'interazione tra giocatori, ma anche per ricompensare gli utenti per il tempo passato a giocare.

Grazie alle statistiche è possibile monitorare informazioni dettagliate quali il tempo di gioco, il numero di potenziamenti utilizzati e così via. Puoi scegliere di utilizzare le statistiche per il semplice monitoraggio interno dei dati di gioco. In questo modo, ad esempio, consentirai all'utente di ottenere un achievement in base alle statistiche accumulate in più sessioni di gioco e da computer diversi.

Panoramica sull'implementazione

Definire le statistiche e gli achievement del gioco

Gli achievement sono diversi per ogni applicazione e possono essere configurati nella pagina di amministrazione dell'applicazione sul sito dei partner di Steamworks.

Il gioco può conservare informazioni su tre tipi di statistiche:

• INT: un valore numerico intero a 32 bit (segnato), ad esempio il numero di partite giocate dall'utente.
  
• FLOAT: un valore a virgola mobile a 32 bit, ad esempio il numero di chilometri percorsi.
  
• AVGRATE: una media mobile. Consulta Statistica di tipo AVGRATE.

Il sito web di Steamworks per i partner fornisce un'interfaccia per la definizione e l'aggiornamento delle statistiche e degli achievement del gioco. Tramite l'interfaccia è possibile:

• Definire le statistiche e gli achievement iniziali.
  
• Aggiungere ulteriori statistiche e achievement.
  
• Aggiornare nomi, descrizioni e icone degli achievement.
  
• Aggiornare parametri e vincoli statistici (valori massimi e minimi, dimensioni della finestra della media mobile ecc.).

Proprietà delle statistiche:

• ID: un ID numerico generato automaticamente per ogni statistica.
  
• Tipo: il tipo di statistica (INT, FLOAT o AVGRATE).
  
• Nome API: la stringa utilizzata per accedere alla statistica utilizzando l'API.
  
• Impostata da: stabilisce chi può modificare la statistica. L'impostazione predefinita è "Client". Per ulteriori informazioni, consulta Statistiche del server di gioco.
  
• Solo incremento: impostando questa proprietà, il valore della statistica può solo aumentare nel tempo.
  
• Variazione max: impostando questa proprietà si configura il limite di variazioni che il valore della statistica può subire tra due chiamate SetStat.
  
• Valore min: se impostato, indica il valore numerico minimo che la statistica può assumere. Per impostazione predefinita, il valore minimo corrisponde al valore minimo del tipo numerico sottostante (INT_MIN o -FLT_MAX).
  
• Valore max: se impostato, indica il valore numerico massimo che la statistica può assumere. Per impostazione predefinita, il valore massimo corrisponde al valore massimo del tipo numerico sottostante (INT_MAX o FLT_MAX).
  
• Valore predefinito: se impostato, indica il valore predefinito iniziale della statistica per un nuovo utente. Se non viene impostato, il valore predefinito è zero.
  
• Aggregata: impostando questa proprietà, Steam tiene traccia del totale globale della statistica. Per ulteriori informazioni, consulta la sezione relativa alle statistiche globali riportata più in basso.
  
• Nome visualizzato: il nome della statistica visualizzato nella tua applicazione.

Statistiche AVGRATE: le statistiche hanno le seguenti proprietà aggiuntive:

• Finestra: le dimensioni della "finestra scorrevole" utilizzata per calcolare la media dei dati.

Per le statistiche AVGRATE la media viene calcolata automaticamente da Steam. Per ulteriori informazioni, consulta la sezione AVGRATE riportata di seguito.

Achievement: consulta il tutorial sugli achievement.

Ecco l'elenco degli achievement di Esempio di applicazione dell'API di Steamworks (SpaceWar):

Considerazioni speciali

• I nomi e le icone degli achievement devono essere adatti a tutte le età.
  
• Per impostazione predefinita, esiste un limite iniziale di 100 achievement per gioco. Sarà possibile aggiungere altri achievement dopo che la tua applicazione avrà raggiunto il limite per Funzionalità del profilo.

Come usare statistiche e achievement

Per accedere a statistiche e achievement dall'interno del gioco:

• Dopo aver inizializzato l'API di Steamworks, è possibile iniziare a utilizzare l'API relativa a statistiche e achievement contenuta in ISteamUserStats.
  
• Esegui l'iterazione dei dati e inizializza lo stato di gioco con ISteamUserStats::GetStat e ISteamUserStats::GetAchievement.
  
• Se desideri che gli achievement vengano mostrati nel gioco, puoi usare ISteamUserStats::GetAchievementDisplayAttribute per recuperare le proprietà dell'achievement leggibili dall'utente, incluso il nome ("name") e la descrizione ("desc"). Sul sito web di Steamworks per i partner è possibile tradurre queste proprietà. I dati restituiti varieranno a seconda della lingua impostata nel gioco dall'utente. Con ISteamUserStats::GetAchievementIcon è inoltre possibile ottenere l'icona di un achievement, mentre ISteamUserStats::GetAchievementAndUnlockTime restituisce l'orario in cui ciascun achievement è stato sbloccato.
  
• Quando le statistiche subiscono modifiche, specialmente prima che queste vengano mostrate all'utente, effettua la chiamata a ISteamUserStats::SetStat o a ISteamUserStats::UpdateAvgRateStat. Queste chiamate modificano solo lo stato in memoria di Steam e richiedono poche risorse. In questo modo, Steam può mantenere le modifiche tra sessioni anche in caso di crash del gioco.
  
• In punti strategici all'interno del gioco, come in corrispondenza di checkpoint o al passaggio da un livello all'altro, effettua la chiamata a ISteamUserStats::StoreStats per caricare le modifiche. Riceverai la callback da ISteamUserStats::UserStatsStored_t al completamento del processo.
  
• Per gli achievement che prevedono una barra di avanzamento, utilizza ISteamUserStats::IndicateAchievementProgress in punti strategici del gioco per mostrare un messaggio popup indicante il progresso. Ad esempio, se per ottenere un achievement sono necessarie 20 vittorie, potresti utilizzare la funzione di chiamata al raggiungimento della decima vittoria per informare l'utente che è a metà del cammino.
  
• Ogni volta che uno o più achievement vengono sbloccati, effettua la chiamata a ISteamUserStats::SetAchievement per ciascun achievement e poi a ISteamUserStats::StoreStats per eseguirne il caricamento immediato. Il gioco riceverà la callback di ISteamUserStats::UserStatsStored_t, più una callback di ISteamUserStats::UserAchievementStored_t per ogni achievement sbloccato. L'Overlay di Steam mostrerà all'utente una notifica nel gioco.

Statistica di tipo AVGRATE

Questo tipo di statistica consente di ottenere funzionalità uniche ed estremamente utili, ma richiede una spiegazione più dettagliata.

Immaginiamo che tu voglia monitorare una media statistica, come ad esempio i "punti guadagnati all'ora". Per ottenere questo valore, si potrebbe applicare una strategia che preveda l'impiego di due statistiche, una con valori integrali (INT) "TotalPoints" (punti totali) e una con valori a virgola mobile FLOAT "TotalPlayTimeHours" (tempo di gioco totale) e dividere quindi i punti per il tempo di gioco.

Lo svantaggio di questa implementazione consiste nel fatto che, quando il giocatore ha accumulato un ammontare di tempo notevole, la media calcolata si modifica molto lentamente: sostanzialmente, più un utente gioca, meno la media è sensibile. Se un utente ha accumulato 100 ore di gioco, la media calcolata subirà un "ritardo" di circa 50 ore. All'aumento delle abilità, i punti all'ora non aumenteranno come l'utente si aspetta che facciano.

La statistica di tipo AVGRATE consente di implementare una "finestra scorrevole" alla media. Ad esempio, è possibile utilizzare come base statistica solo le ultime ore di gioco, in modo che il valore rifletta in modo più accurato il livello di abilità attuale del giocatore.

Per impostare una statistica AVGRATE allo scopo di implementare il valore "punti all'ora", dove solo le ultime 20 ore di gioco sono in grado di influire sul valore, procedi come segue:

• Tieni presente che le unità di tutti i parametri orari associati a questa statistica saranno in "ore", in quanto la media sarà calcolata "all'ora": questo è valido sia per la proprietà della finestra sulla statistica stessa, sia per il parametro "dSessionLength" (durata della sessione) passato a UpdateAvgRateStat in basso.
  
• Crea una statistica AVGRATE denominata "AvgPointsPerHour" e inserisci il valore 20,0 come proprietà della finestra (ricorda, si tratta di "ore").
  
• In punti strategici del gioco, effettua la chiamata a ISteamUserStats::UpdateAvgRateStat con i seguenti parametri:
  
  • pchName: "AvgPointsPerHour".
    
  • flCountThisSession: il numero di punti che il giocatore ha guadagnato dall'ultima chiamata a UpdateAvgRateStat.
    
  • dSessionLength: il tempo di gioco trascorso dall'ultima chiamata a UpdateAvgRateStat. L'unità deve corrispondere a quella indicata nella proprietà della finestra della statistica, nel nostro caso "ore".
    
• Ad esempio, se il giocatore ha guadagnato 77 punti nell'ultimo round, durato 0,225 ore (13 minuti e 30 secondi), sarebbe SteamUserStats()->UpdateAvgRateStat( "AvgPointsPerHour", 77, 0.225 )

Nell'esempio appena citato, Steam calcola la media attuale dei round di 342,2 punti all'ora (77 diviso 0,225) e unisce quindi questo valore a quello precedentemente accumulato. In questo modo il risultato rifletterà la media totale delle ultime 20 ore di gioco dell'utente. Se si fosse trattato del primo aggiornamento di questa statistica per l'utente in questione, il valore risulterebbe pari a 342,2.

In questo esempio abbiamo utilizzato le ore come unità, ma puoi scegliere qualsiasi altro valore temporale desideri. Ricorda semplicemente di utilizzare le unità di tempo in modo coerente durante l'impostazione della proprietà della finestra e per il parametro "dSessionLength" relativo alla durata della sessione.

Ottenere statistiche di altri utenti

Puoi ottenere le statistiche di un altro utente attraverso la chiamata a ISteamUserStats::RequestUserStats, accedendo quindi ai relativi dati con ISteamUserStats::GetUserStat, ISteamUserStats::GetUserAchievement e ISteamUserStats::GetUserAchievementAndUnlockTime. Questi dati non vengono aggiornati automaticamente al caricamento di nuove statistiche da parte dell'utente, quindi effettua nuovamente la chiamata a ISteamUserStats::RequestUserStats per aggiornarli.

Per evitare di utilizzare troppa memoria, è prevista una cache LRU per gli elementi usati meno di recente, mentre le statistiche degli altri utenti vengono scaricate periodicamente. Allo scaricamento dei dati, viene inviata automaticamente la callback ISteamUserStats::UserStatsUnloaded_t, che renderà le statistiche dell'utente specificato non disponibili fino alla nuova chiamata a ISteamUserStats::RequestUserStats.

Modalità offline

Steam conserva una cache locale di dati delle statistiche e degli achievement in modo da consentire il normale utilizzo delle API anche in modalità offline. Tutte le statistiche il cui salvataggio non va a buon fine vengono conservate fino al successivo accesso online dell'utente. Se le modifiche sono avvenute da più di un computer, Steam unirà automaticamente gli achievement scegliendo le statistiche che riportano un avanzamento maggiore. Poiché Steam conserva una cache locale dei dati delle statistiche di gioco, non è necessario disporre di una cache locale di dati anche sul disco. La presenza di due cache genera spesso conflitti che possono tradursi in esperienze poco piacevoli per l'utente, come ad esempio vedere il proprio avanzamento azzerato.

Statistiche del server di gioco

Se per le statistiche dell'utente è disponibile l'API ISteamUserStats, per i server di gioco esiste ISteamGameServerStats. Con questa API è possibile ottenere le statistiche degli utenti nello stesso modo (descritto in precedenza) in cui vengono ottenute dal client e impostare statistiche e assegnare achievement se la proprietà "Impostato da" è configurata su un server di gioco (GS) o sul server di gioco ufficiale. La differenza tra i server di gioco e i server di gioco ufficiali è che i secondi sono server ospitati e controllati dallo sviluppatore. L'impostazione delle statistiche tramite i server di gioco ufficiali offre una maggiore protezione contro l'utilizzo di trucchi e contro la modifica o la falsificazione dei server da parte degli utenti. Per definire i server di gioco ufficiali, immetti gli intervalli IP dei server qui.

Le statistiche e gli achievement che possono essere impostati dai server di gioco non possono essere impostati dal client. Nei server di gioco è possibile impostare statistiche e achievement solo per gli utenti che stanno attualmente giocando sul server. Se l'utente abbandona il server, viene concesso un breve periodo di tolleranza per l'impostazione di eventuali statistiche finali, dopo il quale i nuovi caricamenti verranno negati. Ciò consente di garantire la coerenza e impedisce ai server di gioco dannosi l'impostazione di statistiche per gli utenti in qualsiasi momento. In considerazione di questa misura restrittiva, per impostare le statistiche è importante non aspettare fino alla fine di un round, ma piuttosto impostarle in modo continuo, in modo che sia possibile conservare le relative informazioni una volta che l'utente chiude la sessione.

Quando un server di gioco modifica le statistiche dei client, questi riceveranno degli aggiornamenti automatici. Tuttavia, come per i client, le statistiche caricate dal server per gli altri utenti non vengono aggiornate automaticamente e possono essere datate.

Azzerare le statistiche

Durante lo sviluppo, per scopi di test è spesso necessario effettuare una pulizia completa delle statistiche e degli achievement di uno o di tutti gli account. Per azzerare le statistiche di un account, effettua la chiamata a ISteamUserStats::ResetAllStats e imposta bAchievementsToo su true per azzerare anche gli achievement. Una volta inviata la chiamata, ricorda di eseguire l'iterazione delle statistiche e degli achievement e di ripristinare lo stato di gioco in memoria. Non c'è alcun modo per azzerare le statistiche e gli achievement di tutti gli utenti a livello globale: questo perché, tra le altre ragioni, pur effettuando una pulizia a tappeto i giochi in corso potrebbero sfuggire alla cancellazione e scrivere nuovamente dei valori in memoria. Fortunatamente, puoi creare un sistema di pulizia globale nel tuo gioco con i semplici passaggi descritti di seguito:

• Assegna a una statistica un nome, ad esempio "versione".
  
• Inserisci nel gioco un numero di versione a codifica fissa per le statistiche.
  
• Una volta che le statistiche sono state caricate, confronta la statistica "versione" con il numero di versione a codifica fissa.
  
• Se non corrispondono, effettua la chiamata a ISteamUserStats::ResetAllStats e imposta la statistica "versione" sul numero a codifica fissa.

In questo modo, ogni volta che vorrai eseguire una pulizia globale sarà sufficiente modificare il numero di versione a codifica fissa delle statistiche per far sì che la pulizia abbia luogo quando gli utenti aggiornano alla nuova build.

Coerenza delle statistiche

Riflettere sul modo in cui le statistiche sono correlate tra loro è una buona pratica per evitare incoerenze. Supponiamo che tu abbia configurato tre statistiche: "partite vinte", "partite perse" e "partite giocate". A dispetto delle migliori intenzioni, le statistiche possono perdere (e succede!) la sincronizzazione reciproca. Se ciò avviene, le partite vinte e quelle perse non corrispondono al totale delle partite giocate. Volendo aggirare il problema rimuovendo la statistica "partite perse" e deducendola dal calcolo "partite giocate" meno "partite vinte", la presenza di un'incoerenza potrebbe generare un valore negativo per le "partite perse". In questo caso, è meglio rimuovere la statistica "partite giocate" e calcolarla addizionando tra loro "partite vinte" e "partite perse".

Statistiche globali

Attribuendo alle statistiche la proprietà "aggregata" dalla pagina dell'amministratore è possibile far sì che Steam tenga traccia del totale globale dei valori di tutti gli utenti per la statistica. Questa proprietà può essere utile per ottenere dati sul denaro totale, sulle uccisioni complessive, sulle armi e le mappe preferite nonché sulle squadre che realizzano i punteggi migliori. D'altra parte, non è opportuno utilizzare questa proprietà per statistiche del tipo "Max numero di uccisioni", in quanto non avrebbe senso calcolare la somma di questo valore per più utenti. Poiché le statistiche sono nelle mani dei giocatori, è possibile che questi dati vengano manipolati. Di conseguenza, quando si utilizzano le statistiche aggregate è fondamentale impostare dei limiti pertinenti per il valore minimo, il valore massimo, la variazione massima e la proprietà "solo incremento", se necessaria. La variazione massima svolge un ruolo particolare per le statistiche aggregate: quando viene caricato un nuovo valore, il valore globale non può infatti modificarsi superando la variazione massima indicata. Questa proprietà rallenta l'influenza dei cheater sui totali globali.

Per accedere ai totali globali, effettua la chiamata a ISteamUserStats::RequestGlobalStats e quindi a ISteamUserStats::GetGlobalStat per ciascuna statistica globale. Inviando la chiamata a ISteamUserStats::RequestGlobalStats puoi richiedere un numero specifico di giorni della cronologia, la quale indica di quanto si è modificata la statistica ogni giorno. Accedi alla cronologia utilizzando ISteamUserStats::GetGlobalStatHistory.

Puoi richiedere anche le percentuali globali di completamento degli achievement dal client: per prima cosa, effettua la chiamata a ISteamUserStats::RequestGlobalAchievementPercentages, quindi ordina gli achievement in ordine decrescente di completamento inviando la chiamata a ISteamUserStats::GetMostAchievedAchievementInfo e ISteamUserStats::GetNextMostAchievedAchievementInfo. Se vuoi ottenere la percentuale di completamento per un determinato achievement, effettua la chiamata a ISteamUserStats::GetAchievementAchievedPercent.

Testing

Prima del rilascio della tua applicazione non potrai vedere quali achievement sono stati ottenuti nella Comunità o nella Libreria di Steam. La tua applicazione avrà bisogno di un modo per visualizzare gli achievement ottenuti dall'utente.

Per azzerare un achievement o delle statistiche senza aggiungere codice al tuo gioco, puoi usare la console del client di Steam. Avviala con steam.exe -console, seguito da:

• achievement_clear <appid> <achievement name>
  
• reset_all_stats <appid>

La Comunità di Steam

Quando rilasci un gioco, le informazioni sull'avanzamento globale e individuale degli achievement vengono mostrate nella Comunità di Steam. Nel profilo della Comunità di ciascun giocatore sarà presente un collegamento a una pagina dove vengono esposti gli achievement completati e quelli ancora da sbloccare.
Ciascun achievement presente nell'elenco avrà l'icona appropriata e il nome e la descrizione impostati dal pannello di controllo di Steamworks. Se il nome e la descrizione dell'achievement sono stati tradotti nella lingua selezionata dall'utente, verranno visualizzati in tale lingua.

Inoltre, ci saranno due ulteriori collegamenti, uno da questa pagina e uno dalla pagina principale di Steam del gioco, a un set di statistiche globali degli achievement per il tuo gioco che mostreranno la percentuale di giocatori di Steam che hanno completato ciascuno di questi, ordinandoli dal più comune al più raro. Per i giocatori è divertente visualizzare le percentuali, mentre per te come sviluppatore costituiscono un'importante risorsa per capire se le sfide che hai ideato sono sufficientemente difficili o se, forse, lo sono troppo. Questa informazione è disponibile anche sul sito dei rapporti su vendite e attivazioni.

Altre domande?

Partecipa alle discussioni sulle statistiche e sugli achievement.