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...
EditorPlugin¶
由编辑器使用，用于扩展其功能。
描述¶
编辑器使用插件来扩展功能。最常见的插件类型是编辑给定的节点或资源类型的插件、导入插件和导出插件。另见 EditorScript，能够向编辑器添加功能。
注意：这个类中的部分名称中包含“left”和“right”（例如 DOCK_SLOT_LEFT_UL）。这些 API 假设的是从左至右的布局，使用从右至左布局时是反的。保留这些名称是出于兼容的原因。
教程¶
方法¶
信号¶
main_screen_changed ( String screen_name )
当用户改变工作空间（2D、3D、Script、AssetLib）时发出。也适用于由插件定义的自定义屏幕。
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
主编辑器的工具栏，旁边是运行按钮。
3D 编辑器处于活动状态时出现的工具栏。
CustomControlContainer CONTAINER_SPATIAL_EDITOR_SIDE_LEFT = 2
3D 编辑器的左侧边栏。
CustomControlContainer CONTAINER_SPATIAL_EDITOR_SIDE_RIGHT = 3
3D 编辑器的右侧边栏。
CustomControlContainer CONTAINER_SPATIAL_EDITOR_BOTTOM = 4
3D 编辑器的底部面板。
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
public override void _Forward3DDrawOverViewport(Control viewportControl)
{
// 在光标位置画一个圆。
viewportControl.DrawCircle(viewportControl.GetLocalMousePosition(), 64, Colors.White);
}
public override EditorPlugin.AfterGuiInput _Forward3DGuiInput(Camera3D viewportCamera, InputEvent @event)
{
if (@event is InputEventMouseMotion)
{
// 当光标被移动时，重绘视口。
UpdateOverlays();
return EditorPlugin.AfterGuiInput.Stop;
}
return EditorPlugin.AfterGuiInput.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
// 阻止 InputEvent 到达其他编辑类。
public override EditorPlugin.AfterGuiInput _Forward3DGuiInput(Camera3D camera, InputEvent @event)
{
return EditorPlugin.AfterGuiInput.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
// 消耗 InputEventMouseMotion 并转发其他 InputEvent 类型。
public override EditorPlugin.AfterGuiInput _Forward3DGuiInput(Camera3D camera, InputEvent @event)
{
return @event is InputEventMouseMotion ? EditorPlugin.AfterGuiInput.Stop : EditorPlugin.AfterGuiInput.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
public override void _ForwardCanvasDrawOverViewport(Control viewportControl)
{
// 在光标位置画一个圆。
viewportControl.DrawCircle(viewportControl.GetLocalMousePosition(), 64, Colors.White);
}
public override bool _ForwardCanvasGuiInput(InputEvent @event)
{
if (@event is InputEventMouseMotion)
{
// 当光标被移动时，重绘视口。
UpdateOverlays();
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
// 阻止 InputEvent 到达其他编辑类。
public override bool ForwardCanvasGuiInput(InputEvent @event)
{
return true;
}
必须 return false 才能将 InputEvent 转发到其他编辑器类。
示例：
# 消耗 InputEventMouseMotion 并转发其他 InputEvent 类型。
func _forward_canvas_gui_input(event):
if (event is InputEventMouseMotion):
return true
return false
// 消耗 InputEventMouseMotion 并转发其他 InputEvent 类型。
public override bool _ForwardCanvasGuiInput(InputEvent @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")
public override Texture2D _GetPluginIcon()
{
// 你可以使用一个自定义的图标：
return ResourceLoader.Load<Texture2D>("res://addons/my_plugin/my_plugin_icon.svg");
// 或者使用一个内置的图标：
return EditorInterface.Singleton.GetEditorTheme().GetIcon("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（它与 2D、3D、Script 和 AssetLib 一起进入工作区选择器）。
当该插件的工作区被选中时，其他主屏幕插件将被隐藏，但你的插件不会自动出现。它需要被添加为 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 移除自定义控件，并使用