Ringkasan

Steam mendukung papan peringkat persisten dengan entri yang disusun secara otomatis. Papan peringkat ini bisa digunakan untuk menampilkan papan peringkat global atau teman dalam game-mu dan di halaman web komunitasmu. Setiap game di Steamworks dapat membuat hingga 10.000 papan peringkat, dan setiap papan peringkat bisa ditarik langsung setelah skor pemain dimasukkan.

Untuk setiap papan peringkat, pemain dapat memasukkan satu entri. Tidak ada batasan jumlah pemain untuk setiap papan peringkat. Setiap entri berisi memiliki skor untuk papan peringkat (int32) dan secara opsional hingga 64 int32 dari data terkait. Data terkait bisa digunakan untuk menyimpan informasi khusus game tentang sesi bermain yang menghasilkan entri papan peringkat pengguna. Data ini tidak diurutkan atau diurai oleh Steam, dan diganti ketika entri papan peringkat baru dibuat untuk pengguna.

Semua fungsi papan peringkat berada di ISteamUserGameStats.h, dan dua sampel papan peringkat sudah diimplementasikan di contoh Steamworks. Juga memungkinkan untuk melihat dan mengelola papan peringkat untuk game-mu di Admin Game Steamwork.

Persiapan

Semua fungsi asinkron papan peringkat mengembalikan handle ke hasil panggilan API Steam. Kamu bisa menemukan informasi lebih lanjut tentang cara menerima hasil-hasil ini di bagian Hasil Panggilan dalam dokumen Permulaan.

Membuat Papan peringkat

Papan peringkat adalah aplikasi khusus dan diatur di halaman Admin Game situs partner Steamworks atau via API.

Membuat via Web

Kamu dapat membuat dan mengelola papan peringkat di Admin Aplikasi Steamworks untuk AppID-mu dengan pergi ke Statistik & Pencapaian -> Papan Peringkat.


Kolom-kolom berikut harus diisi untuk mendefinisikan papan peringkat:

• Name - Isi dengan nama yang masuk akal sebagai bagian dari pengembangan internal.
  
• Nama Komunitas - Jika papan peringkat akan ditampilkan di Hub Komunitas, atur nama halaman untuk publik di sini. Jika tidak ada nama yang dimasukkan, papan peringkat tidak akan ditampilkan.
  
• Metode pengurutan - Atur urutan untuk pengurutan papan peringkat. Untuk pengurutan berdasarkan posisi, gunakan Naik. Jika berdasarkan skor tertinggi, gunakan Turun.
  
• Jenis Tampilan - Tentukan jenis data yang akan ditampilkan di papan peringkat. Pilih dari Numerik, Detik, atau Milidetik.
  
• Tulisan - Jika ini diatur ke Terpercaya, skor papan peringkat tidak bisa diatur oleh client, dan hanya bisa diatur via Web API SetLeaderboardScore. Default ke false.
  
• Membaca - Jika ini diatur ke Teman, game hanya bisa membaca skor papan peringkat teman dari pengguna, dan semua skor hanya bisa dibaca oleh Web API. Default ke false.

Membuat via API

Papan peringkat untuk game-mu bisa dibuat melalui Admin Aplikasi Steamworks atau diprogram dengan memanggil ISteamUserStats::FindOrCreateLeaderboard. Di Steam, semua papan peringkat untuk judul Steamworks diidentifikasikan dengan nama unik. Nama papan peringkat hanya digunakan sebagai pengenal di API Steamworks, dan tidak ditampilkan ke pengguna melalui Komunitas Steam. Ketika membuat papan peringkat, kamu harus memilih:

• metode pengurutan - k_ELeaderboardSortMethodAscending (entri paling atas adalah pengguna dengan skor terendah) atau k_ELeaderboardSortMethodDescending (entri teratas adalah pengguna dengan skor tertinggi)
  
• jenis tampilan - ELeaderboardDisplayType digunakan untuk mendeskripsikan apa yang direpresentasikan oleh skor papan peringkat, dan hanya digunakan oleh komunitas untuk memformat skor papan peringkat ketika ditampilkan

