Bevy Debug Grid

A plugin for creating debug mesh grids in the bevy game engine.

The default_cube example

Installation

To install this plugin, add the following to the Cargo.toml:

[dependencies]
bevy_debug_grid = "0.1"

Setup

To use the plugin, import it by first doing use bevy_debug_grid::*; and then add the provided DebugGridPlugin plugin.

use bevy::prelude::*;
use bevy_debug_grid::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugin(DebugGridPlugin::with_floor_grid())
        .run();
}

It is also possible to avoid spawning a default floor grid by doing .add_plugin(DebugGridPlugin::without_floor_grid())

Examples

Several examples are provided, they can be launched by cloning this repository and running cargo run --example <example name>

All examples use the bevy_spectator camera plugin for movement. Use the W A S D, Shift, Space, and CTRL keys to move. Use Esc to release the cursor.
The camera spawns at world origin, so it needs to be moved a bit to see the examples in action.

Here's an exhaustive list of the provided examples:

default_cube - the minimal example, resembling Blender's default scene. Has a tracked grid and a cube at world origin (+0.5_f32 on Y).
moving_grid - an example of how a grid can be transformed, either by moving it, or by moving its parent.
changing_grid - an example of dynamically changing the properties of grids and sub-grids
changing_grid_axis - an example of dynamically changing grid axis appearance
dynamic_floor_grid - an example of a custom floor grid tracked on the X axis and a dynamic offset

Behavior

All grids spawned by this plugin are meshes, rendered with a polygoneMode of PolyginMode::Line.
An alternative would've been to create a plane and draw the lines using a shader, but it's not what has been chosen for this plugin.

This plugin's components work by spawning marked children. For example, a Grid will spawn a GridChild which will contain a Mesh and a Material.
This has implications regarding transforming the grid.

If there is no need to transform the grid separately, it can be spawned on the same level as all other components of the entity
If the grid needs to be transformed relative to its parent, spawn it as a child of the the entity

An demonstration of this can seen by running the moving_grid example.

Features

Grid

The Grid component spawns a configurable a mesh grid.

commands.spawn((
    Grid {
        // Space between each line
        spacing: 1.0_f32,
        // Line count along a single axis
        count: 8,
        // Color of the lines
        color: Color::SILVER,
        // Alpha mode for all components
        alpha_mode: AlphaMode::Opaque,
    },
    TransformBundle::default(),
    VisibilityBundle::default(),
));

The Grid::default() is a small silver grid with 8 lines per axis and a spacing of 0.25_f32 between them.

Grids have an alpha_mode, which determines the alpha mode for the grid material, as well as all other related materials, such as sub-grids, and grid axis.
The color should have an alpha value for alpha modes outside of AlphaMode::Opaque to make sense.
The default alpha mode for grids is AlphaMode::Blend.

Sub-Grid

The SubGrid component spawns a configurable mesh sub-grid when added next to a grid.
It creates lines between the lines of the main grid.

commands.spawn((
    Grid { /* ... */ },
    SubGrid {
        // Line count between each line of the main grid
        count: 4,
        // Line color
        color: Color::GRAY,
    },
    // Other components...
));

Grid Axis Color Overrides

The GridAxis component allows for setting custom colors per grid axis.

commands.spawn((
    Grid { /* ... */ },
    GridAxis {
        x: Some(Color::RED),
        z: Some(Color::Blue),
        // Fills the remainging axis with None
        ..default()
    },
    // Other components...
));

Tracked Grid

The TrackedGrid makes a grid tracked along a given axis.
The grid will move along with the camera and have its material clip at a certain distance, creating the illusion of an infinite grid.

commands.spawn((
    Grid { /* ... */ },
    TrackedGrid {
        // This will track it as a "floor"
        alignment: GridAlignment::Y,
        // The offset along the Y axis
        offset: 0.0_f32,
    },
    // Other components...
));

Known Bugs & Missing Features

Bug: removing TrackedGrid or GridAxis will not properly update the other components. It will currently just break. Current workaround is to desapawn the entity.
Missing: allowing grid tracking by custom means (it is by With<Camera> query.get_single() at the moment)