実績 は、目標またはトロフィーであり、インゲーム タスクの達成に対してゲーム環境の外部で獲得されるか、ロック解除されるか、または報酬として与えられます。実績は、プレイヤーにインセンティブ、チャレンジ、報酬を提供する手段となります。これを利用すると、次のことが可能です。
- プレイヤーをゲーム内で誘導する
- ゲームのリプレイバリューを高める
- プレイヤー間の競争意識を維持する
オンライン サービスの Achievements インターフェース は、実績の定義の読み取りのほか、プレイヤーの実績 ステートの読み取りおよび更新を行うためのツールを提供します。Achievements インターフェースは、実績の作成、削除、または変更は処理しません。各オンライン サービスには、実績のこうした側面を管理する独自のバックエンド システムがあります。
インターフェースのコンフィギュレーションに応じて次のメカニズムを設定し、実績のロックを解除できます。
- プラットフォーム サービス管理：関連付けられた統計が事前定義されたしきい値に達すると、実績は自動的にプラットフォーム サービスによってロック解除されます。
- タイトル管理 (自動)：関連付けられた統計が事前定義されたしきい値に達すると、実績は自動的にタイトルによってロックが解除されます。詳細については、「自動的なタイトル管理の実績を設定する」セクションを参照してください。
- タイトル管理 (手動)：実績は、タイトルのロジックおよび
UnlockAchievements関数に従って手動でロックが解除されます。
これら 3 つのオプションが利用できるかどうかは、オンライン サービスの利用する実装/プラットフォームによって異なります。詳細については、特定のオンライン サービスの実装向けのドキュメントを参照してください。
API の概要
関数
次は、Achievements インターフェースによって提供される関数の概要を示した表です。
| 関数 | 定義 |
|---|---|
QueryAchievementDefinitions |
このタイトルのすべての実績の定義をクエリします。 |
GetAchievementIds |
QueryAchievementDefinitions によってキャッシュされている実績の実績 ID を取得します。 |
GetAchievementDefinition |
QueryAchievementDefinitions によってキャッシュされている、入力された実績 ID を使用し、実績の定義を取得します。 |
QueryAchievementStates |
与えられたプレイヤーのすべての実績のステートをクエリします。 |
GetAchievementState |
与えられたプレイヤーの ID 別に実績のステートを取得します。 |
UnlockAchievements |
与えられた実績を手動でロック解除します。 |
DisplayAchievementUI |
与えられた実績のプラットフォーム UI を起動します。 |
OnAchievementStateUpdated |
プレイヤーの実績 ステートが変更されると、イベントがトリガーされます。 |
主な構造体
Achievements インターフェースは、パラメータと戻り値を渡すための関数固有の構造体に加えて、主に 3 つの構造体 FAchievementDefinition、FAchievementStatDefinition、および FAchievementState によって伝達されます。
FAchievementDefinition
| メンバー | 型 | 説明 |
|---|---|---|
AchievementId |
FString |
固有の実績 ID。 |
UnlockedDisplayName |
FText |
ロック解除完了後に使用される、この実績のローカライズされた表示名。 |
UnlockedDescription |
FText |
ロック解除完了後に使用される、この実績のローカライズされた説明。 |
LockedDisplayName |
FText |
ロック中に使用される、この実績のローカライズされた表示名。 |
LockedDescription |
FText |
ロック中に使用される、この実績のローカライズされた説明。 |
FlavorText |
FText |
ローカライズされたフレーバー テキスト。 |
UnlockedIconUrl |
FString |
ロック解除完了後に使用される、この実績のアイコンの URL。 |
LockedIconUrl |
FString |
ロック中に使用される、この実績のアイコンの URL。 |
bIsHidden |
bool |
ロック解除されるまで、この実績を非表示にするかどうか。 |
StatDefinitions |
TArray<FAchievementStatDefinition> |
この実績に関連する統計。 |
FAchievementStatDefinition
| メンバー | 型 | 説明 |
|---|---|---|
StatId |
FString |
統計固有の ID。 |
UnlockThreshold |
uint32 |
関連付けられた統計を使用し、実績を自動ロック解除するためにユーザーが満たす必要があるしきい値。 |
FAchievementState
| メンバー | 型 | 説明 |
|---|---|---|
AchievementId |
FString |
このステートが関連する実績。 |
Progress |
float |
この実績のロック解除に向けた進捗 (0.0 ～ 1.0 のパーセンテージ)。1.0 未満の値は、実績がロックされていることを示します。値 1.0 は、実績がロック解除されたことを意味します。 |
UnlockTime |
FDateTime |
ロック解除された場合、この実績がロック解除された時間。 |
自動のタイトル管理の実績を設定する
Achievements インターフェースは、実績がプラットフォーム サービス管理の場合、またはタイトル管理で手動でロック解除される場合、エンジンのコンフィギュレーションが不要です。実績の進捗がタイトル管理であり、1 つ以上の統計が事前定義したしきい値に達したときに実績が自動的にロック解除される場合は、エンジンのコンフィギュレーションが必要です。
自動ロック解除を行うタイトル管理の実績では、Achievements インターフェースは Stats インターフェース と連携して動作します。このメカニズムについては、エンジンを設定して実績のロック解除ルールを設定し、Stats インターフェースのコンフィギュレーションで定義されている統計に基づいて条件を確立する必要があります。
G一般的な構文
DefaultEngine.ini
[OnlineServices.Achievements]
bIsTitleManaged=true
!UnlockRules=ClearRules
+UnlockRules=(AchievementId=<AchievementId1>, Conditions=((StatName=<StatName>, UnlockThreshold="<Type>:<Value>"), ...))
+UnlockRules=(AchievementId=<AchievementId2>, Conditions=((StatName=<StatName>, UnlockThreshold="<Type>:<Value>"), ...))
...
自動ロック解除を行うタイトル管理の実績で、統計情報の変化に基づいて更新を行うには、bIsTitleManaged フラグを true に設定する必要があります。このフラグでは、Online Services の Stats インターフェースの FStatsUpdated イベントをリッスンして、統計情報の変化に応じて実績ステートを自動的に更新するようクライアントを設定します。bIsTitleManaged フラグのデフォルト値は false です。このフラグを true に設定しないと、実績は、「DefaultEngine.ini」の実績定義で設定された統計の変化に基づいて自動的に更新されません。
UnlockRules 内の Conditions のリストには、個々の条件のペアが含まれています。実績は、UnlockThreshold と組み合わせられる 1 つ以上の統計に依存します。実績は、関連付けられた Conditions リストのすべての統計が満たされるか、事前定義されたしきい値を超えないとロック解除されません。
ロック解除のルール
| フィールド | 型 | 説明 |
|---|---|---|
AchievementId |
String |
このロック解除ルールが関連付けられている実績の ID。 |
Conditions |
List |
この実績がロック解除される条件のリスト。 |
条件
| フィールド | 型 | 説明 |
|---|---|---|
StatName |
String |
この実績のロック解除のしきい値を関連付ける統計の名前。 |
UnlockThreshold |
コロンで区切られた Type:Value のペア |
<Type>:<Value> の形式のペア。ここで、Type はこの統計の型であり、Value は、この条件が満たされるとこの実績がロック解除されるしきい値です。 |
コンフィギュレーション例
2 つの異なる実績を持つ Achievements インターフェースのコンフィギュレーション例を、以下に示します。最初の実績は、プレイヤーが移動した合計距離 (メートル) を記録する単一の統計 Total_Distance に依存します。2 番目の実績のロック解除は、Distance_Run、Distance_Swim、および Distance_Cycle (すべてメートル単位で測定) という 3 つの異なる統計に依存します。
DefaultEngine.ini
[OnlineServices.Stats]
!StatDefinitions=ClearDefinitions
+StatDefinitions=(Name=Total_Distance, Id=0, ModifyMethod=Sum)
+StatDefinitions=(Name=Distance_Run, Id=1, ModifyMethod=Sum)
+StatDefinitions=(Name=Distance_Swim, Id=2, ModifyMethod=Sum)
+StatDefinitions=(Name=Distance_Cycle, Id=3, ModifyMethod=Sum)
[OnlineServices.Achievements]
bIsTitleManaged=true
!UnlockRules=ClearRules
+UnlockRules=(AchievementId=Around_the_World, Conditions=((StatName=Total_Distance, UnlockThreshold="Int32:40075000"))
+UnlockRules=(AchievementId=Triathlon, Conditions=((StatName=Distance_Run, UnlockThreshold="Int32:10000"),(StatName=Distance_Swim, UnlockThreshold="Int32:1500"), (StatName=Distance_Cycle, UnlockThreshold="Int32:40000"))
読み取り
Achievements インターフェースの目的は、実績の定義とステートを読み取ることです。定義およびステートの読み取りに関連するステップの概要を、以下に示します。コード例として、Online Services インターフェースを利用した情報のクエリおよび取得プロセスは、Stats インターフェース のドキュメントで統計のクエリおよび取得について紹介されている例と非常に似ています。
実績定義
次の手順に従うことで、Achievements インターフェースではプラットフォーム サービス上に設定された任意の実績の定義を読み取ることができます。
QueryAchievementDefinitionsがローカル インターフェースのキャッシュに実績定義を入力します。GetAchievementIdsが手順 1 でキャッシュされた実績の ID のリストを取得します。GetAchievementDefinitionが手順 2 の各 ID に関連付けられている完全な定義を取得します。
FAchievementDefintion 構造体は、実績定義を表現します。プラットフォーム サービス管理の実績の場合は、この定義には実績に関連付けられている統計とロック解除のしきい値が含まれ、これを上回ると実績が自動的にロック解除されます。
実績ステート
「実績定義」セクションで説明したとおりにプレイヤーの実績定義をクエリおよび取得したら、QueryAchievementStates および GetAchievementState を使用して、次のようにプレイヤーの実績 ステートを読み取ります。
QueryAchievementStatesがローカル インターフェースのキャッシュに実績ステート情報を入力します。- 実績がまだロックされている場合は、実績のロック解除のために
GetAchievementStateが現在の進捗を取得します。または、実績がロック解除されている場合は時間をロック解除します。
タイトル管理の実績の場合、進捗はバイナリの 0.0 (ロック) また 1.0 (ロック解除) です。プラットフォーム サービス管理の実績で統計に基づくロック解除ルールがある場合、その進捗には実績に向けた現在の進捗が 0.0 ～ 1.0 のパーセンテージで正確に反映できます。
追加資料
ヘッダ ファイル
詳細については、必要に応じて「Achievements.h」ヘッダ ファイルを直接確認してください。Achievements インターフェースのヘッダ ファイル「Achievements.h」は次のディレクトリに格納されています。
Engine\Plugins\Online\OnlineServices\Source\OnlineServicesInterface\Public\Online
UE のソース コードの入手方法については、「Unreal Engine のソース コードをダウンロードする」を参照してください。
関数パラメータおよび戻り型
関数のパラメータと戻り型、およびパラメータの渡し方や関数が戻ったときの結果の処理などについては、「Online Services の概要」ページの「関数」セクションを参照してください。
