Ringkasan

Statistik dan Pencapaian Steam menyediakan cara mudah bagi game-mu untuk menyediakan pelacakan pencapaian dan statistik yang persisten untuk penggunamu. Data pengguna dikaitkan ke akun Steam mereka, dan setiap pencapaian pengguna dan statistik bisa dibentuk dan ditampilkan di Profil Komunitas Steam mereka.

Kegunaan

Selain memberikan hadiah bernilai tinggi kepada pemain game-mu, pencapaian sangatlah berguna untuk mendorong dan menghargai kerja sama tim dan interaksi pemain, menambah dimensi tujuan game, dan memberi penghargaan kepada pengguna yang menghabiskan lebih banyak waktu mereka di dalam game.

Statistik melacak informasi yang sangat terinci seperti waktu bermain, jumlah power-up yang digunakan, dll. Kamu boleh menggunakannya hanya sebagai alat untuk melacak data internal game - agar kamu bisa memberikan pencapaian berdasarkan dari statistik yang dikumpulkan dari multisesi gameplay dari pengguna dari berbagai komputer.

Ringkasan Implementasi

Tentukan Statistik dan Pencapaian Game-mu

Pencapaian setiap aplikasi berbeda dan disiapkan di halaman Admin Aplikasi dari situs partner Steamworks.

Ada tiga jenis statistik yang bisa disimpan game-mu:

• INT - integer 32-bit bertanda (cth. jumlah game yang dimainkan)
  
• FLOAT - nilai poin float 32-bit (cth. jarak tempuh dalam mil)
  
• AVGRATE - Rata-rata variabel. Lihat: Jenis statistik AVGRATE

Situs web Partner Steamworks memberikan antarmuka untuk menentukan dan memperbarui game statistik dan pencapaianmu. Dengan ini, kamu bisa:

• Tentukan statistik dan pencapaian awal
  
• Tambahkan statistik dan pencapaian tambahan
  
• Perbarui nama pencapaian, deskripsi, dan ikon
  
• Perbarui parameter dan batasan statistik ( nilai maks./min., rata-rata variabel ukuran jendela, dll.)

Statistik memiliki properti berikut:

• ID - ID numerik yang dibuat secara otomatis untuk setiap statistik.
  
• Jenis - Jenis dari Statistik - INT, FLOAT, atau AVGRATE.
  
• Nama API - String yang digunakan untuk mengakses statistik ini menggunakan API.
  
• Diatur Oleh - Untuk memilih siapa yang bisa mengubah statistik ini. Client merupakan default-nya. Untuk info lebih lanjut lihat Statistik Server Game.
  
• Hanya Kenaikan Berjangka - jika diatur, nilai statistik ini hanya boleh ditingkatkan seiring waktu.
  
• Perubahan Maks. - Mengatur jumlah yang ditetapkan untuk membatasi perubahan nilai statistik yang bisa berubah dari satu nilai ke nilai lainnya.
  
• Nilai Min. - Mengatur nilai numerik minimum yang bisa digunakan statistik ini. Secara default, Min adalah nilai minimum jenis numerik yang mendasarinya (INT_MIN atau -FLT_MAKS).
  
• Nilai Maks. - Jika diatur, ini menjadi nilai numerik maksimum yang bisa digunakan statistik ini. Secara default, maks adalah nilai maksimum jenis numerik yang mendasarinya (INT_MAX or FLT_MAX).
  
• Secara Default - Jika diatur, digunakan sebagai nilai default untuk statistik awal yang diatur untuk pengguna baru. Jika tidak diatur, nilai default-nya adalah nol.
  
• Agregat jika diatur, Steam akan menyimpan jumlah total global untuk statistik ini. Lihat Statistik Global di bawah untuk info lebih lanjut.
  
• Nama Tampilan - Nama statistik ini saat ditampilkan di aplikasimu.

AVGRATE memiliki properti tambahan berikut ini:

• Jendela - Ukuran "jendela geser" yang digunakan untuk menghitung rata-rata datamu.

Statistik AVGRATE adalah salah satu stat yang dirata-ratakan oleh Steam secara otomatis. Lihat bagian AVGRATE di bawah untuk info lebih lanjut.

Pencapaian memiliki properti berikut:

• ID - ID numerik yang dibuat secara otomatis untuk setiap pencapaian.
  
• Nama API - String yang digunakan untuk mengakses pencapaian ini menggunakan API.
  
• Statistik Progres - Menentukan statistik yang digunakan sebagai bilah progres di Komunitas untuk pencapaiannya. Pencapaian juga akan dibuka secara otomatis ketika statistik mencapai nilai yang dibutuhkan untuk membukanya.
  
