GitHub CopilotWrite better code with AI | MCP RegistryIntegrate external tools | ActionsAutomate any workflow | CodespacesInstant dev environments | IssuesPlan and track work | Code ReviewManage code changes | Code QualityEnforce quality at merge | Why GitHub | Marketplace | View all features | Enterprises | Small and medium teams | Startups | View all use cases | View all industries | View all solutions | AI | Software Development | DevOps | Security | View all topics | Customer stories | Events & webinars | Ebooks & reports | Business insights | Trust center | Partners | View all resources
UnrealYAML: A Unreal-Compatible Wrapper for the yaml-cpp Library
Welcome to the UnrealYAML Plugin, a Plugin that allows the parsing and emitting of YAML files, based on the
Current yaml-cpp base commit:
Installation
To install this Plugin, copy or clone the whole repository into the Plugins directory of your project:
git clone https://github.com/jwindgassen/UnrealYAML.git Plugins/UnrealYAML
You might need to activate this Plugin in the Plugin Manager inside the editor or include it inside the MyProject.Build.cs:
PublicDependencyModuleNames.Add("UnrealYAML")Features
Basic Interaction with YAML Nodes in C++:
UnrealYAML provides the FYamlNode type, which can be used to create and work with YAML Values inside C++. UnrealYAML can work with many of the common Unreal Types, e.g. FString and FVector, as well as the container types TArray, TSet and TMap. A list of all supported types can be found
.
FYamlNode Node; // Assignment Node["someValue"] = 42; Node["strings"] = TArray<FString>{"aString", "anotherString"}; // Retrieving FString SecondString = Node["strings"][1].As<FString>(); // Use TOptional if you don't know if the value exists: TOptional<FVector> MaybeVector = Node["vec"].AsOptional<FVector>(); // Iterate over sequences and maps: FYamlNode Sequence{TArray<int32>{1, 2, 3, 4}}; for (constauto& [Index, Value] : Sequence) { UE_LOG(LogTemp, Log, TEXT("Sequence[%d]: %s"), Index.As<int32>(), *Index.GetContent()); } // Read and write YAML files to disk: FYamlNode File; UYamlParsing::LoadYamlFromFile("example1.yml", Node); File["someValue"] = 42; UYamlParsing::WriteYamlToFile("example1.yml", Node);Blueprint Support:
Most functionality can also be used inside Blueprints
Interfacing with Unreal Engine's Reflection system
Structs and Classes defined with the Unreal Engine's Reflection system (USTRUCT() and UCLASS()) can be directly converted to and from FYamlNodes. With the type information generated by the Unreal Header Tool, the data inside a Struct can be written to a Nodes (Serialization) or the data inside a Node can be parsed into the instance of a Struct (Deserialization):
Supported types:
Simple scalar values, such as int32, float, FString, FName and FText
UEnum values, which can be expressed in YAML as both string (case-insensitive) and numeric representations.
TMap and TArray, and nested USTRUCTs
Object references: TSoftObjectPtr and TSubclassOf
Custom conversions for your own types.
During parsing, any errors encountered will be collected and can be accessed afterward.
Serialization
USTRUCT() structFMyData { GENERATED_BODY() UPROPERTY() int32 MyInteger; UPROPERTY() TArray<FString> StringData; }; // Create some data to serialize FMyData Data; Data.MyInteger = 42; Data.StringData = {"oneString", "anotherString"}; // Control the Serialization. See the documentation of `FYamlSerializeOptions` // for an explanation of all available options. FYamlSerializeOptions Options; Options.Capitalization = EYamlKeyCapitalization::CamelCase; // Serialize the Data into a FYamlNode FYamlNode YamlData; FYamlSerializationResult Result = SerializeStruct(YamlData, Data, Options); // The Result contains all errors that occurred during the parsing:checkf(Result.Success(), TEXT("Could not Serialize FMyData")) // Write the Data to disk: UYamlParsing::WriteYamlToFile("data.yml", YamlData);Result:
myInteger: 42stringData: - oneString - anotherString Deserialization
// Load the data to disk FYamlNode YamlData; UYamlParsing::LoadYamlFromFile("data.yml", YamlData); // Control the Deserialization. See the documentation of // `FYamlDeserializeOptions` for an explanation of all options. FYamlDeserializeOptions Options; Options.StrictTypes = true; Options.AllowUnusedValues = false; // Parse the data into an instance of FMyData FMyData Data; DeserializeStruct(YamlData, Data, Options); check(Data.MyInteger == 42)Tutorial
You can find more examples on the
. Since this Plugin is syntactically very similar to the underlying yaml-cpp library, many of the things in their
can also be applied to this Plugin.
Contributing
While this Plugin provides most of basic functionality you would expect from a plugin like this, there are still features left to implement. Especially Blueprint integration can still be improved a lot. Any contributions are warmly welcome!
ToDos
Sequences and Maps into TArray<Node> and TMap<FString, Node> for Iteration in Blueprints
Interfacing with Unreal JSON Plugin?
Wrapper class for the Emitter?
Schema Verification?
Patches
I applied some patches on top of the yaml-cpp library to ease the integration:
enum-class: Changed enums to enum classes to remove -Wshadow error
unreachable-code: Removes some unreachable code, which might cause compiler errors otherwise
filename-conflicts: Renamed yaml-cpp/stc/emitter.h