このページでは、目的に合わせた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)で値を取り出します。
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 を書き換えても、取得済みのオブジェクトには影響しません。
セーブデータを作成して保存する
ゲーム内のデータをYAMLとして組み立て、ファイルに保存する例です。
Create Empty Yaml Objectの戻り値を変数NewYamlに保存します。Write Int、Write Float、Write String、Write Boolでスカラー値を書き込みます。- 別の
Yaml Objectを作成してWrite Objectで埋め込むと、階層構造を作れます。 - シーケンスは
Add Int To Array、Add String To Array、Add Object To Arrayなどで要素を追加します。シーケンスは指定したパスに自動的に作成されます。 Save Yaml To Fileで保存します。
Save Yaml To File の File Path に SaveData/PlayerSave.yaml のような相対パスを指定すると、Contentディレクトリの下に保存されます。保存先のフォルダが存在しない場合は自動的に作成されます。
作成した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を返すかで判定します。
