Godot YAML GDExtension

This is the C++ GDExtension implementation of the Godot YAML plugin. It provides high-performance YAML parsing and serialization using RapidYAML as the core engine, offering sub-millisecond processing for most YAML documents. This extension is built for Godot 4.3 or later.

🔄 Version History

• 1.1.0 (Current) - Nested YAML files can now be loaded with the !Resource tag, and some fixes
• 1.0.0 - First major release with custom YAML editor, streamlined API, and several fixes. See the plugin changelog for details
• 0.12.1 - Build support for Linux (x86 64-bit)
• 0.12.0 - Performance optimizations, bug fixes, and comprehensive tests for all variant types
• 0.11.0 - Added support for parsing multiple documents, and error handling for custom class deserialization
• 0.10.1 - Fixed issue with custom Resources not being serializable
• 0.10.0 - Added custom class serialization support, upgraded to Godot 4.3
• 0.9.0 - Initial public release

🚀 Quick Start

# Parse YAML
var result = YAML.parse("key: value\nlist:\n  - item1\n  - item2")
if result.has_error():
    push_error(result.get_error())
    return

var data = result.get_data()
print(data.key)  # Outputs: value
print(data.list) # Outputs: [item1, item2]

# Generate YAML
var yaml_text = YAML.stringify(data).get_data()
print(yaml_text)

📌 For full usage details and API documentation, see the plugin README:
📂 project/addons/yaml/README.md

🔥 Key Features

• ⚡ High Performance: Built on the lightweight and efficient RapidYAML library
• 🧩 Comprehensive Variant Support: Handles all Godot built-in Variant types (except Callable and RID)
• 🧪 Custom Class Serialization: Register your GDScript classes for seamless serialization and deserialization
• 🔄 Multi-Document Support: Parse YAML files with multiple --- separated documents
• 🎨 Style Customization: Control how YAML is formatted with customizable style options
• 🔍 Comprehensive Error Handling: Detailed error reporting with line and column information
• 🔀 Thread-Safe: Fully supports multi-threaded parsing and emission
• ✅ Validation: Separate validation step for checking YAML syntax without full parsing
• 🗂️ Resource References: Use !Resource tags to reference and load external resources
• 🛡️ Security Controls: Manage resource loading security during YAML parsing

🛠️ Installation & Setup

Building From Source

Prerequisites

• Git (for cloning and submodules)
• Python 3.x (for SCons build system)
• C++ compiler with C++17 support:
  • Windows: Visual Studio 2022 with C++ workload
  • Linux/macOS: GCC 9+ or Clang 10+
• SCons build system (pip install scons)

Step 1: Clone the Repository

# Clone with submodules
git clone --recursive https://github.com/fimbul-works/godot-yaml

# Or if already cloned, initialize submodules
git submodule update --init --recursive

Step 2: Build the Extension

# Debug build
scons target=template_debug

# Release build
scons target=template_release

# Specify platform (default is platform-dependent)
scons platform=windows target=template_release
scons platform=linux target=template_release

Build Options

• platform: Target (windows, linux, macos, etc.)
• target: Build type (template_debug, template_release)
• arch: CPU architecture (x86_32, x86_64, arm64, etc.)
• dev_build: Enable extra debugging (yes/no)
• use_llvm: Use Clang/LLVM compiler (yes/no)
• verbose: Verbose build output (yes/no)

✅ Supported Platforms

• Windows: ✅ Prebuilt binaries available.
• Linux: ✅ Prebuilt binaries available for x86 64-bit architecture.
• macOS: 🚧 Not yet prebuilt, but should compile without issues.

📌 Contributions welcome! If you can help with Linux/macOS, open a PR.

🧑‍💻 Contributing

Development Guidelines

1. Follow Godot's API design patterns.
2. Minimize allocations (use ryml::cstring instead of std::string).
3. Error handling: Use YAMLResult and throw YAMLException for C++ errors.
4. Thread safety: No global state; ensure safe multithreading.
5. Write tests: Every new feature should have test coverage.
6. Document your changes: All public APIs must be documented.

Code Formatting

# Format code (requires clang-format)
clang-format -i src/*.cpp src/*.h src/variants/*.cpp src/variants/*.h

📜 License

MIT License (see LICENSE file for details).

🚀 Built with ⚡ by FimbulWorks