Up to date

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

EditorNode3DGizmo¶

继承： Node3DGizmo < RefCounted < Object

用于编辑 Node3D 对象的小工具。

描述¶

小工具可用于为 Node3D 对象提供自定义可视化和编辑功能（控柄和子小工具）。可以被重写以创建自定义小工具，但对于简单的小工具而言，通常建议创建 EditorNode3DGizmoPlugin。

方法¶

void	_commit_handle ( int id, bool secondary, Variant restore, bool cancel ) virtual
void	_commit_subgizmos ( PackedInt32Array ids, Transform3D[] restores, bool cancel ) virtual
String	_get_handle_name ( int id, bool secondary ) virtual const
Variant	_get_handle_value ( int id, bool secondary ) virtual const
Transform3D	_get_subgizmo_transform ( int id ) virtual const
bool	_is_handle_highlighted ( int id, bool secondary ) virtual const
void	_redraw ( ) virtual
void	_set_handle ( int id, bool secondary, Camera3D camera, Vector2 point ) virtual
void	_set_subgizmo_transform ( int id, Transform3D transform ) virtual
PackedInt32Array	_subgizmos_intersect_frustum ( Camera3D camera, Plane[] frustum ) virtual const
int	_subgizmos_intersect_ray ( Camera3D camera, Vector2 point ) virtual const
void	add_collision_segments ( PackedVector3Array segments )
void	add_collision_triangles ( TriangleMesh triangles )
void	add_handles ( PackedVector3Array handles, Material material, PackedInt32Array ids, bool billboard=false, bool secondary=false )
void	add_lines ( PackedVector3Array lines, Material material, bool billboard=false, Color modulate=Color(1, 1, 1, 1) )
void	add_mesh ( Mesh mesh, Material material=null, Transform3D transform=Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0), SkinReference skeleton=null )
void	add_unscaled_billboard ( Material material, float default_scale=1, Color modulate=Color(1, 1, 1, 1) )
void	clear ( )
Node3D	get_node_3d ( ) const
EditorNode3DGizmoPlugin	get_plugin ( ) const
PackedInt32Array	get_subgizmo_selection ( ) const
bool	is_subgizmo_selected ( int id ) const
void	set_hidden ( bool hidden )
void	set_node_3d ( Node node )

方法说明¶

void _commit_handle ( int id, bool secondary, Variant restore, bool cancel ) virtual

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

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

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

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

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

如果 cancel 参数为 true，则restores 变换应被直接设置，而无需任何 UndoRedo 动作。

String _get_handle_name ( int id, bool secondary ) virtual const

覆盖该方法，以返回编辑的控柄的名称（控柄必须先前通过 add_handles 添加的）。可以命名控柄以供用户在编辑时引用。

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

Variant _get_handle_value ( int id, bool secondary ) virtual const

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

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

Transform3D _get_subgizmo_transform ( int id ) virtual const

覆盖该方法，以返回子小工具的当前变换。该变换将在编辑开始时被请求，并用作 _commit_subgizmos 中的 restore 参数。

bool _is_handle_highlighted ( int id, bool secondary ) virtual const

覆盖该方法，只要给定的控柄应该在编辑器中被高亮显示时就返回 true。

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

void _redraw ( ) virtual

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

void _set_handle ( int id, bool secondary, Camera3D camera, Vector2 point ) virtual

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

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

void _set_subgizmo_transform ( int id, Transform3D transform ) virtual

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

PackedInt32Array _subgizmos_intersect_frustum ( Camera3D camera, Plane[] frustum ) virtual const

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

int _subgizmos_intersect_ray ( Camera3D camera, Vector2 point ) virtual const

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

void add_collision_segments ( PackedVector3Array segments )

将指定的 segments 添加到小工具的碰撞形状以进行拾取。在 _redraw 期间调用该方法。

void add_collision_triangles ( TriangleMesh triangles )

将碰撞三角形添加到小工具以进行拾取。TriangleMesh 也可以从常规 Mesh 生成。在 _redraw 期间调用该方法。

void add_handles ( PackedVector3Array handles, Material material, PackedInt32Array ids, bool billboard=false, bool secondary=false )

添加可用于编辑该小工具的 Node3D 属性的一组控柄（点）。ids 参数可用于为每个控柄指定一个自定义的标识符，如果传递了一个空的数组，id 将按照 handles 参数顺序自动分配。

secondary 参数将添加的控柄标记为次要控柄，这意味着它们通常比普通控柄具有更低的选择优先级。当用户按住 Shift 键时，次要控柄将被切换为比普通控柄具有更高的优先级。这种优先级的变化可用于在同一点放置多个控柄，同时仍让用户控制他们的选择。

这些虚方法将在编辑这些控柄时被调用。在 _redraw 期间将调用该方法。

void add_lines ( PackedVector3Array lines, Material material, bool billboard=false, Color modulate=Color(1, 1, 1, 1) )

为小工具添加使用给定材质的线段（一对对点的集合）。线段将用于展示和选择。请在 _redraw 期间调用此方法。

void add_mesh ( Mesh mesh, Material material=null, Transform3D transform=Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0), SkinReference skeleton=null )

为小工具添加网格，可以指定材质 material、本地变换 transform 和骨架 skeleton。请在 _redraw 期间调用此方法。

void add_unscaled_billboard ( Material material, float default_scale=1, Color modulate=Color(1, 1, 1, 1) )

添加未缩放的公告板，将用于展示和选择。请在 _redraw 期间调用此方法。

void clear ( )

移除小工具中的一切，包括网格、碰撞和控柄。

Node3D get_node_3d ( ) const

返回与这个小工具关联的 Node3D 节点。

EditorNode3DGizmoPlugin get_plugin ( ) const

返回拥有该小工具的 EditorNode3DGizmoPlugin。可以在使用 EditorNode3DGizmoPlugin.get_material 获取材质时使用。

PackedInt32Array get_subgizmo_selection ( ) const

返回当前选定的子小工具的列表。可用于在 _redraw 期间高亮显示所选元素。

bool is_subgizmo_selected ( int id ) const

如果给定的子小工具是当前所选定的，则返回 true。可用于在 _redraw 期间高亮显示所选元素。

void set_hidden ( bool hidden )

设置该小工具的隐藏状态。如果为 true，则该小工具将被隐藏。如果为 false 则会显示。

void set_node_3d ( Node node )

设置该小工具参考的 Node3D 节点。node 必须继承自 Node3D。