Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

EditorPlugin

继承: Node < Object

由编辑器使用,用于扩展其功能。

描述

编辑器使用插件来扩展功能。最常见的插件类型是编辑给定的节点或资源类型的插件、导入插件和导出插件。另见 EditorScript,能够向编辑器添加功能。

注意:这个类中的部分名称中包含“left”和“right”(例如 DOCK_SLOT_LEFT_UL)。这些 API 假设的是从左至右的布局,使用从右至左布局时是反的。保留这些名称是出于兼容的原因。

教程

方法

void

_apply_changes ( ) virtual

bool

_build ( ) virtual

void

_clear ( ) virtual

void

_disable_plugin ( ) virtual

void

_edit ( Object object ) virtual

void

_enable_plugin ( ) virtual

void

_forward_3d_draw_over_viewport ( Control viewport_control ) virtual

void

_forward_3d_force_draw_over_viewport ( Control viewport_control ) virtual

int

_forward_3d_gui_input ( Camera3D viewport_camera, InputEvent event ) virtual

void

_forward_canvas_draw_over_viewport ( Control viewport_control ) virtual

void

_forward_canvas_force_draw_over_viewport ( Control viewport_control ) virtual

bool

_forward_canvas_gui_input ( InputEvent event ) virtual

PackedStringArray

_get_breakpoints ( ) virtual const

Texture2D

_get_plugin_icon ( ) virtual const

String

_get_plugin_name ( ) virtual const

Dictionary

_get_state ( ) virtual const

String

_get_unsaved_status ( String for_scene ) virtual const

void

_get_window_layout ( ConfigFile configuration ) virtual

bool

_handles ( Object object ) virtual const

bool

_has_main_screen ( ) virtual const

void

_make_visible ( bool visible ) virtual

void

_save_external_data ( ) virtual

void

_set_state ( Dictionary state ) virtual

void

_set_window_layout ( ConfigFile configuration ) virtual

void

add_autoload_singleton ( String name, String path )

Button

add_control_to_bottom_panel ( Control control, String title )

void

add_control_to_container ( CustomControlContainer container, Control control )

void

add_control_to_dock ( DockSlot slot, Control control )

void

add_custom_type ( String type, String base, Script script, Texture2D icon )

void

add_debugger_plugin ( EditorDebuggerPlugin script )

void

add_export_plugin ( EditorExportPlugin plugin )

void

add_import_plugin ( EditorImportPlugin importer, bool first_priority=false )

void

add_inspector_plugin ( EditorInspectorPlugin plugin )

void

add_node_3d_gizmo_plugin ( EditorNode3DGizmoPlugin plugin )

void

add_resource_conversion_plugin ( EditorResourceConversionPlugin plugin )

void

add_scene_format_importer_plugin ( EditorSceneFormatImporter scene_format_importer, bool first_priority=false )

void

add_scene_post_import_plugin ( EditorScenePostImportPlugin scene_import_plugin, bool first_priority=false )

void

add_tool_menu_item ( String name, Callable callable )

void

add_tool_submenu_item ( String name, PopupMenu submenu )

void

add_translation_parser_plugin ( EditorTranslationParserPlugin parser )

void

add_undo_redo_inspector_hook_callback ( Callable callable )

EditorInterface

get_editor_interface ( )

PopupMenu

get_export_as_menu ( )

String

get_plugin_version ( ) const

ScriptCreateDialog

get_script_create_dialog ( )

EditorUndoRedoManager

get_undo_redo ( )

void

hide_bottom_panel ( )

void

make_bottom_panel_item_visible ( Control item )

void

queue_save_layout ( )

void

remove_autoload_singleton ( String name )

void

remove_control_from_bottom_panel ( Control control )

void

remove_control_from_container ( CustomControlContainer container, Control control )

void

remove_control_from_docks ( Control control )

void

remove_custom_type ( String type )

void

remove_debugger_plugin ( EditorDebuggerPlugin script )

void

remove_export_plugin ( EditorExportPlugin plugin )

void

remove_import_plugin ( EditorImportPlugin importer )

void