• Nama Tampilan - Nama pencapaian ini akan memiliki pop-up pemberitahuan Client, dan di Komunitas. Bisa dilokalkan.
  
• Deskripsi - Deskripsi pencapaian ini, untuk ditampilkan di Komunitas. Bisa dilokalkan.
  
• Diatur Oleh - Untuk memilih siapa yang bisa mengubah pencapaian ini. Client merupakan default-nya. Untuk info lebih lanjut lihat Statistik Server Game.
  
• Tersembunyi? - Jika true, pencapaian yang "tersembunyi" tidak ditampilkan di halaman Komunitas pengguna (sama sekali) sampai mereka mencapainya.
  
• Ikon Tercapai - Ikon yang ditampilkan ketika tercapai.
  
• Ikon Tidak Tercapai - Ikon yang ditampilkan ketika tidak tercapai.

Berikut ini adalah daftar pencapaian dari Steamworks API Example Application (SpaceWar):

Pertimbangan khusus

• Nama pencapaian dan ikon harus sesuai untuk semua usia.
  
• Secara default, maks. pencapaian dalam game adalah 100 di awal. Setelah aplikasimu mencapai ambang batas untuk Fitur Profil, kamu akan bisa menambahkan lebih banyak pencapaian.

Cara menggunakan

Mengakses Statistik dan Pencapaian dari dalam game-mu:

• Setelah menginisiasi API Steamworks kamu bisa mulai menggunakan API Statistik dan Pencapaian yang berisi ISteamUserStats.
  
• Di awal sesi game, panggil ISteamUserStats::RequestCurrentStats untuk mengambil statistik pengguna dan data pencapaian dari back end Steam. Kamu akan menerima callback ISteamUserStats::UserStatsReceived_t ketika data sudah siap.
  
• Gunakan ISteamUserStats::GetStat dan ISteamUserStats::GetAchievement untuk pengulangan data dan memulai status game.
  
• Jika kamu ingin menampilkan pencapaian di game-mu, kamu bisa menggunakan ISteamUserStats::GetAchievementDisplayAttribute untuk mendapatkan properti pencapaian yang bisa dibaca, termasuk nama ("name") dan deskripsinya ("desc"). Properti ini bisa dilokalkan di Situs Web Partner Steamworks, dan data yang didapatkan bervariasi tergantung dari bahasa yang digunakan oleh pengguna game. Kamu juga bisa mendapatkan ikon pencapaian menggunakan ISteamUserStats::GetAchievementIcon atau waktu setiap pencapaian dibuka dengan ISteamUserStats::GetAchievementAndUnlockTime.
  
• Setiap kali statistik berubah, khususnya sebelum perubahan ditampilkan kepada pengguna, panggil ISteamUserStats::SetStat atau ISteamUserStats::UpdateAvgRateStat. Panggilan ini hanya mengubah status dalam memori Steam dan sangat murah. Dengan melakukannya, maka Steam akan tetap dapat menyimpan perubahan antar-sesi meskipun game-nya mengalami crash.
  
• Di titik yang tepat dalam game-mu (cth. titik pemeriksaan, transisi level), panggilISteamUserStats::StoreStats untuk mengunggah perubahan. Kamu akan menerima callback ISteamUserStats::UserStatsStored_t ketika proses sudah selesai.
  
• Untuk pencapaian dengan bilah progres, gunakan ISteamUserStats::IndicateAchievementProgress pada titik penting untuk menampilkan pop-up berisi progres. Misalnya, jika dibutuhkan 20 kemenangan, kamu dapat memanggil ini di 10 kemenangan untuk memberi tahu bahwa pengguna sudah mencapai setengah jalan.
  
• Setiap kali satu atau lebih pencapaian dibuka, panggil ISteamUserStats::SetAchievement untuk setiap pencapaian yang dibuka dan ISteamUserStats::StoreStats untuk langsung mengunggahnya. Kamu akan melihat callback ISteamUserStats::UserStatsStored_t dalam game-mu, ditambah callback ISteamUserStats::UserAchievementStored_t untuk setiap pencapaian yang terbuka. Overlay Game Steam akan menampilkan panel pemberitahuan kepada pengguna.

Jenis statistik AVGRATE

Jenis statistik ini memiliki fungsionalitas yang unik dan sangat berguna, tapi membutuhkan lebih banyak rincian penjelasan.

