Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

EditorNode3DGizmoPlugin

继承： Resource < RefCounted < Object

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

描述

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

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

教程

Node3D 小工具插件

方法

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

方法说明

void _begin_handle_action(gizmo: EditorNode3DGizmo, handle_id: int, secondary: bool) virtual 🔗

该方法目前没有描述，请帮我们贡献一个吧！

bool _can_be_hidden() virtual const 🔗

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

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

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

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

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

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

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

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

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

EditorNode3DGizmo _create_gizmo(for_node_3d: Node3D) virtual const 🔗

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

String _get_gizmo_name() virtual const 🔗

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

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

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

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

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

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

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

int _get_priority() virtual const 🔗

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

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

Transform3D _get_subgizmo_transform(gizmo: EditorNode3DGizmo, subgizmo_id: int) virtual const 🔗

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

bool _has_gizmo(for_node_3d: Node3D) virtual const 🔗

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

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

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

bool _is_selectable_when_hidden() virtual const 🔗

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

void _redraw(gizmo: EditorNode3DGizmo) virtual 🔗

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

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

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

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

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

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

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

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

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

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

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

void add_material(name: String, material: StandardMaterial3D) 🔗

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

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

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

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

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

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

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

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

StandardMaterial3D get_material(name: String, gizmo: EditorNode3DGizmo = null) 🔗

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