bevyengine/bevy

bevy_gizmos

Immediate-mode debug drawing. The Gizmos system parameter lets any system draw lines, arrows, circles, spheres, frustums, grids, and other shapes for one frame at a time — no asset, no entity, just a function call.

Purpose

Gizmos exist for visual debugging: physics colliders, AI sight lines, curve previews, gizmo handles for an editor. The API is intentionally simple:

fn draw_things(mut gizmos: Gizmos) {
    gizmos.line(Vec3::ZERO, Vec3::X, Color::WHITE);
    gizmos.sphere(Vec3::ZERO, 1.0, Color::RED);
    gizmos.arrow(Vec3::ZERO, Vec3::Y, Color::GREEN);
}

The data lives in a per-frame buffer. bevy_gizmos_render (separate crate) extracts and renders it.

Directory layout

crates/bevy_gizmos/src/
├── lib.rs                # GizmoPlugin, Gizmos system param
├── gizmos.rs             # Gizmos struct + drawing methods
├── config.rs             # GizmoConfig, GizmoConfigGroup, GizmoConfigStore
├── primitives/           # Drawing routines per math primitive
├── arcs.rs, arrows.rs, axes.rs, circles.rs, cross.rs, curves.rs, grid.rs, rounded_box.rs
├── retained.rs           # Retained gizmos (last more than one frame)
├── light.rs              # Light visualizations
├── camera_view.rs        # Camera frustum visualization
├── aabb.rs               # AABB drawing
└── …

Key abstractions

Type	File	Description
`Gizmos<Config>`	`crates/bevy_gizmos/src/gizmos.rs`	System parameter; stores the per-frame draw queue.
`GizmoConfig`	`crates/bevy_gizmos/src/config.rs`	Color, line width, depth-bias settings.
`GizmoConfigGroup`	`crates/bevy_gizmos/src/config.rs`	Trait for grouping gizmo configs (you can have many configs).
`GizmoConfigStore`	`crates/bevy_gizmos/src/config.rs`	Resource: looks up configs by group.
`RetainedGizmo`	`crates/bevy_gizmos/src/retained.rs`	Long-lived gizmo (used by the retained API).

How it works

Gizmos is a SystemParam backed by a per-frame GizmoStorage resource. Each draw call appends vertices to a thread-local buffer that gets merged in Last. bevy_gizmos_render extracts the merged buffers into the render world and draws them as line lists / triangle strips with a small dedicated shader.

Configurations let one consumer (say, your physics colliders) have its own color/style without affecting another (your camera frustum visualization).

Integration points

Depends on: bevy_app, bevy_ecs, bevy_math, bevy_color, bevy_render (optional — for the data types it shares with the renderer), bevy_reflect.
Depended on by: bevy_gizmos_render, bevy_dev_tools.

Entry points for modification

New shape: add a method to Gizmos in the relevant primitive file. The drawing reduces to a list of (start, end, color) line segments.
Custom gizmo group: define a struct deriving GizmoConfigGroup, register with app.init_gizmo_group::<MyGroup>(). Then call gizmos.<...> with Gizmos<MyGroup>.