bevy_debug_grid 0.1.0

A bevy plugin for creating grids, for debugging purposes
Documentation

Bevy Debug Grid

Bevy tracking

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

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,
    },
    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.

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)
  • Missing: grid color alpha

Compatibility

Bevy Version Plugin Version
0.10 0.1.0

License

This plugin is dual-licensed under either: