Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

EditorNode3DGizmoPlugin¶

编辑器用来定义 Node3D 小工具类型的类。

描述¶

EditorNode3DGizmoPlugin 允许定义一种新的小工具类型。定义主要有两种方法：比较简单的小工具可以扩展 EditorNode3DGizmoPlugin，否则可以创建新的 EditorNode3DGizmo 类型。有关详细信息，请参阅文档中的教程。

要使用 EditorNode3DGizmoPlugin，请先使用 EditorPlugin.add_node_3d_gizmo_plugin 方法注册它。

教程¶

Node3D 小工具插件

方法¶

bool	_can_be_hidden ( ) virtual const
void	_commit_handle ( EditorNode3DGizmo gizmo, int handle_id, bool secondary, Variant restore, bool cancel ) virtual
void	_commit_subgizmos ( EditorNode3DGizmo gizmo, PackedInt32Array ids, Transform3D[] restores, bool cancel ) virtual
EditorNode3DGizmo	_create_gizmo ( Node3D for_node_3d ) virtual const
String	_get_gizmo_name ( ) virtual const
String	_get_handle_name ( EditorNode3DGizmo gizmo, int handle_id, bool secondary ) virtual const
Variant	_get_handle_value ( EditorNode3DGizmo gizmo, int handle_id, bool secondary ) virtual const
int	_get_priority ( ) virtual const
Transform3D	_get_subgizmo_transform ( EditorNode3DGizmo gizmo, int subgizmo_id ) virtual const
bool	_has_gizmo ( Node3D for_node_3d ) virtual const
bool	_is_handle_highlighted ( EditorNode3DGizmo gizmo, int handle_id, bool secondary ) virtual const
bool	_is_selectable_when_hidden ( ) virtual const
void	_redraw ( EditorNode3DGizmo gizmo ) virtual
void	_set_handle ( EditorNode3DGizmo gizmo, int handle_id, bool secondary, Camera3D camera, Vector2 screen_pos ) virtual
void	_set_subgizmo_transform ( EditorNode3DGizmo gizmo, int subgizmo_id, Transform3D transform ) virtual
PackedInt32Array	_subgizmos_intersect_frustum ( EditorNode3DGizmo gizmo, Camera3D camera, Plane[] frustum_planes ) virtual const
int	_subgizmos_intersect_ray ( EditorNode3DGizmo gizmo, Camera3D camera, Vector2 screen_pos ) virtual const
void	add_material ( String name, StandardMaterial3D material )
void	create_handle_material ( String name, bool billboard=false, Texture2D texture=null )
void	create_icon_material ( String name, Texture2D texture, bool on_top=false, Color color=Color(1, 1, 1, 1) )
void	create_material ( String name, Color color, bool billboard=false, bool on_top=false, bool use_vertex_color=false )
StandardMaterial3D	get_material ( String name, EditorNode3DGizmo gizmo=null )

方法说明¶

bool _can_be_hidden ( ) virtual const

覆盖该方法，以定义是否可以隐藏该插件处理的小工具。如果未被覆盖，则返回 true。

void _commit_handle ( EditorNode3DGizmo gizmo, int handle_id, bool secondary, Variant restore, bool cancel ) virtual

覆盖该方法，以提交正在编辑的控柄（控柄必须是先前在 _redraw 期间通过 EditorNode3DGizmo.add_handles 添加的）。这通常意味着为该更改创建一个 UndoRedo 动作，将当前控柄值用作“做”，并将 restore 参数用作“撤销”。

如果 cancel 参数为 true，则 restore 值应被直接设置，无需任何 UndoRedo 动作。

当提交的控柄为次要控柄时，secondary 参数为 true（有关更多信息，请参阅 EditorNode3DGizmo.add_handles）。

为该插件的活动小工具而调用。

void _commit_subgizmos ( EditorNode3DGizmo gizmo, PackedInt32Array ids, Transform3D[] restores, bool cancel ) virtual

覆盖该方法，以提交一组正在编辑的子小工具（参见 _subgizmos_intersect_ray 和 _subgizmos_intersect_frustum）。这通常意味着为该更改创建一个 UndoRedo 动作，将当前变换用作“做”，并将 restores 变换用作“撤消”。

如果 cancel 参数为 true，则 restores 变换应被直接设置，无需任何 UndoRedo 动作。对于所有子小工具方法，变换是在与小工具的 Node3D 相关的局部空间中给出的。为该插件的活动小工具而调用。

EditorNode3DGizmo _create_gizmo ( Node3D for_node_3d ) virtual const

覆盖此方法，为选择的空间节点返回一个自定义的 EditorNode3DGizmo，为其余节点返回 null。另见 _has_gizmo。

String _get_gizmo_name ( ) virtual const

覆盖该方法，以提供将出现在小工具可见性菜单中的名称。

String _get_handle_name ( EditorNode3DGizmo gizmo, int handle_id, bool secondary ) virtual const

覆盖该方法，以提供小工具的控柄名称。当请求的控柄是次要控柄时，secondary 参数为 true（有关更多信息，请参阅 EditorNode3DGizmo.add_handles）。为该插件的活动小工具而调用。

Variant _get_handle_value ( EditorNode3DGizmo gizmo, int handle_id, bool secondary ) virtual const

覆盖该方法，以返回一个控柄的当前值。该值将在编辑开始时被请求，并用作 _commit_handle 中的 restore 参数。

当请求的控柄是次要控柄时，secondary 参数为 true（有关更多信息，请参阅 EditorNode3DGizmo.add_handles）。

为该插件的活动小工具而调用。