Pertimbangkan kasus di mana kamu ingin melacak statistik rata-rata, seperti "Poin yang didapatkan per jam". Salah satu pendekatannya adalah dengan menggunakan dua statistik, INT "TotalPoints" dan FLOAT "TotalPlayTimeHours", kemudian bagi poin berdasarkan waktu untuk mendapatkan Poin per Jam.

Kelemahan dari pengimplementasian ini adalah, setelah pemain sudah bermain cukup lama, perhitungan rata-rata akan berubah dengan sangat lambat. Faktanya, semakin banyak pemain yang memainkan game, semakin tidak responsif rata-rata itu. Setelah pengguna menghabiskan 100 jam bermain game, rata-rata yang dihitung akan tertinggal sekitar 50 jam dari angka ini. Jika mereka meningkatkan skill, mereka tidak akan melihat peningkatan itu di Poin Per Jam seperti yang diharapkan.

Statistik jenis AVGRATE memungkinkanmu untuk mengimplementasikan efek "jendela geser" pada rata-rata. Misalnya, kamu hanya dapat memperhitungkan beberapa jam terakhir dari waktu bermain agar statistiknya dapat mencerminkan level skill terkini pemain dengan lebih akurat.

Siapkan statistik AVGRATE untuk diimplementasikan di "poin per jam", di mana hanya 20 jam terakhir dari waktu bermain yang memengaruhi nilainya. Untuk melakukan ini, kamu harus:

• Perhatikan dengan baik bahwa rata-ratanya adalah "per jam", maka satuan waktu pada parameter yang terkait dengan statistik ini akan dalam "jam". Ini diaplikasikan ke properti Jendela di statistiknya sendiri, dan juga untuk parameter "dSessionLength", yang diteruskan ke UpdateAvgRateStat di bawah.
  
• Buat statistik AVGRATE bernama "AvgPointsPerHour", dan properti Jendela 20.0 (ingat bahwa satuannya adalah "jam")
  
• Pada titik yang tepat ketika game berlangsung, panggil ISteamUserStats::UpdateAvgRateStat dengan parameter berikut:
  
  • pchName - "AvgPointsPerHour"
    
  • flCountThisSession - Jumlah poin yang didapatkan pemain sejak panggilan terakhir ke UpdateAvgRateStat.
    
  • dSessionLength - Jumlah waktu game berjalan sejak panggilan terakhir ke UpdateAvgRateStat. Satuannya harus sama dengan satuan di statistik properti Jendela. Kita bicara soal "jam".
    
• Misalnya, jika pemain mendapatkan 77 poin di ronde terakhir, yang berlangsung selama 0,225 jam (13,5 menit), maka kita akan mendapatkan SteamUserStats()->UpdateAvgRateStat( "AvgPointsPerHour", 77, 0,225 )

Dalam contoh di atas, Steam akan mengambil rata-rata dari ronde yang sedang berlangsung, yaitu 342,2 poin per jam (77 dibagi 0,225) dan menggabungkannya ke nilai sebelumnya. Hasilnya akan mencerminkan rata-rata total dari 20 jam terakhir dari waktu bermain pemain itu. Jika ini adalah pertama kali statistiknya diperbarui untuk pemain saat ini, nilai saat ini adalah 342,2.

Contoh ini menggunakan "jam" sebagai satuan waktu, tapi kamu dapat menggunakan satuan waktu apa pun yang kamu mau. Perlu diingat bahwa kamu harus secara konsisten menggunakan satuan ini sebagai basis untuk "dSessionLength", juga untuk properti Jendela.

Mendapatkan statistik untuk pengguna lain

Kamu bisa menggunakan ISteamUserStats::RequestUserStats untuk mendapatkan statistik dari pemain lain. Kemudian kamu bisa menggunakan ISteamUserStats::GetUserStat,ISteamUserStats::GetUserAchievement, dan ISteamUserStats::GetUserAchievementAndUnlockTime untuk mendapatkan data dari pengguna tersebut. Data ini tidak diperbarui secara otomatis saat pengguna lain mengunggah statistik baru, jadi untuk me-refresh data, panggil lagi ISteamUserStats::RequestUserStats.

Untuk menghindari penggunaan memori yang terlalu besar, cache LRU (Paling Sedikit Digunakan) dipertahankan dan statistik pengguna lain kadang-kadang akan dihapus. Ketika ini terjadi, callback ISteamUserStats::UserStatsUnloaded_t secara otomatis dikirimkan. Ketika callback ini dikirim maka statistik pengguna yang ditentukan tidak akan tersedia sampai ISteamUserStats::RequestUserStats dipanggil lagi.