remove_inspector_plugin ( EditorInspectorPlugin plugin )

void

remove_node_3d_gizmo_plugin ( EditorNode3DGizmoPlugin plugin )

void

remove_resource_conversion_plugin ( EditorResourceConversionPlugin plugin )

void

remove_scene_format_importer_plugin ( EditorSceneFormatImporter scene_format_importer )

void

remove_scene_post_import_plugin ( EditorScenePostImportPlugin scene_import_plugin )

void

remove_tool_menu_item ( String name )

void

remove_translation_parser_plugin ( EditorTranslationParserPlugin parser )

void

remove_undo_redo_inspector_hook_callback ( Callable callable )

void

set_force_draw_over_forwarding_enabled ( )

void

set_input_event_forwarding_always_enabled ( )

int

update_overlays ( ) const


信号

main_screen_changed ( String screen_name )

当用户改变工作空间(2D3DScriptAssetLib)时发出。也适用于由插件定义的自定义屏幕。


project_settings_changed ( )

当任意项目设置发生改变时发出。

已废弃。请改用 ProjectSettings.settings_changed


resource_saved ( Resource resource )

给定的资源 resource 保存到磁盘时发出。


scene_changed ( Node scene_root )

在编辑器中更改场景时发出。该参数将返回刚刚变为活动状态的场景的根节点。如果此场景是新场景且为空,则参数将为 null


scene_closed ( String filepath )

当用户关闭场景时发出。参数是关闭的场景的文件路径。


枚举

enum CustomControlContainer:

CustomControlContainer CONTAINER_TOOLBAR = 0

主编辑器的工具栏,旁边是运行按钮。

CustomControlContainer CONTAINER_SPATIAL_EDITOR_MENU = 1

3D 编辑器处于活动状态时出现的工具栏。

CustomControlContainer CONTAINER_SPATIAL_EDITOR_SIDE_LEFT = 2

3D 编辑器的左侧边栏。

CustomControlContainer CONTAINER_SPATIAL_EDITOR_SIDE_RIGHT = 3

3D 编辑器的右侧边栏。

CustomControlContainer CONTAINER_SPATIAL_EDITOR_BOTTOM = 4

3D 编辑器的底部面板。

CustomControlContainer CONTAINER_CANVAS_EDITOR_MENU = 5

2D 编辑器处于活动状态时出现的工具条。

CustomControlContainer CONTAINER_CANVAS_EDITOR_SIDE_LEFT = 6

2D 编辑器的左侧边栏。

CustomControlContainer CONTAINER_CANVAS_EDITOR_SIDE_RIGHT = 7

2D 编辑器的右侧边栏。

CustomControlContainer CONTAINER_CANVAS_EDITOR_BOTTOM = 8

2D 编辑器的底部面板。

CustomControlContainer CONTAINER_INSPECTOR_BOTTOM = 9

检查器的底部。

CustomControlContainer CONTAINER_PROJECT_SETTING_TAB_LEFT = 10

项目设置对话框中的选项卡,在其他选项卡的左侧。

CustomControlContainer CONTAINER_PROJECT_SETTING_TAB_RIGHT = 11

项目设置对话框中的选项卡,在其他选项卡的右侧。


enum DockSlot:

DockSlot DOCK_SLOT_LEFT_UL = 0

左侧停靠槽的左上(默认布局中为空)。

DockSlot DOCK_SLOT_LEFT_BL = 1

左侧停靠槽的左下(默认布局中为空)。

DockSlot DOCK_SLOT_LEFT_UR = 2

左侧停靠槽的右上(默认布局中为“场景”和“导入”面板)。

DockSlot DOCK_SLOT_LEFT_BR = 3

左侧停靠槽的右下(默认布局中为“文件系统”面板)。

DockSlot DOCK_SLOT_RIGHT_UL = 4

右侧停靠槽的左上(默认布局中为“检查器”“节点”以及“历史”面板)。

DockSlot DOCK_SLOT_RIGHT_BL = 5

右侧停靠槽的左下(默认布局中为空)。

DockSlot DOCK_SLOT_RIGHT_UR = 6

