イントロダクション
以下のステップバイステップガイドでは、アプリケーションにごく基本的なSteamランキングを10分未満で実装する方法を説明します。
Steamworks SDK内の
Spacewar は、様々なSteam機能を含む非常に役立つサンプルアプリケーションです。Steamのすべての機能の動作を確認するためにも、ぜひ最初にご覧ください。 このチュートリアルでは、Spacewarや
ISteamUserStats内のランキングAPIの情報の中からSteamランキングを理解するのに必要な分だけの情報に絞り込んで説明します。
ステップ1 - ゲームのランキングの定義
ランキングはアプリケーション固有のものであり、Steamworksパートナーサイトの
ランキング構成ページで設定できます。
ランキングを定義するには、次のフィールドを埋める必要があります：
- 名前－内部の開発者向けにわかりやすい名前を設定してください。
- コミュニティ名－ランキングがコミュニティハブに表示される場合は、ここに公開用の名前を設定します。 名前が入力されていない場合、ランキングは表示されません。
- 並べ替え方法－ランキングの並べ替え順序を設定します。 順位を基にしたランキングの場合は昇順を使用します。 ハイスコアベースの場合は降順を使用します。
- 表示タイプ－ランキングに表示するデータの種類を決定します。 数値、秒、ミリ秒から選択できます。
- 書き込み－これがTrustedに設定されている場合、ランキングスコアはクライアントでは設定できず、SetLeaderboardScore WebAPI経由でのみ設定できます。 デフォルトはfalseです。
- 読み取り－これがFriendsに設定されている場合、ゲームはユーザーのフレンドのランキングスコアのみを読み取ることができます。全スコアは常にWebAPIで読み取ることができます。 デフォルトはfalseです。
ステップ2 - ランキングのカプセル化作業
以下のコードはゲームから独立したもので、必要に応じてゲームに追加することができます。 クラスはこのままでも機能しますが、将来的に必要であれば簡単に拡張できます。 すべてのコードはSpacewarサンプルのファイル、
Leaderboards.cpp/hからの抜粋です。
ヘッダーファイル
すべてのSteamランキングAPI呼び出しをラップし、Steamの呼び出し結果のハンドラを作成するヘルパークラスを定義します。
class CSteamLeaderboards
{
private:
SteamLeaderboard_t m_CurrentLeaderboard; // ランキングへのハンドル
public:
int m_nLeaderboardEntries; // エントリー数？
LeaderboardEntry_t m_leaderboardEntries[10]; // エントリー
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;
};
コードファイル
コンストラクター
パラメーター －なし
戻り値 －なし
動作 －このコンストラクターがメンバー変数を初期化します。
CSteamLeaderboards::CSteamLeaderboards() :
m_CurrentLeaderboard( NULL ),
m_nLeaderboardEntries( 0 )
{
}
FindLeaderboard()
パラメーター －見つけたいランキングの文字列識別子（例： 「Feet Traveled」等）
戻り値 －なし
動作 －このメソッドは
ISteamUserStats::FindLeaderboardの呼び出しをラップします。これは、指定のランキングへのハンドルを要求するSteamへの非同期呼び出しです。 これは、ランキングエントリーの取得または設定の前に呼び出される必要があります。 このメソッドは使用するコールリターンメソッドも設定します。
void CSteamLeaderboards::FindLeaderboard( const char *pchLeaderboardName )
{
m_CurrentLeaderboard = NULL;
SteamAPICall_t hSteamAPICall = SteamUserStats()->FindLeaderboard(pchLeaderboardName);
m_callResultFindLeaderboard.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnFindLeaderboard);
}
OnFindLeaderboard()
パラメーター －なし
戻り値 －なし
動作 －このメソッドは、Steamでランキングを探す際に呼び出されるコールバックです。 リクエストされたランキングが見つかると、そのランキングのハンドルが現在のランキングとして設定されます。
void CSteamLeaderboards::OnFindLeaderboard( LeaderboardFindResult_t *pCallback, bool bIOFailure )
{
// 呼び出し中のエラーの有無を確認
if ( !pCallback->m_bLeaderboardFound || bIOFailure )
{
OutputDebugString( "Leaderboard could not be found\n" );
return;
}
m_CurrentLeaderboard = pCallback->m_hSteamLeaderboard;
}
UploadScore()
パラメーター －現在のランキングに格納する値を表すint32。
戻り値 －ランキングが選択されていない場合はfalse、それ以外はtrueを返します。
動作 －このメソッドは、現在選択されているランキングに、現在のユーザーのスコアをアップロードするSteamへの非同期呼び出しである、
ISteamUserStats::UploadLeaderboardScoreへの呼び出しをラップします。 このメソッドは使用するコールリターンメソッドも設定します。 この呼び出しは
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()
パラメーター －なし
戻り値 －なし
動作 －このメソッドはSteamのランキングにスコアをアップロードしようとする時に必ず呼び出されるコールバックです。
void CSteamLeaderboards::OnUploadScore(LeaderboardScoreUploaded_t *pCallback, bool bIOFailure)
{
if ( !pCallback->m_bSuccess || bIOFailure )
{
OutputDebugString( "Score could not be uploaded to Steam\n" );
}
}
DownloadScores()
パラメーター －なし
戻り値 －ランキングが選択されていない場合はfalse、それ以外はtrueを返します。
動作 －このメソッドは、現在選択されているランキングから一連のエントリーをダウンロードするSteamへの非同期呼び出しである
ISteamUserStats::DownloadLeaderboardEntriesへの呼び出しをラップします。 この例では、10個のエントリーをダウンロードしています。含まれるのは、現在のユーザーの前の4人、現在のユーザー、そして現在のユーザーの後の5人です。 この呼び出しは、ランキング内の順位に関わらず任意の数のエントリーを返すように変更できます。 このメソッドは使用するコールリターンメソッドも設定します。 この呼び出しは
FindLeaderboard()を使用してランキングを選択した後に実行される必要があります。
bool CSteamLeaderboards::DownloadScores()
{
if (!m_CurrentLeaderboard)
return false;
// 現在のユーザー周辺の指定されたランキングデータを読み込む
SteamAPICall_t hSteamAPICall = SteamUserStats()->DownloadLeaderboardEntries(
m_CurrentLeaderboard, k_ELeaderboardDataRequestGlobalAroundUser, -4, 5);
m_callResultDownloadScore.Set(hSteamAPICall, this,
&CSteamLeaderboards::OnDownloadScore);
return true;
}
OnDownloadScore()
パラメーター －なし
戻り値 －なし
動作 －このメソッドはSteamでランキングからエントリーをダウンロードしようとするたびに呼び出されるコールバックです。 データが正常にダウンロードされた場合、そのデータをSteamのエントリーの配列にコピーします。 ダウンロードされたエントリーの数は
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);
}
}
}
ステップ3－ゲームへの統合
以下はあなたのゲームの適切な位置に埋め込む必要があるコードスニペットの全リストです。
定義とグローバル
以下は、ランキングの構築に必要なインクルードファイルと、ヘルパーオブジェクトへのグローバルポインターのリストです。
...
#include "steam_api.h"
#include "SteamLeaderboards.h"
// ランキングオブジェクトへのグローバルアクセス
CSteamLeaderboards* g_SteamLeaderboards = NULL;
...
初期化
SteamAPI_Initへの呼び出しは、Steam全体を初期化するもので、一番最初に呼び出される必要があります。 呼び出しが成功するとヘルパーオブジェクトが作成されます。
...
// Steamを初期化
bool bRet = SteamAPI_Init();
// Steamが正常に初期化された場合、SteamLeaderboardsオブジェクトを作成
if (bRet)
{
g_SteamLeaderboards = new CSteamLeaderboards();
}
...
コールバックの処理
Steamのすべてのコールバックを確実に処理するために、新たなメッセージを定期的にチェックする必要があります。 これは、この呼び出しをゲームループに追加することで実現できます。
...
SteamAPI_RunCallbacks();
...
シャットダウン
SteamAPI_Shutdownへの呼び出しは、おそらく既にコード内に含まれています。 これはSteamをシャットダウンするものであり、アプリケーションを閉じる前に呼び出す必要があります。 最後に、作成したヘルパーオブジェクトを削除します。
...
//Steamをシャットダウン
SteamAPI_Shutdown();
//SteamLeaderboardsオブジェクトを削除
if (g_SteamLeaderboards)
delete g_SteamLeaderboards;
...
ステップ4－テストおよびトラブルシューティング
デバッグ情報をデバッグコンソールに出力するこのサンプルコードは、どの呼び出しが成功、または失敗するかを理解するのに役立ちます。 以下は典型的なエラーメッセージと修正例です。
This application has failed to start because steam_api.dll was not found. Re-installing the application may fix this problem.（steam_api.dllが見つからないため、このアプリケーションの起動に失敗しました。アプリケーションを再インストールすると、この問題が解決する場合があります。）steam_api.dllが実行ファイルと同じディレクトリーにあることを確認してください。
[S_API FAIL] SteamAPI_Init() failed; unable to locate a running instance of Steam, or a local steamclient.dll（[S_API FAIL] SteamAPI_Init() が失敗しました; Steamの実行中のインスタンス、またはローカルのSteamclient.dll が見つかりません。）Steamクライアントが実行されていない可能性があります。 Steamを起動してログインしてください。
[S_API FAIL] SteamAPI_Init() failed; no appID found.（[S_API FAIL] SteamAPI_Init() が失敗しました; appID が見つかりません。）steam_appid.txtファイルが所定の場所にない可能性があります。 同ファイルをソースフォルダーに配置して、その中にあなたのAppID番号があることを確認してください。
