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

    Each file format consist of a data container and a .

    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. /* resource_loader_json.cpp */
    3. #include "resource_loader_json.h"
    5. #include "resource_json.h"
    7. RES ResourceFormatLoaderJson::load(const String &p_path, const String &p_original_path, Error *r_error) {
    8. Ref<JsonResource> json = memnew(JsonResource);
    9.     if (r_error) {
    10.             *r_error = OK;
    11.     }
    12.     Error err = json->load_file(p_path);
    13.     return json;
    14. }
    16. void ResourceFormatLoaderJson::get_recognized_extensions(List<String> *r_extensions) const {
    17.     if (!r_extensions->find("json")) {
    18.             r_extensions->push_back("json");
    19.     }
    20. }
    22. String ResourceFormatLoaderJson::get_resource_type(const String &p_path) const {
    23.     return "Resource";
    24. }
    26. bool ResourceFormatLoaderJson::handles_type(const String &p_type) const {
    27.     return ClassDB::is_parent_class(p_type, "Resource");
    28. }

    If you’d like to be able to edit and save a resource, you can implement a ResourceFormatSaver:

    1. /* resource_saver_json.h */
    3. #ifndef RESOURCE_SAVER_JSON_H
    4. #define RESOURCE_SAVER_JSON_H
    6. #include "core/io/resource_saver.h"
    8. class ResourceFormatSaverJson : public ResourceFormatSaver {
    9.     GDCLASS(ResourceFormatSaverJson, ResourceFormatSaver);
    10. public:
    11.     virtual Error save(const String &p_path, const RES &p_resource, uint32_t p_flags = 0);
    12.     virtual bool recognize(const RES &p_resource) const;
    13.     virtual void get_recognized_extensions(const RES &p_resource, List<String> *r_extensions) const;
    14. };
    15. #endif // RESOURCE_SAVER_JSON_H

    Creating custom data types

    Godot may not have a proper substitute within its or managed resources. Godot needs a new registered data type to understand additional binary formats such as machine learning models.

    2. #ifndef RESOURCE_JSON_H
    3. #define RESOURCE_JSON_H
    5. #include "core/io/json.h"
    6. #include "core/variant_parser.h"
    8. class JsonResource : public Resource {
    9.     GDCLASS(JsonResource, Resource);
    11. protected:
    12.     static void _bind_methods() {
    14.             ClassDB::bind_method(D_METHOD("get_dict"), &JsonResource::get_dict);
    16.             ADD_PROPERTY(PropertyInfo(Variant::DICTIONARY, "content"), "set_dict", "get_dict");
    17.     }
    19. private:
    20.     Dictionary content;
    22. public:
    23.     Error load_file(const String &p_path);
    24.     Error save_file(const String &p_path, const RES &p_resource);
    26.     void set_dict(const Dictionary &p_dict);
    27.     Dictionary get_dict();
    28. };
    29. #endif // RESOURCE_JSON_H
    1. /* resource_json.cpp */
    3. #include "resource_json.h"
    5. Error JsonResource::load_file(const String &p_path) {
    6.     Error error;
    7.     FileAccess *file = FileAccess::open(p_path, FileAccess::READ, &error);
    8.     if (error != OK) {
    9.             if (file) {
    10.                     file->close();
    11.             }
    12.             return error;
    13.     }
    15.     String json_string = String("");
    16.     while (!file->eof_reached()) {
    17.             json_string += file->get_line();
    18.     }
    19.     file->close();
    21.     String error_string;
    22.     int error_line;
    23.     JSON json;
    24.     Variant result;
    25.     error = json.parse(json_string, result, error_string, error_line);
    26.     if (error != OK) {
    27.             file->close();
    28.             return error;
    29.     }
    31.     content = Dictionary(result);
    32.     return OK;
    33. }
    35. Error JsonResource::save_file(const String &p_path, const RES &p_resource) {
    36.     FileAccess *file = FileAccess::open(p_path, FileAccess::WRITE, &error);
    37.     if (error != OK) {
    38.             if (file) {
    39.                     file->close();
    40.             }
    41.             return error;
    42.     }
    44.     Ref<JsonResource> json_ref = p_resource.get_ref_ptr();
    45.     JSON json;
    47.     file->store_string(json.print(json_ref->get_dict(), "    "));
    48.     file->close();
    49.     return OK;
    50. }
    52. void JsonResource::set_dict(const Dictionary &p_dict) {
    53.     content = p_dict;
    54. }
    56. Dictionary JsonResource::get_dict() {
    57.     return content;
    58. }

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

    For example, here is the code for translating FileAccess calls into std::istream.

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

    1. /* register_types.h */
    3. void register_json_types();
    4. void unregister_json_types();
    1. /* register_types.cpp */
    3. #include "register_types.h"
    5. #include "core/class_db.h"
    6. #include "resource_loader_json.h"
    7. #include "resource_saver_json.h"
    8. #include "resource_json.h"
    10. static Ref<ResourceFormatLoaderJson> json_loader;
    11. static Ref<ResourceFormatSaverJson> json_saver;
    13. void register_json_types() {
    14.     ClassDB::register_class<JsonResource>();
    16.     json_loader.instance();
    17.     ResourceLoader::add_resource_format_loader(json_loader);
    19.     json_saver.instance();
    20.     ResourceSaver::add_resource_format_saver(json_saver);
    21. }
    23. void unregister_json_types() {
    24.     ResourceLoader::remove_resource_format_loader(json_loader);
    25.     json_loader.unref();
    27.     ResourceSaver::remove_resource_format_saver(json_saver);
    28.     json_saver.unref();
    29. }

    Loading it on GDScript

    Then attach the following script to any node:

    1. extends Node
    3. onready var json_resource = load("res://demo.json")