EditorImportPlugin¶

继承： ResourceImporter < RefCounted < Object

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

描述¶

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

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

下面是一个示例编辑器导入插件，它从扩展名为“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()
    # 将“文件”中读取的数据填充到网格中，其余部分请读者自行完成。

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

using i3D;

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 i3D.Collections.Array<i3D.Collections.Dictionary> _GetImportOptions(string path, int presetIndex)
    {
        return
        [
            new i3D.Collections.Dictionary
            {
                { "name", "myOption" },
                { "default_value", false },
            },
        ];
    }

    public override Error _Import(string sourceFile, string savePath, i3D.Collections.Dictionary options, i3D.Collections.Array<string> platformVariants, i3D.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();
        // 将“文件”中读取的数据填充到网格中，其余部分请读者自行完成。
        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 const
int	_get_import_order() virtual const
String	_get_importer_name() virtual 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 const
float	_get_priority() virtual const
PackedStringArray	_get_recognized_extensions() virtual const
String	_get_resource_type() virtual const
String	_get_save_extension() virtual const
String	_get_visible_name() virtual const
Error	_import(source_file: String, save_path: String, options: Dictionary, platform_variants: Array[String], gen_files: Array[String]) virtual const
Error	append_import_external_resource(path: String, custom_options: Dictionary = {}, custom_importer: String = "", generator_parameters: Variant = null)

方法说明¶

bool _can_import_threaded() virtual const 🔗

告诉这个导入器是否可以在线程上并行运行，或者相反，编辑器只能安全地从主线程调用它，一次一个文件。

如果此方法未被覆盖，则默认返回false。

如果此导入器的实现是线程安全的并且可以并行运行，请使用true覆盖它以优化并发。

int _get_format_version() virtual const 🔗

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

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

获取此索引处预设的选项和默认值。返回包含以下键的字典数组：name，default_value，property_hint（可选），hint_string（可选），使用（可选）。

int _get_import_order() virtual const 🔗

获取导入资源时要运行的此导入器的顺序。将首先调用具有较低导入顺序的导入器，稍后将调用较高的值。使用此命令可确保导入器在依赖项已导入后运行。默认导入顺序为0，除非被特定导入器覆盖。有关某些预定义值，请参阅ImportOrder。

String _get_importer_name() virtual const 🔗

获取导入器的唯一名称。

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

如果满足条件，可以重写此方法来隐藏特定的导入选项。这主要用于在其中一个选项被禁用时隐藏依赖于其他选项的选项。

func _get_option_visibility(option, options):
    # 只有在压缩模式设置为“有损压缩”时，才显示有损质量设置选项。
    if option == "compress/lossy_quality" and options.has("compress/mode"):
        return int(options["compress/mode"]) == COMPRESS_LOSSY # This is a constant that you set

    return true

public void _GetOptionVisibility(string option, i3D.Collections.Dictionary options)
{
    // 只有在压缩模式设置为“有损压缩”时，才显示有损质量设置选项。
    if (option == "compress/lossy_quality" && options.ContainsKey("compress/mode"))
    {
        return (int)options["compress/mode"] == CompressLossy; // This is a constant you set
    }

    return true;
}

返回 true 以使所有选项始终可见。

int _get_preset_count() virtual const 🔗

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

String _get_preset_name(preset_index: int) virtual const 🔗

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

float _get_priority() virtual const 🔗

获取此插件对已识别扩展的优先级。优先级较高的插件将是首选。默认优先级为1.0。

PackedStringArray _get_recognized_extensions() virtual const 🔗

获取要与此加载程序关联的文件扩展名列表（不区分大小写）。例如["obj"]。

String _get_resource_type() virtual const 🔗

获取与此加载器关联的i3D资源类型。例如"Mesh"或"Animation"。

String _get_save_extension() virtual const 🔗

获取用于将此资源保存在. i3d/进口目录中的扩展名（参见ProjectSettings.application/config/use_hidden_project_data_directory）。

String _get_visible_name() virtual const 🔗

获取要在导入窗口中显示的名称。您应该选择此名称作为“导入为”的延续，例如“导入为特殊网格”。

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

使用指定的importoptions将source_file导入save_path。此函数将修改platform_variants和gen_files数组。

必须重写此方法才能完成实际的导入工作。有关重写此方法的示例，请参阅此类的描述。

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哈希。