このページでは、YAMLのデータ型とノードの対応、アクセス文字列の仕様、ファイル入出力の動作、トラブル発生時の確認項目を説明します。
YAMLの型とノードの対応
YAMLの値の型と、読み取りに使うノードの対応は以下のとおりです。
| YAMLの型 | 読み取りノード | 書き込みノード | 備考 |
|---|---|---|---|
| 整数 | Read Int |
Write Int |
int64(64bit) |
| 小数 | Read Float |
Write Float |
double精度。整数値も読み取れます |
| 文字列 | Read String |
Write String |
|
| 真偽値 | Read Bool |
Write Bool |
true / false |
| マップ | Read Object |
Write Object |
キーと値の集まり |
| マップ配列 | Read Objects |
Add Object To Array |
各要素がマップのシーケンス |
| シーケンス | アクセス文字列で要素指定 | Add Int To Array 等 |
items[0] のように要素ごとに読み取ります |
| null | 対応ノードなし | Write Null |
読み取りではデフォルト値が返ります |
型の違いはエラーにならず、デフォルト値の返却で処理されます。数値の 10 を Read String で読んでも文字列には変換されません。
YAMLでは 1.0 は小数、1 は整数、"1" は文字列のように、書き方で型が決まります。書き出し時は、数値として解釈できる文字列("10" など)は自動的に引用符付きで出力され、読み込み直しても文字列のまま保持されます。
アクセス文字列の仕様
アクセス文字列の基本記法はユースケースで説明したとおり、キーをドットでつなぎ、シーケンス要素は [ ] で指定します。
- インデックスは0始まりです。
- 複数の
[ ]を並べた多次元シーケンスの指定(matrix[1][2])や、ルートがシーケンスのドキュメントへの指定([0].name)が可能です。 .、[、]の前後の空白は無視されます。- 存在しないパスを読み取るとデフォルト値が返ります。シーケンスの範囲外インデックスも同様です。
.そのものを含むキーはドット記法では指定できません。C++からGetRootNodeとFindChildを使ってアクセスしてください。
書き込みでは、パスの途中に存在しないマップやシーケンスがあれば自動的に作成されます。ただし、次の2つの動作に注意してください。
- ルートがマップでないドキュメント(ルートシーケンスなど)に名前付きパスを書き込むと、ルートが空のマップで置き換えられ、以前の内容は失われます。
- 書き込みパスのインデックスが一定の上限(100000)を超える場合、その書き込みは無視されます。
items[1000000]のような指定で巨大なシーケンスが作られるのを防ぐ仕様です。
ファイル入出力の動作
パスの解決
Load Yaml From File と Save Yaml To File の File Path は、Is Absolute がオフのとき Contentディレクトリ基準の相対パス として解釈されます。Data/GameConfig.yaml は <プロジェクト>/Content/Data/GameConfig.yaml を指します。
Is Absolute をオンにすると、パスをそのまま使用します。プロジェクト外のファイル(ユーザーのドキュメントフォルダなど)を読み書きする場合は、オンにして完全なパスを指定してください。
保存の動作
Save Yaml To File の特徴は以下のとおりです。
- 保存先のフォルダが存在しない場合、フォルダ階層が自動的に作成されます。
- 出力は常に改行とインデント付きの整形形式です。YAMLではインデントが文法の一部であるため、1行にまとめた形式はありません。
- 書き込みに失敗した場合は
Successがfalseになり、Error CodeとError Messageに内容が出力されます。
パッケージ化での注意
パッケージ化したゲームでは、Content内の非アセットファイル(.yaml)は既定ではパッケージに含まれません。設定ファイルを同梱する場合は、プロジェクト側のパッケージ設定でYAMLファイルの取り扱いを確認してください。パッケージ内のContentは読み取り専用になるため、セーブデータの保存先には Is Absolute での絶対パス指定(FPaths::ProjectSavedDir() 配下など)を検討してください。
コピーの共有とスナップショット
Yaml Object のコピーと読み取り系ノードの戻り値では、内部データの扱いが異なります。
| 操作 | 戻り値の性質 |
|---|---|
Yaml Object のコピー |
ドキュメントを共有。一方への書き込みは他方からも見える |
Read Object / Read Objects |
独立したディープコピー。取得後の元ドキュメントの変更は反映されない |
Read Value / Read Array * |
ノードのスナップショット。取得後の元ドキュメントの変更は反映されない |
Blueprintで Yaml Object 変数を別の変数に代入するとコピーが作られますが、書き込みは共有ツリーに対して行われます。ドキュメントを独立して保持したい場合は、Read Object で取得したオブジェクトを使ってください。
USTRUCTとの変換
C++では、FEasyYamlObject の TryReadStruct / TryWriteStruct でYAMLドキュメントとUSTRUCTインスタンスを相互変換できます。Blueprintからは使用できません。
TryReadStructは、YAMLドキュメントのルートがマップのとき、各UPROPERTYを対応するキーの値で埋めます。ルートがマップでない場合は失敗します。TryWriteStructは、USTRUCTの各UPROPERTYをマップとして書き出し、ドキュメントのルートを置き換えます。失敗時はルートを変更しません。- UObject参照、デリゲート、カスタムシリアライザを持つプロパティは変換対象外です。
- 数値はYAMLのInt / Floatノードから読み取られ、FStringは文字列ノードからのみ読み取られます。
- 変換の内部処理の都合上、int64のうち絶対値が2の53乗(9007199254740992)を超える値は、変換の往復で精度が落ちることがあります。
トラブルシューティング
| 症状 | 原因と対策 |
|---|---|
Load Yaml From String が必ず失敗する |
YAMLの文法エラー(インデントの不揃い、コロンと値の間の空白の欠落、引用符の対応)。Error Message の line X column Y を確認 |
Load Yaml From File が File not found になる |
File Path の指定ミス。相対パスはContentディレクトリ基準 |
| 読み取った値が常にデフォルト値になる | アクセス文字列のつづり・階層・インデックスの誤り。Has Path でパスの存在を確認 |
| シーケンスの要素が読み取れない | インデックスが0始まりであることを確認 |
文字列のはずの値が Read String で読めない |
値がYAML上で数値や真偽値として解釈されている。Read Value + Get Node Type で実際の型を確認 |
| 書き込んだはずの値が反映されない | 書き込みパスのインデックスが上限(100000)を超えていないか。対象の Yaml Object 変数を接続しているか |
| パッケージ後にYAMLファイルが読めない | Content内の非アセットファイルがパッケージに含まれていない。ファイル入出力の動作を確認 |
| 保存したYAMLからコメントが消える | 仕様です。コメントは読み込み・保存の往復では保持されません |
注意事項
- YAMLのコメントは、読み込んで保存し直すと保持されません。コメント付きファイルを扱う場合は、元ファイルを上書き保存しない運用にしてください。
Write Object・Add Object To Arrayで渡したYaml Objectはコピーされて埋め込まれます。埋め込み後に元の変数を書き換えても、保存済みのYAMLには反映されません。- ドキュメントのネストの深さは、読み込み時に512レベルまでに制限されています。読み込めたドキュメントは必ず書き出せます。
