Achievements インターフェース

Achievements (アチーブメント) インターフェース は、プレイヤーのアチーブメント関するデータを取得したり、そのプレイヤーのアチーブメントをロック解除したり、アプリケーションに属するすべてのアチーブメントに関するデータを取得したりする方法をデベロッパーに提供します。

Achievements インターフェースにアクセスする

Achievements インターフェースにアクセスするには、EOS_Platform_GetAchievementsInterface 関数を呼び出して EOS_HAchievements ハンドルを取得する必要があります。他のすべてのインターフェースと同様に、リクエストが完了したときに適切なコールバックが確実にトリガーされるように、EOS_HPlatform ハンドルが動作していることが重要となります。

アチーブメントの定義

アチーブメントの定義データを取得すると、次のパラメータを持つ構造体 EOS_Achievements_DefinitionV2 に含まれます。

アチーブメント定義をクエリする

関数 EOS_Achievements_QueryDefinitions を使用して、アプリケーションの Developer Portal で作成したすべてのアチーブメント定義の配列を取得できます。

クエリが完了すると、アチーブメントの定義は関数から返されるのではなく、ローカルにキャッシュされます。そして、EOS_Achievements_CopyAchievementDefinitionV2ByIndex または EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId を使用してキャッシュにアクセスし、EOS_Achievements_DefinitionV2 のコピーを取得できます。その際、これらのコピーされた定義を保存するには、EOS_Achievements_DefinitionV2_Release を使用してメモリを解放する必要があります。アチーブメントのコピーの詳細については、以下の「キャッシュされたアチーブメント定義をコピーする」セクションを参照してください。

EOS_Achievements_QueryDefinitions は次のパラメータを取ります。

クエリが成功した場合、この関数は EOS_Success の EOS_EResult 値を返します。その他の結果の場合は、エラーまたは不正なパラメータであることを示します。

クエリは LocalUserId を使用してユーザーの ロケール を決定します。これは、ユーザーがリンクされた Epic Online Services アカウント ID を持っている場合にローカライズされたテキストを返すために使用されます。 また、 EOS_Platform_SetOverrideLocaleCode を呼び出して、選択したロケールを使用してアチーブメント情報を取得するようシステムに強制することもできます。

クエリ定義の完全なコールバック

コールバック関数 EOS_Achievements_OnQueryDefinitionsCompleteCallback は、クエリを定義する操作が完了し、EOS_Achievements_OnQueryDefinitionsCompleteCallbackInfo 構造体を返すときに呼び出されます。コールバック情報には、ResultCode と、ClientData パラメータを使用して EOS_Achievements_QueryDefinitionsOptions で設定されたクライアント データが含まれます。

キャッシュされたアチーブメント定義をコピーする

EOS_Achievements_QueryDefinitions 操作が完了すると、アチーブメントの定義はローカルにキャッシュされます。そして、EOS_Achievements_CopyAchievementDefinitionV2ByIndex または EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId を使用して、EOS_Achievements_DefinitionV2 のコピーを取得できます。

キャッシュされたアチーブメントの数を取得する

GetAchievementDefinitionCount 関数を使用して、キャッシュされた利用可能なアチーブメントの数を取得できます。この関数は、カウントを整数として返し、EOS_Achievements_GetAchievementDefinitionCountOptions 構造体をパラメータとして受け取ります。

EOS_Achievements_GetAchievementDefinitionCountOptions 構造体自体は ApiVersion パラメータのみを受け取ります。これは EOS_ACHIEVEMENTS_GETACHIEVEMENTDEFINITIONCOUNT_API_LATEST の値に設定する必要があります。

インデックスでアチーブメントの定義をコピーする

関数 EOS_Achievements_CopyAchievementDefinitionV2ByIndex は、キャッシュされたアチーブメント リスト内のインデックス値を使用して EOS_Achievements_DefinitionV2 のコピーを取得し、そのコピーを出力パラメータ OutDefinition を介して出力します。この関数が取るパラメータを以下に示します。

この関数は、情報が利用可能で OutDefinition に渡された場合、EOS_Success の値を持つ EOS_EResult を返します。出力パラメータに null ポインタを渡すと、EOS_InvalidParameters が返されます。リクエストされたアチーブメント定義が見つからない場合は、EOS_NotFound を返します。

ID でアチーブメント定義をコピーする

関数 EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId は、アチーブメントのキャッシュで指定された AchievementId と一致するアチーブメントを検索し、そのデータのコピーを出力パラメータ OutDefinition を介して出力します。この関数が取るパラメータを以下に示します。

この関数は、情報が利用可能で OutDefinition に渡された場合、EOS_Success の値を持つ EOS_EResult を返します。出力パラメータに null ポインタを渡すと、EOS_InvalidParameters が返されます。リクエストされたアチーブメント定義が見つからない場合は、EOS_NotFound を返します。