右侧停靠槽的右上(默认布局中为空)。

DockSlot DOCK_SLOT_RIGHT_BR = 7

右侧停靠槽的右下(默认布局中为空)。

DockSlot DOCK_SLOT_MAX = 8

代表 DockSlot 枚举的大小。


enum AfterGUIInput:

AfterGUIInput AFTER_GUI_INPUT_PASS = 0

将该 InputEvent 转发给其他 EditorPlugin。

AfterGUIInput AFTER_GUI_INPUT_STOP = 1

阻止该 InputEvent 到达其他 Editor 类。

AfterGUIInput AFTER_GUI_INPUT_CUSTOM = 2

将该 InputEvent 传递给除主 Node3D 插件之外的其他编辑器插件。这可用于防止节点选择更改并且改为使用子小工具。


方法说明

void _apply_changes ( ) virtual

当编辑器将要进行保存项目、切换选项卡等操作时,将调用该方法。它要求插件应用所有暂挂的状态更改以确保一致性。

例如,在着色器编辑器中使用它来使插件将用户编写的着色代码应用于对象。


bool _build ( ) virtual

该方法在编辑器即将运行项目时被调用。这样,插件可以在项目运行之前,执行所需的操作。

该方法必须返回一个布尔值。如果该方法返回 false,则项目将不会运行。运行会立即中止,因此这也会阻止运行所有其他插件的 _build 方法。


void _clear ( ) virtual

清除所有状态,并将正在编辑的对象重置为零。这可确保你的插件不会继续编辑当前存在的节点或来自错误场景的节点。


void _disable_plugin ( ) virtual

当用户在项目设置窗口的插件选项卡中禁用 EditorPlugin 时,由引擎调用。


void _edit ( Object object ) virtual

该函数用于编辑特定对象类型(节点或资源)的插件。它请求编辑器编辑给定的对象。

如果该插件刚刚正在编辑一个对象,且它不想再处理任何选定的对象,则 object 可以为 null。这可用于清理编辑状态。


void _enable_plugin ( ) virtual

当用户在项目设置窗口的插件选项卡中启用该 EditorPlugin 时,由引擎调用。


void _forward_3d_draw_over_viewport ( Control viewport_control ) virtual

当 3D 编辑器的视口更新时由引擎调用。将 overlay Control 用于绘制。可以通过调用 update_overlays 手动更新该视口。

func _forward_3d_draw_over_viewport(overlay):
    # 在光标位置画一个圆。
    overlay.draw_circle(overlay.get_local_mouse_position(), 64)

func _forward_3d_gui_input(camera, event):
    if event is InputEventMouseMotion:
        # 当光标被移动时,重绘视口。
        update_overlays()
        return EditorPlugin.AFTER_GUI_INPUT_STOP
    return EditorPlugin.AFTER_GUI_INPUT_PASS

void _forward_3d_force_draw_over_viewport ( Control viewport_control ) virtual

该方法与 _forward_3d_draw_over_viewport 相同,只是它绘制在所有内容之上。当需要一个显示在其他任何内容之上的额外图层时很有用。

需要使用 set_force_draw_over_forwarding_enabled 来启用该方法的调用。


int _forward_3d_gui_input ( Camera3D viewport_camera, InputEvent event ) virtual

在当前编辑的场景中有根节点时调用,实现 _handles 并在 3D 视口中产生 InputEvent。返回值决定 InputEvent 是被消费还是被转发给其他 EditorPlugin。有关选项,请参阅 AfterGUIInput

示例:

# 阻止 InputEvent 到达其他编辑类。
func _forward_3d_gui_input(camera, event):
    return EditorPlugin.AFTER_GUI_INPUT_STOP

必须为 return EditorPlugin.AFTER_GUI_INPUT_PASS 以便将 InputEvent 转发给其他编辑器类。

示例:

# 消耗 InputEventMouseMotion 并转发其他 InputEvent 类型。
func _forward_3d_gui_input(camera, event):
    return EditorPlugin.AFTER_GUI_INPUT_STOP if event is InputEventMouseMotion else EditorPlugin.AFTER_GUI_INPUT_PASS

