Achievements インターフェース は、プレイヤーのアチーブメント関するデータを取得したり、そのプレイヤーの Epic Online Services アチーブメントをロック解除したり、アプリケーションに属するすべての Epic Online Services アチーブメントに関するデータを取得したりする方法をデベロッパーに提供します。
EOS SDK バージョン 1.8 以降、アチーブメント アイコンの処理方法が更新されました。1.7 から 1.8 に移行した場合は中断は発生しないはずですが、一部のアイコンがデフォルトの状態に戻る可能性があります。そのような表示になった場合は、アカウント担当者にサポート依頼をしてください。
Achievements インターフェースにアクセスする
Achievements インターフェースにアクセスするには、EOS_Platform_GetAchievementsInterface 関数を呼び出して EOS_HAchievements ハンドルを取得する必要があります。他のすべてのインターフェースと同様に、リクエストが完了したときに適切なコールバックが確実にトリガーされるように、EOS_HPlatform ハンドルが動作していることが重要となります。
Epic Online Services アチーブメントの定義
Epic Online Services アチーブメントに関するデータを取得したり、手動でロックを解除したりするには、まず Developer Portal (デベロッパーポータル) で Epic Online Services アチーブメントを定義する必要があります。
Epic Online Services アチーブメント定義において LATEST 集約タイプはサポートしなくなりました。以下の影響があります。
集約タイプ LATEST を使ったスタッツを作成することはできます。
ただし、集約タイプ LATEST を使ったスタッツを参照する Epic Online Services アチーブメントを作成することはできません。
集約タイプ LATEST を使ったスタッツを参照する Epic Online Services アチーブメントがすでにある場合、編集はまだ行うことができます。
Epic Online Services アチーブメントの定義データを取得すると、次のパラメータを持つ構造体 EOS_Achievements_DefinitionV2 に含まれます。
|
|
|
|---|---|
|
パラメータ |
説明 |
|
|
|
|
|
アチーブメントを一意に識別するために使用できるアチーブメント ID。 |
|
|
ロック解除されたときのローカライズされたアチーブメントの表示名。 |
|
|
ロック解除されたときのローカライズされたアチーブメントの説明。 |
|
|
ロックされているときのローカライズされたアチーブメントの表示名。 |
|
|
ロックされているときのローカライズされたアチーブメントの説明。 |
|
|
ゲームが任意の方法で使用できるローカライズされたフレーバー テキスト。Developer Portal でデータが設定されていない場合、これは null になる可能性があります。 |
|
|
ロック解除されたときにアチーブメントに表示するアイコンの URL。Developer Portal でデータが設定されていない場合、この値は null になり、ソーシャル オーバーレイ はデフォルト画像を使用します。 |
|
|
ロックされているか非表示になっているときにアチーブメントに表示するアイコンの URL。Developer Portal でデータが設定されていない場合、この値は null になり、ソーシャル オーバーレイ はデフォルト画像を使用します。 |
|
|
アチーブメントが非表示の場合は |
|
|
このアチーブメントに対する進行状況を監視するために使用されるスタッツしきい値の数。 |
|
|
この Epic Online Services アチーブメントのロックを解除するために満たす必要がある |
Epic Online Services アチーブメント定義をクエリする
関数 EOS_Achievements_QueryDefinitions を使用して、アプリケーションの Developer Portal で作成したすべての Epic Online Services アチーブメント定義の配列を取得できます。
Epic Online Services アチーブメントに関するデータを取得したり、手動でロックを解除したりするには、まず Developer Portal (デベロッパーポータル) で 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 は次のパラメータを取ります。
|
|
||
|---|---|---|
|
パラメータ |
説明 |
|
|
|
有効な |
|
|
|
ローカライズされたテキストの取得に関連するデータと、返されるデータの種類に関する |
|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
定義をクエリするユーザーの製品ユーザー ID。 |
|
|
|
非推奨です。null に設定する必要があります。 |
|
|
|
非推奨。null に設定する必要があります。 |
|
|
|
非推奨。ゼロに設定する必要があります。 |
|
クエリが成功した場合、この関数は EOS_Success の EOS_EResult 値を返します。その他の結果の場合は、エラーまたは不正なパラメータであることを示します。
クエリは 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 を介して出力します。この関数が取るパラメータを以下に示します。
|
|
||
|---|---|---|
|
パラメータ |
説明 |
|
|
|
有効な |
|
|
|
キャッシュからコピーするためにリクエストされたインデックスを含む |
|
|
|
リクエストされた |
|
|
|
||
|
|
|
|
|
|
キャッシュから取得するアチーブメント定義のインデックス。 |
|
この関数は、情報が利用可能で OutDefinition に渡された場合、EOS_Success の値を持つ EOS_EResult を返します。出力パラメータに null ポインタを渡すと、EOS_InvalidParameters が返されます。リクエストされたアチーブメント定義が見つからない場合は、EOS_NotFound を返します。
ID でアチーブメント定義をコピーする
関数 EOS_Achievements_CopyAchievementDefinitionV2ByAchievementId は、アチーブメントのキャッシュで指定された AchievementId と一致するアチーブメントを検索し、そのデータのコピーを出力パラメータ OutDefinition を介して出力します。この関数が取るパラメータを以下に示します。
|
|
||
|---|---|---|
|
パラメータ |
説明 |
|
|
|
有効な |
|
|
|
キャッシュを検索するアチーブメント ID を含む |
|
|
|
リクエストされた |
|
|
|
||
|
|
|
|
|
|
キャッシュからアチーブメントをコピーするときに検索するアチーブメント 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 は、特定のプレイヤーの Epic Online Services アチーブメントのロック解除に向けた進行状況、(すでにロック解除されている場合は) ロックが解除された時間、およびロック解除に関連するスタッツを追跡します。EOS_Achievements_PlayerAchievement のパラメータは次のとおりです。
|
|
||
|---|---|---|
|
パラメータ |
説明 |
|
|
|
|
|
|
|
アチーブメントを識別するために使用される一意の識別子。 |
|
|
|
このアチーブメント達成に対するパーセンテージで表した進行状況。 |
|
|
|
アチーブメントがロック解除された POSIX タイムスタンプ。アチーブメントがロック解除されていない場合、この値は EOS_ACHIEVEMENTS_ACHIEVEMENT_UNLOCKTIME_UNDEFINED になります。 |
|
|
|
このアチーブメントに関連付けられているプレイヤー スタッツ エントリの数。 |
|
|
|
アチーブメントのロックを解除するために使用されるスタッツしきい値と、それらスタッツに対するプレイヤーの現在の値に関する情報を含む |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ゲームが任意の方法で使用できるローカライズされたフレーバー テキスト。Developer Portal でデータが設定されていない場合、これは null になる可能性があります。 |
|
|
|
||
|
|
|
|
|
|
スタッツの名前。 |
|
|
|
スタッツの現在の値。 |
|
|
|
スタッツのしきい値。 |
|
プレイヤースタッツの詳細については「Stats Interface」のページを参照してください。
プレイヤーのアチーブメント進行状況をクエリする
アチーブメントに関するデータを取得したり、手動でロックを解除したりするには、まず Developer Portal (デベロッパーポータル) で Epic Online Services アチーブメントを定義する必要があります。
非同期関数 EOS_Achievements_QueryPlayerAchievements を使用して、プレイヤーのアチーブメント進行状況データを取得できます。クエリが完了すると、リクエストされたデータがローカルにキャッシュされるリストに格納されます。次に、EOS_Achievements_CopyPlayerAchievementByIndex または EOS_Achievements_CopyPlayerAchievementByAchievementId を使用してそれらにアクセスし、目的のデータのコピーを取得できます。これが完了したら、EOS_Achievements_PlayerAchievement_Release を呼び出してメモリからコピーした情報を解放する必要があります。
EOS_Achievements_QueryPlayerAchievements のパラメータは次のとおりです。
|
|
||
|---|---|---|
|
パラメータ |
説明 |
|
|
|
有効な |
|
|
|
情報をクエリするプレイヤーの |
|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
取得しているアチーブメント進行状況データを保持しているユーザーのアカウント 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 を通じて出力します。この関数が取るパラメータを以下に示します。
|
|
||
|---|---|---|
|
パラメータ |
説明 |
|
|
|
有効な |
|
|
|
キャッシュからコピーするためにリクエストされたインデックスを含む |
|
|
|
リクエストされた |
|
|
|
||
|
|
|
|
|
|
アチーブメントをコピーしているユーザーのアカウント ID を表す有効な |
|
|
|
キャッシュから取得するプレイヤーのアチーブメント データのインデックス。 |
|
この関数は、情報が利用可能で OutAchievement に渡された場合、EOS_Success の値を持つ EOS_EResult を返します。出力パラメータを介して null ポインタを渡すと、EOS_InvalidParameters が返されます。リクエストされたプレイヤーのアチーブメントが見つからない場合は、EOS_NotFound を返します。
ID でプレイヤーのアチーブメントをコピーする
EOS_Achievements_CopyPlayerAchievementByAchievementId 関数は、アチーブメントのキャッシュで指定された AchievementId と一致するアチーブメントを検索し、そのデータのコピーを出力パラメータ OutAchievement を介して出力します。この関数が取るパラメータを以下に示します。
|
|
||
|---|---|---|
|
パラメータ |
説明 |
|
|
|
有効な |
|
|
|
キャッシュを検索するアチーブメント ID を含む |
|
|
|
リクエストされた |
|
|
|
||
|
|
|
|
|
|
アチーブメントをコピーしているユーザーのアカウント ID を表す有効な |
|
|
|
キャッシュからアチーブメントをコピーするときに検索するアチーブメント 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 アチーブメントのロックを解除できます。この関数のパラメータは次のとおりです。
|
|
||
|---|---|---|
|
パラメータ |
説明 |
|
|
|
有効な |
|
|
|
Epic Online Services アチーブメントのロックを解除するプレイヤーに関する情報と、ロックを解除する Epic Online Services アチーブメントの情報を含む |
|
|
|
|
|
|
|
|
|
|
|
||
|
|
|
|
|
|
ロックを解除するアチーブメントを持つユーザーのアカウント ID を表す |
|
|
|
ロックを解除するアチーブメント ID のリスト。 |
|
|
|
ロックを解除したいアチーブメントの数。 |
|
EOS_Achievements_UnlockAchievements 操作が完了すると、コールバック関数 EOS_Achievements_OnUnlockAchievementsCompleteCallback が実行されます。このコールバック関数は、その操作からデータを受け取る必要があります。このパラメータは次のとおりです。
|
|
|
|---|---|
|
パラメータ |
説明 |
|
|
操作のステータスを示す |
|
|
|
|
|
このリクエストを開始したユーザーのアカウント ID を表す |
|
|
ロックを解除するアチーブメントの数。 |
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 文字 |
|
アチーブメントあたりのローカライズ テキスト バリエーション |
19 |
|
ローカライズ テキストの長さ |
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」を参照してください。