Jika kamu memilih untuk hanya menampilkan papan peringkatmu melalui Admin Aplikasi, kamu dapat menggunakan ISteamUserStats::FindLeaderboard untuk mengambil handle untuk papan peringkatmu. FindLeaderboard dan FindOrCreateLeaderboard adalah metode asinkron, dan mengembalikan handle papan peringkat untuk papan peringkat tertentu melalui hasil panggilan ISteamUserStats::LeaderboardFindResult_t.

Setelah papan peringkat dibuat, kamu bisa mengubah metode pengurutan dan jenis tampilan untuk papan peringkat melalui Admin Game. Ketika FindOrCreateLeaderboard dipanggil unutk papan peringkat yang sudah ada, metode pengurutan dan parameter jenis tampilannya diabaikan.

Mengunggah Skor

Untuk mengunggah skor papan peringkat, cukup panggil ISteamUserStats::UploadLeaderboardScore melalui target handle papan peringkat (diambil melalui FindLeaderboard), skor pengguna dan secara opsional data terkait yang dibuat ketika mengatur skor baru. Jika skor papan peringkat pengguna sudah diperbarui, data terkait yang disalurkan ke ISteamUserStats::UploadLeaderboardScore akan menggantikan data yang disimpan sebelumnya. Kamu dapat memilih antara dua metode pembaruan ketika mengunggah skor papan peringkat pengguna:

• ISteamUserStats::k_ELeaderboardUploadScoreMethodKeepBest - Steam akan membandingkan skor baru pengguna dengan skor yang sudah disimpan di papan peringkat, dan menyimpan skor terbaik pengguna (skor terendah untuk papan peringkat dengan pengurutan Ascending; skor tertinggi untuk papan peringkat dengan pengurutan Descending).
  
• ISteamUserStats::k_ELeaderboardUploadScoreMethodForceUpdate - Steam akan selalu mengganti skor pengguna di papan peringkat dengan skor yang baru.
  
• ISteamUserStats::UploadLeaderboardScore adalah panggilan asinkron, dan hasil dari pengunggahan yang dikembalikan ke hasil panggilan LeaderboardScoreUploaded_t. Hasil berisi penanda jika skor pengguna sudah diubah, dan ranking global lama dan baru lama dan baru. Setelah diunggah, papan peringkat Steamworks segera diperbarui untuk mencerminkan skor yang baru, dan urutan entri yang baru dapat diperoleh melalui DownloadLeaderboardEntries.

Melampirkan Konten Buatan Pengguna

Setelah skor diunggah kamu memiliki opsi untuk melampirkan konten buatan pengguna untuk entri tersebut. Untuk melakukannya, cukup panggil ISteamUserStats::AttachLeaderboardUGC. Konten ini dapat berisi pemutaran ulang dari pencapaian pengguna meraih skor atau projeksi melawan orang lain. Handle yang dilampirkan akan tersedia ketika entri diambil dan bisa diunduh oleh pengguna lain. Untuk membuat dan mengunduh konten buatan pengguna, lihat dokumentasi untuk Steam Cloud.

Setelah dilampirkan, konten akan tersedia meskipun jika file Cloud yang mendasarinya diubah atau dihapus oleh pengguna.

Mengambil Entri Papan Peringkat

ISteamUserStats::DownloadLeaderboardEntries digunakan untuk mengambil entri papan peringkat menggunakan handle papan peringkat yang diambil melalui ISteamUserStats::FindLeaderboard.

Setelah kamu mengambil semua entri yang diunduh dari GetDownloadedLeaderboardEntry, data entri akan dibebaskan dan SteamLeaderboardEntries_t dalam LeaderboardScoresDownloaded_t tidak akan valid lagi.

Mengambil Informasi Papan Peringkat

Dengan handle papan peringkat yand dikembalikan dari FindLeaderboard, kamu akan mendapatkan informasi tentang papan peringkat melalui hal-hal berikut:

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