|
@@ -1,13 +1,13 @@
|
|
-.. _doc_spatial_gizmo_plugins:
|
|
|
|
|
|
+.. _doc_3d_gizmo_plugins:
|
|
|
|
|
|
-Spatial gizmo plugins
|
|
|
|
-=====================
|
|
|
|
|
|
+3D gizmo plugins
|
|
|
|
+================
|
|
|
|
|
|
Introduction
|
|
Introduction
|
|
------------
|
|
------------
|
|
|
|
|
|
-Spatial gizmo plugins are used by the editor and custom plugins to define the
|
|
|
|
-gizmos attached to any kind of Spatial node.
|
|
|
|
|
|
+3D gizmo plugins are used by the editor and custom plugins to define the
|
|
|
|
+gizmos attached to any kind of Node3D node.
|
|
|
|
|
|
This tutorial shows the two main approaches to defining your own custom
|
|
This tutorial shows the two main approaches to defining your own custom
|
|
gizmos. The first option works well for simple gizmos and creates less clutter in
|
|
gizmos. The first option works well for simple gizmos and creates less clutter in
|
|
@@ -16,11 +16,11 @@ your plugin structure, and the second one will let you store some per-gizmo data
|
|
.. note:: This tutorial assumes you already know how to make generic plugins. If
|
|
.. note:: This tutorial assumes you already know how to make generic plugins. If
|
|
in doubt, refer to the :ref:`doc_making_plugins` page.
|
|
in doubt, refer to the :ref:`doc_making_plugins` page.
|
|
|
|
|
|
-The EditorSpatialGizmoPlugin
|
|
|
|
-----------------------------
|
|
|
|
|
|
+The EditorNode3DGizmoPlugin
|
|
|
|
+---------------------------
|
|
|
|
|
|
Regardless of the approach we choose, we will need to create a new
|
|
Regardless of the approach we choose, we will need to create a new
|
|
-:ref:`EditorSpatialGizmoPlugin <class_EditorSpatialGizmoPlugin>`. This will allow
|
|
|
|
|
|
+:ref:`EditorNode3DGizmoPlugin <class_EditorNode3DGizmoPlugin>`. This will allow
|
|
us to set a name for the new gizmo type and define other behaviors such as whether
|
|
us to set a name for the new gizmo type and define other behaviors such as whether
|
|
the gizmo can be hidden or not.
|
|
the gizmo can be hidden or not.
|
|
|
|
|
|
@@ -29,7 +29,7 @@ This would be a basic setup:
|
|
::
|
|
::
|
|
|
|
|
|
# MyCustomGizmoPlugin.gd
|
|
# MyCustomGizmoPlugin.gd
|
|
- extends EditorSpatialGizmoPlugin
|
|
|
|
|
|
+ extends EditorNode3DGizmoPlugin
|
|
|
|
|
|
|
|
|
|
func get_name():
|
|
func get_name():
|
|
@@ -49,14 +49,14 @@ This would be a basic setup:
|
|
|
|
|
|
|
|
|
|
func _enter_tree():
|
|
func _enter_tree():
|
|
- add_spatial_gizmo_plugin(gizmo_plugin)
|
|
|
|
|
|
+ add_node3d_gizmo_plugin(gizmo_plugin)
|
|
|
|
|
|
|
|
|
|
func _exit_tree():
|
|
func _exit_tree():
|
|
- remove_spatial_gizmo_plugin(gizmo_plugin)
|
|
|
|
|
|
+ remove_node3d_gizmo_plugin(gizmo_plugin)
|
|
|
|
|
|
|
|
|
|
-For simple gizmos, inheriting :ref:`EditorSpatialGizmoPlugin <class_EditorSpatialGizmoPlugin>`
|
|
|
|
|
|
+For simple gizmos, inheriting :ref:`EditorNode3DGizmoPlugin <class_EditorNode3DGizmoPlugin>`
|
|
is enough. If you want to store some per-gizmo data or you are porting a Godot 3.0 gizmo
|
|
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.
|
|
to 3.1+, you should go with the second approach.
|
|
|
|
|
|
@@ -64,21 +64,21 @@ to 3.1+, you should go with the second approach.
|
|
Simple approach
|
|
Simple approach
|
|
---------------
|
|
---------------
|
|
|
|
|
|
-The first step is to, in our custom gizmo plugin, override the :ref:`has_gizmo()<class_EditorSpatialGizmoPlugin_method_has_gizmo>`
|
|
|
|
-method so that it returns ``true`` when the spatial parameter is of our target type.
|
|
|
|
|
|
+The first step is to, in our custom gizmo plugin, override the :ref:`_has_gizmo()<class_EditorNode3DGizmoPlugin_method__has_gizmo>`
|
|
|
|
+method so that it returns ``true`` when the node parameter is of our target type.
|
|
|
|
|
|
::
|
|
::
|
|
|
|
|
|
# ...
|
|
# ...
|
|
|
|
|
|
|
|
|
|
- func has_gizmo(spatial):
|
|
|
|
- return spatial is MyCustomSpatial
|
|
|
|
|
|
+ func _has_gizmo(node):
|
|
|
|
+ return node is MyCustomNode3D
|
|
|
|
|
|
|
|
|
|
# ...
|
|
# ...
|
|
|
|
|
|
-Then we can override methods like :ref:`redraw()<class_EditorSpatialGizmoPlugin_method_redraw>`
|
|
|
|
|
|
+Then we can override methods like :ref:`_redraw()<class_EditorNode3DGizmoPlugin_method__redraw>`
|
|
or all the handle related ones.
|
|
or all the handle related ones.
|
|
|
|
|
|
::
|
|
::
|
|
@@ -94,17 +94,17 @@ or all the handle related ones.
|
|
func redraw(gizmo):
|
|
func redraw(gizmo):
|
|
gizmo.clear()
|
|
gizmo.clear()
|
|
|
|
|
|
- var spatial = gizmo.get_spatial_node()
|
|
|
|
|
|
+ var node3d = gizmo.get_node3d()
|
|
|
|
|
|
var lines = PackedVector3Array()
|
|
var lines = PackedVector3Array()
|
|
|
|
|
|
lines.push_back(Vector3(0, 1, 0))
|
|
lines.push_back(Vector3(0, 1, 0))
|
|
- lines.push_back(Vector3(0, spatial.my_custom_value, 0))
|
|
|
|
|
|
+ lines.push_back(Vector3(0, node3d.my_custom_value, 0))
|
|
|
|
|
|
var handles = PackedVector3Array()
|
|
var handles = PackedVector3Array()
|
|
|
|
|
|
handles.push_back(Vector3(0, 1, 0))
|
|
handles.push_back(Vector3(0, 1, 0))
|
|
- handles.push_back(Vector3(0, spatial.my_custom_value, 0))
|
|
|
|
|
|
+ handles.push_back(Vector3(0, node3d.my_custom_value, 0))
|
|
|
|
|
|
gizmo.add_lines(lines, get_material("main", gizmo), false)
|
|
gizmo.add_lines(lines, get_material("main", gizmo), false)
|
|
gizmo.add_handles(handles, get_material("handles", gizmo))
|
|
gizmo.add_handles(handles, get_material("handles", gizmo))
|
|
@@ -113,7 +113,7 @@ or all the handle related ones.
|
|
# ...
|
|
# ...
|
|
|
|
|
|
Note that we created a material in the `_init` method, and retrieved it in the `redraw`
|
|
Note that we created a material in the `_init` method, and retrieved it in the `redraw`
|
|
-method using :ref:`get_material()<class_EditorSpatialGizmoPlugin_method_get_material>`. This
|
|
|
|
|
|
+method using :ref:`get_material()<class_EditorNode3DGizmoPlugin_method_get_material>`. This
|
|
method retrieves one of the material's variants depending on the state of the gizmo
|
|
method retrieves one of the material's variants depending on the state of the gizmo
|
|
(selected and/or editable).
|
|
(selected and/or editable).
|
|
|
|
|
|
@@ -121,10 +121,10 @@ So the final plugin would look somewhat like this:
|
|
|
|
|
|
::
|
|
::
|
|
|
|
|
|
- extends EditorSpatialGizmoPlugin
|
|
|
|
|
|
+ extends EditorNode3DGizmoPlugin
|
|
|
|
|
|
|
|
|
|
- const MyCustomSpatial = preload("res://addons/my-addon/MyCustomSpatial.gd")
|
|
|
|
|
|
+ const MyCustomNode3D = preload("res://addons/my-addon/MyCustomNode3D.gd")
|
|
|
|
|
|
|
|
|
|
func _init():
|
|
func _init():
|
|
@@ -132,54 +132,54 @@ So the final plugin would look somewhat like this:
|
|
create_handle_material("handles")
|
|
create_handle_material("handles")
|
|
|
|
|
|
|
|
|
|
- func has_gizmo(spatial):
|
|
|
|
- return spatial is MyCustomSpatial
|
|
|
|
|
|
+ func _has_gizmo(node):
|
|
|
|
+ return node is MyCustomNode3D
|
|
|
|
|
|
|
|
|
|
func redraw(gizmo):
|
|
func redraw(gizmo):
|
|
gizmo.clear()
|
|
gizmo.clear()
|
|
|
|
|
|
- var spatial = gizmo.get_spatial_node()
|
|
|
|
|
|
+ var node3d = gizmo.get_node3d()
|
|
|
|
|
|
var lines = PackedVector3Array()
|
|
var lines = PackedVector3Array()
|
|
|
|
|
|
lines.push_back(Vector3(0, 1, 0))
|
|
lines.push_back(Vector3(0, 1, 0))
|
|
- lines.push_back(Vector3(0, spatial.my_custom_value, 0))
|
|
|
|
|
|
+ lines.push_back(Vector3(0, node3d.my_custom_value, 0))
|
|
|
|
|
|
var handles = PackedVector3Array()
|
|
var handles = PackedVector3Array()
|
|
|
|
|
|
handles.push_back(Vector3(0, 1, 0))
|
|
handles.push_back(Vector3(0, 1, 0))
|
|
- handles.push_back(Vector3(0, spatial.my_custom_value, 0))
|
|
|
|
|
|
+ handles.push_back(Vector3(0, node3d.my_custom_value, 0))
|
|
|
|
|
|
gizmo.add_lines(lines, get_material("main", gizmo), false)
|
|
gizmo.add_lines(lines, get_material("main", gizmo), false)
|
|
gizmo.add_handles(handles, get_material("handles", gizmo))
|
|
gizmo.add_handles(handles, get_material("handles", gizmo))
|
|
|
|
|
|
|
|
|
|
# You should implement the rest of handle-related callbacks
|
|
# You should implement the rest of handle-related callbacks
|
|
- # (get_handle_name(), get_handle_value(), commit_handle()...).
|
|
|
|
|
|
+ # (_get_handle_name(), _get_handle_value(), _commit_handle(), ...).
|
|
|
|
|
|
Note that we just added some handles in the redraw method, but we still need to implement
|
|
Note that we just added some handles in the redraw method, but we still need to implement
|
|
-the rest of handle-related callbacks in :ref:`EditorSpatialGizmoPlugin <class_EditorSpatialGizmoPlugin>`
|
|
|
|
|
|
+the rest of handle-related callbacks in :ref:`EditorNode3DGizmoPlugin <class_EditorNode3DGizmoPlugin>`
|
|
to get properly working handles.
|
|
to get properly working handles.
|
|
|
|
|
|
Alternative approach
|
|
Alternative approach
|
|
--------------------
|
|
--------------------
|
|
|
|
|
|
-In some cases we want to provide our own implementation of :ref:`EditorSpatialGizmo<class_EditorSpatialGizmo>`,
|
|
|
|
|
|
+In some cases we want to provide our own implementation of :ref:`EditorNode3DGizmo<class_EditorNode3DGizmo>`,
|
|
maybe because we want to have some state stored in each gizmo or because we are porting
|
|
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.
|
|
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
|
|
In these cases all we need to do is, in our new gizmo plugin, override
|
|
-:ref:`create_gizmo()<class_EditorSpatialGizmoPlugin_method_create_gizmo>`, so it returns our custom gizmo implementation
|
|
|
|
-for the Spatial nodes we want to target.
|
|
|
|
|
|
+:ref:`_create_gizmo()<class_EditorNode3DGizmoPlugin_method__create_gizmo>`, so it returns our custom gizmo implementation
|
|
|
|
+for the Node3D nodes we want to target.
|
|
|
|
|
|
::
|
|
::
|
|
|
|
|
|
# MyCustomGizmoPlugin.gd
|
|
# MyCustomGizmoPlugin.gd
|
|
- extends EditorSpatialGizmoPlugin
|
|
|
|
|
|
+ extends EditorNode3DGizmoPlugin
|
|
|
|
|
|
|
|
|
|
- const MyCustomSpatial = preload("res://addons/my-addon/MyCustomSpatial.gd")
|
|
|
|
|
|
+ const MyCustomNode3D = preload("res://addons/my-addon/MyCustomNode3D.gd")
|
|
const MyCustomGizmo = preload("res://addons/my-addon/MyCustomGizmo.gd")
|
|
const MyCustomGizmo = preload("res://addons/my-addon/MyCustomGizmo.gd")
|
|
|
|
|
|
|
|
|
|
@@ -188,19 +188,19 @@ for the Spatial nodes we want to target.
|
|
create_handle_material("handles")
|
|
create_handle_material("handles")
|
|
|
|
|
|
|
|
|
|
- func create_gizmo(spatial):
|
|
|
|
- if spatial is MyCustomSpatial:
|
|
|
|
|
|
+ func _create_gizmo(node):
|
|
|
|
+ if node is MyCustomNode3D:
|
|
return MyCustomGizmo.new()
|
|
return MyCustomGizmo.new()
|
|
else:
|
|
else:
|
|
return null
|
|
return null
|
|
|
|
|
|
This way all the gizmo logic and drawing methods can be implemented in a new class extending
|
|
This way all the gizmo logic and drawing methods can be implemented in a new class extending
|
|
-:ref:`EditorSpatialGizmo<class_EditorSpatialGizmo>`, like so:
|
|
|
|
|
|
+:ref:`EditorNode3DGizmo<class_EditorNode3DGizmo>`, like so:
|
|
|
|
|
|
::
|
|
::
|
|
|
|
|
|
# MyCustomGizmo.gd
|
|
# MyCustomGizmo.gd
|
|
- extends EditorSpatialGizmo
|
|
|
|
|
|
+ extends EditorNode3DGizmo
|
|
|
|
|
|
|
|
|
|
# You can store data in the gizmo itself (more useful when working with handles).
|
|
# You can store data in the gizmo itself (more useful when working with handles).
|
|
@@ -210,17 +210,17 @@ This way all the gizmo logic and drawing methods can be implemented in a new cla
|
|
func redraw():
|
|
func redraw():
|
|
clear()
|
|
clear()
|
|
|
|
|
|
- var spatial = get_spatial_node()
|
|
|
|
|
|
+ var node3d = get_node3d()
|
|
|
|
|
|
var lines = PackedVector3Array()
|
|
var lines = PackedVector3Array()
|
|
|
|
|
|
lines.push_back(Vector3(0, 1, 0))
|
|
lines.push_back(Vector3(0, 1, 0))
|
|
- lines.push_back(Vector3(gizmo_size, spatial.my_custom_value, 0))
|
|
|
|
|
|
+ lines.push_back(Vector3(gizmo_size, node3d.my_custom_value, 0))
|
|
|
|
|
|
var handles = PackedVector3Array()
|
|
var handles = PackedVector3Array()
|
|
|
|
|
|
handles.push_back(Vector3(0, 1, 0))
|
|
handles.push_back(Vector3(0, 1, 0))
|
|
- handles.push_back(Vector3(gizmo_size, spatial.my_custom_value, 0))
|
|
|
|
|
|
+ handles.push_back(Vector3(gizmo_size, node3d.my_custom_value, 0))
|
|
|
|
|
|
var material = get_plugin().get_material("main", self)
|
|
var material = get_plugin().get_material("main", self)
|
|
add_lines(lines, material, false)
|
|
add_lines(lines, material, false)
|
|
@@ -230,8 +230,8 @@ This way all the gizmo logic and drawing methods can be implemented in a new cla
|
|
|
|
|
|
|
|
|
|
# You should implement the rest of handle-related callbacks
|
|
# You should implement the rest of handle-related callbacks
|
|
- # (get_handle_name(), get_handle_value(), commit_handle()...).
|
|
|
|
|
|
+ # (_get_handle_name(), _get_handle_value(), _commit_handle(), ...).
|
|
|
|
|
|
Note that we just added some handles in the redraw method, but we still need to implement
|
|
Note that we just added some handles in the redraw method, but we still need to implement
|
|
-the rest of handle-related callbacks in :ref:`EditorSpatialGizmo<class_EditorSpatialGizmo>`
|
|
|
|
|
|
+the rest of handle-related callbacks in :ref:`EditorNode3DGizmo<class_EditorNode3DGizmo>`
|
|
to get properly working handles.
|
|
to get properly working handles.
|