EditorImportPlugin

继承： ResourceImporter < RefCounted < Object

在编辑器中注册一个自定义资源导入器。使用该类来解析任何文件，并将其作为新的资源类型导入。

描述

EditorImportPlugin 提供了一种方法来扩展编辑器的资源导入功能。使用它们从自定义文件中导入资源，或为编辑器的现有导入器提供替代方案。

EditorImportPlugin 通过与特定的文件扩展名和资源类型相关联来工作。请参见 _get_recognized_extensions() 和 _get_resource_type()。它们可以选择性地指定一些影响导入过程的导入预设。EditorImportPlugin 负责创建资源并将它们保存在 .godot/imported 目录中（见 ProjectSettings.application/config/use_hidden_project_data_directory）。

下面是一个 EditorImportPlugin 的示例，它从扩展名为“.special”或“.spec”的文件中导入 Mesh：

@tool
extends EditorImportPlugin

func _get_importer_name():
    return "my.special.plugin"

func _get_visible_name():
    return "Special Mesh"

func _get_recognized_extensions():
    return ["special", "spec"]

func _get_save_extension():
    return "mesh"

func _get_resource_type():
    return "Mesh"

func _get_preset_count():
    return 1

func _get_preset_name(preset_index):
    return "Default"

func _get_import_options(path, preset_index):
    return [{"name": "my_option", "default_value": false}]

func _import(source_file, save_path, options, platform_variants, gen_files):
    var file = FileAccess.open(source_file, FileAccess.READ)
    if file == null:
        return FAILED
    var mesh = ArrayMesh.new()
    # 使用从“file”中读取的数据填充 Mesh，留作读者的练习。

    var filename = save_path + "." + _get_save_extension()
    return ResourceSaver.save(mesh, filename)

using Godot;

public partial class MySpecialPlugin : EditorImportPlugin
{
    public override string _GetImporterName()
    {
        return "my.special.plugin";
    }

    public override string _GetVisibleName()
    {
        return "Special Mesh";
    }

    public override string[] _GetRecognizedExtensions()
    {
        return ["special", "spec"];
    }

    public override string _GetSaveExtension()
    {
        return "mesh";
    }

    public override string _GetResourceType()
    {
        return "Mesh";
    }

    public override int _GetPresetCount()
    {
        return 1;
    }

    public override string _GetPresetName(int presetIndex)
    {
        return "Default";
    }

    public override Godot.Collections.Array<Godot.Collections.Dictionary> _GetImportOptions(string path, int presetIndex)
    {
        return
        [
            new Godot.Collections.Dictionary
            {
                { "name", "myOption" },
                { "default_value", false },
            },
        ];
    }

    public override Error _Import(string sourceFile, string savePath, Godot.Collections.Dictionary options, Godot.Collections.Array<string> platformVariants, Godot.Collections.Array<string> genFiles)
    {
        using var file = FileAccess.Open(sourceFile, FileAccess.ModeFlags.Read);
        if (file.GetError() != Error.Ok)
        {
            return Error.Failed;
        }

        var mesh = new ArrayMesh();
        // 使用从“file”中读取的数据填充 Mesh，留作读者的练习
        string filename = $"{savePath}.{_GetSaveExtension()}";
        return ResourceSaver.Save(mesh, filename);
    }
}

要使用 EditorImportPlugin，请先使用 EditorPlugin.add_import_plugin() 方法注册它。

教程

导入插件

方法

bool	_can_import_threaded() virtual const
int	_get_format_version() virtual const
Array[Dictionary]	_get_import_options(path: String, preset_index: int) virtual required const
int	_get_import_order() virtual const
String	_get_importer_name() virtual required const
bool	_get_option_visibility(path: String, option_name: StringName, options: Dictionary) virtual const
int	_get_preset_count() virtual const
String	_get_preset_name(preset_index: int) virtual required const
float	_get_priority() virtual const
PackedStringArray	_get_recognized_extensions() virtual required const
String	_get_resource_type() virtual required const
String	_get_save_extension() virtual required const
String	_get_visible_name() virtual required const
Error	_import(source_file: String, save_path: String, options: Dictionary, platform_variants: Array[String], gen_files: Array[String]) virtual required const
Error	append_import_external_resource(path: String, custom_options: Dictionary = {}, custom_importer: String = "", generator_parameters: Variant = null)

方法说明

bool _can_import_threaded() virtual const 🔗

Tells whether this importer can be run in parallel on threads, or, on the contrary, it's only safe for the editor to call it from the main thread, for one file at a time.

If this importer's implementation is thread-safe and can be run in parallel, override this with true to optimize for concurrency.

