Bevy Debug Text Overlay

A proof of concept for adding a very convenient text overlay macro to the bevy game engine.

This is derived from the code I used during the first bevy game jam. There are major improvements: most notably the text doesn't jump around all the time, and each message can have its own color.

screen_print! is very convenient, if you are an incorrigible println-debugger, you will love this crate when working with bevy!

Usage

toml [dependencies] bevy-debug-text-overlay = "5.1"

This bevy plugin is fairly trivial to use. You must: 1. Add the OverlayPlugin to your app 2. Use the screen_print! macro wherever you want, just use it like you would use println!, no need to pass special arguments.

This will display on the top left of the screen the text for a short time.

Please see the screen_print! documentation for detailed usage instructions.

Code example

```rust,norun use bevy::prelude::*; use bevydebugtextoverlay::{screen_print, OverlayPlugin};

fn main() { App::new() .addplugins(DefaultPlugins) // !!!!IMPORTANT!!!! Add the OverlayPlugin here .addplugin(OverlayPlugin { fontsize: 32.0, ..default() }) .addstartupsystem(setup) .addsystem(screenprinttext) .run(); } fn setup(mut commands: Commands) { commands.spawn(Camera2dBundle::default()); } // Notice how we didn't have to add any special system parameters fn screenprinttext(time: Res) { let currenttime = time.elapsedsecondsf64(); let atinterval = |t: f64| currenttime % t < time.deltasecondsf64(); let x = (13, 3.4, vec![1,2,3,4,5,6,7,8]); if atinterval(0.1) { let lastfps = 1.0 / time.deltaseconds(); screenprint!(col: Color::CYAN, "fps: {lastfps:.0}"); screenprint!("current time: {currenttime:.2}") } if atinterval(2.0) { let col = Color::FUCHSIA; screenprint!(sec: 0.5, col: col, "every two seconds: {}, {:?}", x.0, x.2) } if atinterval(5.0) { screenprint!(sec: 3.0, "every five seconds: {x:#?}"); } } ```

This should look like as follow:

https://user-images.githubusercontent.com/26321040/158537677-e9339fd0-3bed-4a83-a4cc-bc1340e5d78b.mp4

Cargo features

builtin-font

The plugin provides its own ascii font by default, but if you want to disable it, you can disable the builtin-font cargo feature.

debug

It is possible to replace screen_print! by an empty macro by disabling the debug cargo feature. This also disables all of bevy-debug-text-overlay dependencies, since there is no code to run.

No further action is required to completely disable the plugin. Mock implementations are provided for release mod.

To use that feature, you can setup your Cargo.toml as follow:

```toml

Add a debug feature to your own Cargo.toml, make it default

[features] debug = ["bevy-debug-text-overlay/debug"] default = ["debug"]

Manually specify features for bevy-debug-text-overlay (omitting "debug")

bevy-debug-text-overlay = { version = "5.0", default-features = false, features = ["builtin-font"] } ```

Now when making your release build, you should use sh cargo build --release --no-default-features

I'm aware that it can be cumbersome for some, please fill an issue if this really doesn't mix well with your own workflow.

Known limitations

I'm welcoming contributions if you have any fixes: * There is no way to specify the overlay position with regard to user-defined UI, so you might end up with the debug text showing behind your own UI. * There is a very custom, very dodgy resource allocation module. If someone can link me to a good 1D res alloc crate, I'd be happy to use it instead of block. * This is not part of bevy itself, so you gotta add it as a dependency to your app :( * You can't set it up so that it's displayed from the bottom up or to the right of the screen.

Changelog

• 2.0.0: Breaking: bump bevy version to 0.7 (you should be able to upgrade from 1.0.0 without changing your code)
• 3.0.0: Breaking: bump bevy version to 0.8 (you should be able to upgrade from 2.0.0 without changing your code)
• 4.0.0: Breaking: bump bevy version to 0.9 (you should be able to upgrade from 3.0.0 without changing your code)
• 4.0.1: Fix the README "Usage" version
• 5.0.0: Breaking: bump bevy version to 0.10 (you should be able to upgrade from 4.0.1 without changing your code)
• 5.1.0: Add the push option to screen_print! macro, this allows printing multiple messages from the same macro call, this makes the macro usable in loops, or for messages that makes sense to duplicate on screen.

Version matrix

| bevy | latest supporting version | |------|--------| | 0.10 | 5.1.0 | | 0.9 | 4.0.1 | | 0.8 | 3.0.0 | | 0.7 | 2.0.0 | | 0.6 | 1.0.0 |

API stability warning

This is a tinny crate so it's literally impossible to cause major breaking changes. But I'm not convinced the current macro API is optimal, and it might change in the future.

License

This library is licensed under Apache 2.0.

Font

The font in screen_debug_text.ttf is derived from Adobe SourceSans, licensed under the SIL OFL. see file at licenses/SIL Open Font License.txt.