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

表示該匯入器是否可以線上程上並行執行，或者相反，編輯器只能從主執行緒呼叫安全，一次處理一個檔案。

如果該匯入器的實作是執行緒安全的並且可以並行執行，請將其覆蓋為 true 以最佳化併發效能。

如果未覆蓋，則回傳 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 雜湊值。