Gizmos
Draw debug lines, shapes, arrows, grids and text in 2D and 3D with the Gizmos system parameter, style them with config groups, and keep static ones with GizmoAsset.
Gizmos are lines you draw for one frame from any system: a ray, a box around an entity, a path, a label. Ask for Gizmos in a system, call its methods, and the lines appear in that frame, on top of every camera. They're the quickest way to see what your code thinks is happening.
Gizmos and their rendering are on in NEO's builds, on every platform.
Drawing#
use neo::prelude::*;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_systems(Startup, |mut commands: Commands| {
commands.spawn((Camera3d::default(), Transform::from_xyz(0.0, 4.0, 8.0).looking_at(Vec3::ZERO, Vec3::Y)));
})
.add_systems(Update, draw)
.run();
}
fn draw(mut gizmos: Gizmos, time: Res<Time>) {
let t = time.elapsed_secs();
gizmos.grid(Quat::from_rotation_x(std::f32::consts::FRAC_PI_2), UVec2::splat(20), Vec2::splat(1.0), LinearRgba::gray(0.6));
gizmos.sphere(Vec3::new(t.sin() * 2.0, 1.0, 0.0), 0.5, Color::srgb(1.0, 0.2, 0.2));
gizmos.arrow(Vec3::ZERO, Vec3::Y * 2.0, Color::srgb(1.0, 1.0, 0.0));
gizmos.text(Isometry3d::from_translation(Vec3::new(0.0, 2.5, 0.0)), "origin", 0.3, Vec2::ZERO, Color::WHITE);
}Most methods take a position or an Isometry3d (position and rotation) and a colour, and come in 3D and _2d forms:
| 3D | 2D | Draws |
|---|---|---|
line, ray, linestrip, line_gradient | line_2d, ray_2d, linestrip_2d, linestrip_gradient_2d | Lines, from a point or along a direction. |
arrow | arrow_2d | An arrow; .with_double_end(), .with_tip_length(..). |
sphere, circle, ellipse, arc_3d, short_arc_3d_between | circle_2d, ellipse_2d, arc_2d, short_arc_2d_between | Round shapes; .resolution(n) sets the number of segments. |
cube, rect, rounded_rect, cross | rect_2d, rounded_rect_2d, cross_2d | Boxes and markers. |
grid, grid_3d | grid_2d | Grids; .outer_edges() closes them. |
axes(transform, length) | axes_2d | Red, green and blue axes of a transform. |
curve_3d, curve_gradient_3d | curve_2d, curve_gradient_2d | A sampled Curve. |
primitive_3d(&shape, isometry, colour) | primitive_2d | Any math primitive: Cuboid, Capsule3d, Cone, Torus and the rest. |
text(isometry, "..", size, anchor, colour) | text_2d | Text in a simple stroke font. |
Gizmos drawn from FixedUpdate stay on screen until the next fixed step, so they don't flicker.
Styling with config groups#
Every gizmo belongs to a config group; plain Gizmos is DefaultGizmoConfigGroup. Change a group's GizmoConfig through GizmoConfigStore:
GizmoConfig field | What it does |
|---|---|
enabled | Draw this group or not. |
line.width | Line width in pixels (or world-scaled with line.perspective). |
line.style | GizmoLineStyle::Solid, Dotted or Dashed { gap_scale, line_scale }. |
line.joints | GizmoLineJoint::None, Miter, Round(n) or Bevel where line strips bend. |
depth_bias | -1.0 draws on top of everything, 0.0 is depth-tested like geometry. |
render_layers | Which cameras show the group. |
Make your own group to switch a kind of debug drawing on and off together:
#[derive(Default, Reflect, GizmoConfigGroup)]
struct PathGizmos;
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.init_gizmo_group::<PathGizmos>()
.add_systems(Update, (draw_paths, toggle_paths))
.run();
}
fn draw_paths(mut gizmos: Gizmos<PathGizmos>) {
gizmos.linestrip([Vec3::ZERO, Vec3::X, Vec3::new(1.0, 0.0, 1.0)], Color::srgb(0.2, 0.8, 1.0));
}
fn toggle_paths(keys: Res<ButtonInput<KeyCode>>, mut store: ResMut<GizmoConfigStore>) {
if keys.just_pressed(KeyCode::F4) {
let (config, _) = store.config_mut::<PathGizmos>();
config.enabled ^= true;
}
}Built-in debug views#
| Group or component | What it shows |
|---|---|
AabbGizmoConfigGroup (draw_all), ShowAabbGizmo | Bounding boxes of every entity, or of the ones with the component. |
LightGizmoConfigGroup (draw_all, color), ShowLightGizmo | The shape and range of point, spot and directional lights. |
ShowFrustumGizmo | A camera's view frustum. |
fn show_all_bounds(mut store: ResMut<GizmoConfigStore>) {
store.config_mut::<AabbGizmoConfigGroup>().1.draw_all = true;
}Static gizmos#
Redrawing thousands of lines every frame costs time. For lines that don't change, build a GizmoAsset once and spawn it with a Gizmo component; it's drawn like a mesh, moves with the entity's Transform, and costs nothing per frame to keep:
fn spawn_marker(mut commands: Commands, mut gizmo_assets: ResMut<Assets<GizmoAsset>>) {
let mut gizmo = GizmoAsset::new();
gizmo.sphere(Isometry3d::IDENTITY, 0.5, Color::srgb(0.9, 0.1, 0.3)).resolution(64);
commands.spawn((
Gizmo {
handle: gizmo_assets.add(gizmo),
line_config: GizmoLineConfig { width: 3.0, ..default() },
..default()
},
Transform::from_xyz(2.0, 1.0, 0.0),
));
}Examples: cargo run --example 2d_gizmos, axes, light_gizmos, 2d_text_gizmos, 3d_text_gizmos and anchored_text_gizmos. 3d_gizmos needs --features free_camera.