EasyYamlParser データ形式と運用

YAMLの型とノードの対応、アクセス文字列の仕様、ファイル入出力の動作、コピーの共有とスナップショット、USTRUCT変換、トラブルシューティング。

このページでは、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レベルまでに制限されています。読み込めたドキュメントは必ず書き出せます。