Pendahuluan
Berikut ini adalah panduan cepat untuk mengintegrasikan Papan Peringkat Steam yang sangat mendasar ke dalam aplikasimu dalam kurang dari 10 menit.
SDK Steamworks hadir dengan contoh aplikasi yang sangat bagus, yaitu
Spacewar, yang menunjukkan beragamnya pilihan fitur Steam dan seharusnya menjadi tempat pertamamu untuk melihat kerja seluruh fitur Steam. Tutorial ini merangkum informasi yang ditemukan di Spacewar dan API Papan Peringkat yang ada di dalam
ISteamUserStats, sehingga hanya menyajikan informasi yang diperlukan untuk memahami cara kerja Papan Peringkat Steam.
Langkah 1 - Mendefinisikan Papan Peringkat game-mu
Papan Peringkat bersifat khusus untuk aplikasi dan diatur di halaman
Konfigurasi Papan Peringkat di Situs Partner Steamworks.
Kolom berikut harus diisi untuk dapat mendefinisikan papan peringkat:
- Nama - Tetapkan nama yang mudah dipahami oleh pengembang internal.
- Nama Komunitas - Jika papan peringkat akan ditampilkan di Hub Komunitas, tetapkan nama untuk publik di sini. Jika tidak ada nama yang dimasukkan, papan peringkat tidak akan muncul.
- Metode Pengurutan - Tetapkan cara pengurutan papan peringkat. Untuk pengurutan berdasarkan posisi, gunakan Naik. Jika berdasarkan skor tertinggi, gunakan Turun.
- Jenis Tampilan - Menentukan jenis data yang akan ditampilkan di papan peringkat. Pilih antara Numerik, Detik, atau Milidetik.
- Tulis - Jika disetel ke Terpercaya, skor papan peringkat tidak dapat diatur oleh client, dan hanya dapat diatur melalui Web API SetLeaderboardScore. Default-nya adalah false.
- Baca - Jika disetel ke Teman, game hanya akan dapat membaca skor papan peringkat teman-teman pengguna. Semua skor dapat dibaca oleh Web API. Default-nya adalah false.
Langkah 2 - Mengenkapsulasi kerja Papan Peringkat
Kode berikut bisa diterapkan pada game apa pun dan bisa ditambahkan ke game-mu sesuai kebutuhan. Kelasnya berfungsi penuh tanpa harus diubah, tapi bisa diekstensi untuk memenuhi kebutuhan lebih lanjut. Semua kode ini diambil langsung dari file Spacewar
Leaderboards.cpp/h.
File Tajuk
Kami mendefinisikan kelas helper yang akan membungkus semua panggilan API Papan Peringkat Steam serta membuat semua handler hasil panggilan Steam.
class CSteamLeaderboards
{
private:
SteamLeaderboard_t m_CurrentLeaderboard; // Handle ke papan peringkat
public:
int m_nLeaderboardEntries; // Ada berapa entri yang kita punya？
LeaderboardEntry_t m_leaderboardEntries[10]; // Entri
CSteamLeaderboards();
~CSteamLeaderboards(){};
void FindLeaderboard( const char *pchLeaderboardName );
bool UploadScore( int score );
bool DownloadScores();
void OnFindLeaderboard( LeaderboardFindResult_t *pResult, bool bIOFailure);
CCallResult m_callResultFindLeaderboard;
void OnUploadScore( LeaderboardScoreUploaded_t *pResult, bool bIOFailure);
CCallResult m_callResultUploadScore;
void OnDownloadScore( LeaderboardScoresDownloaded_t *pResult, bool bIOFailure);
CCallResult m_callResultDownloadScore;
};
File Kode
Konstruktor
Parameter - Tidak ada
Hasil - N/A
Fungsi - Konstruktor ini hanya menginisialisasi variabel anggota.
CSteamLeaderboards::CSteamLeaderboards() :
m_CurrentLeaderboard( NULL ),
m_nLeaderboardEntries( 0 )
{
}
FindLeaderboard()
Parameter - Pengidenfikasi string dari papan peringkat yang ingin kamu cari (cth. "Jarak dalam Satuan Kaki")
Hasil - Tidak ada
Fungsi - Metode ini membungkus panggilan ke
ISteamUserStats::FindLeaderboard yang merupakan panggilan asinkron ke Steam yang meminta handle ke papan peringkat yang diberikan. Panggilan ini perlu dilakukan sebelum kamu dapat mengambil atau mengatur entri papan peringkat. Metode ini juga mengatur metode pengembalian panggilan yang digunakan.
void CSteamLeaderboards::FindLeaderboard( const char *pchLeaderboardName )
{
m_CurrentLeaderboard = NULL;
SteamAPICall_t hSteamAPICall = SteamUserStats()->FindLeaderboard(pchLeaderboardName);
m_callResultFindLeaderboard.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnFindLeaderboard);
}
OnFindLeaderboard()
Parameter - N/A
Hasil - Tidak ada
Fungsi - Metode ini adalah callback yang dipanggil kapan saja kamu mencoba untuk mencari papan peringkat di Steam. Jika papan peringkat yang diminta ditemukan, maka tetapkan handle papan peringkat tersebut sebagai papan peringkat saat ini.
void CSteamLeaderboards::OnFindLeaderboard( LeaderboardFindResult_t *pCallback, bool bIOFailure )
{
// lihat apabila ada eror selama panggilan
if ( !pCallback->m_bLeaderboardFound || bIOFailure )
{
OutputDebugString( "Leaderboard could not be found\n" );
return;
}
m_CurrentLeaderboard = pCallback->m_hSteamLeaderboard;
}
UploadScore()
Parameter - int32 mewakili nilai yang akan disimpan di papan peringkat saat ini.
Hasil - false jika papan peringkat belum dipilih, dan akan kembali ke true jika sudah.
Fungsi - Metode ini membungkus panggilan ke
ISteamUserStats::UploadLeaderboardScore yang merupakan panggilan asinkron ke Steam yang mengunggah skor pengguna saat ini ke papan peringkat yang dipilih. Metode ini juga mengatur metode pengembalian panggilan yang digunakan. Panggilan ini harus dibuat setelah kamu memilih papan peringkat menggunakan
FindLeaderboard().
bool CSteamLeaderboards::UploadScore( int score )
{
if (!m_CurrentLeaderboard)
return false;
SteamAPICall_t hSteamAPICall =
SteamUserStats()->UploadLeaderboardScore( m_CurrentLeaderboard, k_ELeaderboardUploadScoreMethodKeepBest, score, NULL, 0 );
m_callResultUploadScore.Set(hSteamAPICall, this, &CSteamLeaderboards::OnUploadScore);
return true;
}
OnUploadScore()
Parameter - N/A
Hasil - Tidak ada
Fungsi - Metode ini adalah callback yang dipanggil kapan saja kamu mencoba untuk mengunggah skor ke papan peringkat di Steam.
void CSteamLeaderboards::OnUploadScore(LeaderboardScoreUploaded_t *pCallback, bool bIOFailure)
{
if ( !pCallback->m_bSuccess || bIOFailure )
{
OutputDebugString( "Score could not be uploaded to Steam\n" );
}
}
DownloadScores()
Parameter - N/A
Hasil - false jika papan peringkat belum dipilih, dan akan kembali ke true jika sudah.
Fungsi - Metode ini membungkus panggilan ke
ISteamUserStats::DownloadLeaderboardEntries yang merupakan panggilan asinkron ke Steam yang mengunduh set entri dari papan peringkat yang dipilih. Pada contoh ini, kita mengunduh 10 entri; empat sebelum pengguna saat ini, pengguna saat ini, dan lima setelahnya. Panggilan ini dapat diubah untuk mengembalikan sejumlah entri dari mana pun di papan peringkat. Metode ini juga mengatur metode pengembalian panggilan yang digunakan. Panggilan ini harus dibuat setelah kamu memilih papan peringkat menggunakan
FindLeaderboard().
bool CSteamLeaderboards::DownloadScores()
{
if (!m_CurrentLeaderboard)
return false;
// muat data dari papan peringkat di sekitar pengguna saat ini
SteamAPICall_t hSteamAPICall = SteamUserStats()->DownloadLeaderboardEntries(
m_CurrentLeaderboard, k_ELeaderboardDataRequestGlobalAroundUser, -4, 5);
m_callResultDownloadScore.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnDownloadScore);
return true;
}
OnDownloadScore()
Parameter - N/A
Hasil - Tidak ada
Fungsi - Metode ini adalah callback yang dipanggil kapan saja kamu mencoba untuk mengunduh entri dari papan peringkat di Steam. Jika data berhasil diunduh, salinlah data tersebut ke dalam array entri. Jumlah entri yang diunduh disimpan di
m_nLeaderboardEntries.
void CSteamLeaderboards::OnDownloadScore(LeaderboardScoresDownloaded_t *pCallback, bool bIOFailure)
{
if (!bIOFailure)
{
m_nLeaderboardEntries = min(pCallback->m_cEntryCount, 10);
for (int index = 0; index < m_nLeaderboardEntries; index++)
{
SteamUserStats()->GetDownloadedLeaderboardEntry(
pCallback->m_hSteamLeaderboardEntries,index,&m_leaderboardEntries[index],NULL,0);
}
}
}
Langkah 3 - Mengintegrasikan ke game-mu
Berikut adalah daftar lengkap cuplikan kode yang harus kamu integrasikan ke game-mu di lokasi yang sesuai.
Definisi dan Global
Berikut ini adalah daftar pernyataan penyertaan yang dibutuhkan untuk membuat Papan Peringkat, serta penunjuk global ke objek helper kita.
...
#include "steam_api.h"
#include "SteamLeaderboards.h"
// Akses global ke Objek Papan Peringkat
CSteamLeaderboards* g_SteamLeaderboards = NULL;
...
Inisialisasi
Panggilan ke
SteamAPI_Init menginisialisasi keseluruhan Steam dan harus dipanggil sebelum yang lainnya. Jika panggilannya berhasil, maka buatlah objek helper.
...
// Inisialisasi Steam
bool bRet = SteamAPI_Init();
// Buat objek SteamLeaderboards jika Steam berhasil diinisialisasi
if (bRet)
{
g_SteamLeaderboards = new CSteamLeaderboards();
}
...
Memproses Callback
Untuk memastikan bahwa kita sudah memproses semua callback Steam, kita harus mengirimkan pesan baru secara teratur. Ini dicapai dengan menambahkan panggilan ini ke loop game.
...
SteamAPI_RunCallbacks();
...
Mematikan
Panggilan ke
SteamAPI_Shutdown adalah sesuatu yang mungkin sudah ada di kodemu. Ini akan menutup Steam dan harus dipanggil sebelum aplikasimu tertutup. Terakhir, hapus objek helper yang kita buat.
...
// Matikan Steam
SteamAPI_Shutdown();
// Hapus objek SteamLeaderboards
if (g_SteamLeaderboards)
delete g_SteamLeaderboards;
...
Langkah 4 - Pengujian dan Troubleshoot
Kode contoh ini mengeluarkan informasi debug ke konsol debug yang dapat membantumu mengidentifikasi panggilan mana yang berhasil dan gagal. Berikut ini adalah beberapa pesan kegagalan umum dan perbaikannya:
Aplikasi ini gagal dijalankan karena steam_api.dll tidak ditemukan. Menginstal ulang aplikasi dapat memperbaiki masalah ini.Pastikan steam_api.dll berada di direktori yang sama dengan executable.
[S_API FAIL] SteamAPI_Init() failed; tidak dapat menemukan Steam yang sedang dijalankan, atau steamclient.dll lokalKemungkinan besar tidak ada Steam Client yang sedang dijalankan. Buka Steam dan login.
[S_API FAIL] SteamAPI_Init() failed; tidak menemukan AppID.Kemungkinan besar file steam_appid.txt tidak ada. Tempatkan file di folder source dan pastikan file tersebut berisi AppID aplikasimu.
