bevy-gizmos

name	bevy-gizmos
description	Reference for Bevy gizmos — immediate-mode visual debugging, GizmoPlugin, Gizmos system param, retained GizmoAsset, config groups, and line styles.
metadata	{"crate":"bevy_gizmos","bevy":"0.19"}

Setup

Gizmos are enabled via GizmoPlugin, which is included in DefaultPlugins:

App::new()
    .add_plugins(DefaultPlugins)  // includes GizmoPlugin
    .run();

Or add it manually: .add_plugins(GizmoPlugin).

Immediate mode — Gizmos system param

Gizmos are drawn per-frame and cleared automatically after rendering.

fn draw_gizmos(mut gizmos: Gizmos) {
    gizmos.line(Vec3::ZERO, Vec3::X, GREEN);
}

Use in Update (per-frame) or FixedMain (per-tick).

Drawing primitives

Shape	3D	2D
Line	gizmos.line(start, end, color)	gizmos.line_2d(start, end, color)
Ray	gizmos.ray(origin, direction, color)	gizmos.ray_2d(origin, direction, color)
Linestrip	gizmos.linestrip(positions, color)	gizmos.linestrip_2d(positions, color)
Lineloop	gizmos.lineloop(positions, color)	—
Rect	gizmos.rect(isometry, size, color)	gizmos.rect_2d(isometry, size, color)
Circle	gizmos.circle(isometry, radius, color)	gizmos.circle_2d(isometry, radius, color)
Sphere	gizmos.sphere(isometry, radius, color)	—
Ellipse	gizmos.ellipse(isometry, half_size, color)	gizmos.ellipse_2d(isometry, half_size, color)
Cube	gizmos.cube(transform, color)	—
Arrow	gizmos.arrow(start, end, color)	gizmos.arrow_2d(start, end, color)
Cross	gizmos.cross(isometry, half_size, color)	gizmos.cross_2d(isometry, half_size, color)
Grid	gizmos.grid(rotation, cells, spacing, color)	gizmos.grid_2d(...)
AABB	gizmos.aabb_3d(aabb, transform, color)	—

Lines with color gradients

gizmos.line_gradient(Vec3::ZERO, Vec3::X, GREEN, RED);
gizmos.ray_gradient(Vec3::Y, Vec3::X, CYAN, MAGENTA);
gizmos.linestrip_gradient([(Vec3::ZERO, GREEN), (Vec3::X, RED)]);

Curves

Requires bevy_math::curve::Curve trait:

let domain = Interval::UNIT;
let curve = FunctionCurve::new(domain, |t| Vec2::from(t.sin_cos()));
gizmos.curve_2d(curve, (0..=100).map(|n| n as f32 / 100.0), RED);
gizmos.curve_3d(curve_3d, times, BLUE);

// With gradient:
gizmos.curve_gradient_2d(curve, (0..=100).map(|n| n as f32 / 100.0).map(|t| (t, GREEN.mix(&RED, t))));

Arcs & ellispes

Arc builder methods return a builder with .resolution(n):

gizmos.arc_3d(angle_rad, radius, isometry, color).resolution(64);
gizmos.short_arc_3d_between(center, from, to, color);
gizmos.long_arc_3d_between(center, from, to, color);

Arrow builder

gizmos.arrow(start, end, ORANGE_RED)
    .with_double_end()
    .with_tip_length(0.5);

Axes

Draw XYZ axes from a transform:

gizmos.axes(transform, base_length);
gizmos.axes_2d(transform, base_length);

Rounded cuboids / rectangles

gizmos.rounded_cuboid(center, size, TURQUOISE)
    .edge_radius(0.1)
    .arc_resolution(4);
gizmos.rounded_rect(isometry, size, color);
gizmos.rounded_rect_2d(isometry, size, color);

Primitives

All bevy_math primitives renderable:

gizmos.primitive_3d(
    &Plane3d { normal: Dir3::Y, half_size: Vec2::splat(1.0) },
    isometry,
    GREEN,
).cell_count(UVec2::new(5, 10))
 .spacing(Vec2::new(0.2, 0.1));

Config groups

Create custom config groups to independently toggle/style sets of gizmos:

#[derive(Default, Reflect, GizmoConfigGroup)]
struct MyRoundGizmos;

app.init_gizmo_group::<MyRoundGizmos>();

fn system(mut my_gizmos: Gizmos<MyRoundGizmos>) {
    my_gizmos.sphere(Isometry3d::IDENTITY, 1.0, RED);
}

Use AppGizmoBuilder::insert_gizmo_config for custom initial config.

Config store (GizmoConfigStore)

Access and modify gizmo configuration at runtime:

fn update_config(mut config_store: ResMut<GizmoConfigStore>) {
    let (config, _) = config_store.config_mut::<DefaultGizmoConfigGroup>();
    config.enabled ^= true;  // toggle visibility
    config.depth_bias = -1.0;  // always in front
    config.line.width = 5.0;
    config.line.perspective ^= true;

    // Custom config group
    let (my_config, _) = config_store.config_mut::<MyRoundGizmos>();
    my_config.line.width += 1.0;
}

Config fields

Field	Type	Description
enabled	bool	Toggle all gizmos for this group
depth_bias	f32	-1 (in front) to 1 (behind); 0 = normal
line.width	f32	Line width in pixels
line.perspective	bool	Perspective-correct line width
line.style	GizmoLineStyle	Solid, Dotted, Dashed { gap_scale, line_scale }
line.joints	GizmoLineJoint	Bevel, Miter, Round(n), None
mesh	MeshConfig	Mesh gizmo config

AABB gizmos

// Enable on specific entities by adding ShowAabbGizmo component
// Or draw all with:
config_store.config_mut::<AabbGizmoConfigGroup>().1.draw_all = true;

Retained mode (GizmoAsset + Gizmo component)

For many static lines, use retained gizmos for better performance:

fn spawn_retained(mut commands: Commands, mut gizmo_assets: ResMut<Assets<GizmoAsset>>) {
    let mut gizmo = GizmoAsset::new();
    gizmo.sphere(Isometry3d::IDENTITY, 0.5, CRIMSON)
        .resolution(30_000 / 3);

    commands.spawn(Gizmo {
        handle: gizmo_assets.add(gizmo),
        line_config: GizmoLineConfig { width: 5.0, ..default() },
        ..default()
    });
}

Gizmo component fields: handle (Handle<GizmoAsset>), line_config, depth_bias.

GizmoAsset supports the same drawing API as Gizmos (line, circle, sphere, etc.).

Light gizmos

Feature: bevy_light. Debug visualization of lights:

// Requires bevy_light feature
// Automatically drawn for PointLight, SpotLight, DirectionalLight