EasyYamlParserは、Unreal EngineでYAMLデータの読み取りと書き込みを行うためのプラグインです。Blueprint(ビジュアルスクリプト)だけでYAMLを扱え、C++のコードを書く必要はありません。
EasyYamlParser最大の特徴は、ドット記法のアクセス文字列です。階層の深いYAMLの値を player.stats.level のように1つの文字列で直接指定できます。ネストしたマップを1段ずつたどる組み立ては不要です。
読み込み(パース)と書き出し(作成)の両方に対応しています。読み込んだYAMLを編集して保存し直すことも、空のドキュメントから新しく組み立てることもできます。パースに失敗したときは、エラーメッセージに行番号と列番号が付いて返るため、原因のあった場所をそのまま確認できます。
| 最初に確認したいこと | 読むページ |
|---|---|
| まず1本、YAMLの読み書きを完走させたい | クイックスタートでYAMLの読み取りと書き込みを完走する |
| 導入手順を知りたい | セットアップで導入の流れを確認 |
| アクセス文字列の書き方を知りたい | ユースケースで目的別の選択表と記法を確認 |
| ノードの入出力を調べたい | Blueprint APIリファレンスで公開APIを確認 |
基本用語
| 用語 | 説明 |
|---|---|
| YAML | インデントで階層を表すデータ記述形式。設定ファイルで広く使われる |
| アクセス文字列 | YAML内の読み取り先を指定する文字列。player.name のようにキーをドットでつなぐ |
| ドット記法 | キーを . でつないで階層を表す書き方。Access String ピンに入力する |
| YamlObject | 読み込んだYAML 1つ分を表すオブジェクト。Yaml Object 型の変数として扱う |
| マップ | キーと値の集まり。key: value の形式で並べる |
| シーケンス | YAMLの配列。- 記号で並べる。アクセス文字列では items[0] のように [ ] で指定する |
EasyYamlParserの構成を示します。Blueprintのノード呼び出しが Yaml Object 型の値を経由してYAMLデータを操作します。
flowchart LR
BP["Blueprint / C++"] --> F["EasyYamlParser ノード"]
F --> Y["Yaml Object"]
Y --> TXT["YAML文字列 / ファイル"]
EasyYamlParserでできること
- ドット記法のアクセス文字列による値の読み取り(
Read Int、Read Float、Read String、Read Bool) - 途中のマップの取得と、マップ配列の一括取得(
Read Object、Read Objects) - YAML文字列とファイルからの読み込み(
Load Yaml From String、Load Yaml From File) - YAMLの新規作成と書き込み(
Create Empty Yaml ObjectとWrite IntなどのWrite系ノード) - null値の明示的な書き込み(
Write Null) - シーケンスへの値の追加(
Add Int To ArrayなどのAdd系ノード) - ファイルへの保存とYAML文字列への変換(
Save Yaml To File、Yaml To String) - 多次元シーケンスへのアクセス(
matrix[1][2]のようなアクセス文字列) - パスの存在チェックとノード型の判定(
Has Path、Get Root Type、Get Node Type) - Yaml Objectの有効性チェックと比較(
Is Yaml Object Valid、Are Yaml Objects Equal) - エラーコードと行番号・列番号付きのエラー報告(
Error Code、Error Messageピン) - C++ではUSTRUCTとの相互変換(
TryReadStruct/TryWriteStruct)
Easyシリーズの他プラグインとの対応
EasyYamlParserは、EasyJsonParser V2と同じ考え方のアクセス文字列とノード構成を採用しています。EasyJsonParserを使ったことがある人は、同じ要領でYAMLを扱えます。
| 項目 | EasyJsonParser V2 | EasyYamlParser |
|---|---|---|
| 扱う形式 | JSON | YAML |
| 読み取り・書き込み | 対応 | 対応 |
| 整数の型 | int32 | int64(大きな整数もそのまま扱える) |
| エラー情報 | 成功フラグとメッセージ | 成功フラグ・メッセージ・エラーコード・行番号・列番号 |
| nullの書き込み | 専用ノードなし | Write Null で明示的に書ける |
| USTRUCTとの変換 | Blueprintノードあり | C++専用API(TryReadStruct / TryWriteStruct) |
このようなプロジェクトにおすすめします
- 設定ファイルやマスターデータをYAMLで管理したいプロジェクト
- 人間が手で書く設定ファイルを読み込みたいプロジェクト
- C++を書かずにBlueprintだけでYAML処理を完結させたいプロジェクト
- 読み込みエラーの原因を行番号で把握したいプロジェクト
基本的な使用手順
- プラグインを導入してEasyYamlParserを有効にします。
Load Yaml From StringまたはLoad Yaml From FileでYaml Objectを作成し、変数に保存します。Read StringなどのRead系ノードにアクセス文字列を指定して、値を読み取ります。- 書き込む場合は
Create Empty Yaml Objectで作成し、Write StringなどのWrite系ノードで値を書き込みます。 Save Yaml To Fileでファイルに保存します。
具体的な手順はクイックスタートで説明します。
対応環境
Unreal Engine対応バージョン
EasyYamlParserはUnreal Engine 5.6 - 5.8に対応しています。
AyuMaxSoftのプラグインは、基本的に最新のUnreal Engine 3バージョン向けにアップデートを公開しています。
プラグインバージョンごとの対応状況は以下の通りです。
| プラグインバージョン | 対応UEバージョン |
|---|---|
| v0.1.0 | UE5.6 - 5.8 |
対応プラットフォーム
| 区分 | プラットフォーム |
|---|---|
| ターゲットプラットフォーム | Windows, Mac, Linux, Android, iOS |
現在の主な制約
- YAMLのコメントは、読み込んで保存し直すと保持されません。コメント付きの設定ファイルを読み取り専用で使う場合には影響ありません。
- 読み込みは同期的に行われます。大きなファイルを読み込む場合はゲームスレッドの処理がブロックされる点に注意してください。
- 相対パスでのファイル読み書きは、プロジェクトのContentディレクトリが基準になります。詳細はデータ形式と運用を参照してください。
- USTRUCTとの変換はC++専用のAPIです。Blueprintからは使用できません。
販売とライセンス
本製品は、Fabで購入・取得した際に適用されるEpic Gamesのライセンス条件に基づいてご利用いただけます。
よくある質問はFAQにまとめています。EasyYamlParserカテゴリに、Blueprintだけで使えるかどうか、コメントの保持、nullの扱いなどの質問があります。