void _forward_canvas_draw_over_viewport ( Control viewport_control ) virtual

当 2D 编辑器的视口更新时由引擎调用。将 overlay Control 用于绘制。可以通过调用 update_overlays 手动更新该视口。

func _forward_canvas_draw_over_viewport(overlay):
    # 在光标位置画一个圆。
    overlay.draw_circle(overlay.get_local_mouse_position(), 64, Color.WHITE)

func _forward_canvas_gui_input(event):
    if event is InputEventMouseMotion:
        # 当光标被移动时,重绘视口。
        update_overlays()
        return true
    return false

void _forward_canvas_force_draw_over_viewport ( Control viewport_control ) virtual

该方法与 _forward_canvas_draw_over_viewport 相同,只是它绘制在所有内容之上。当需要一个显示在其他任何内容之上的额外图层时很有用。

需要使用 set_force_draw_over_forwarding_enabled 来启用该方法的调用。


bool _forward_canvas_gui_input ( InputEvent event ) virtual

在当前编辑的场景中有根节点时调用,实现 _handles 并在 2D 视口中产生 InputEvent。如果 return true EditorPlugin 消耗 event,则拦截该 InputEvent;否则将 event 转发给其他编辑器类。

示例:

# 阻止 InputEvent 到达其他编辑类。
func _forward_canvas_gui_input(event):
    return true

必须 return false 才能将 InputEvent 转发到其他编辑器类。

示例:

# 消耗 InputEventMouseMotion 并转发其他 InputEvent 类型。
func _forward_canvas_gui_input(event):
    if (event is InputEventMouseMotion):
        return true
    return false

PackedStringArray _get_breakpoints ( ) virtual const

该函数用于编辑基于脚本的对象的编辑器。可以返回格式为(script:line)的断点的列表,例如:res://path_to_script.gd:25


Texture2D _get_plugin_icon ( ) virtual const

在插件中覆盖该方法,以返回一个 Texture2D 以便为插件提供一个图标。

对于主界面插件,它出现在屏幕顶部,“2D”、“3D”、“脚本”和 “AssetLib” 按钮的右侧。

理想情况下,插件图标应为透明背景的白色,大小为 16x16 像素。

func _get_plugin_icon():
    # 你可以使用一个自定义的图标:
    return preload("res://addons/my_plugin/my_plugin_icon.svg")
    # 或者使用一个内置的图标:
    return EditorInterface.get_editor_theme().get_icon("Node", "EditorIcons")

String _get_plugin_name ( ) virtual const

在插件中覆盖该方法,以在 Godot 编辑器中显示时提供该插件的名称。

对于主屏幕插件,它显示在屏幕顶部,在“2D”“3D”“脚本”“AssetLib”按钮的右侧。


Dictionary _get_state ( ) virtual const

覆盖该方法,以提供要保存的状态数据,如视图位置、网格设置、折叠等。这可用于保存场景(再次打开时,保持状态)和切换选项卡( 选项卡返回时,可以恢复状态)。每个场景的数据会自动被保存在编辑器元数据文件夹中的 editstate 文件中。如果想为插件存储全局的(独立于场景的)编辑器数据,可以改用 _get_window_layout

使用 _set_state 恢复保存的状态。

注意:此方法不应该用于保存应随项目保留的重要设置。

注意:必须实现 _get_plugin_name,才能正确存储和恢复状态。

func _get_state():
    var state = {"zoom": zoom, "preferred_color": my_color}
    return state

String _get_unsaved_status ( String for_scene ) virtual const

覆盖该方法以提供列出未保存更改的自定义消息。编辑器将在退出或关闭场景时调用该方法,并在确认对话框中显示返回的字符串。如果该插件没有未保存的更改,则返回空字符串。

关闭场景时,for_scene 是正在关闭的场景的路径。你可以使用它来处理该场景中的内置资源。

如果用户确认保存,将在关闭编辑器之前将调用 _save_external_data

func _get_unsaved_status(for_scene):
    if not unsaved:
        return ""

    if for_scene.is_empty():
        return "Save changes in MyCustomPlugin before closing?"
    else:
        return "Scene %s has changes from MyCustomPlugin. Save before closing?" % for_scene.get_file()

