This page documents the 3D editor gizmo system: the EditorNode3DGizmoPlugin and EditorNode3DGizmo classes, how they relate to Node3D nodes in the editor, and how to implement custom gizmos with handles and subgizmos.
For general 3D editor viewport behavior and camera navigation, see the Node3D Editor page. For the 2D equivalent (CanvasItem overlays), see the CanvasItem Editor page.
Gizmos are the interactive overlays drawn on top of Node3D objects in the 3D editor viewport. They display visual cues (lines, meshes, billboards) and provide draggable handles that let the user edit node properties directly in the viewport without touching the Inspector.
The system consists of three primary classes:
| Class | Role |
|---|---|
Node3DGizmo | Abstract base class for 3D gizmos. editor/scene/3d/node_3d_editor_gizmos.h38-42 |
EditorNode3DGizmo | Concrete gizmo instance attached to a specific Node3D. editor/scene/3d/node_3d_editor_gizmos.h111-115 |
EditorNode3DGizmoPlugin | Factory and behavior handler; creates and manages gizmo instances. editor/scene/3d/node_3d_editor_gizmos.h207-210 |
Sources:
The gizmo system builds upon RefCounted and Resource for its base classes. Node3DGizmo is the abstract base for all 3D gizmos, while EditorNode3DGizmo is the concrete implementation used in the editor. EditorNode3DGizmoPlugin is a Resource that manages the creation and behavior of EditorNode3DGizmo instances.
Diagram: Gizmo System Class Hierarchy
Sources:
There are two implementation paths for creating custom gizmos, depending on the complexity and specific requirements:
| Approach | When to use | How |
|---|---|---|
| Plugin-only (simple) | When the gizmo needs no per-instance state or custom logic beyond what the EditorNode3DGizmo base class provides. | Extend EditorNode3DGizmoPlugin and override its virtual methods that receive a gizmo parameter (e.g., _redraw(gizmo)). editor/scene/3d/node_3d_editor_gizmos.h223-232 |
| Custom gizmo class | When per-instance state or complex interaction logic is required for the gizmo itself. | Extend EditorNode3DGizmoPlugin and override _create_gizmo() to return an instance of a custom EditorNode3DGizmo subclass. This custom subclass will then implement its own _redraw(), _set_handle(), etc. editor/scene/3d/node_3d_editor_gizmos.h229 |
Both approaches require registering the plugin with the Node3DEditor using Node3DEditor::add_gizmo_plugin(). editor/scene/3d/node_3d_editor_plugin.cpp1152-1155
Sources:
EditorNode3DGizmoPlugin acts as a factory and behavior delegator for gizmos. A single plugin instance manages all active gizmo instances of its type.
Diagram: Plugin Lifecycle and Data Flow
Sources:
_has_gizmo(Node3D *p_node): This virtual method determines if the plugin should create a gizmo for the given Node3D. editor/scene/3d/node_3d_editor_gizmos.h228_get_priority(): Returns an integer representing the plugin's priority. Higher values mean the plugin is checked earlier when determining which gizmo to use for a node. editor/scene/3d/node_3d_editor_gizmos.h225_get_gizmo_name(): Returns the name of the gizmo type, used for display in the editor's "Gizmos" menu. editor/scene/3d/node_3d_editor_gizmos.h223_can_be_hidden(): Returns true if the gizmo can be hidden via the editor's gizmo visibility settings. editor/scene/3d/node_3d_editor_gizmos.h226EditorNode3DGizmoPlugin provides helper methods to create and manage materials for gizmo rendering:
create_material(name, color, billboard, on_top, use_vertex_color): Creates a StandardMaterial3D or ShaderMaterial for general gizmo drawing. editor/scene/3d/node_3d_editor_gizmos.h234create_handle_material(name, billboard, texture): Creates a material specifically for gizmo handles. editor/scene/3d/node_3d_editor_gizmos.h235create_icon_material(name, texture, on_top, color): Creates a material for billboard icons. editor/scene/3d/node_3d_editor_gizmos.h236add_material(name, material): Registers a material with the plugin for later retrieval. editor/scene/3d/node_3d_editor_gizmos.h237get_material(name, gizmo): Retrieves a registered material by name. editor/scene/3d/node_3d_editor_gizmos.h238Sources:
EditorNode3DGizmo represents a single gizmo instance bound to one Node3D. It holds the visual elements and collision data for that specific node.
The _redraw() function (or the plugin's _redraw(gizmo)) is the entry point for building the gizmo's visual representation.
clear() to remove all previously added visual and collision elements. editor/scene/3d/node_3d_editor_gizmos.cpp1312-1320get_node_3d() to access the target node's properties and transform. editor/scene/3d/node_3d_editor_gizmos.cpp1292-1294add_lines, add_mesh, or add_unscaled_billboard to draw the gizmo's visual components.add_handles for draggable points that allow user interaction. editor/scene/3d/node_3d_editor_gizmos.cpp1367-1373add_collision_segments or add_collision_triangles to define the areas where the gizmo can be selected or interacted with. editor/scene/3d/node_3d_editor_gizmos.cpp1389-1400| Method | Description |
|---|---|
add_lines(lines, material, billboard, modulate) | Adds line segments using a PackedVector3Array. billboard makes lines face the camera, modulate applies a color tint. editor/scene/3d/node_3d_editor_gizmos.cpp1347-1353 |
add_mesh(mesh, material, transform, skeleton) | Adds a static or skinned mesh. transform applies an additional transformation, skeleton links to a skeleton for skinned meshes. editor/scene/3d/node_3d_editor_gizmos.cpp1355-1361 |
add_handles(handles, material, ids, billboard, secondary) | Adds draggable points for property manipulation. handles is a PackedVector3Array of handle positions. ids are unique identifiers for each handle. secondary indicates if handles are for secondary interaction. editor/scene/3d/node_3d_editor_gizmos.cpp1367-1373 |
add_unscaled_billboard(material, default_scale, modulate) | Adds a billboard that does not scale with distance. Useful for icons. editor/scene/3d/node_3d_editor_gizmos.cpp1375-1381 |
add_collision_segments(segments) | Adds invisible line segments for ray-cast picking. segments is a PackedVector3Array of start and end points. editor/scene/3d/node_3d_editor_gizmos.cpp1389-1393 |
add_collision_triangles(triangles) | Adds invisible triangles for ray-cast picking. triangles is a PackedVector3Array of vertex positions (3 vertices per triangle). editor/scene/3d/node_3d_editor_gizmos.cpp1395-1400 |
Sources:
Handles allow users to modify properties (like a collision shape's radius or a light's range) by dragging points in 3D space.
Diagram: Handle Callback Dispatch
Sources:
These virtual methods are called by the editor during handle interaction:
_get_handle_name(id, secondary): Returns the name of the handle for UI tooltips. id is the handle's identifier, secondary indicates if it's a secondary handle. editor/scene/3d/node_3d_editor_gizmos.h124_get_handle_value(id, secondary): Returns the current value of the property being edited by the handle. editor/scene/3d/node_3d_editor_gizmos.h125_set_handle(id, secondary, camera, point): Called as the user drags a handle. This method should update the corresponding node property in real-time based on the new point in 3D space, projected from the camera. editor/scene/3d/node_3d_editor_gizmos.h126_commit_handle(id, secondary, restore, cancel): Called when dragging ends. This method should create an EditorUndoRedoManager action to make the change permanent and undoable. restore is the original value, cancel indicates if the action should be cancelled. editor/scene/3d/node_3d_editor_gizmos.h127_begin_handle_action(id, secondary): Called when a handle drag begins. editor/scene/3d/node_3d_editor_gizmos.h123_is_handle_highlighted(id, secondary): Returns true if the handle should be highlighted. editor/scene/3d/node_3d_editor_gizmos.h128Sources:
Subgizmos are selectable sub-elements within a Node3D (e.g., individual bones in a skeleton, points in a path, or vertices in a mesh). They support complex selection and transformation independent of the main node.
_subgizmos_intersect_ray or _subgizmos_intersect_frustum to determine which sub-elements are picked by a ray or within a frustum. These methods return a PackedInt32Array of subgizmo IDs. editor/scene/3d/node_3d_editor_gizmos.h134-135_get_subgizmo_transform(id): Retrieves the current local transform of the sub-element identified by id. editor/scene/3d/node_3d_editor_gizmos.h136_set_subgizmo_transform(id, transform): Updates the sub-element's local transform as the user manipulates the gizmo. editor/scene/3d/node_3d_editor_gizmos.h137_commit_subgizmos(ids, restores, cancel): Finalizes the transformation for multiple sub-elements. ids are the affected subgizmos, restores are their original transforms, and cancel indicates if the action should be cancelled. This method should create an EditorUndoRedoManager action. editor/scene/3d/node_3d_editor_gizmos.h138Sources:
The 3D Editor uses specific rendering layers for gizmos to ensure they are visible and interactable without interfering with the main scene rendering. These layers are defined in Node3DEditorConstants.
| Layer Constant | Value | Purpose |
|---|---|---|
GIZMO_BASE_LAYER | 27 | Standard gizmo geometry. editor/scene/3d/node_3d_editor_plugin.h184 |
GIZMO_EDIT_LAYER | 26 | Active or highlighted gizmo elements. editor/scene/3d/node_3d_editor_plugin.h185 |
GIZMO_GRID_LAYER | 25 | Viewport grid. editor/scene/3d/node_3d_editor_plugin.h186 |
Sources:
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.