EditorPlugin

Inherits: Node < Object

Used by the editor to extend its functionality.

Description

Plugins are used by the editor to extend functionality. The most common types of plugins are those which edit a given node or resource type, import plugins and export plugins. See also EditorScript to add functions to the editor.

Tutorials

Methods

void

_apply_changes ( ) virtual

bool

_build ( ) virtual

void

_clear ( ) virtual

void

_disable_plugin ( ) virtual

void

_edit ( Variant 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

bool

_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

void

_get_window_layout ( ConfigFile configuration ) virtual

bool

_handles ( Variant 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 ( Script script )

void

add_export_plugin ( EditorExportPlugin plugin )

void

add_import_plugin ( EditorImportPlugin importer )

void

add_inspector_plugin ( EditorInspectorPlugin plugin )

void

add_scene_import_plugin ( EditorSceneImporter scene_importer )

void

add_spatial_gizmo_plugin ( EditorNode3DGizmoPlugin plugin )

void

add_tool_menu_item ( String name, Callable callable )

void

add_tool_submenu_item ( String name, Object submenu )

void

add_translation_parser_plugin ( EditorTranslationParserPlugin parser )

void

add_undo_redo_inspector_hook_callback ( Callable callable )

EditorInterface

get_editor_interface ( )

ScriptCreateDialog

get_script_create_dialog ( )

UndoRedo

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 ( Script script )

void

remove_export_plugin ( EditorExportPlugin plugin )

void

remove_import_plugin ( EditorImportPlugin importer )

void

remove_inspector_plugin ( EditorInspectorPlugin plugin )

void

remove_scene_import_plugin ( EditorSceneImporter scene_importer )

void

remove_spatial_gizmo_plugin ( EditorNode3DGizmoPlugin 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

Signals

  • main_screen_changed ( String screen_name )

Emitted when user changes the workspace (2D, 3D, Script, AssetLib). Also works with custom screens defined by plugins.


  • project_settings_changed ( )



  • scene_changed ( Node scene_root )

Emitted when the scene is changed in the editor. The argument will return the root node of the scene that has just become active. If this scene is new and empty, the argument will be null.


  • scene_closed ( String filepath )

Emitted when user closes a scene. The argument is file path to a closed scene.

Enumerations

enum CustomControlContainer:

  • CONTAINER_TOOLBAR = 0

  • CONTAINER_SPATIAL_EDITOR_MENU = 1

  • CONTAINER_SPATIAL_EDITOR_SIDE_LEFT = 2

  • CONTAINER_SPATIAL_EDITOR_SIDE_RIGHT = 3

  • CONTAINER_SPATIAL_EDITOR_BOTTOM = 4

  • CONTAINER_CANVAS_EDITOR_MENU = 5

  • CONTAINER_CANVAS_EDITOR_SIDE_LEFT = 6

  • CONTAINER_CANVAS_EDITOR_SIDE_RIGHT = 7

  • CONTAINER_CANVAS_EDITOR_BOTTOM = 8

  • CONTAINER_PROPERTY_EDITOR_BOTTOM = 9

  • CONTAINER_PROJECT_SETTING_TAB_LEFT = 10

  • CONTAINER_PROJECT_SETTING_TAB_RIGHT = 11


enum DockSlot:

  • DOCK_SLOT_LEFT_UL = 0

  • DOCK_SLOT_LEFT_BL = 1

  • DOCK_SLOT_LEFT_UR = 2

  • DOCK_SLOT_LEFT_BR = 3

  • DOCK_SLOT_RIGHT_UL = 4

  • DOCK_SLOT_RIGHT_BL = 5

  • DOCK_SLOT_RIGHT_UR = 6

  • DOCK_SLOT_RIGHT_BR = 7

  • DOCK_SLOT_MAX = 8 --- Represents the size of the DockSlot enum.

Method Descriptions

  • void _apply_changes ( ) virtual

This method is called when the editor is about to save the project, switch to another tab, etc. It asks the plugin to apply any pending state changes to ensure consistency.

This is used, for example, in shader editors to let the plugin know that it must apply the shader code being written by the user to the object.


  • bool _build ( ) virtual

This method is called when the editor is about to run the project. The plugin can then perform required operations before the project runs.

This method must return a boolean. If this method returns false, the project will not run. The run is aborted immediately, so this also prevents all other plugins' _build methods from running.


  • void _clear ( ) virtual

Clear all the state and reset the object being edited to zero. This ensures your plugin does not keep editing a currently existing node, or a node from the wrong scene.


  • void _disable_plugin ( ) virtual

Called by the engine when the user disables the EditorPlugin in the Plugin tab of the project settings window.


  • void _edit ( Variant object ) virtual

This function is used for plugins that edit specific object types (nodes or resources). It requests the editor to edit the given object.


  • void _enable_plugin ( ) virtual

Called by the engine when the user enables the EditorPlugin in the Plugin tab of the project settings window.


  • void _forward_3d_draw_over_viewport ( Control viewport_control ) virtual

Called by the engine when the 3D editor's viewport is updated. Use the overlay Control for drawing. You can update the viewport manually by calling update_overlays.

func _forward_3d_draw_over_viewport(overlay):
    # Draw a circle at cursor position.
    overlay.draw_circle(overlay.get_local_mouse_position(), 64)

func _forward_3d_gui_input(camera, event):
    if event is InputEventMouseMotion:
        # Redraw viewport when cursor is moved.
        update_overlays()
        return true
    return false

  • void _forward_3d_force_draw_over_viewport ( Control viewport_control ) virtual

This method is the same as _forward_3d_draw_over_viewport, except it draws on top of everything. Useful when you need an extra layer that shows over anything else.

You need to enable calling of this method by using set_force_draw_over_forwarding_enabled.


Called when there is a root node in the current edited scene, _handles is implemented and an InputEvent happens in the 3D viewport. Intercepts the InputEvent, if return true EditorPlugin consumes the event, otherwise forwards event to other Editor classes. Example:

# Prevents the InputEvent to reach other Editor classes.
func _forward_3d_gui_input(camera, event):
    return true

Must return false in order to forward the InputEvent to other Editor classes. Example:

# Consumes InputEventMouseMotion and forwards other InputEvent types.
func _forward_3d_gui_input(camera, event):
    return event is InputEventMouseMotion

  • void _forward_canvas_draw_over_viewport ( Control viewport_control ) virtual

Called by the engine when the 2D editor's viewport is updated. Use the overlay Control for drawing. You can update the viewport manually by calling update_overlays.

func _forward_canvas_draw_over_viewport(overlay):
    # Draw a circle at cursor position.
    overlay.draw_circle(overlay.get_local_mouse_position(), 64, Color.white)

func _forward_canvas_gui_input(event):
    if event is InputEventMouseMotion:
        # Redraw viewport when cursor is moved.
        update_overlays()
        return true
    return false

  • void _forward_canvas_force_draw_over_viewport ( Control viewport_control ) virtual

This method is the same as _forward_canvas_draw_over_viewport, except it draws on top of everything. Useful when you need an extra layer that shows over anything else.

You need to enable calling of this method by using set_force_draw_over_forwarding_enabled.


Called when there is a root node in the current edited scene, _handles is implemented and an InputEvent happens in the 2D viewport. Intercepts the InputEvent, if return true EditorPlugin consumes the event, otherwise forwards event to other Editor classes. Example:

# Prevents the InputEvent to reach other Editor classes
func _forward_canvas_gui_input(event):
    return true

Must return false in order to forward the InputEvent to other Editor classes. Example:

# Consumes InputEventMouseMotion and forwards other InputEvent types.
func _forward_canvas_gui_input(event):
    return event is InputEventMouseMotion

This is for editors that edit script-based objects. You can return a list of breakpoints in the format (script:line), for example: res://path_to_script.gd:25.


  • Texture2D _get_plugin_icon ( ) virtual const

Override this method in your plugin to return a Texture2D in order to give it an icon.

For main screen plugins, this appears at the top of the screen, to the right of the "2D", "3D", "Script", and "AssetLib" buttons.

Ideally, the plugin icon should be white with a transparent background and 16x16 pixels in size.

func _get_plugin_icon():
    # You can use a custom icon:
    return preload("res://addons/my_plugin/my_plugin_icon.svg")
    # Or use a built-in icon:
    return get_editor_interface().get_base_control().get_icon("Node", "EditorIcons")

  • String _get_plugin_name ( ) virtual const

Override this method in your plugin to provide the name of the plugin when displayed in the Godot editor.

For main screen plugins, this appears at the top of the screen, to the right of the "2D", "3D", "Script", and "AssetLib" buttons.


Gets the state of your plugin editor. This is used when saving the scene (so state is kept when opening it again) and for switching tabs (so state can be restored when the tab returns).


  • void _get_window_layout ( ConfigFile configuration ) virtual

Gets the GUI layout of the plugin. This is used to save the project's editor layout when queue_save_layout is called or the editor layout was changed(For example changing the position of a dock).


Implement this function if your plugin edits a specific type of object (Resource or Node). If you return true, then you will get the functions _edit and _make_visible called when the editor requests them. If you have declared the methods _forward_canvas_gui_input and _forward_3d_gui_input these will be called too.


  • bool _has_main_screen ( ) virtual const

Returns true if this is a main screen editor plugin (it goes in the workspace selector together with 2D, 3D, Script and AssetLib).


  • void _make_visible ( bool visible ) virtual

This function will be called when the editor is requested to become visible. It is used for plugins that edit a specific object type.

Remember that you have to manage the visibility of all your editor controls manually.


  • void _save_external_data ( ) virtual

This method is called after the editor saves the project or when it's closed. It asks the plugin to save edited external scenes/resources.


Restore the state saved by _get_state.


  • void _set_window_layout ( ConfigFile configuration ) virtual

Restore the plugin GUI layout saved by _get_window_layout.


Adds a script at path to the Autoload list as name.


Adds a control to the bottom panel (together with Output, Debug, Animation, etc). Returns a reference to the button added. It's up to you to hide/show the button when needed. When your plugin is deactivated, make sure to remove your custom control with remove_control_from_bottom_panel and free it with Node.queue_free.


Adds a custom control to a container (see CustomControlContainer). There are many locations where custom controls can be added in the editor UI.

Please remember that you have to manage the visibility of your custom controls yourself (and likely hide it after adding it).

When your plugin is deactivated, make sure to remove your custom control with remove_control_from_container and free it with Node.queue_free.


Adds the control to a specific dock slot (see DockSlot for options).

If the dock is repositioned and as long as the plugin is active, the editor will save the dock position on further sessions.

When your plugin is deactivated, make sure to remove your custom control with remove_control_from_docks and free it with Node.queue_free.


Adds a custom type, which will appear in the list of nodes or resources. An icon can be optionally passed.

When a given node or resource is selected, the base type will be instantiated (e.g. "Node3D", "Control", "Resource"), then the script will be loaded and set to this object.

You can use the virtual method _handles to check if your custom object is being edited by checking the script or using the is keyword.

During run-time, this will be a simple object with a script so this function does not need to be called then.


  • void add_debugger_plugin ( Script script )

Adds a Script as debugger plugin to the Debugger. The script must extend EditorDebuggerPlugin.


Registers a new EditorExportPlugin. Export plugins are used to perform tasks when the project is being exported.

See add_inspector_plugin for an example of how to register a plugin.


Registers a new EditorImportPlugin. Import plugins are used to import custom and unsupported assets as a custom Resource type.

Note: If you want to import custom 3D asset formats use add_scene_import_plugin instead.

See add_inspector_plugin for an example of how to register a plugin.


Registers a new EditorInspectorPlugin. Inspector plugins are used to extend EditorInspector and provide custom configuration tools for your object's properties.

Note: Always use remove_inspector_plugin to remove the registered EditorInspectorPlugin when your EditorPlugin is disabled to prevent leaks and an unexpected behavior.

const MyInspectorPlugin = preload("res://addons/your_addon/path/to/your/script.gd")
var inspector_plugin = MyInspectorPlugin.new()

func _enter_tree():
    add_inspector_plugin(inspector_plugin)

func _exit_tree():
    remove_inspector_plugin(inspector_plugin)

Registers a new EditorSceneImporter. Scene importers are used to import custom 3D asset formats as scenes.


Registers a new EditorNode3DGizmoPlugin. Gizmo plugins are used to add custom gizmos to the 3D preview viewport for a Node3D.

See add_inspector_plugin for an example of how to register a plugin.


Adds a custom menu item to Project > Tools named name. When clicked, the provided callable will be called.


  • void add_tool_submenu_item ( String name, Object submenu )

Adds a custom submenu under Project > Tools > name. submenu should be an object of class PopupMenu. Use remove_tool_menu_item(name) on plugin clean up to remove the menu.


Registers a custom translation parser plugin for extracting translatable strings from custom files.


  • void add_undo_redo_inspector_hook_callback ( Callable callable )

Hooks a callback into the undo/redo action creation when a property is modified in the inspector. This allows, for example, to save other properties that may be lost when a given property is modified.

The callback should have 4 arguments: Object undo_redo, Object modified_object, String property and Variant new_value. They are, respectively, the UndoRedo object used by the inspector, the currently modified object, the name of the modified property and the new value the property is about to take.


Returns the EditorInterface object that gives you control over Godot editor's window and its functionalities.


Gets the Editor's dialogue used for making scripts.

Note: Users can configure it before use.


Gets the undo/redo object. Most actions in the editor can be undoable, so use this object to make sure this happens when it's worth it.


  • void hide_bottom_panel ( )

Minimizes the bottom panel.


  • void make_bottom_panel_item_visible ( Control item )

Makes a specific item in the bottom panel visible.


  • void queue_save_layout ( )

Queue save the project's editor layout.


  • void remove_autoload_singleton ( String name )

Removes an Autoload name from the list.


  • void remove_control_from_bottom_panel ( Control control )

Removes the control from the bottom panel. You have to manually Node.queue_free the control.


Removes the control from the specified container. You have to manually Node.queue_free the control.


  • void remove_control_from_docks ( Control control )

Removes the control from the dock. You have to manually Node.queue_free the control.


  • void remove_custom_type ( String type )

Removes a custom type added by add_custom_type.


  • void remove_debugger_plugin ( Script script )

Removes the debugger plugin with given script from the Debugger.


Removes an export plugin registered by add_export_plugin.


Removes an import plugin registered by add_import_plugin.


Removes an inspector plugin registered by add_import_plugin


Removes a scene importer registered by add_scene_import_plugin.


Removes a gizmo plugin registered by add_spatial_gizmo_plugin.


  • void remove_tool_menu_item ( String name )

Removes a menu name from Project > Tools.


Removes a custom translation parser plugin registered by add_translation_parser_plugin.


  • void remove_undo_redo_inspector_hook_callback ( Callable callable )

Removes a callback previsously added by add_undo_redo_inspector_hook_callback.


  • void set_force_draw_over_forwarding_enabled ( )

Enables calling of _forward_canvas_force_draw_over_viewport for the 2D editor and _forward_3d_force_draw_over_viewport for the 3D editor when their viewports are updated. You need to call this method only once and it will work permanently for this plugin.


  • void set_input_event_forwarding_always_enabled ( )

Use this method if you always want to receive inputs from 3D view screen inside _forward_3d_gui_input. It might be especially usable if your plugin will want to use raycast in the scene.


  • int update_overlays ( ) const

Updates the overlays of the 2D and 3D editor viewport. Causes methods _forward_canvas_draw_over_viewport, _forward_canvas_force_draw_over_viewport, _forward_3d_draw_over_viewport and _forward_3d_force_draw_over_viewport to be called.