If not overridden, returns false.

int _get_format_version() virtual const 🔗

获取此导入器的格式版本号。当对导入资源的格式进行不兼容的更改时，应递增此版本号。

若未覆写，格式版本号默认为 0。

Array[Dictionary] _get_import_options(path: String, preset_index: int) virtual required const 🔗

获取该索引下预设的选项和默认值。返回一个字典数组，包含以下键名：name、default_value、property_hint（可选）、hint_string（可选）、usage（可选）。

int _get_import_order() virtual const 🔗

获取该导入器在导入资源时的运行顺序。具有较低导入顺序的导入器将被首先调用，较高值的将被其后调用。使用这个来确保导入器在依赖项已经被导入后执行。默认的导入顺序是 0，除非被指定的导入器重写。参阅 ImportOrder 了解相关预定义的值。

String _get_importer_name() virtual required const 🔗

获取导入器的唯一名称。

bool _get_option_visibility(path: String, option_name: StringName, options: Dictionary) virtual const 🔗

获取名为 option_name 的导入选项是否应当在“导入”面板中可见。默认实现始终返回 true，即所有选项均可见。主要用于在禁用某个选项时隐藏与其存在依赖关系的选项。

func _get_option_visibility(path, option_name, options):
    # 只有在压缩模式为“Lossy”时显示 Lossy 质量设置。
    if option_name == "compress/lossy_quality" and options.has("compress/mode"):
        return int(options["compress/mode"]) == COMPRESS_LOSSY # 这是你设置的常量

    return true

public override bool _GetOptionVisibility(string path, StringName optionName, Godot.Collections.Dictionary options)
{
    // 只有在压缩模式为“Lossy”时显示 Lossy 质量设置。
    if (optionName == "compress/lossy_quality" && options.ContainsKey("compress/mode"))
    {
        return (int)options["compress/mode"] == CompressLossy; // 这是你设置的常量
    }

    return true;
}

int _get_preset_count() virtual const 🔗

获取插件定义的初始预设的数量。使用 _get_import_options() 获取预设的默认选项，使用 _get_preset_name() 获取预设的名称。

默认情况下，不提供任何预设。

String _get_preset_name(preset_index: int) virtual required const 🔗

获取该索引处预设的选项名称。

float _get_priority() virtual const 🔗

获取该插件对识别的扩展的优先级。优先级越高的插件会被优先选择。默认的优先级是 1.0。

PackedStringArray _get_recognized_extensions() virtual required const 🔗

获取与该加载器相关联的文件扩展名列表（不区分大小写），例如 ["obj"]。

String _get_resource_type() virtual required const 🔗

获取与此加载程序关联的 Godot 资源类型，例如 "Mesh" 或 "Animation"。

String _get_save_extension() virtual required const 🔗

获取用于在 .godot/imported 目录中保存此资源的扩展名（请参阅 ProjectSettings.application/config/use_hidden_project_data_directory）。

String _get_visible_name() virtual required const 🔗

获取在导入窗口中显示的名称。你应该选择这个名字作为“导入为”的延续，例如“导入为 Special Mesh”。

Error _import(source_file: String, save_path: String, options: Dictionary, platform_variants: Array[String], gen_files: Array[String]) virtual required const 🔗

使用导入选项 options 导入源文件 source_file。如果导入成功应返回 @GlobalScope.OK，其他值表示失败。

导入的资源应保存至 save_path + "." + _get_save_extension()。如果希望针对某个特性标签优先使用不同的版本，请将该版本的资源保存至 save_path + "." + 标签 + "." + _get_save_extension()，并将该特性标签添加至 platform_variants。

如果在资源文件系统（res://）中生成了额外的资源文件，请将其完整路径添加至 gen_files，从而使编辑器得知这些文件依赖于 source_file。

必须覆盖这个方法进行实际的导入工作。覆盖示例见这个类的描述。

Error append_import_external_resource(path: String, custom_options: Dictionary = {}, custom_importer: String = "", generator_parameters: Variant = null) 🔗

该函数只能在 _import() 回调期间调用，它允许从中手动导入资源。当导入的文件生成需要导入的外部资源（例如图像）时，这很有用。“.import”文件的自定义参数可以通过 custom_options 传递。此外，在多个导入器可以处理一个文件的情况下，可以指定 custom_importer 以强制使用某个特定的导入器。该函数会执行一次资源导入并立即返回成功或错误代码。generator_parameters 定义可选的额外元数据，这些元数据将作为 generator_parameters 存储在 .import 文件的 remap 小节中，例如存储源数据的一个 md5 散列值。