Mode offline

Steam menyimpan cache lokal dari data statistik dan pencapaian sehingga API bisa digunakan secara normal saat dalam mode offline. Statistik apa pun yang tidak tersedia untuk dipanggil akan disimpan dan akan tersedia ketika pengguna online. Jika ada modifikasi di lebih dari satu mesin, Steam akan secara otomatis menggabungkan pencapaian dan memilih set statistik yang memiliki progres terbanyak. Karena Steam menyimpan cache lokal dari data statistik, maka game tidak perlu juga menyimpan data cache lokal di disk. Cache semacam itu sering bertentangan. Ketika terjadi, pengguna akan melihat bahwa progres mereka telah dibatalkan, dan itu bisa membuat mereka frustasi.

Statistik Server Game

Pararel dengan ISteamUserStats adalah ISteamGameServerStats untuk server game. Ini memungkinkanmu untuk mendapatkan statistik pengguna dengan cara yang sama seperti Client (seperti yang dijelaskan di atas). Ini juga bisa digunakan untuk mendapatkan statistik dan pencapaian penghargaan, tapi hanya jika "Diatur oleh"-nya diatur ke GS (server game) atau GS resmi. Perbedaan antara server game dan server game resmi adalah server game resmi dapat kamu hosting dan kontrol. Menggunakan server game resmi untuk mengatur statistik memungkinkan peningkatan keamanan terhadap kecurangan, karena pengguna mana pun dapat memodifikasi server game mereka sendiri atau berpura-pura menjadi server game. Untuk menentukan server game resmi, masukkan rentang IP server di sini.

Statistik dan pencapaian yang bisa diatur oleh server game tidak bisa diatur oleh Client. Server game hanya bisa mengatur statistik dan pencapaian untuk pengguna yang sedang bermain di server. Jika pengguna meninggalkan server, maka akan ada masa tenggang singkat untuk menetapkan statistik akhir, dan setelah itu pengunggahan apa pun akan ditolak. Ini berfungsi untuk membantu memastikan konsistensi dan menghindari kemungkinan server game berbahaya dari menetapkan statistik seseorang kapan pun. Dengan adanya pembatasan, sangat penting untuk tidak menunggu hingga akhir ronde untuk menetapkan statistik. Tetapkan statistik secara terus menerus agar kamu bisa menyimpannya saat pengguna keluar dari game.

Client akan mendapatkan pembaruan otomatis ketika server game mengubah statistik mereka. Namun, seperti Client, statistik yang dimuat oleh server untuk pengguna lain tidak di-refresh secara otomatis dan bisa kedaluwarsa.

Mereset statistik

Selama pengembangan, penghapusan statistik dan pencapaian pada satu atau semua akun sering kali diperlukan untuk tujuan pengujian. Untuk menghapus statistik dari satu akun, panggil ISteamUserStats::ResetAllStats dengan bAchievementsToo yang diatur ke true untuk juga menghapus pencapaian. Setelah dipanggil, ingat untuk mengulangi statistik dan pencapaianmu dan mereset status game dalam memori. Tidak ada cara untuk menghapus statistik dan pencapaian secara global untuk semua pengguna. Salah satu alasannya adalah meskipun penghapusan global dilakukan, game yang sedang berjalan mungkin saja tidak mengetahui adanya penghapusan dan menulis kembali nilai dalam memori. Untungnya, ada cara mudah untuk membangun sistem penghapusan global ke dalam game-mu. Untuk melakukannya:

• Tentukan statistik dengan nama seperti "Version"
  
• Masukkan nomor versi statistik yang dikodekan ke dalam game
  
• Setelah statistik dimuat, bandingkan statistik "Version" dengan nomor dari versi yang dikodekan
  
• Jika tidak cocok, panggil ISteamUserStats::ResetAllStats dan atur statistik "Version" menjadi sama dengan nomor dari versi yang dikodekan.

Dengan begitu, kapan pun kamu ingin menghapus secara global, kamu hanya perlu mengubah nomor versi statistik yang dikodekan. Penghapusan global ini akan berlangsung saat pengguna mendapatkan build yang baru.

Konsistensi statistik

