Add a gizmo-based overlay to show UI node outlines #10420

nicopap · 2023-11-06T20:24:47Z

Objective

It is useful to be able to visualize the outline of UI nodes. Especially if you have intermediary transparent containers, it's useful to see how they look like.

Currently, bevy doesn't have any way to visualize UI nodes. The current best workaround is to set the Outline component, however, this may interfere with user code.

cuicui_layout does have a debug overlay though.

Solution

Port the cuicui_layout debug overlay to bevy UI.

An interesting aspect of the cuicui_layout debug overlay is that it "insets" the outline of containers set within other containers. It can be otherwise hard to see which node contains what.

Design

We create a new camera with order set to 255, and UI disabled.
We set the RenderLayers of gizmos to 16
We iterate through the UI tree every frame, adding lines for each rectangles
We store "insets", so that we avoid re-drawing outlines on top of parent outlines.

Limitations

Currently, enabling the UI debug overlay monopolizes gizmos, it will disable gizmos rendering from other sources than the debug overlay. #10342 would allow to fix this.

Changelog

Add a UI outline debug overlay.

It is enabled as follow:

Enable the --feature bevy_ui_debug cargo feature (off by default
Press F9 to toggle the UI debug overlay (instructions are printed in the log output)

github-actions · 2023-11-06T20:42:38Z

You added a new feature but didn't update the readme. Please run cargo run -p build-templated-pages -- update features to update it, and commit the file change.

alice-i-cecile · 2023-11-06T20:47:33Z

crates/bevy_ui/src/lib.rs

@@ -12,6 +12,8 @@ pub mod ui_material;
 pub mod update;
 pub mod widget;

+#[cfg(feature = "debug")]


I think we should rename this feature to something like debug_layout, just to reduce ambiguity.

alice-i-cecile · 2023-11-06T20:47:58Z

crates/bevy_ui/src/debug_overlay/mod.rs

+    }
+    fn finish(&self, _app: &mut App) {
+        info!(
+            "The bevy_ui debug overlay is active!\n\


Suggested change

"The bevy_ui debug overlay is active!\n\

"The bevy_ui layout debug overlay is active!\n\

alice-i-cecile · 2023-11-06T20:48:17Z

crates/bevy_ui/src/debug_overlay/mod.rs

+            ----------------------------------------------\n\
+            \n\
+            This will show the outline of UI nodes.\n\
+            Press `F9` to switch between debug mods."


Suggested change

Press `F9` to switch between debug mods."

Press `F9` to cycle between debug modes."

nicopap · 2023-11-07T09:31:46Z

This needs to move to the bevy_gizmos crate. I'll put this in draft mode until I fix the PR feedbacks & move the module.

aevyrie · 2023-11-07T15:32:44Z

I really don't want to set the precedent of scattering magic keybinds throughout the codebase. IMO that is out of scope of any library, and is the responsibility of a user's keybinding plugin. Hardcoding these - even if they are configurable defaults - means users will need to know where all these mappings happen throughout the code, and where to disable them. I'd much prefer the crate exposes an event. This keeps the library unopinionated about what is triggering the event, because the source can be anything - a ui button, a keypress, etc.

If we want to start developing default keybinds, that belongs in a separate DefaultKeybinds (?) plugin in bevy_utils.

nicopap · 2023-11-07T16:55:47Z

In this specific case, you have to explicitly enable the behavior. As a reminder: this is strictly for debugging, it would never make it to the player, and it is off by default (in the sense it is not compiled into the app, it's behind a cfg(…) attribute). Furthermore, enabling it prints a 5 lines message in the log saying "Press F9 to toggle the overlay".

I already took a careful look at user impact when adding this feature to cuicui_layout. I think your point stands for situations where those keybindings exist for regular behaviors or for implicitly brought-in code. But it hold little water in this specific situation: The keybinding is printed in the console, it is a debugging feature, it only exists when the feature is enabled, it must be enabled explicitly and it is a rarely used key.

Is it difficult to find which key is set? No, it is printed in the console
Does the user need to disable the key? No, it is behind a feature flag they have to explicitly enable
Can this be done by exposing an event? No, the usefulness of the feature depends on users not having to write any additional code to get the layout overlay.
Is this setting a precedent for scattering magic keybinds throughout the codebase? It doesn't even do that. Also this phrasing could be taken as condescending or rude.

I really don't want to lock that kind of feature behind having to write additional code. I see your point if the main way of interacting with bevy debugging feature is through the editor, but fundamentally, there is no reason to lock this behind an editor, writing boilerplate or bringing in a dependency.

JMS55 · 2023-11-07T17:18:29Z

Users might already use F9 for keybinds in their game, however. Perhaps we could make it configurable under the plugin setup?

DefaultPlugins.set(UiDebugPlugin {
    trigger_key: Keycode::SPACE, // Defaults to F9
});

nicopap · 2023-11-08T06:59:48Z

I'm not interested in implementing this feature. I'm really busy and have much more interesting (and profitable) things to do.

But anyone who wants it, feel free to take the mantle. I wrote the most difficult part, all is left is to do is integrate it with bevy.

The PR is up for adoption.

# Objective - This is an adopted version of #10420 - The objective is to help debugging the Ui layout tree with helpful outlines, that can be easily enabled/disabled ## Solution - Like #10420, the solution is using the bevy_gizmos in outlining the nodes --- ## Changelog ### Added - Added debug_overlay mod to `bevy_dev_tools` - Added bevy_ui_debug feature to `bevy_dev_tools` ## How to use - The user must use `bevy_dev_tools` feature in TOML - The user must use the plugin UiDebugPlugin, that can be found on `bevy::dev_tools::debug_overlay` - Finally, to enable the function, the user must set `UiDebugOptions::enabled` to true Someone can easily toggle the function with something like: ```rust fn toggle_overlay(input: Res<ButtonInput<KeyCode>>, options: ResMut<UiDebugOptions>) { if input.just_pressed(KeyCode::Space) { // The toggle method will enable if disabled and disable if enabled options.toggle(); } } ``` Note that this feature can be disabled from dev_tools, as its in fact behind a default feature there, being the feature bevy_ui_debug. # Limitations Currently, due to limitations with gizmos itself, it's not possible to support this feature to more the one window, so this tool is limited to the primary window only. # Showcase ![image](https://github.com/bevyengine/bevy/assets/126117294/ce9d70e6-0a57-4fa9-9753-ff5a9d82c009) Ui example with debug_overlay enabled ![image](https://github.com/bevyengine/bevy/assets/126117294/e945015c-5bab-4d7f-9273-472aabaf25a9) And disabled --------- Co-authored-by: Nicola Papale <[email protected]> Co-authored-by: Pablo Reinhardt <[email protected]> Co-authored-by: Alice Cecile <[email protected]>

Add a gizmo-based overlay to show UI node outlines

d929a43

nicopap added C-Feature A new feature, making something new possible A-UI Graphical user interfaces, styles, layouts, and widgets A-Gizmos Visual editor and debug gizmos labels Nov 6, 2023

Document cargo feature

2b94433

alice-i-cecile added this to the 0.13 milestone Nov 6, 2023

alice-i-cecile requested a review from ickshonpe November 6, 2023 20:34

alice-i-cecile requested a review from nicoburns November 6, 2023 20:45

alice-i-cecile reviewed Nov 6, 2023

View reviewed changes

alice-i-cecile requested a review from IceSentry November 6, 2023 20:55

nicopap marked this pull request as draft November 7, 2023 09:31

nicopap added the S-Adopt-Me The original PR author has no intent to complete this work. Pick me up! label Nov 7, 2023

pablo-lua mentioned this pull request Jan 6, 2024

Add a gizmo-based overlay to show UI node outlines (Adopted) #11237

Merged

alice-i-cecile closed this Jan 6, 2024

pablo-lua mentioned this pull request Jan 16, 2024

Allow user to choose the default ui camera #11377

Closed

pablo-lua mentioned this pull request Mar 8, 2024

Fps overlay #12382

Merged

pablo-lua mentioned this pull request Mar 18, 2024

Abstraction dev tools #12427

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add a gizmo-based overlay to show UI node outlines #10420

Add a gizmo-based overlay to show UI node outlines #10420

nicopap commented Nov 6, 2023 •

edited

Loading

github-actions bot commented Nov 6, 2023

alice-i-cecile Nov 6, 2023

alice-i-cecile Nov 6, 2023

alice-i-cecile Nov 6, 2023

nicopap commented Nov 7, 2023

aevyrie commented Nov 7, 2023

nicopap commented Nov 7, 2023

JMS55 commented Nov 7, 2023

nicopap commented Nov 8, 2023 •

edited

Loading

	"The bevy_ui debug overlay is active!\n\
	"The bevy_ui layout debug overlay is active!\n\

	Press `F9` to switch between debug mods."
	Press `F9` to cycle between debug modes."

Add a gizmo-based overlay to show UI node outlines #10420

Add a gizmo-based overlay to show UI node outlines #10420

Conversation

nicopap commented Nov 6, 2023 • edited Loading

Objective

Solution

Design

Limitations

Changelog

github-actions bot commented Nov 6, 2023

alice-i-cecile Nov 6, 2023

Choose a reason for hiding this comment

alice-i-cecile Nov 6, 2023

Choose a reason for hiding this comment

alice-i-cecile Nov 6, 2023

Choose a reason for hiding this comment

nicopap commented Nov 7, 2023

aevyrie commented Nov 7, 2023

nicopap commented Nov 7, 2023

JMS55 commented Nov 7, 2023

nicopap commented Nov 8, 2023 • edited Loading

nicopap commented Nov 6, 2023 •

edited

Loading

nicopap commented Nov 8, 2023 •

edited

Loading