int _get_priority ( ) virtual const

覆盖该方法，以设置该小工具的优先级。具有更高优先级的小工具，将在处理控柄或子小工具选择等输入时具有优先权。

所有内置编辑器小工具都会返回 -1 的优先级。如果未被覆盖，该方法将返回 0，这意味着自定义小工具将自动获得比内置小工具更高的优先级。

Transform3D _get_subgizmo_transform ( EditorNode3DGizmo gizmo, int subgizmo_id ) virtual const

覆盖该方法，以返回子小工具的当前变换。对于所有子小工具方法，变换应该在相对于小工具的 Node3D 的局部空间中。此变换将在编辑开始时被请求，并在 _commit_subgizmos 中的 restore 参数中使用。为该插件的活动小工具而调用。

bool _has_gizmo ( Node3D for_node_3d ) virtual const

覆盖该方法，以定义哪些 Node3D 节点具有来自该插件的小工具。每当将 Node3D 节点添加到场景时，该方法都会被调用，如果它返回 true，则该节点将被分配一个通用的 EditorNode3DGizmo，并被添加到该插件的活动小工具列表中。

bool _is_handle_highlighted ( EditorNode3DGizmo gizmo, int handle_id, bool secondary ) virtual const

覆盖该方法，以在编辑器中高亮显示给定控柄时返回 true。当请求的控柄是次要控柄时，secondary 参数为 true（有关更多信息，请参阅 EditorNode3DGizmo.add_handles）。为该插件的活动小工具而调用。

bool _is_selectable_when_hidden ( ) virtual const

覆盖该方法，以定义具有该小工具的 Node3D 是否应该是可选的，即使该小工具被隐藏。

void _redraw ( EditorNode3DGizmo gizmo ) virtual

覆盖该方法，以在每当请求小工具更新时添加所有小工具元素。通常在该方法的开头调用 EditorNode3DGizmo.clear，然后根据节点的属性添加可视元素。

void _set_handle ( EditorNode3DGizmo gizmo, int handle_id, bool secondary, Camera3D camera, Vector2 screen_pos ) virtual

覆盖该方法，以在用户拖动小工具控柄（控柄是之前使用 EditorNode3DGizmo.add_handles 添加的）时更新节点的属性。提供的 screen_pos 是屏幕坐标中的鼠标位置， camera 可用于将其转换为射线投射。

当编辑的控柄是次要控柄时，secondary 参数为 true（有关更多信息，请参阅 EditorNode3DGizmo.add_handles）。

为该插件的活动小工具而调用。

void _set_subgizmo_transform ( EditorNode3DGizmo gizmo, int subgizmo_id, Transform3D transform ) virtual

覆盖该方法，以在子小工具编辑期间更新节点属性（参见 _subgizmos_intersect_ray 和 _subgizmos_intersect_frustum）。transform 在 Node3D 的局部坐标系中给出。为该插件的活动小工具而调用。

PackedInt32Array _subgizmos_intersect_frustum ( EditorNode3DGizmo gizmo, Camera3D camera, Plane[] frustum_planes ) virtual const

覆盖该方法，以允许使用鼠标拖动框选来选择子小工具。给定一个 camera 和 frustum_planes，该方法应返回哪些子小工具包含在视锥体中。frustum_planes 参数由一个构成选择视锥体的所有 Plane 的数组组成。返回的值应该包含一个唯一的子小工具标识符列表，这些标识符可以有任何非负值，并将用于其他虚方法，如 _get_subgizmo_transform 或 _commit_subgizmos。为该插件的活动小工具而调用。

int _subgizmos_intersect_ray ( EditorNode3DGizmo gizmo, Camera3D camera, Vector2 screen_pos ) virtual const

覆盖该方法，以允许使用鼠标点击选择子小工具。给定屏幕坐标中的 camera 和 screen_pos 时，该方法应返回应选择哪个子小工具。返回值应该是一个唯一的子小工具标识符，它可以有任何非负值，并将用于其他虚方法，如 _get_subgizmo_transform 或 _commit_subgizmos。为该插件的活动小工具而调用。

void add_material ( String name, StandardMaterial3D material )

将新材质添加到该插件的内部材质列表中。然后可以使用 get_material 访问它。不应被重写。

void create_handle_material ( String name, bool billboard=false, Texture2D texture=null )

创建具有变体（选定的和/或可编辑的）的控柄材质，并将它们添加到内部材质列表中。然后可以使用 get_material 访问它们，并在 EditorNode3DGizmo.add_handles 中使用它们。不应被重写。

可以选择提供一个要使用的纹理代替默认图标。

void create_icon_material ( String name, Texture2D texture, bool on_top=false, Color color=Color(1, 1, 1, 1) )

创建具有变体（选定的和/或可编辑的）的图标材质，并将它们添加到内部材质列表中。然后可以使用 get_material 访问它们，并在 EditorNode3DGizmo.add_unscaled_billboard 中使用它们。不应被重写。

void create_material ( String name, Color color, bool billboard=false, bool on_top=false, bool use_vertex_color=false )

创建具有变体（选定的和/或可编辑的）的未着色材质，并将它们添加到内部材质列表中。然后可以使用 get_material 访问它们，并在 EditorNode3DGizmo.add_mesh 和 EditorNode3DGizmo.add_lines 中使用。不应被重写。

StandardMaterial3D get_material ( String name, EditorNode3DGizmo gizmo=null )

从内部材质列表中获取材质。如果提供了一个 EditorNode3DGizmo，它将尝试获取相应的变体（选定的和/或可编辑的）。