Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

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 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 🔗

表示该导入器是否能够利用线程并行执行，不能的话表示编辑器只能从主线程安全调用，一次一个文件。

如果没有覆盖该方法，则默认返回 true。

如果该导入器的实现为线程安全的，可以并行执行，请覆盖该方法并返回 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（可选）、usage（可选）。

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):
    # 仅在压缩模式设为“Lossy”时显示有损压缩质量设置。
    if option == "compress/lossy_quality" and options.has("compress/mode"):
        return int(options["compress/mode"]) == COMPRESS_LOSSY # 这是你设置的常量

    return true

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

    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 🔗

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

String _get_save_extension() virtual const 🔗

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

String _get_visible_name() virtual const 🔗

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

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

使用指定的导入选项 options 将 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 散列值。