Custom resource format loaders

    This guide assumes the reader knows how to create C++ modules and Godot data types. If not, refer to this guide .

    What for?

    • Adding new support for many file formats
    • Audio formats
    • Video formats
    • Machine learning models
    • Raster images

    ImageFormatLoader should be used to load images.

    Creating a ResourceFormatLoader

    ResourceFormatLoaders are usually simple classes which return all the necessary metadata for supporting new extensions in Godot. The class must the return the format name and the extension string.

    In addition, ResourceFormatLoaders must convert file paths into resources with the load function. To load a resource, load must read and handle data serialization.

    1. #include "my_json_loader.h"
    2. #include "my_json.h"
    4. ResourceFormatLoaderMyJson::ResourceFormatLoaderMyJson() {
    5. }
    7. RES ResourceFormatLoaderMyJson::load(const String &p_path, const String &p_original_path, Error *r_error) {
    8.         MyJson *my = memnew(MyJson);
    9.                 *r_error = OK;
    10.         Error err = my->set_file(p_path);
    11.         return Ref<MyJson>(my);
    12. }
    14. void ResourceFormatLoaderMyJson::get_recognized_extensions(List<String> *p_extensions) const {
    15.         p_extensions->push_back("mjson");
    16. }
    18. String ResourceFormatLoaderMyJson::get_resource_type(const String &p_path) const {
    20.         if (p_path.get_extension().to_lower() == "mjson")
    22.         return "";
    23. }
    25. bool ResourceFormatLoaderMyJson::handles_type(const String &p_type) const {
    26.         return (p_type == "MyJson");
    27. }

    Here is an example of how to create a custom datatype

    Some libraries may not define certain common routines such as IO handling. Therefore, Godot call translations are required.

    1. #include <istream>
    2. #include <streambuf>
    4. class GodotFileInStreamBuf : public std::streambuf {
    6. public:
    7.         GodotFileInStreamBuf(FileAccess *fa) {
    8.                 _file = fa;
    9.         }
    10.                 if (_file->eof_reached()) {
    11.                         return EOF;
    12.                 } else {
    13.                         size_t pos = _file->get_position();
    14.                         uint8_t ret = _file->get_8();
    16.                         return ret;
    17.                 }
    18.         }
    19.         int uflow() {
    20.                 return _file->eof_reached() ?  EOF : _file->get_8();
    21.         }
    23. private:
    24.         FileAccess *_file;
    25. };

    Registering the new file format

    Godot registers ResourcesFormatLoader with a ResourceLoader handler. The handler selects the proper loader automatically when load is called.

    1. {
    2.   "savefilename" : "demo.mjson",
    3.   "demo": [
    4.     "welcome",
    5.     "to",
    6.     "godot",
    7.     "resource",
    8.     "loaders"
    9. }