AchievementSystem 2.0

Unreal Engine 向けの、モジュール式で柔軟な実績システム。UI やセーブ処理を強制せず、実績とカテゴリを管理するためのクリーンなコアを提供します。

はじめに

AchievementSystem は、実績とカテゴリを管理するためのクリーンなコアを提供します。UI やセーブ処理は一切強制されないため、すべてを自分でコントロールできます。すべてのデータはデータテーブル（Data Table）から読み込まれるため、ローカライズや効率的なスケーリングが可能です。

データテーブル駆動名前・説明・アイコンはデータテーブルに格納され、ローカライズにすぐ対応できます。

2階層のカテゴリトップレベルカテゴリがカテゴリを含み、カテゴリが実績を含みます。

進捗の追跡各実績は進捗と最大進捗を持ち、自動的に達成判定されます。

UI にすぐ使えるデータ読み取り専用の構造化された関数を、そのままウィジェットに接続できます。

マルチプレイ対応オンラインや複数プロフィールのゲーム向けに、プレイヤーごとのシステム参照を利用できます。

追加マクロFor Each With Delay と Get All Data Table Items を同梱しています。

システムの仕組み

システムはシンプルなデータフローを中心に構築されています。

定義
実績とカテゴリはデータテーブルで定義され、実行時にプリロードされます。
セーブとロード
実績の保存方法と読み込み方法は開発者が制御し、その後、すでに解除済みの実績をシステムに伝えます。
活用
ロード後、システムは実績をカテゴリ別に整理し、UI やゲームプレイのロジックでそのまま使える構造化データを提供します。

導入手順

子ブループリントを作成
BP_AchievementsSystem を開き、子ブループリントクラス（Child Blueprint Class）を作成します。この子ブループリントが、メインの実績システムのインスタンスになります。
構造体を作成
実績データを保持する構造体（Structure）を作成します。ID（整数）と Max Progress（整数）を必ず含めてください。
データテーブルを作成
データテーブルを作成し、先ほどの構造体を割り当てます。実績データ（名前、説明、アイコンなど）を入力してください。
イベントグラフを開く
BP_Achievements_Child を開き、イベントグラフ（Event Graph）に移動します。
Preload Achievement Data を追加
関数 Preload Achievement Data を追加します。3つの値が必要です（下の表を参照）。
値を接続
プリロードしたい各実績について、必要な値をすべて接続します。

入力	説明
`ID`	実績の一意の識別子。
`Max Progress`	実績の達成に必要な最大進捗値。
`Row Name`	データテーブル内の、この実績の行名。

サンプルが必要ですか？ デモの AchievementStyle_01 を参照してください。

カテゴリの概要

カテゴリシステムは、2階層のみのシンプルなツリー構造です。トップレベルカテゴリ（Top Level Categories）と実績カテゴリ（Achievement Categories）の2つです。これにより、システムは分かりやすく効率的になります。

トップレベルカテゴリ 01
├─ カテゴリ 01
│   ├─ 実績
│   └─ 実績
└─ カテゴリ 02
    ├─ 実績
    └─ 実績

トップレベルカテゴリは、他のカテゴリを含みます。
カテゴリは、実績を含みます。
実績の内部には何も含まれません。

実績カテゴリのプリロード

どの実績がどのカテゴリに属するかを定義するには、Preload Achievement Category を使用します。実績のプリロードと同じ方法で動作します。

入力	説明
`Category ID`	カテゴリの一意の識別子。
`Achievement IDs`（Array）	このカテゴリに属するすべての実績 ID。
`Row Name`	カテゴリ用データテーブル内の、このカテゴリの行名。

トップレベルカテゴリのプリロード

トップレベルカテゴリは、複数のカテゴリをまとめます。Preload Top Level Category を使用します。

入力	説明
`Category ID`	トップレベルカテゴリの一意の識別子。
`Category IDs`（Array）	このトップレベルカテゴリに属するすべてのカテゴリ ID。
`Row Name`	データテーブル内の、このトップレベルカテゴリの行名。

簡単な例

進行（トップレベルカテゴリ 01）
├─ ストーリー（カテゴリ 01）
│   ├─ 最初の一歩
│   └─ 新たな始まり
└─ 探索（カテゴリ 02）
    ├─ 最初の発見
    └─ 探索の達人

スキル（トップレベルカテゴリ 02）
├─ 一般スキル（カテゴリ 01）
│   └─ 完璧な実行
└─ 精密さ（カテゴリ 02）
    ├─ ワンショットの妙技
    └─ ぶれない手

関数リファレンス

注意：これらの関数は読み取り専用で、データを変更しません（Achievement Trigger を除く）。

達成済み実績（Complete Achievements）

以下の3つの関数は、同じ構造体を返します。

Number of Completed Achievements：達成済みの実績の合計数。
Max Completed Achievements：取得可能な実績の最大数。
Achievements Array：すべての実績とそのデータ（ID、進捗、達成状態など）の配列。

関数	入力	説明
`Get All Completed Achievements`	なし	システム内のすべての実績の全体進捗。統計、UI、プレイヤーへのフィードバックに使用します。
`Get All Completed Achievements By Category`	Category ID	特定のカテゴリ内の進捗。カテゴリの進捗を UI に表示する場合や、カテゴリがすべて達成されたかを確認する場合に使用します。
`Get Completed Achievements In Top Level Category`	Category ID（トップレベル）	トップレベルカテゴリ内（すべてのサブカテゴリを含む）の進捗。複数のカテゴリをまとめた進捗を表示する場合に使用します。

ロード（Load）

実績のロード関数は、次の項目を持つ構造体の配列を返します：Row Name、Complete Date（String）、Progress（Int）、Max Progress（Int）、Is Completed（Bool）。

