Achievements インターフェース を使って以下の操作を行います。
- 特定のプレイヤーの実績ステートに関するデータを抽出する。
- 呼び出しによって実績を手動でロック解除する。
- アプリケーションに属する実績のすべてのデータを抽出する。
API リファレンスの詳細については、「EOS Achievements インターフェース API のリファレンス」を参照してください。
Achievements インターフェイスで定義した実績は、「Epic Online Services の実績」と呼ばれます。商品が利用するプラットフォームやストア フロントに関係なく、商品に追加することができます。
EOS SDK バージョン 1.8 以降、実績アイコンの処理方法が更新されました。1.7 から 1.8 に移行した場合は中断は発生しないはずですが、一部のアイコンがデフォルトの状態に戻る可能性があります。そのような表示になった場合は、アカウント担当者にサポート依頼をしてください。
製品 を Epic Games ストアで公開すると、Epic Games Store の実績によって製品のユーザー エクスペリエンスを強化することができます。Epic Games Store の実績は Epic Online Services の実績を拡張します。これらは、ユーザーの Epic プレイヤー アカウントに経験値 (XP) などの特典を与えるものです。詳細については、「Epic Games Store の実績」ドキュメントを参照してください。
実績の紹介動画
Youtube.com の紹介動画「Introduction to Achievements」をご覧ください。
Video:Accessing the Achievements Interface
Achievements インターフェースにアクセスする
Achievements インターフェースにアクセスするには、EOS_Platform_GetAchievementsInterface 関数を呼び出して EOS_HAchievements ハンドルを取得する必要があります。他のすべてのインターフェースと同様に、リクエストが完了したときに適切なコールバックが確実にトリガーされるように、EOS_HPlatform ハンドルが動作していることが重要となります。
Epic Online Services の実績の定義
Epic Online Services の実績定義において LATEST 集約タイプはサポートしなくなりました。以下の影響があります。
- 集約タイプ LATEST を使ったスタッツを作成することはできます。
- ただし、集約タイプ LATEST を使ったスタッツを参照する Epic Online Services の実績を作成することはできません。
- 集約タイプ LATEST を使ったスタッツを参照する Epic Online Services の実績がすでにある場合、編集はまだ行うことができます。
Epic Online Services の実績の定義データを取得すると、次のパラメータを持つ構造体 EOS_Achievements_DefinitionV2 に含まれます。
EOS_Achievements_DefinitionV2: | |
|---|---|
| パラメータ | 説明 |
ApiVersion | EOS_ACHIEVEMENTS_DEFINITIONV2_API_LATEST |
AchievementId | 実績を一意に識別するために使用できる実績 ID。 |
UnlockedDisplayName | ロック解除されたときのローカライズされた実績の表示名。 |
UnlockedDescription | ロック解除されたときのローカライズされた実績の説明。 |
LockedDisplayName | ロックされているときのローカライズされた実績の表示名。 |
LockedDescription | ロックされているときのローカライズされた実績の説明。 |
FlavorText | ゲームが任意の方法で使用できるローカライズされたフレーバー テキスト。デベロッパー ポータル でデータが設定されていない場合、これは null になる可能性があります。 |
UnlockedIconURL | ロック解除されたときに実績に表示するアイコンの URL。デベロッパー ポータル でデータが設定されていない場合、この値は null になり、ソーシャル オーバーレイ はデフォルト画像を使用します。 |
LockedIconURL | ロック解除されたときに実績に表示するアイコンの URL。デベロッパー ポータル でデータが設定されていない場合、この値は null になり、ソーシャル オーバーレイ はデフォルト画像を使用します。 |
bIsHidden | 実績が非表示の場合は EOS_TRUE、それ以外の場合は EOS_FALSE。EOS_TRUE に設定する場合、ソーシャル オーバーレイ は実績がロックされている間は表示名に "Hidden Achievement" および説明に空の文字列を使用します。しかしながら、この構造体内の LockedDisplayName と LockedDescription の値は変わりません。 |
StatThresholdsCount | この実績に対する進行状況を監視するために使用されるスタッツしきい値の数。 |
StatThresholds | この Epic Online Services の実績のロックを解除するために満たす必要がある EOS_Achievements_StatThresholds の配列。名前としきい値で構成されています。 |
Epic Online Services の実績定義をクエリする
関数 EOS_Achievements_QueryDefinitions を使用して、アプリケーションの デベロッパー ポータル で作成したすべての Epic Online Services の実績定義の配列を取得できます。
クエリが完了すると、Epic Online Services の実績の定義は関数から返されるのではなく、ローカルにキャッシュされます。そして、EOS_Achievements_CopyAchievementDefinitionV2ByIndex または EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId を使用してキャッシュにアクセスし、EOS_Achievements_DefinitionV2 のコピーを取得できます。その際、これらのコピーされた定義を保存するには、EOS_Achievements_DefinitionV2_Release を使用してメモリを解放する必要があります。 Epic Online Services の実績のコピーの詳細については、以下の「キャッシュされた実績定義をコピーする」セクションを参照してください。
EOS_Achievements_QueryDefinitions は次のパラメータを取ります。
EOS_Achievements_QueryDefinitions: | ||
|---|---|---|
| パラメータ | 説明 | |
Handle | 有効な EOS_HAchievements ハンドル。 | |
Options | ローカライズされたテキストの取得に関連するデータと、返されるデータの種類に関する EOS_Achievements_QueryDefinitionsOptions オプションを含む構造体。 | |
ClientData | CompletionDelegate で返される任意のデータ。 | |
CompletionDelegate | EOS_Achievements_OnQueryDefinitionsCompleteCallback と一致するシグネチャを使用した操作の完了時に呼び出される関数。 | |
EOS_Achievements_QueryDefinitionsOptions: | ||
|---|---|---|
| パラメータ | 説明 | |
ApiVersion | Set to EOS_ACHIEVEMENTS_QUERYDEFINITIONS_API_LATEST. | |
LocalUserId | 定義をクエリするユーザーの製品ユーザー ID。 | |
EpicUserId | 非推奨です。null に設定する必要があります。 | |
HiddenAchievementIds | 非推奨です。null に設定する必要があります。 | |
HiddenAchievementsCount | 非推奨です。ゼロに設定する必要があります。 | |
クエリは LocalUserId を使用してユーザーの ロケール を決定します。これは、ユーザーがリンクされた Epic Online Services アカウント ID を持っている場合にローカライズされたテキストを返すために使用されます。 また、 EOS_Platform_SetOverrideLocaleCode を呼び出して、選択したロケールを使用して Epic Online Services の実績情報を取得するようシステムに強制することもできます。
クエリ定義の完全なコールバック
コールバック関数 EOS_Achievements_OnQueryDefinitionsCompleteCallback は、クエリを定義する操作が完了し、EOS_Achievements_OnQueryDefinitionsCompleteCallbackInfo 構造体を返すときに呼び出されます。コールバック情報には、ResultCode と、ClientData パラメータを使用して EOS_Achievements_QueryDefinitionsOptions で設定されたクライアント データが含まれます。
キャッシュされた Epic Online Services の実績定義をコピーする
EOS_Achievements_QueryDefinitions 操作が完了すると、 Epic Online Services の実績の定義はローカルにキャッシュされます。そして、EOS_Achievements_CopyAchievementDefinitionV2ByIndex または EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId を使用して、EOS_Achievements_DefinitionV2 のコピーを取得できます。
キャッシュされた Epic Online Services の実績の数を取得する
GetAchievementDefinitionCount 関数を使用して、キャッシュされた利用可能な Epic Online Services の実績の数を取得できます。この関数は、カウントを整数として返し、EOS_Achievements_GetAchievementDefinitionCountOptions 構造体をパラメータとして受け取ります。
EOS_Achievements_GetAchievementDefinitionCountOptions 構造体自体は ApiVersion パラメータのみを受け取ります。これは EOS_ACHIEVEMENTS_GETACHIEVEMENTDEFINITIONCOUNT_API_LATEST の値に設定する必要があります。
インデックスで Epic Online Services の実績定義をコピーする
関数 EOS_Achievements_CopyAchievementDefinitionV2ByIndex は、キャッシュされた Epic Online Services の実績リスト内のインデックス値を使用して EOS_Achievements_DefinitionV2 のコピーを取得し、そのコピーを出力パラメータ OutDefinition を介して出力します。この関数が取るパラメータを以下に示します。
EOS_Achievements_CopyAchievementDefinitionV2ByIndex: | |
|---|---|
| パラメータ | 説明 |
Handle | 有効な EOS_HAchievements ハンドル。 |
Options | キャッシュからコピーするためにリクエストされたインデックスを含む EOS_Achievements_CopyAchievementDefinitionV2ByIndexOptions 構造体。 |
OutDefinition | リクエストされた EOS_Achievements_DefinitionV2 のコピーを含む出力パラメータ。OutDefinition に有効なデータが含まれている場合は、このデータで EOS_Achievements_DefinitionV2_Release を呼び出してメモリから解放する必要があります。 |
EOS_Achievements_CopyAchievementDefinitionV2ByIndexOptions: | |
|---|---|
| パラメータ | 説明 |
ApiVersion | EOS_ACHIEVEMENTS_COPYDEFINITIONV2BYINDEX_API_LATEST |
AchievementIndex | キャッシュから取得する実績定義のインデックス。 |
この関数は、情報が利用可能で OutDefinition に渡された場合、EOS_Success の値を持つ EOS_EResult を返します。出力パラメータに null ポインタを渡すと、EOS_InvalidParameters が返されます。リクエストされた実績定義が見つからない場合は、EOS_NotFound を返します。
ID で実績定義をコピーする
関数 EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId は、実績のキャッシュで指定された AchievementId と一致する実績を検索し、そのデータのコピーを出力パラメータ OutDefinition を介して出力します。この関数が取るパラメータを以下に示します。
EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId: | |
|---|---|
| パラメータ | 説明 |
Handle | 有効な EOS_HAchievements ハンドル。 |
Options | キャッシュを検索する実績 ID を含む EOS_Achievements_CopyAchievementDefinitionV2ByAchievementIdOptions 構造体。 |
OutDefinition | リクエストされた EOS_Achievements_DefinitionV2 のコピーを含む出力パラメータ。OutDefinition に有効なデータが含まれている場合は、このデータで EOS_Achievements_DefinitionV2_Release を呼び出してメモリから解放する必要があります。 |
CopyAchievementDefinitionV2ByAchievementIdOptions: | |
|---|---|
| パラメータ | 説明 |
ApiVersion | Set to EOS_ACHIEVEMENTS_COPYDEFINITIONV2BYACHIEVEMENTID_API_LATEST. |
AchievementId | キャッシュから実績をコピーするときに検索する実績 ID。 |
この関数は、情報が利用可能で 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 はバックエンドの Epic Online Services の実績に関する一般情報が含む一方で、EOS_Achievements_PlayerAchievement は、特定のプレイヤーの実績のロック解除に向けた進行状況、(すでにロック解除されている場合は) ロックが解除された時間、およびロック解除に関連するスタッツを追跡します。
EOS_Achievements_PlayerAchievement のパラメータは次のとおりです。
EOS_Achievements_PlayerAchievement: | |
|---|---|
| パラメータ | 説明 |
ApiVersion | Set to EOS_ACHIEVEMENTS_PLAYERACHIEVEMENT_API_LATEST. |
AchievementId | 実績を識別するために使用される一意の識別子。 |
Progress | この実績の完了までの進行状況のパーセント。 現在の進行状況は、 EOS_Achievements_QueryPlayerAchievements が成功したときと実績がロック解除されたときに更新されます。 |
UnlockTime | 実績がロック解除された POSIX タイムスタンプ。実績がロック解除されていない場合、この値は EOS_ACHIEVEMENTS_ACHIEVEMENT_UNLOCKTIME_UNDEFINED になります。 |
StatInfoCount | この実績に関連付けられているプレイヤー スタッツ エントリの数。 |
StatInfo | 実績のロックを解除するために使用されるスタッツしきい値と、それらスタッツに対するプレイヤーの現在の値に関する情報を含む EOS_Achievements_PlayerStatInfo 構造体の配列。 |
DisplayName | この特定プレイヤーの現在の実績進行状況に基づく、実績のローカライズされた表示名。 DisplayName は EOS_Achievements_QueryDefinitions が正常に呼び出されるまで SDK キャッシュ内で null になります。 |
Description | この特定プレイヤーの現在の実績進行状況に基づく、実績のローカライズされた 説明。 EOS_Achievements_QueryPlayerAchievements が成功したとき、および実績が解除されたときに、現在の進捗が更新されます。 |
IconURL | この特定プレイヤーの現在の実績進行状況に基づく、実績に表示するアイコンの URL。デベロッパー ポータル でデータが設定されていない場合、これは null になる可能性があります。IconURL は EOS_Achievements_QueryDefinitions が正常に呼び出されるまで SDK キャッシュ内で null になります。 |
FlavorText | ゲームが任意の方法で使用できるローカライズされたフレーバー テキスト。デベロッパー ポータル でデータが設定されていない場合、これは null になる可能性があります。
FlavorText is EOS_Achievements_QueryDefinitions が正常に呼び出されるまで SDK キャッシュ内で null になります。 |
EOS_Achievements_PlayerStatInfo: | |
|---|---|
| パラメータ | 説明 |
ApiVersion | EOS_ACHIEVEMENTS_PLAYERSTATINFO_API_LATEST に設定します。 |
Name | スタッツの名前。 |
CurrentValue | スタッツの現在の値。 |
ThresholdValue | スタッツのしきい値。 |
プレイヤースタッツの詳細については「Stats Interface」のページを参照してください。
プレイヤーの実績進行状況をクエリする
非同期関数 EOS_Achievements_QueryPlayerAchievements を使用して、プレイヤーの実績進行状況データを取得できます。クエリが完了すると、リクエストされたデータがローカルにキャッシュされるリストに格納されます。次に、EOS_Achievements_CopyPlayerAchievementByIndex または EOS_Achievements_CopyPlayerAchievementByAchievementId を使用してそれらにアクセスし、目的のデータのコピーを取得できます。これが完了したら、EOS_Achievements_PlayerAchievement_Release を呼び出してメモリからコピーした情報を解放する必要があります。
EOS_Achievements_QueryPlayerAchievements のパラメータは次のとおりです。
EOS_Achievements_QueryPlayerAchievements: | |
|---|---|
| パラメータ | 説明 |
Handle | 有効な EOS_HAchievements ハンドル。 |
Options | 情報をクエリするプレイヤーの UserId を含む EOS_Achievements_QueryPlayerAchievementsOptions 構造体。 |
ClientData | CompletionDelegate で返される任意のデータ。 |
CompletionDelegate | EOS_Achievements_OnQueryPlayerAchievementsCompleteCallback と一致するシグネチャを使用した操作の完了時に呼び出される関数。 |
EOS_Achievements_QueryPlayerAchievementsOptions | |
| パラメータ | 説明 |
ApiVersion | EOS_ACHIEVEMENTS_QUERYPLAYERACHIEVEMENTS_API_LATEST に設定します。 |
UserId | 取得している実績進行状況データを保持しているユーザーのアカウント ID。 |
クエリしたプレイヤーの実績完了コールバック
コールバック関数 EOS_Achievements_OnQueryPlayerAchievementsCompleteCallback は、プレイヤーの実績進行状況のクエリが完了したときに呼び出され、EOS_Achievements_OnQueryPlayerAchievementsCompleteCallbackInfo 構造体を返します。コールバック情報には、ResultCode と、EOS_Achievements_QueryDefinitionsOptions で設定されたクライアント データ、およびデータを所有するプレイヤーのユーザー ID が含まれます。
プレイヤーの実績進行状況をコピーする
プレイヤーの実績 データはローカルにキャッシュされます。EOS_Achievements_GetPlayerAchievementCount を使用して、キャッシュされている Epic Online Services の実績の数を取得できます。
関数 EOS_Achievements_CopyPlayerAchievementByIndex と EOS_Achievements_CopyPlayerAchievementByAchievementId は、EOS_Achievements_PlayerAchievement のコピーを取得するために使用できます。EOS_Achievements_PlayerAchievement_Release を使用して、このコピーされたデータに関連付けられているメモリを解放する必要があります。
インデックスでプレイヤーの実績をコピーする
関数 EOS_Achievements_CopyPlayerAchievementByIndex は、キャッシュされた実績 リスト内のインデックス値を使用してローカル キャッシュから EOS_Achievements_PlayerAchievement 構造体のコピーを取得し、そのコピーを出力パラメータ OutAchievement を通じて出力します。この関数が取るパラメータを以下に示します。
EOS_Achievements_CopyPlayerAchievementByIndex: | |
|---|---|
| パラメータ | 説明 |
Handle | 有効な EOS_HAchievements ハンドル。 |
Options | キャッシュからコピーするためにリクエストされたインデックスを含む EOS_Achievements_CopyPlayerAchievementByIndexOptions 構造体。 |
OutAchievement | リクエストされた EOS_Achievements_PlayerAchievement のコピーを含む出力パラメータ。OutAchievement に有効なデータが含まれている場合は、このデータで EOS_Achievements_PlayerAchievement_Release を呼び出してメモリから解放する必要があります。 |
EOS_Achievements_CopyPlayerAchievementByIndexOptions: | |
|---|---|
| パラメータ | 説明 |
ApiVersion | EOS_ACHIEVEMENTS_COPYPLAYERACHIEVEMENTBYINDEX_API_LATEST に設定します。 |
UserId | 実績をコピーしているユーザーのアカウント ID を表す有効な EOS_ProductUserId。 |
AchievementIndex | キャッシュから取得するプレイヤーの実績 データのインデックス。 |
この関数は、情報が利用可能で OutAchievement に渡された場合、EOS_Success の値を持つ EOS_EResult を返します。出力パラメータを介して null ポインタを渡すと、EOS_InvalidParameters が返されます。リクエストされたプレイヤーの実績が見つからない場合は、EOS_NotFound を返します。
ID でプレイヤーの実績をコピーする
EOS_Achievements_CopyPlayerAchievementByAchievementId 関数は、実績のキャッシュで指定された AchievementId と一致する実績を検索し、そのデータのコピーを出力パラメータ OutAchievement を介して出力します。この関数が取るパラメータを以下に示します。
EOS_Achievements_CopyPlayerAchievementByAchievementId: | |
|---|---|
| パラメータ | 説明 |
Handle | 有効な EOS_HAchievements ハンドル。 |
Options | キャッシュを検索する実績 ID を含む EOS_Achievements_CopyPlayerAchievementByAchievementIdOptions 構造体。 |
OutAchievement | リクエストされた EOS_Achievements_PlayerAchievement のコピーを含む出力パラメータ。OutAchievement に有効なデータが含まれている場合は、このデータで EOS_Achievements_PlayerAchievement_Release を呼び出してメモリから解放する必要があります。 |
EOS_Achievements_CopyPlayerAchievementByAchievementIdOptions: | |
|---|---|
| パラメータ | 説明 |
ApiVersion | EOS_ACHIEVEMENTS_COPYPLAYERACHIEVEMENTBYACHIEVEMENTID_API_LATEST に設定します。 |
UserId | 実績をコピーしているユーザーのアカウント ID を表す有効な EOS_ProductUserId。 |
AchievementId | キャッシュから実績をコピーするときに検索する実績 ID。 |
この関数は、情報が利用可能で 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 へのポインタを受け取ります。
Epic Online Services の実績のロックを解除する
Epic Online Services の実績は、 Epic Online Services の実績にリンクされた スタッツ が取り込まれたときに自動的にロック解除されるようにするか、EOS_Achievements_UnlockAchievements 関数を呼び出して手動でロック解除することができます。
スタッツを介して Epic Online Services の実績のロックを解除する
Epic Online Services の実績は、スタッツしきい値のセットで定義されます。これは、スタッツの名前と Epic Online Services の実績をロック解除するためのスタッツ量で構成されています。必要なしきい値がすべて満たされると、実績のロックが解除され、Progress (進行状況) が「1.0」に設定されます。
スタッツの取り込み 操作でスタッツを更新する方法の詳細については、「Stats Interface」のページを参照してください。
Epic Online Services の実績を手動でロック解除する
EOS_Achievements_UnlockAchievements 関数で、ユーザーの 1 つ以上の Epic Online Services の実績のロックを解除できます。この関数のパラメータは次のとおりです。
EOS_Achievements_UnlockAchievements: | |
|---|---|
| パラメータ | 説明 |
Handle | 有効な EOS_HAchievements ハンドル。 |
Options | Epic Online Services の実績のロックを解除するプレイヤーに関する情報と、ロックを解除する Epic Online Services の実績の情報を含む EOS_Achievements_UnlockAchievementsOptions 構造体。 |
ClientData | CompletionDelegate で返される任意のデータ。 |
CompletionDelegate | EOS_Achievements_OnUnlockAchievementsCompleteCallback と一致するシグネチャを使用した操作の完了時に呼び出される関数。 |
EOS_Achievements_UnlockAchievementsOptions: | |
|---|---|
| パラメータ | 説明 |
ApiVersion | EOS_ACHIEVEMENTS_UNLOCKACHIEVEMENTS_API_LATEST に設定します。 |
UserId | ロックを解除する実績を持つユーザーのアカウント ID を表す EOS_ProductUserId。 |
AchievementIds | ロックを解除する実績 ID のリスト。 |
AchievementsCount | ロックを解除したい実績の数。 |
EOS_Achievements_UnlockAchievements 操作が完了すると、コールバック関数 EOS_Achievements_OnUnlockAchievementsCompleteCallback が実行されます。このコールバック関数は、その操作からデータを受け取る必要があります。この関数のパラメータは以下の通りです。
EOS_Achievements_OnUnlockAchievementsCompleteCallback: | |
|---|---|
| パラメータ | 説明 |
ResultCode | 操作のステータスを示す EOS_EResult。結果が EOS_Success の場合、操作が正常に完了したことを意味します。その他の結果はエラーを示します。 |
ClientData | EOS_Achievements_UnlockAchievements に渡されたコンテキスト。 |
UserId | このリクエストを開始したユーザーのアカウント ID を表す EOS_ProductUserId。 |
AchievementsCount | ロックを解除する実績の数。 |
SDK は、実績ステートをローカルまたはオフラインで保存しないことに注意してください。サービス停止中にスタッツ サービスにバッキングされていない Epic Online Services の実績をアンロックする問題を減らすためにには、以下を検討してください。
-
ログイン時に常にユーザーの実績ステータスをダウンロードします。
-
アンロック状態をバッキングスタッツ / データと比較し、条件が満たされた場合は実績をアンロックします。
このプロセスは、アップデートで導入された新しい Epic Online Services の実績を完了した可能性のあるユーザーも対象としています。
EOS_Achievements_UnlockAchievements は、適切な再試行率を尊重し、完了ステータスが返されるのを待ってから試行する限り、起動ごとに複数回呼び出すこともできます。
Epic Online Services の実績を通知する
Epic Online Services の実績のロックが解除されたときに 通知 を受け取ることができます。実績の通知は、スタッツの取り込みまたは手動での実績のロック解除のいずれかからトリガーできます。
関数 EOS_Achievements_AddNotifyAchievementsUnlockedV2 は、 Epic Online Services の実績が正常にロック解除されたときに通知をサブスクライブできます。これは、構造体 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、および Epic Online Services の実績が属するユーザーの UserId も含まれます。
RemoveNotifyAchievementsUnlocked は通知のサブスクライブ解除に使用できます。
使用上の制限事項
Achievements インターフェース は、プレイヤーの Epic Online Services の実績関するデータを取得したり、そのプレイヤーの Epic Online Services の実績をロック解除したり、アプリケーションに属するすべての Epic Online Services の実績に関するデータを取得したりする方法をデベロッパーに提供します。スロットリング、使用クォータ、ベストプラクティスの一般情報については、「サービス使用上の制限事項」を参照してください。
以下の制限事項は Epic Online Services の実績のデプロイメントの使用全体に適用されます。
| 機能 | 制限事項 |
|---|---|
| 実績の総数 | 1000 |
| 実績あたりの統計情報 | 3 |
| 実績 ID の長さ | 256 文字 |
| Localized text variations per achievement | 22. オーバーレイは 16 言語をサポートしています。 |
| ローカライズ テキストの長さ | 256 文字 |
| 実績アイコンのファイル サイズ | 1.02 MB |
| 実績アイコンの解像度 | 1024x1024 pixels |
| 実績アイコンのファイル タイプ | PNG、JPG、BMP、GIF (アニメートなし) |
Epic Online Services の実績を定義するときは、EOS_Achievements_DefinitionV2 の AchievementId パラメーターで次の記号を使用しないでください。
, { ^ } % ` ] > [ ~ < # | & $ @ = ; : + ? ! \ ( ) * /
これらのシンボルは、定義をインポートまたはエクスポートするときに問題を引き起こす可能性があります。
ユーザーごと、または「デプロイメントごと」に適用される使用レート制限もあります。ユーザーごとの制限は、ゲームをプレイし既存の実績を操作する個々のユーザーに適用されます。デプロイメントごとの制限は、プレイヤーが見てアンロックすることができる実績を設定するコールに適用されます。
| 機能 | ユーザーごとの制限 | デプロイメントごとの制限 |
|---|---|---|
| すべての実績定義を取得 | 10 リクエスト / 分 | - |
| 1 つの実績定義を取得 | 100 リクエスト / 分 | - |
| プレイヤーの実績を取得 | 100 リクエスト / 分 | - |
| 実績をアンロック | 100 リクエスト / 分 | - |
| 実績を作成 | - | 100 リクエスト / 分 |
| 実績を削除 | - | 100 リクエスト / 分 |
Epic Online Services の実績をテストする
テストサンドボックスの 1 つへ展開して、Epic Online Services の実績をテストすることができます。これは、ライブ環境にデプロイする前に行う必要があります。これにより、実績定義のエラーをチェックし、プレイヤーが Epic Online Services の実績のロックを正常に解除できることを確認できます。 製品 のテスト サンドボックス の作成に関する情報は、「製品、サンドボックス、およびデプロイメント ID」を参照してください。