Merupakan hal yang bijak untuk memikirkan bagaimana statistik yang terkait bisa jadi tidak konsisten. Misalnya, kamu mungkin memiliki tiga statistik, yaitu "GamesWon","GameLost", dan "GamePlayed". Terlepas dari niat baik, statistik dapat dan memang menjadi tidak sinkron satu sama lain. Dalam kasus ini, itu dapat menyebabkan kemenangan dan kekalahan dalam game tidak menambah total sesi game yang dimainkan. Jika ini diselesaikan dengan menghapus statistik "GamesLost", dan sebagai gantinya menghitungnya dengan "GamesPlayed" - "GamesWon", ketidakkonsistenan ini bisa menyebabkan "GamesLost" menjadi negatif. Dalam hal ini, sebaiknya hapus statistik "GamesPlayed" dan hitung dengan "GamesWon" + "GamesLost".

Statistik Global

Statistik dapat ditandai sebagai agregat di halaman admin untuk memberi tahu Steam agar menyimpan total global dari nilai semua pemain untuk statistik tersebut. Ini bisa digunakan untuk mendapatkan data tentang total uang dalam game, total kill, senjata favorit, map favorit, dan tim mana yang cenderung bermain lebih baik. Di sisi lain, ini tidak seharusnya digunakan untuk statistik seperti "MostKills", karena menambahkannya untuk beberapa pengguna menjadikan datanya tidak berguna. Karena statistik ada di tangan pengguna, data ini dapat dimanipulasi. Maka, sangat penting untuk menerapkan nilai minimum, nilai maksimum, hanya kenaikan bertahap (jika sesuai), dan perubahan maksimum ketika menggunakan statistik secara agregat. Perubahan maskimum memiliki arti khusus untuk statistik agregat. Ketika nilai baru diunggah, nilai global tidak akan berubah melebihi nilai perubahan maksimum yang ditentukan. Ini akan membatasi kecepatan cheater dari memengaruhi nilai total global.

Untuk mengakses total global, panggil ISteamUserStats::RequestGlobalStats dan ISteamUserStats::GetGlobalStat untuk setiap statistik global. Kamu juga bisa memanggil ISteamUserStats::RequestGlobalStats untuk meminta riwayat dalam jumlah hari tertentu. Riwayat adalah jumlah perubahan harian yang dialami statistik. Kamu bisa mengakses riwayat dengan ISteamUserStats::GetGlobalStatHistory.

Kamu juga bisa meminta persentase penyelesaian pencapaian global dari Client. Untuk melakukannya, panggil ISteamUserStats::RequestGlobalAchievementPercentages terlebih dulu. Lalu, ulangi pencapaian dengan urutan dari yang paling banyak dicapai ke yang paling sedikit dengan ISteamUserStats::GetMostAchievedAchievementInfo dan ISteamUserStats::GetNextMostAchievedAchievementInfo. Kamu bisa juga mendapatkan persentase penyelesaian dari pencapaian tertentu dengan memanggil ISteamUserStats::GetAchievementAchievedPercent.

Pengujian

Sebelum aplikasimu dirilis, kamu tidak akan bisa melihat pencapaian yang sudah didapatkan di Komunitas Steam atau perpustakaan. Aplikasimu membutuhkan cara untuk menampilkan pencapaian yang sudah didapatkan oleh pengguna.

Untuk menghapus pencapaian atau statistik tanpa menambahkan kode ke game-mu, kamu bisa menggunakan konsol Steam Client. Jalankan dengan steam.exe -console, kemudian:

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

Komunitas Steam

Setelah game-mu dirilis, informasi tentang progres pencapaian individu dan global akan ditampilkan di Komunitas Steam. Setiap pemain akan memilki tautan dari profil Komunitas mereka yang ditampilkan di halaman yang menampilkan pencapaian mereka, dan apa yang belum mereka capai.
Setiap pencapaian ditampilkan dengan ikon, juga nama dan deskripsi yang sesuai, seperti yang diatur di panel kontrol Steamworks. Jika nama dan deskripsi pencapaian sudah dilokalkan ke bahasa yang dipilih pengguna, maka pencapaian itu akan ditampilkan dalam bahasa tersebut.

Juga akan ada tautan dari halaman ini, dan satu lagi dari halaman utama Steam game-mu, ke serangkaian statistik pencapaian global untuk game-mu. Di sana terdapat persentase pemain Steam yang telah mencapai setiap pencapaiannya, diurutkan dari yang paling umum ke yang paling langka. Ini sangatlah menyenangkan untuk dilihat bagi pemain, dan juga menjadi sumber daya yang bagus bagi pengembang: apakah tantangan spesialnya cukup sulit? Atau mungkin terlalu sulit? (informasi ini juga tersedia di situs Laporan Penjualan dan Aktivasi).

Ada Pertanyaan Lain?

Ajukan pertanyaan di papan diskusi Statistik dan Pencapaian