EasyYamlParser ユースケース

目的別の使用方法。アクセス文字列の記法、設定ファイルの読み込み、セーブデータの作成、多次元シーケンス、nullの扱い。

このページでは、目的に合わせたYAMLの読み書きの方法を説明します。ノードごとの入出力の詳細はBlueprint APIリファレンスを参照してください。

目的別の選択表

目的 使うノード 読む場所
文字列からYAMLを読み込みたい Load Yaml From String クイックスタート
ファイルからYAMLを読み込みたい Load Yaml From File 設定ファイルを読み込む
階層の深い値を直接読み取りたい Read Int などのRead系 + アクセス文字列 アクセス文字列の指定方法
途中のマップをまとめて取得したい Read Object / Read Objects オブジェクトを取得する
YAMLを作成・編集して保存したい Create Empty Yaml Object + Write系 + Save Yaml To File セーブデータを作成して保存する
マス目のような多次元データを読みたい アクセス文字列 matrix[1][2] 多次元シーケンスを読み込む
null値を書き込みたい・判定したい Write Null / Has Path + Read Value nullを扱う

アクセス文字列の指定方法

読み取りと書き込みは、すべてアクセス文字列(Access String ピン)で対象の位置を指定します。

シンプルなケース

YAMLのトップレベルにある値は、キーをそのまま指定します。次のYAMLの prop を読み取るアクセス文字列は prop です。

prop: abc

階層構造のマップ

キーをドットでつないで階層をたどります。次のYAMLの obj の中の prop は、obj.prop でアクセスします。

obj:
  prop: abc

シーケンスが含まれる場合

シーケンスの要素は [ ] でインデックスを指定します。次のYAMLで1番目の要素の prop は obj[0].prop、2番目の要素は obj[1].prop です。インデックスは0始まりです。

obj:
  - prop: abc
  - prop: def

多次元シーケンスへのアクセス

シーケンスの中にシーケンスがある場合も [ ] を並べて指定します。次の matrix では matrix[0][0] が 1、matrix[1][2] が 6、matrix[2][1] が 8 になります。

matrix:
  - [1, 2, 3]
  - [4, 5, 6]
  - [7, 8, 9]

マップとシーケンスの組み合わせも自由です。users[0].contacts[1].values[0] のような指定が可能です。

ドキュメント全体がシーケンスの場合

YAMLのルートがマップではなくシーケンスのときは、[0].name のように先頭にインデックスを指定します。

- name: Alice
  age: 30
- name: Bob
  age: 25

この場合、[0].name が Alice、[1].age が 25 です。

指定したパスが存在しない場合、Read系ノードはエラーにならず Default Value を返します。この動作を利用して、値が省略された設定ファイルをデフォルト値で補完できます。

. や [ ] そのものを含むキーはドット記法では指定できません。そのようなキーは、C++から GetRootNode と FindChild を使ってアクセスします。

設定ファイルを読み込む

ゲームの設定をYAMLファイルで管理する例です。Contentディレクトリに Data/GameConfig.yaml を配置します。

player:
  name: Hero
  level: 10
maxPlayers: 4

Load Yaml From File ノードを使用します。

ピン 値
File Path Data/GameConfig.yaml
Is Absolute オフ

File Path が相対パスの場合はContentディレクトリが基準になります。プロジェクトの外のファイルを読む場合は Is Absolute をオンにして絶対パスを指定します。

読み込んだ Yaml Object は変数に保存して、Read String(player.name)や Read Int(maxPlayers)で値を取り出します。

Load Yaml From FileでファイルからYAMLを読み込むBlueprintの構成例

YAMLではコメントを書けるため、手で編集する設定ファイルの可読性が高くなります。ただし、コメントは読み込んで保存し直すと失われる点に注意してください(現在の主な制約)。

パッケージ化したゲームでContent内のファイルを読む場合は、ファイルがパッケージに含まれるか(非アセットファイルの追加設定)をプロジェクト側で確認してください。

オブジェクトを取得する

Read Object と Read Objects は、値ではなくYAMLのマップを Yaml Object として取得するノードです。

  • Read Object はアクセス文字列が指すマップを1つ返します。取得したオブジェクトに対して、さらにRead系ノードで相対的なアクセス文字列を指定できます。game マップを取得したあとに player.name を読むような使い方です。
  • Read Objects はマップのシーケンスをまとめて返します。inventory.items のような、要素がマップのシーケンスを For Each Loop で処理する場合に使用します。

どちらも取得したオブジェクトは独立したコピーです。取得後に元の Yaml Object を書き換えても、取得済みのオブジェクトには影響しません。

Read ObjectとRead Objectsノードの構成例

セーブデータを作成して保存する

ゲーム内のデータをYAMLとして組み立て、ファイルに保存する例です。

  1. Create Empty Yaml Object の戻り値を変数 NewYaml に保存します。
  2. Write Int、Write Float、Write String、Write Bool でスカラー値を書き込みます。
  3. 別の Yaml Object を作成して Write Object で埋め込むと、階層構造を作れます。
  4. シーケンスは Add Int To Array、Add String To Array、Add Object To Array などで要素を追加します。シーケンスは指定したパスに自動的に作成されます。
  5. Save Yaml To File で保存します。
Add系ノードでYAMLシーケンスに値を追加するBlueprintの構成例

Save Yaml To File の File Path に SaveData/PlayerSave.yaml のような相対パスを指定すると、Contentディレクトリの下に保存されます。保存先のフォルダが存在しない場合は自動的に作成されます。

Save Yaml To FileノードでYAMLを保存するBlueprintの構成例

作成したYAMLは Yaml To String で文字列に変換できます。出力は常に改行とインデント付きの整形形式です。

多次元シーケンスを読み込む

ゲームボードやグリッドマップのような2次元のデータは、アクセス文字列で直接要素を指定できます。Read Int の Access String に matrix[1][2] を指定すると、2行目の3列目(0始まり)の値が読み取れます。

3次元以上のシーケンスも voxel[1][2][3] のように [ ] を並べて指定できます。

nullを扱う

YAMLのnullは ~ または null と書きます。EasyYamlParserでは、nullは「パスが存在しない」とは区別される値として扱われます。

  • 書き込むときは Write Null を使います。key: null のように明示的にnullが書き出されます。
  • nullの値を Read Int などで読み取ると Default Value が返ります。
  • パスの有無は Has Path で、値がnullかどうかは Read Value で取得した Yaml Value の Get Node Type が Null を返すかで判定します。