関数	入力	出力 / 用途
`Load Achievements By Category`	Category ID	カテゴリ内のすべての実績。1つのカテゴリ用の UI を構築する場合に使用します。
`Load All Achievements`	なし	すべての実績を一度に取得します。全体の統計やゲーム終了時のサマリーに使用します。
`Load All Categories`	なし	`ID` と `Row` を持つ構造体の配列。カテゴリ一覧の作成や、カテゴリ単位の処理に使用します。
`Load Child Categories`	Category ID（親 / トップレベル）	各子カテゴリの `ID` と `Row`。トップレベルカテゴリ内のサブカテゴリを表示する場合に使用します。
`Load Top Level Categories`	なし	`Row`、`Category ID`、`Category IDs`（子カテゴリの配列）を持つ構造体の配列。すべてのトップレベルカテゴリとそのサブカテゴリを表示する場合に使用します。

ステート（States）

3つとも Pure 関数です。

関数	入力	出力	用途
`Get Progress`	Achievement ID (Int)	`Progress` (Int)、`Max Progress` (Int)	1つの実績の進捗を表示または確認します。
`Get Row Name`	Achievement ID (Int)	`Row Name` (Name)	実績のローカライズ済みデータ（名前、説明、アイコン）を取得します。
`Is Completed ?`	Achievement ID (Int)	`Return Value` (Bool)	ゲームプレイのロジックや UI 更新のために、達成状態を確認します。

Achievement Trigger

指定したプレイヤーについて、特定の実績の進捗をトリガーし、更新します。

入力	説明
`Achievement ID` (Int)	トリガーする実績の ID。
`Player Ref` (Actor)	実績をトリガーしたプレイヤーへの参照。

指定した実績の進捗を増加または更新します。
最大進捗に達すると、自動的に達成済みとしてマークします。
完了時に、達成状態と達成時刻を保存します。

用途：実績に関連するアクション（討伐、収集、探索、インタラクトなど）をプレイヤーが行うたびに呼び出します。

Get Achievement Data

デフォルトの Achievement System インスタンスを検索し、その参照を返します。

入力：なし
出力：Return Value（BP_AchievementSystem 参照）、Is Valid（Bool）。システムが存在しない場合、Is Valid は false になります。
用途：シングルプレイのゲーム、UI、グローバルな実績システム、または特定のプレイヤー参照が不要な場合。

Get Achievement Data By Reference

特定のプレイヤーに紐づく Achievement System を返します。これにより、プレイヤーごとに独立した実績データを持てます。

入力：Player Ref（Actor 参照）
出力：Return Value（BP_AchievementSystem 参照）、Is Valid（Bool）
用途：マルチプレイのゲーム、複数のプレイヤープロフィール、プレイヤーごとの実績追跡。

アーキテクチャに関する重要な注意

このシステムの関数は、Achievement Trigger を除き、内部的にすべて Get Achievement Data の上に構築されています。つまり、これらの関数には次の特徴があります。

デフォルトの Achievement System 参照を自動的に使用します。
UI での使用に安全で、推奨されます。
主に UI 向けに設計されています。

マルチプレイ / オンラインゲームに関する注意

オンラインまたはマルチプレイのゲームを開発している場合、ゲームプレイのロジックにこれらの関数を使用しないでください。進捗、達成済み実績、カテゴリの表示など、UI のみで使用してください。

プレイヤー専用の Achievement System 参照を使用するには：

BP_AchievementFunctions を開きます。
使用したい関数を探します。
その関数を複製（Duplicate）します。
複製した関数が Get Achievement Data By Reference を使用するように変更します。
関数に Player Reference 入力を追加します。

これにより、プレイヤーごとの実績データと、マルチプレイに安全なロジックを完全にコントロールできます。

Achievement Trigger が異なる理由

Achievement Trigger は Get Achievement Data に依存しません。実績 ID とプレイヤー参照を必要とするため、ゲームプレイのロジックに安全で、マルチプレイに対応し、開発者が完全に制御できます。

プレイヤー不在のマップに関する注意

プレイヤーやキャラクターが存在しないレベルでは、実績システムはデフォルトでは動作しません。これを解決するには、BP_AchievementsWorld をレベルに追加し、そのプロパティを設定します。

プロパティ	説明
`Achievement Class`	使用する実績コンポーネントを選択します（例：`BP_AchievementStyle_01`）。
`EAchievement Date Format`	達成日の日付形式（例：USA、MM/DD/YYYY）。
`Use Category Optimized Loading`	カテゴリ単位の最適化ロードを有効にします。
`Auto Load Category`	カテゴリの自動ロードを有効にします。

これにより、メインメニュー、ログイン画面、その他のプレイヤー不在のマップでも、システムが正しく動作します。

追加ツール

For Each With Delay (Macro)

通常の For Each Loop と同じように動作しますが、各反復の間に遅延を追加します。

ピン	説明
`Array`	ループ対象の配列。
`Duration` (Float)	各要素を処理する間隔（デフォルトは 0.05）。
`Loop Body`、`Array Element`、`Array Index`、`Completed`	標準の For Each Loop と同じ動作です。

UI 要素や実績、その他の配列データを、ゲームをフリーズさせずに順次ロードするのに便利です。

Get All Data Table Items (Macro)

複数のノードを書かずに、データテーブルのすべての行を取得します。

ピン	説明
`Table` (input)	読み取りたいデータテーブル。
`Loop Body`	各行に対して実行されます。`Array Element` / `Out Row` は現在の項目の行構造体です。
`Row Not Found`	行が存在しない場合にトリガーされます。
`Completed`	すべての行の処理が終わった後にトリガーされます。

データテーブルを、クリーンかつ効率的に素早く反復処理するのに便利です。