Spatial gizmo plugins

    This tutorial will show you the two main approaches to defining your own custom gizmos. The first option works well for simple gizmos and creates less clutter in your plugin structure, while the second one will let you store some per-gizmo data.

    Note

    This tutorial assumes you already know how to make generic plugins. If in doubt, refer to the page.

    Regardless of the approach we choose, we will need to create a new EditorSpatialGizmoPlugin. This will allow us to set a name for the new gizmo type and define other behaviors such as whether the gizmo can be hidden or not.

    2. tool
    3. extends EditorPlugin
    6. const MyCustomGizmoPlugin = preload("res://addons/my-addon/MyCustomGizmoPlugin.gd")
    8. var gizmo_plugin = MyCustomGizmoPlugin.new()
    11. func _enter_tree():
    12.     add_spatial_gizmo_plugin(gizmo_plugin)
    15. func _exit_tree():
    16.     remove_spatial_gizmo_plugin(gizmo_plugin)

    For simple gizmos, just inheriting is enough. If you want to store some per-gizmo data or you are porting a Godot 3.0 gizmo to 3.1+, you should go with the second approach.

    The first step is to, in our custom gizmo plugin, override the has_gizmo() method so that it returns true when the spatial parameter is of our target type.

    Then we can override methods like or all the handle related ones.

    1. # ...
    3. func _init():
    5.     create_handle_material("handles")
    8. func redraw(gizmo):
    9.     gizmo.clear()
    11.     var spatial = gizmo.get_spatial_node()
    13.     var lines = PoolVector3Array()
    15.     lines.push_back(Vector3(0, 1, 0))
    16.     lines.push_back(Vector3(0, spatial.my_custom_value, 0))
    18.     var handles = PoolVector3Array()
    20.     handles.push_back(Vector3(0, 1, 0))
    21.     handles.push_back(Vector3(0, spatial.my_custom_value, 0))
    23.     gizmo.add_handles(handles, get_material("handles", gizmo))
    26. # ...

    Note that we created a material in the _init method, and retrieved it in the redraw method using get_material(). This method retrieves one of the material’s variants depending on the state of the gizmo (selected and/or editable).

    Note that we just added some handles in the redraw method, but we still need to implement the rest of handle-related callbacks in to get properly working handles.

    In some cases we want to provide our own implementation of EditorSpatialGizmo, maybe because we want to have some state stored in each gizmo or because we are porting an old gizmo plugin and we don’t want to go through the rewriting process.

    In these cases all we need to do is, in our new gizmo plugin, override , so it returns our custom gizmo implementation for the Spatial nodes we want to target.

    1. # MyCustomGizmoPlugin.gd
    2. extends EditorSpatialGizmoPlugin
    5. const MyCustomSpatial = preload("res://addons/my-addon/MyCustomSpatial.gd")
    6. const MyCustomGizmo = preload("res://addons/my-addon/MyCustomGizmo.gd")
    9. func _init():
    10.     create_material("main", Color(1, 0, 0))
    11.     create_handle_material("handles")
    14. func create_gizmo(spatial):
    15.     if spatial is MyCustomSpatial:
    16.         return MyCustomGizmo.new()
    17.     else:

    This way all the gizmo logic and drawing methods can be implemented in a new class extending EditorSpatialGizmo, like so: