NEOLearn

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.

Updated October 20, 2026

On this page

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#

src/main.rs
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:

3D2DDraws
line, ray, linestrip, line_gradientline_2d, ray_2d, linestrip_2d, linestrip_gradient_2dLines, from a point or along a direction.
arrowarrow_2dAn arrow; .with_double_end(), .with_tip_length(..).
sphere, circle, ellipse, arc_3d, short_arc_3d_betweencircle_2d, ellipse_2d, arc_2d, short_arc_2d_betweenRound shapes; .resolution(n) sets the number of segments.
cube, rect, rounded_rect, crossrect_2d, rounded_rect_2d, cross_2dBoxes and markers.
grid, grid_3dgrid_2dGrids; .outer_edges() closes them.
axes(transform, length)axes_2dRed, green and blue axes of a transform.
curve_3d, curve_gradient_3dcurve_2d, curve_gradient_2dA sampled Curve.
primitive_3d(&shape, isometry, colour)primitive_2dAny math primitive: Cuboid, Capsule3d, Cone, Torus and the rest.
text(isometry, "..", size, anchor, colour)text_2dText 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 fieldWhat it does
enabledDraw this group or not.
line.widthLine width in pixels (or world-scaled with line.perspective).
line.styleGizmoLineStyle::Solid, Dotted or Dashed { gap_scale, line_scale }.
line.jointsGizmoLineJoint::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_layersWhich cameras show the group.

Make your own group to switch a kind of debug drawing on and off together:

Rust
#[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 componentWhat it shows
AabbGizmoConfigGroup (draw_all), ShowAabbGizmoBounding boxes of every entity, or of the ones with the component.
LightGizmoConfigGroup (draw_all, color), ShowLightGizmoThe shape and range of point, spot and directional lights.
ShowFrustumGizmoA camera's view frustum.
Rust
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:

Rust
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.

Next steps#