Giriş
Aşağıda verilen adımları takip ederek 10 dakikada temel Steam sıralama listelerini uygulamanıza entegre edebilirsiniz.
Steamworks SDK'in beraberinde örnek bir uygulama olan ve Steam özelliklerinin kapsayıcılığını gösteren
Spacewar ile gelir. Bütün Steam özelliklerini çalışırken gözlemlemek istiyorsanız yapmanız gereken ilk şey bu uygulamayı incelemektir. Bu rehberde; Spacewar'da,
ISteamUserStats'teki sıralama listeleri API'ında bulunan bilgiler sadece Steam Sıralama Listeleri ile ilgili olacak şekilde süzülmüştür.
1. Adım - Oyununuzun sıralama listelerini tanımlamak
Sıralama listeleri uygulamaya özgüdür ve Steamworks partner sitesindeki
Sıralama Listesi Yapılandırması sayfasında yapılır.
Bir sıralama listesinin tanımlanabilmesi için aşağıdaki alanlar tamamlanmalıdır:
- Name - Dâhili geliştirme süreci için mantıklı olacak bir ad girin.
- Community Name - Eğer sıralama listesi Topluluk Merkezi'nde gösterilecekse buraya herkese görünecek bir ad girin. Eğer bir ad girilmezse sıralama listesi görünmeyecektir.
- Sort Method - Sıralama listesi sıralaması için bir düzen belirleyin. Konuma bağlı bir sıralama listesi için yükseleni kullanın. Yüksek skorlar için azalanı kullanın.
- Display Type - Sıralama listesinde gösterilecek veri türlerini belirler. Sayısal, saniye veya milisaniyeden birini seçin.
- Writes - Eğer "Güvenilir" olarak ayarlanırsa sıralama listesi skorları istemciler tarafından belirlenemez ve sadece SetLeaderboardScore WebAPI ile belirlenir. Varsayılan değer: false.
- Reads - Eğer bu, "Arkadaşlar" olarak belirlenirse oyun sadece kullanıcının arkadaşlarının sıralama listesi skorlarını okur. Bütün skorlar WebAPI tarafından her daim okunabilir. Varsayılan değer: false.
2. Adım - Sıralama listesini hazırlamak
Aşağıdaki kod oyundan bağımsızdır ve oyununuza istediğiniz şekilde eklenebilir. Sınıf olduğu şekliyle işlevseldir fakat diğer ihtiyaçlarınıza uyum sağlayacak şekilde genişletilebilir. Bu kodun tamamı doğrudan Spacewar'un örnek
Leaderboards.cpp/h dosyalarından alınmıştır.
Üstbilgi Dosyası
Bütün Steam sıralama listesi API çağrılarını saracak ve bütün Steam çağrı sonucu işleyicilerini oluşturacak bir yardımcı sınıf tanımlayacağız.
class CSteamLeaderboards
{
private:
SteamLeaderboard_t m_CurrentLeaderboard; // Sıralama listesine ver
public:
int m_nLeaderboardEntries; // Kaç tane girdimiz var?
LeaderboardEntry_t m_leaderboardEntries[10]; // Girdiler
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;
};
Kod Dosyası
Kurucu
Parametreler - Hiçbiri
Geri dönüş - Mevcut Değil
Eylem - Kurucu sadece üye değişkenleri başlatır.
CSteamLeaderboards::CSteamLeaderboards() :
m_CurrentLeaderboard( NULL ),
m_nLeaderboardEntries( 0 )
{
}
FindLeaderboard()
Parametreler - Bulmak istediğiniz sıralama listesinin tanıtıcı dizisi (ör. "Katedilen Metre")
Geri dönüş - Hiçbir şey
Eylem - Bu yöntem, Steam'e asenkron çağrı yaparak bir sıralama listesinin tanıtıcı değerini istemek için
ISteamUserStats::FindLeaderboard'a yapılan bir çağrıyı sarar. Bu çağrı, siz sıralama listesi girdilerini belirlemeden veya almadan önce yapılmalıdır. Bu yöntem ayrıca kullanılacak çağrı dönüş yöntemini de tanımlar.
void CSteamLeaderboards::FindLeaderboard( const char *pchLeaderboardName )
{
m_CurrentLeaderboard = NULL;
SteamAPICall_t hSteamAPICall = SteamUserStats()->FindLeaderboard(pchLeaderboardName);
m_callResultFindLeaderboard.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnFindLeaderboard);
}
OnFindLeaderboard()
Parametreler - Mevcut Değil
Geri dönüş - Hiçbir şey
Eylem - Bu yöntem, Steam'de bir sıralama listesini bulmaya çalıştığımız zaman çağrılan bir geri çağrıdır. Eğer istenen sıralama listesi bulunduysa bu sıralama listesinin tanıtıcı değerini mevcut sıralama listemiz olarak ayarlarız.
void CSteamLeaderboards::OnFindLeaderboard( LeaderboardFindResult_t *pCallback, bool bIOFailure )
{
// çağrı esnasında bir sorunla karşılaşıp karşılaşmadığımızı kontrol et
if ( !pCallback->m_bLeaderboardFound || bIOFailure )
{
OutputDebugString( "Leaderboard could not be found\n" );
return;
}
m_CurrentLeaderboard = pCallback->m_hSteamLeaderboard;
}
UploadScore()
Parametreler - Mevcut sıralama listesinde saklanacak değeri temsil eden bir int32.
Geri dönüş - eğer sıralama listesi seçilmediyse false, seçildiyse true olarak geri dönüş olur.
Eylem - Bu yöntem, mevcut kullanıcının skorunu seçili sıralama listesine yükleyen Steam'e yapılan bir asenkron çağrı olan
ISteamUserStats::UploadLeaderboardScore'a yapılan bir çağrıyı sarar. Bu yöntem ayrıca kullanılacak çağrı dönüş yöntemini de tanımlar. Bu çağrı, siz
FindLeaderboard() kullanarak bir sıralama listesi seçtikten sonra yapılmalıdır.
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()
Parametreler - Mevcut Değil
Geri dönüş - Hiçbir şey
Eylem - Bu yöntem, Steam'de bir sıralama listesine skor yüklemeye çalıştığımız zaman çağrılan bir geri çağrıdır.
void CSteamLeaderboards::OnUploadScore(LeaderboardScoreUploaded_t *pCallback, bool bIOFailure)
{
if ( !pCallback->m_bSuccess || bIOFailure )
{
OutputDebugString( "Score could not be uploaded to Steam\n" );
}
}
DownloadScores()
Parametreler - Mevcut Değil
Geri dönüş - eğer sıralama listesi seçilmediyse false, seçildiyse true olarak geri dönüş olur.
Eylem - Bu yöntem, seçili sıralama listesindeki girdileri indiren Steam'e yapılan bir asenkron çağrı olan
ISteamUserStats::DownloadLeaderboardEntries'e yapılan bir çağrıyı sarar. Bu durumda on girdi indiririz; mevcut kullanıcıdan yüksekte olan dört kullanıcı, mevcut kullanıcı ve mevcut kullanıcıdan düşük olan beş kullanıcı. Bu çağrı sıralama listesinin istediğiniz kısmından istediğiniz kadar girdi geri döndürecek kadar değiştirilebilir. Bu yöntem ayrıca kullanılacak çağrı dönüş yöntemini de tanımlar. Bu çağrı, siz
FindLeaderboard() kullanarak bir sıralama listesi seçtikten sonra yapılmalıdır.
bool CSteamLeaderboards::DownloadScores()
{
if (!m_CurrentLeaderboard)
return false;
// belirlenen sıralama listesindeki mevcut kullanıcının civarındaki verileri yükle
SteamAPICall_t hSteamAPICall = SteamUserStats()->DownloadLeaderboardEntries(
m_CurrentLeaderboard, k_ELeaderboardDataRequestGlobalAroundUser, -4, 5);
m_callResultDownloadScore.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnDownloadScore);
return true;
}
OnDownloadScore()
Parametreler - Mevcut Değil
Geri dönüş - Hiçbir şey
Eylem - Bu yöntem, Steam'de bir sıralama listesindeki girdileri indirmeye çalıştığımız zaman çağrılan bir geri çağrıdır. Eğer veri başarılı bir şekilde indirildiyse bu veriyi girdi dizinimize kopyalarız. İndirilen girdilerin sayısı
m_nLeaderboardEntries'de saklanır.
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);
}
}
}
3. Adım - Oyununuza entegre etmek
Aşağıda oyununuzun uygun yerlerine entegre etmeniz gereken kod parçalarının tam bir listesi yer almaktadır.
Tanımlamalar ve Küreseller
Aşağıda "Leaderboards" ile derlenmesi gereken içerikler ve yardımcı objemiz için küresel bir işaretleyici vardır.
...
#include "steam_api.h"
#include "SteamLeaderboards.h"
// "Leaderboards" objesine küresel erişim
CSteamLeaderboards* g_SteamLeaderboards = NULL;
...
Başlatma
SteamAPI_Init'e yapılan çağrı Steam'i tamamen başlatır ve bu çağrı diğer her şeyden önce yapılmalıdır. Eğer bu çağrı başarılı olursa yardımcı objeyi oluştururuz.
...
// Initialize Steam
bool bRet = SteamAPI_Init();
// Eğer Steam başarılı bir şekilde başladıysa "SteamLeaderboards" objesini oluştur
if (bRet)
{
g_SteamLeaderboards = new CSteamLeaderboards();
}
...
Geri Çağrıların İşlenmesi
Bütün Steam geri çağrılarını işleyebilmemiz için düzenli olarak yeni mesajlar göndermeliyiz. Bunun başarılabilmesi için şu çağrıyı oyunun döngüsüne eklemelisiniz.
...
SteamAPI_RunCallbacks();
...
Kapatma
SteamAPI_Shutdown'a yapılan çağrı muhtemelen kodunuzda zaten mevcuttur. Steam'i kapatır ve uygulamadan çıkmadan önce çağrılması gereklidir. Son olarak da oluşturduğumuz yardımcı objeyi siliyoruz.
...
// Shutdown Steam
SteamAPI_Shutdown();
// Delete the SteamLeaderboards object
if (g_SteamLeaderboards)
delete g_SteamLeaderboards;
...
4. Adım - Test etme ve sorun giderme
Bu örnek kod, hangi çağrıların başarılı hangilerinin başarısız olduğunu hata ayıklama konsolunda hata ayıklama bilgisi olarak gösterir. Aşağıda bazı tipik hata mesajları ve çözüm yolları yer almaktadır:
steam_api.dll bulunamadığı için bu uygulama başlatılamadı. Uygulamayı tekrar yükleyerek bu sorunu çözebilirsiniz.steam_api.dll'in yürütülebilirle aynı dizinde olduğundan emin olun.
[S_API FAIL] SteamAPI_Init() başarısız: Çalışan bir Steam örneği ya da ya da yerel bir steamclient.dll bulunamadı.Muhtemelen bir Steam istemcisi çalıştırmıyorsunuz. Steam'i başlatın ve giriş yapın.
[S_API FAIL] SteamAPI_Init() başarısız: herhangi bir appID bulunamadı.Muhtemelen steam_appid.txt dosyası olması gereken yerde değil. Kaynak klasöre bu dosyayı yerleştirin ve içinde appID numaranızın oluğundan emin olun.
