EasyYamlParser Data Types and Production

YAML type-to-node mapping, access string specification, file I/O behavior, copy sharing and snapshots, USTRUCT conversion, and troubleshooting.

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++ via GetRootNode and FindChild.

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, Success becomes false and the reason is reported through Error Code and Error 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.

  • TryReadStruct fills each UPROPERTY of an existing struct instance from the matching key. It fails when the document root is not a map.
  • TryWriteStruct exports 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 Object passed to Write Object or Add Object To Array is 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.