自定义资源格式加载器

前言

ResourceFormatLoader 是一个用来加载文件资源的工厂接口. 资源是基本容器. 当再次在同一文件路径上调用load时, 将引用先前加载的Resource. 自然, 加载的资源必须是无状态的.

本指南假定读者知道如何创建C++模块和Godot数据类型. 如果不知道, 请参考本指南 自定义 C++ 模块 .

参考

可以做什么？

  • 添加对多种文件格式的新支持

  • 音频格式

  • 视频格式

  • 机器学习模型

不可以做什么？

  • 光栅图像

应使用ImageFormatLoader加载图像.

参考

创建一个资源格式加载器

每种文件格式都包含一个数据容器和一个 ResourceFormatLoader.

ResourceFormatLoaders通常是简单的类, 返回支持Godot中新扩展的所有必要元数据. 该类必须返回格式名称和扩展字符串.

此外,ResourceFormatLoaders 必须使用 load 函数将文件路径转换为资源(Resource). 要加载资源, load 必须能够读取和处理序列化的资源数据.

  1. /* resource_loader_json.h */
  3. #ifndef RESOURCE_LOADER_JSON_H
  4. #define RESOURCE_LOADER_JSON_H
  6. #include "core/io/resource_loader.h"
  8. class ResourceFormatLoaderJson : public ResourceFormatLoader {
  9.     GDCLASS(ResourceFormatLoaderJson, ResourceFormatLoader);
  10. public:
  11.     virtual RES load(const String &p_path, const String &p_original_path, Error *r_error = NULL);
  12.     virtual void get_recognized_extensions(List<String> *r_extensions) const;
  13.     virtual bool handles_type(const String &p_type) const;
  14.     virtual String get_resource_type(const String &p_path) const;
  15. };
  16. #endif // RESOURCE_LOADER_JSON_H
  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. }

创建ResourceFormatSaver

如果您希望能够编辑和保存资源, 则可以实现 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
  1. /* resource_saver_json.cpp */
  3. #include "resource_saver_json.h"
  5. #include "resource_json.h"
  6. #include "scene/resources/resource_format_text.h"
  8. Error ResourceFormatSaverJson::save(const String &p_path, const RES &p_resource, uint32_t p_flags) {
  9.     Ref<JsonResource> json = memnew(JsonResource);
  10.     Error error = json->save_file(p_path, p_resource);
  11.     return error;
  12. }
  14. bool ResourceFormatSaverJson::recognize(const RES &p_resource) const {
  15.     return Object::cast_to<JsonResource>(*p_resource) != NULL;
  16. }
  18. void ResourceFormatSaverJson::get_recognized_extensions(const RES &p_resource, List<String> *r_extensions) const {
  19.     if (Object::cast_to<JsonResource>(*p_resource)) {
  20.             r_extensions->push_back("json");
  21.     }
  22. }

创建自定义数据类型

Godot在其 核心类型 或托管的资源中可能没有适当的替代品. 这时Godot需要新的注册数据类型来理解其他二进制格式, 例如机器学习模型.

下面是创建自定义数据类型的示例:

  1. /* resource_json.h */
  3. #ifndef RESOURCE_JSON_H
  4. #define RESOURCE_JSON_H
  6. #include "core/io/json.h"
  7. #include "core/variant_parser.h"
  9. class JsonResource : public Resource {
  10.     GDCLASS(JsonResource, Resource);
  12. protected:
  13.     static void _bind_methods() {
  14.             ClassDB::bind_method(D_METHOD("set_dict", "dict"), &JsonResource::set_dict);
  15.             ClassDB::bind_method(D_METHOD("get_dict"), &JsonResource::get_dict);
  17.             ADD_PROPERTY(PropertyInfo(Variant::DICTIONARY, "content"), "set_dict", "get_dict");
  18.     }
  20. private:
  21.     Dictionary content;
  23. public:
  24.     Error load_file(const String &p_path);
  25.     Error save_file(const String &p_path, const RES &p_resource);
  27.     void set_dict(const Dictionary &p_dict);
  28.     Dictionary get_dict();
  29. };
  30. #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.     Error error;
  37.     FileAccess *file = FileAccess::open(p_path, FileAccess::WRITE, &error);
  38.     if (error != OK) {
  39.             if (file) {
  40.                     file->close();
  41.             }
  42.             return error;
  43.     }
  45.     Ref<JsonResource> json_ref = p_resource.get_ref_ptr();
  46.     JSON json;
  48.     file->store_string(json.print(json_ref->get_dict(), "    "));
  49.     file->close();
  50.     return OK;
  51. }
  53. void JsonResource::set_dict(const Dictionary &p_dict) {
  54.     content = p_dict;
  55. }
  57. Dictionary JsonResource::get_dict() {
  58.     return content;
  59. }

注意事项

一些库可能未定义某些通用例程, 例如IO处理. 因此, 需要Godot调用转换.

例如, 下面是将 FileAccess 调用转换为 std::istream 的代码.

  1. #include "core/os/file_access.h"
  3. #include <istream>
  4. #include <streambuf>
  6. class GodotFileInStreamBuf : public std::streambuf {
  8. public:
  9.     GodotFileInStreamBuf(FileAccess *fa) {
  10.             _file = fa;
  11.     }
  12.     int underflow() {
  13.             if (_file->eof_reached()) {
  14.                     return EOF;
  15.             } else {
  16.                     size_t pos = _file->get_position();
  17.                     uint8_t ret = _file->get_8();
  18.                     _file->seek(pos); // Required since get_8() advances the read head.
  19.                     return ret;
  20.             }
  21.     }
  22.     int uflow() {
  23.             return _file->eof_reached() ? EOF : _file->get_8();
  24.     }
  26. private:
  27.     FileAccess *_file;
  28. };

参考

注册新的文件格式

Godot 用 ResourceLoader 处理程序注册 ResourcesFormatLoader. 当调用 load 时, 处理程序会自动选择合适的加载器.

  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. }

参考

将其加载到GDScript

保存具有以下内容的名为 demo.json 的文件, 并将其放置在项目的根文件夹中:

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

创建一个节点并附加下面的脚本：

  1. extends Node
  3. onready var json_resource = load("res://demo.json")
  5. func _ready():
  6.     print(json_resource.get_dict())