func _save_external_data():
    unsaved = false

如果该插件没有特定于场景的更改,则可以在关闭场景时忽略这些调用:

func _get_unsaved_status(for_scene):
    if not for_scene.is_empty():
        return ""

void _get_window_layout ( ConfigFile configuration ) virtual

覆盖该方法,以提供该插件的 GUI 布局、或想要存储的任何其他数据。这用于在调用 queue_save_layout、或更改编辑器布局(例如更改停靠面板的位置)时,保存项目的编辑器布局。数据被存储在编辑器元数据目录中的 editor_layout.cfg 文件中。

使用 _set_window_layout 恢复保存的布局。

func _get_window_layout(configuration):
    configuration.set_value("MyPlugin", "window_position", $Window.position)
    configuration.set_value("MyPlugin", "icon_color", $Icon.modulate)

bool _handles ( Object object ) virtual const

如果插件会编辑特定类型的对象(资源或节点),则请实现该函数。如果返回 true,则将在编辑器请求时,调用函数 _edit_make_visible。如果已经声明了方法 _forward_canvas_gui_input_forward_3d_gui_input,则它们也会被调用。

注意:每个插件一次只应处理一种类型的对象。如果一个插件处理多种类型的对象并且同时编辑这些对象,则会导致错误。


bool _has_main_screen ( ) virtual const

如果这是一个主屏幕编辑器插件,则返回 true(它与 2D3DScriptAssetLib 一起进入工作区选择器)。

当该插件的工作区被选中时,其他主屏幕插件将被隐藏,但你的插件不会自动出现。它需要被添加为 EditorInterface.get_base_control 的子节点,并在 _make_visible 中使其可见。

使用 _get_plugin_name_get_plugin_icon 自定义插件按钮的外观。

var plugin_control

func _enter_tree():
    plugin_control = preload("my_plugin_control.tscn").instantiate()
    EditorInterface.get_editor_main_screen().add_child(plugin_control)
    plugin_control.hide()

func _has_main_screen():
    return true

func _make_visible(visible):
    plugin_control.visible = visible

func _get_plugin_name():
    return "My Super Cool Plugin 3000"

func _get_plugin_icon():
    return EditorInterface.get_editor_theme().get_icon("Node", "EditorIcons")

void _make_visible ( bool visible ) virtual

当编辑器被要求变为可见时,该函数将被调用。它用于编辑特定对象类型的插件。

请记住,你必须手动管理所有编辑器控件的可见性。


void _save_external_data ( ) virtual

这个方法在编辑器保存项目后或关闭项目时被调用,它要求插件保存编辑的外部场景/资源。


void _set_state ( Dictionary state ) virtual

恢复用 _get_state 保存的状态。这个方法会在编辑器的当前场景选项卡发生改变时调用。

注意:你的插件必须实现 _get_plugin_name,否则无法被识别,这个方法也不会被调用。

func _set_state(data):
    zoom = data.get("zoom", 1.0)
    preferred_color = data.get("my_color", Color.WHITE)

void _set_window_layout ( ConfigFile configuration ) virtual

恢复用 _get_window_layout 保存的插件 GUI 布局和数据。编辑器启动时会调用每个插件的这个方法。请使用提供的 configuration 文件读取你保存的数据。

func _set_window_layout(configuration):
    $Window.position = configuration.get_value("MyPlugin", "window_position", Vector2())
    $Icon.modulate = configuration.get_value("MyPlugin", "icon_color", Color.WHITE)

void add_autoload_singleton ( String name, String path )

path 处的脚本作为 name 添加到自动加载列表中。


Button add_control_to_bottom_panel ( Control control, String title )

将控件添加到底部面板(包含“输出”“调试”“动画”等)。返回对添加的按钮的引用。可以根据需要隐藏/显示按钮。停用插件后,请确保使用 remove_control_from_bottom_panel 移除自定义控件,并使用 Node.queue_free 将其释放。


void add_control_to_container ( CustomControlContainer container,