コピーしたアチーブメント定義からメモリを解放する

EOS_Achievements_CopyAchievementDefinitionV2ByIndex または EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId の OutDefinition でコピーされた情報は、関数 EOS_Achievements_DefinitionV2_Release を使用してメモリから解放する必要があります。この関数は、AchievementDefinition と呼ばれる単一の EOS_Achievements_DefinitionV2 へのポインタを受け取ります。

プレイヤーのアチーブメント進行状況データ

プレイヤーのアチーブメント進行状況データは、EOS_Achievements_PlayerAchievement と呼ばれる構造体に含まれています。EOS_Achievements_AchievementDefinition はバックエンドのアチーブメントに関する一般情報が含む一方で、EOS_Achievements_PlayerAchievement は、特定のプレイヤーのアチーブメントのロック解除に向けた進行状況、(すでにロック解除されている場合は) ロックが解除された時間、およびロック解除に関連するスタッツを追跡します。EOS_Achievements_PlayerAchievement のパラメータは次のとおりです。

プレイヤーのアチーブメント進行状況をクエリする

非同期関数 EOS_Achievements_QueryPlayerAchievements を使用して、プレイヤーのアチーブメント進行状況データを取得できます。クエリが完了すると、リクエストされたデータがローカルにキャッシュされるリストに格納されます。次に、EOS_Achievements_CopyPlayerAchievementByIndex または EOS_Achievements_CopyPlayerAchievementByAchievementId を使用してそれらにアクセスし、目的のデータのコピーを取得できます。これが完了したら、EOS_Achievements_PlayerAchievement_Release を呼び出してメモリからコピーした情報を解放する必要があります。

EOS_Achievements_QueryPlayerAchievements のパラメータは次のとおりです。

クエリしたプレイヤーのアチーブメント完了コールバック

コールバック関数 EOS_Achievements_OnQueryPlayerAchievementsCompleteCallback は、プレイヤーのアチーブメント進行状況のクエリが完了したときに呼び出され、EOS_Achievements_OnQueryPlayerAchievementsCompleteCallbackInfo 構造体を返します。コールバック情報には、ResultCode と、EOS_Achievements_QueryDefinitionsOptions で設定されたクライアント データ、およびデータを所有するプレイヤーのユーザー ID が含まれます。

プレイヤーのアチーブメント進行状況をコピーする

プレイヤーのアチーブメント データはローカルにキャッシュされます。EOS_Achievements_GetPlayerAchievementCount を使用して、キャッシュされているアチーブメントの数を取得できます。

関数 EOS_Achievements_CopyPlayerAchievementByIndex と EOS_Achievements_CopyPlayerAchievementByAchievementId は、EOS_Achievements_PlayerAchievement のコピーを取得するために使用できます。EOS_Achievements_PlayerAchievement_Release を使用して、このコピーされたデータに関連付けられているメモリを解放する必要があります。

インデックスでプレイヤーのアチーブメントをコピーする

関数 EOS_Achievements_CopyPlayerAchievementByIndex は、キャッシュされたアチーブメント リスト内のインデックス値を使用してローカル キャッシュから EOS_Achievements_PlayerAchievement 構造体のコピーを取得し、そのコピーを出力パラメータ OutAchievement を通じて出力します。この関数が取るパラメータを以下に示します。

この関数は、情報が利用可能で OutAchievement に渡された場合、EOS_Success の値を持つ EOS_EResult を返します。出力パラメータを介して null ポインタを渡すと、EOS_InvalidParameters が返されます。リクエストされたプレイヤーのアチーブメントが見つからない場合は、EOS_NotFound を返します。

ID でプレイヤーのアチーブメントをコピーする

EOS_Achievements_CopyPlayerAchievementByAchievementId 関数は、アチーブメントのキャッシュで指定された AchievementId と一致するアチーブメントを検索し、そのデータのコピーを出力パラメータ OutAchievement を介して出力します。この関数が取るパラメータを以下に示します。

この関数は、情報が利用可能で OutAchievement に渡された場合、EOS_Success の値を持つ EOS_EResult を返します。出力パラメータを介して null ポインタを渡すと、EOS_InvalidParameters が返されます。リクエストされたプレイヤーのアチーブメントが見つからない場合は、EOS_NotFound を返します。

コピーしたプレイヤーのアチーブメントからメモリを解放する

EOS_Achievements_CopyPlayerAchievementByIndex または EOS_Achievements_CopyPlayerAchievementByAchievementId の OutAchievement でコピーされた情報は、EOS_Achievements_PlayerAchievement_Release 関数を使用してメモリから解放する必要があります。この関数は、Achievement と呼ばれる単一の EOS_Achievements_PlayerAchievement へのポインタを受け取ります。

アチーブメントのロックを解除する

