EditorPlugin

Inherits: Node < Object Used by the editor to extend its functionality.

Description

EditorScript to add functions to the editor.

Tutorials

  • Editor plugins

    Methods

    Signals

  • main_screen_changed ( String screen_name ) 2D, 3D, Script, AssetLib). Also works with custom screens defined by plugins.

- resource_saved ( Resource resource )

  • scene_changed ( Node scene_root ) null.
  • scene_closed ( String filepath ) Emitted when user closes a scene. The argument is file path to a closed scene.

    Enumerations

    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

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

  • add_autoload_singleton ( String name, String path ) path to the Autoload list as name.
  • ToolButton add_control_to_bottom_panel ( Control control, String title ) remove_control_from_bottom_panel and free it with Node.queue_free.
  • add_control_to_container ( CustomControlContainer container, Control control ) 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). remove_control_from_container and free it with Node.queue_free.
  • add_control_to_dock ( DockSlot slot, Control control ) 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. remove_control_from_docks and free it with Node.queue_free.
  • add_custom_type ( String type, String base, Script script, Texture icon ) Adds a custom type, which will appear in the list of nodes or resources. An icon can be optionally passed. When given node or resource is selected, the base type will be instanced (ie, “Spatial”, “Control”, “Resource”), then the script will be loaded and set to this object. 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.
  • add_export_plugin ( EditorExportPlugin plugin ) EditorExportPlugin. Export plugins are used to perform tasks when the project is being exported. add_inspector_plugin for an example of how to register a plugin.
  • add_import_plugin ( EditorImportPlugin importer ) 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. add_inspector_plugin for an example of how to register a plugin.
  • add_inspector_plugin ( EditorInspectorPlugin plugin ) 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.
    1. 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)
  • add_scene_import_plugin ( EditorSceneImporter scene_importer ) EditorSceneImporter. Scene importers are used to import custom 3D asset formats as scenes.
  • add_spatial_gizmo_plugin ( EditorSpatialGizmoPlugin plugin ) EditorSpatialGizmoPlugin. Gizmo plugins are used to add custom gizmos to the 3D preview viewport for a Spatial. add_inspector_plugin for an example of how to register a plugin.
  • add_tool_menu_item ( String name, Object handler, String callback, Variant ud=null ) Project > Tools as name that calls callback on an instance of handler with a parameter ud when user activates it.
  • add_tool_submenu_item ( String name, Object submenu ) Project > Tools > name. submenu should be an object of class PopupMenu. This submenu should be cleaned up using remove_tool_menu_item(name).
  • 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. false, the project will not run. The run is aborted immediately, so this also prevents all other plugins’ build methods from running.
  • 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.
  • disable_plugin ( ) virtual EditorPlugin in the Plugin tab of the project settings window.
  • edit ( Object 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.
  • enable_plugin ( ) virtual EditorPlugin in the Plugin tab of the project settings window.
  • forward_canvas_draw_over_viewport ( Control overlay ) virtual overlay Control for drawing. You can update the viewport manually by calling update_overlays.
    1. 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
  • forward_canvas_force_draw_over_viewport ( Control overlay ) virtual forward_canvas_draw_over_viewport, except it draws on top of everything. Useful when you need an extra layer that shows over anything else. set_force_draw_over_forwarding_enabled.
  • bool forward_canvas_gui_input ( InputEvent event ) virtual 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:
    1. # Prevents the InputEvent to reach other Editor classesfunc forward_canvas_gui_input(event):    var forward = true    return forward
    return false in order to forward the InputEvent to other Editor classes. Example:
    1. # Consumes InputEventMouseMotion and forwards other InputEvent typesfunc forward_canvas_gui_input(event):    var forward = false    if event is InputEventMouseMotion:        forward = true    return forward
  • forward_spatial_draw_over_viewport ( Control overlay ) virtual overlay Control for drawing. You can update the viewport manually by calling update_overlays.
    1. func forward_spatial_draw_over_viewport(overlay):    # Draw a circle at cursor position.    overlay.draw_circle(overlay.get_local_mouse_position(), 64)func forward_spatial_gui_input(camera, event):    if event is InputEventMouseMotion:        # Redraw viewport when cursor is moved.        update_overlays()        return true    return false
  • forward_spatial_force_draw_over_viewport ( Control overlay ) virtual forward_spatial_draw_over_viewport, except it draws on top of everything. Useful when you need an extra layer that shows over anything else. set_force_draw_over_forwarding_enabled.
  • bool forward_spatial_gui_input ( Camera camera, InputEvent event ) virtual 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:
    1. # Prevents the InputEvent to reach other Editor classesfunc forward_spatial_gui_input(camera, event):    var forward = true    return forward
    return false in order to forward the InputEvent to other Editor classes. Example:
    1. # Consumes InputEventMouseMotion and forwards other InputEvent typesfunc forward_spatial_gui_input(camera, event):    var forward = false    if event is InputEventMouseMotion:        forward = true    return forward
  • PoolStringArray get_breakpoints ( ) virtual script:line), for example: res://path_to_script.gd:25.
  • EditorInterface get_editor_interface ( ) EditorInterface object that gives you control over Godot editor’s window and its functionalities.
  • Texture get_plugin_icon ( ) virtual Texture 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.
    1. 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 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.
  • ScriptCreateDialog get_script_create_dialog ( ) Gets the Editor’s dialog used for making scripts. Note: Users can configure it before use. Warning: Removing and freeing this node will render a part of the editor useless and may cause a crash.
  • Dictionary get_state ( ) virtual editstate file in the editor metadata folder. If you want to store global (scene-independent) editor data for your plugin, you can use get_window_layout instead. set_state to restore your saved state. Note: This method should not be used to save important settings that should persist with the project. Note: You must implement get_plugin_name for the state to be stored and restored correctly.
    1. func get_state():    var state = {"zoom": zoom, "preferred_color": my_color}    return state
  • UndoRedo get_undo_redo ( ) 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.
  • get_window_layout ( ConfigFile layout ) virtual queue_save_layout is called or the editor layout was changed (for example changing the position of a dock). The data is stored in the editor_layout.cfg file in the editor metadata directory. set_window_layout to restore your saved layout.
    1. 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 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_spatial_gui_input these will be called too.
  • bool has_main_screen ( ) virtual true if this is a main screen editor plugin (it goes in the workspace selector together with 2D, 3D, Script and AssetLib).
  • hide_bottom_panel ( ) Minimizes the bottom panel.
  • make_bottom_panel_item_visible ( Control item ) Makes a specific item in the bottom panel visible.
  • 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.
  • queue_save_layout ( ) const Queue save the project’s editor layout.
  • remove_autoload_singleton ( String name ) name from the list.
  • remove_control_from_bottom_panel ( Control control ) Node.queue_free the control.
  • remove_control_from_container ( CustomControlContainer container, Control control ) Node.queue_free the control.
  • remove_control_from_docks ( Control control ) Node.queue_free the control.
  • remove_custom_type ( String type ) add_custom_type.
  • remove_export_plugin ( EditorExportPlugin plugin ) add_export_plugin.
  • remove_import_plugin ( EditorImportPlugin importer ) add_import_plugin.
  • remove_inspector_plugin ( EditorInspectorPlugin plugin ) add_import_plugin
  • remove_scene_import_plugin ( EditorSceneImporter scene_importer ) add_scene_import_plugin.
  • remove_spatial_gizmo_plugin ( EditorSpatialGizmoPlugin plugin ) add_spatial_gizmo_plugin.
  • remove_tool_menu_item ( String name ) name from Project > Tools.
  • 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.
  • set_force_draw_over_forwarding_enabled ( ) forward_canvas_force_draw_over_viewport for the 2D editor and forward_spatial_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.
  • set_input_event_forwarding_always_enabled ( ) forward_spatial_gui_input. It might be especially usable if your plugin will want to use raycast in the scene.
  • set_state ( Dictionary state ) virtual get_state. This method is called when the current scene tab is changed in the editor. Note: Your plugin must implement get_plugin_name, otherwise it will not be recognized and this method will not be called.
    1. func set_state(data):    zoom = data.get("zoom", 1.0)    preferred_color = data.get("my_color", Color.white)
  • set_window_layout ( ConfigFile layout ) virtual get_window_layout. This method is called for every plugin on editor startup. Use the provided configuration file to read your saved data.
    1. func set_window_layout(configuration):    $Window.position = configuration.get_value("MyPlugin", "window_position", Vector2())    $Icon.modulate = configuration.get_value("MyPlugin", "icon_color", Color.white)
  • int update_overlays ( ) const forward_canvas_draw_over_viewport, forward_canvas_force_draw_over_viewport, forward_spatial_draw_over_viewport and forward_spatial_force_draw_over_viewport to be called.