This page covers the mapping between YAML types and nodes, the access string specification, file I/O behavior, and what to check when something goes wrong.
YAML types and node mapping
The YAML value types map to the reading nodes as follows.
| YAML type | Reading node | Writing node | Notes |
|---|---|---|---|
| Integer | Read Int |
Write Int |
int64 (64-bit) |
| Float | Read Float |
Write Float |
double precision. Integers are also readable |
| String | Read String |
Write String |
|
| Boolean | Read Bool |
Write Bool |
true / false |
| Map | Read Object |
Write Object |
A collection of keys and values |
| Array of maps | Read Objects |
Add Object To Array |
A sequence whose elements are maps |
| Sequence | Element via access string | Add Int To Array etc. |
Read element by element as in items[0] |
| null | No dedicated node | Write Null |
Reads return the default value |
Type mismatches do not raise errors; they are handled by returning the default value. Reading the number 10 with Read String does not convert it to a string.
In YAML, the notation decides the type: 1.0 is a float, 1 is an integer, and "1" is a string. On output, strings that could be misread as numbers (such as "10") are emitted with automatic quoting, so they stay strings after a round trip.
Access string specification
The basic notation joins keys with dots and addresses sequence elements with [ ], as described in Use Cases.
- Indices are zero-based.
- Multi-dimensional sequences (
matrix[1][2]) and documents whose root is a sequence ([0].name) are addressable. - Whitespace around
.,[, and]is ignored. - Reading a missing path returns the default value; out-of-range indices behave the same way.
- Keys containing
.itself cannot be addressed with dot notation. Access them from C++ viaGetRootNodeandFindChild.
When writing, missing maps and sequences along the path are created automatically. Note the following two behaviors:
- Writing a named path into a document whose root is not a map (a root sequence, for example) replaces the root with an empty map; the previous content is lost.
- A write whose path carries an index above a fixed limit (100000) is ignored. This prevents a path like
items[1000000]from allocating a huge sequence.
File I/O behavior
Path resolution
The File Path of Load Yaml From File and Save Yaml To File is resolved relative to the Content directory when Is Absolute is off. Data/GameConfig.yaml points at <Project>/Content/Data/GameConfig.yaml.
Turning Is Absolute on uses the path as-is. To read or write files outside the project (such as the user’s documents folder), turn it on and specify a full path.
Saving behavior
Save Yaml To File behaves as follows.
- Missing output directories are created automatically.
- The output is always formatted with line breaks and indentation. YAML uses indentation as part of its syntax, so there is no single-line form.
- On failure,
Successbecomesfalseand the reason is reported throughError CodeandError Message.
Packaging notes
In a packaged game, non-asset files inside Content (.yaml) are not included in the package by default. When bundling configuration files, review the project’s packaging settings for YAML files. Content inside a package is read-only, so consider an absolute path via Is Absolute (for example, under FPaths::ProjectSavedDir()) as the destination for save data.
Copy sharing and snapshots
Yaml Object copies and the return values of the reading nodes differ in how they hold the data.
| Operation | Nature of the result |
|---|---|
Copying a Yaml Object |
Shares the document. A write through one copy is visible from the other |
Read Object / Read Objects |
Independent deep copy. Later changes to the source document are not reflected |
Read Value / Read Array * |
Snapshot of the node. Later changes to the source document are not reflected |
Assigning a Yaml Object variable to another variable in Blueprint creates a copy, but writes go to the shared tree. When you need a document to stand on its own, use the object obtained through Read Object.
USTRUCT conversion
From C++, TryReadStruct and TryWriteStruct on FEasyYamlObject convert between a YAML document and a USTRUCT instance. They are not available from Blueprint.
TryReadStructfills each UPROPERTY of an existing struct instance from the matching key. It fails when the document root is not a map.TryWriteStructexports the UPROPERTYs as a map and replaces the document root. On failure the root is left untouched.- UObject references, delegates, and properties with custom serializers are out of scope.
- Numbers are read from YAML Int/Float nodes, and FString properties read from string nodes only.
- Due to the internal conversion path, int64 values beyond +/-2^53 (9007199254740992) can lose precision over a round trip.
Troubleshooting
| Symptom | Cause and remedy |
|---|---|
Load Yaml From String always fails |
A YAML syntax error (uneven indentation, missing whitespace after a colon, mismatched quotes). Check the line X column Y in Error Message |
Load Yaml From File reports File not found |
A mistake in File Path. Relative paths are Content-based |
| Reads always return the default value | A typo or wrong hierarchy/index in the access string. Confirm the path with Has Path |
| Sequence elements cannot be read | Remember that indices are zero-based |
A value you expect to be a string fails Read String |
The value is being interpreted as a number or boolean in YAML. Check the actual type with Read Value + Get Node Type |
| A written value is not reflected | Check that the write path’s index is within the limit (100000) and that a Yaml Object variable is connected |
| YAML files cannot be read after packaging | Non-asset files inside Content are not in the package. See File I/O behavior |
| Comments disappear from a saved YAML file | By design. Comments are not preserved across a load/save round trip |
Notes
- YAML comments are not preserved across a load/save round trip. When handling commented files, avoid overwriting the original file.
- A
Yaml Objectpassed toWrite ObjectorAdd Object To Arrayis copied on embed. Rewriting the source variable afterwards is not reflected in the saved YAML. - Document nesting is limited to 512 levels at parse time. Every document that parsed successfully can be emitted.