アチーブメントは、アチーブメントにリンクされた スタッツ が取り込まれたときに自動的にロック解除されるようにするか、EOS_Achievements_UnlockAchievements 関数を呼び出して手動でロック解除することができます。

スタッツを介してアチーブメントのロックを解除する

アチーブメントは、スタッツしきい値のセットで定義されます。これは、スタッツの名前とアチーブメントをロック解除するためのスタッツ量で構成されています。必要なしきい値がすべて満たされると、アチーブメントのロックが解除され、Progress (進行状況) が「1.0」に設定されます。

スタッツの取り込み 操作でスタッツを更新する方法の詳細については、「Stats Interface」のページを参照してください。

アチーブメントを手動でロック解除する

EOS_Achievements_UnlockAchievements 関数で、ユーザーの 1 つ以上のアチーブメントのロックを解除できます。この関数のパラメータは次のとおりです。

EOS_Achievements_UnlockAchievements 操作が完了すると、コールバック関数 EOS_Achievements_OnUnlockAchievementsCompleteCallback が実行されます。このコールバック関数は、その操作からデータを受け取る必要があります。このパラメータは次のとおりです。

SDK は、アチーブメント ステータスをローカルまたはオフラインで保存しないことに注意してください。サービス停止中にスタッツ サービスにバッキングされていないアチーブメントをアンロックする問題を減らすためにには、以下を検討してください。

1. ログイン時に常にユーザーのアチーブメント ステータスをダウンロードします。

2. アンロック状態をバッキングスタッツ / データと比較し、条件が満たされた場合はアチーブメントをアンロックします。

このプロセスは、アップデートで導入された新しいアチーブメントを完了した可能性のあるユーザーも対象としています。

アチーブメントを通知する

アチーブメントのロックが解除されたときに 通知 を受け取ることができます。アチーブメントの通知は、スタッツの取り込みまたは手動でのアチーブメントのロック解除のいずれかからトリガーできます。

関数 EOS_Achievements_AddNotifyAchievementsUnlockedV2 は、アチーブメントが正常にロック解除されたときに通知をサブスクライブできます。これは、構造体 EOS_Achievements_AddNotifyAchievementsUnlockedV2Options を使用して Options パラメータを受け取り、シグネチャが EOS_Achievements_OnAchievementsUnlockedCallbackV2 と一致する関数への参照を受け取ります。このコールバック関数は、アチーブメントがロック解除されるたびに呼び出されます。ClientData は、発生時に任意のコンテキスト データをそのコールバックに渡すために使用できます。

構造体 EOS_Achievements_AddNotifyAchievementsUnlockedV2Options には ApiVersion が含まれており、これは EOS_ACHIEVEMENTS_ADDNOTIFYACHIEVEMENTSUNLOCKEDV2_API_LATEST に設定する必要があります。

コールバック関数 EOS_Achievements_OnAchievementsUnlockedCallbackV2 は EOS_Achievements_OnAchievementsUnlockedCallbackV2Info 構造体を返します。コールバック情報には、ロックが解除されたアチーブメントの UnlockTime と AchievementId が含まれます。また、EOS_Achievements_AddNotifyAchievementsUnlockedV2 を介して渡された ClientData、およびアチーブメントが属するユーザーの UserId も含まれます。

RemoveNotifyAchievementsUnlocked は通知のサブスクライブ解除に使用できます。

使用上の制限事項

Achievements (アチーブメント) インターフェース は、プレイヤーのアチーブメント関するデータを取得したり、そのプレイヤーのアチーブメントをロック解除したり、アプリケーションに属するすべてのアチーブメントに関するデータを取得したりする方法をデベロッパーに提供します。スロットリング、使用クォータ、ベストプラクティスの一般情報については、「

」を参照してください。

以下の制限事項はアチーブメントのデプロイメントの使用全体に適用されます。

ユーザーごと、またはデプロイメントごとに適用される使用レート制限もあります。ユーザーごとの制限は、ゲームをプレイし既存のアチーブメントを操作する個々のユーザーに適用されます。デプロイメントごとの制限は、プレイヤーが見てアンロックすることができるアチーブメントを設定するコールに適用されます。

アチーブメントをテストする

テストサンドボックスの 1 つへ展開して、アチーブメントをテストすることができます。これは、ライブ環境にデプロイする前に行う必要があります。これにより、アチーブメント定義のエラーをチェックし、プレイヤーがアチーブメントのロックを正常に解除できることを確認できます。 プロダクトのテスト サンドボックスの作成に関する情報は、「製品、サンドボックス、およびデプロイメント ID」を参照してください。

Was this document useful?

yes

no

Thank you for the response!

You’ve marked this document as useful:

yes

You’ve marked this document as not useful:

no

• • Share the document via:
  • Facebook
  • Twitter
  • LinkedIn
  • Reddit
  • Copy URL