API for registering dev tools ui in any layout manager

[rewin123]

Motivation

The GitHub pull request (bevyengine/rfcs#77) offers a unified way to register and enable/disable dev tools in Bevy.

But part of the dev tools may want to display debugging information on the screen or get input from developers. For example, the FPS overlay displays the number of FPS in the bottom right corner, and the entity inspector may want to show editable fields and buttons near the right edge of the screen. Or the real-time statistics render graph will want to display rendering times information somewhere in the static area. If multiple dev_tools claim the same area of the screen to display information, it will be messy. Dev tools can and will conflict over displaying information. Accordingly, the question not solved and not asked in my opinion in RFC is "how is it planned to organize the location of the displayed information of dev modules?"

There's no silver bullet

Already after the RFC was published, several ideas have been proposed to distribute UI from each dev-tool:

• On a grid
• On a second monitor
• As in Godot
• Through tabs and dock mechanisms
• Etc.

It seems to me that each of the proposed approaches has its place for being used effectively, and there is no silver bullet for solving the UI problem in one way. Different use cases require different UI, layouts and styles.

For this reason, I suggest finding some unified way to organize place for dev tool UIs

Proposed solution

Layout engine

It is proposed to introduce the concept of layout engine, which is a plugin that:

• Is responsible for deciding where on the screen dev tool UIs are rendered.
• Creates as many new UI elements as it needs to organise dev tools in an efficient way. (For example, when creating a dock-based layout system, you need to create interactive panels on top of which the dev tool UI will be displayed.)
• Self-registers dev tools from the list of active tools
• Can hide/show dev tools
• Provides a unified interface for developers to interact with the layout engine (for example, through the DevToolsListPlugin system described below)

Each implemented layout engine must inherit the layout engine trait:

pub trait LayoutEngine : ModalDevTool {
    /// type_id - TypeId of registering dev tool
    fn register_dev_tool(&mut self, type_id: TypeId);
}

This way each layout engine can manipulate a given set of dev tools.
LayoutEngine can be designated as the main one, and all new added dev tools will be registered in it automatically via the fn register_dev_tool(&mut self, type_id: TypeId) method;
I propose to declare some layout engine as the main one in the following way

app.add_plugins(MainLayout<CustomLayoutType>);

That said, judging from the trait, the layout engine has no special requirements and can technically be anything, as it is primarily a concept. To which, however, I propose to allow the use of the api for dev tool ui

Dev tool UI trait

Since the main purpose of the layout will be to reorganise nodes, it is proposed to make two traits for bevy_ui based dev tools and for non bevy_ui solutions:

1. For bevy_ui based tools, a new trait will be introduced which extends ModalDevUI (see below) and and an event that notifies layouts to create a node for this tool NewToolUiRoot
2. For non-bevy_ui solutions, the GenericUiModalTool

trait ModalDevUI : ModalDevTool {
    
    /// It is necessary to separate the concepts of enabled dev tool and showing dev tool. 
    /// Since a dev tool can be launched, but not display its information, 
    /// because the layout engine decided to hide the display (for example, the user hided the tab with this dev tool)
    
    /// Show the UI of the dev tool and enable all systems for showing dev tool ui
    fn show(&mut self);
    /// Hide the UI of the dev tool and disable all systems for showing dev tool ui
    fn hide(&mut self);

    /// Is the UI of the dev tool visible
    fn is_showing(&self) -> bool;
}

#[derive(Event)]
pub struct NewToolUiRoot {
    pub id: Entity,
    pub type_id: TypeId,
}

trait GenericUiModalTool : ModalDevUI {
    /// Ask the tool if it has a prefered width
    fn get_prefered_width(&self) -> Option<f32>;
    
    /// Ask the tool if it has a prefered height
    fn get_prefered_height(&self) -> Option<f32>;

    /// Set exact position and size
    fn set_position(&mut self, position: Vec2);
    fn set_size(&mut self, size: Vec2);
}

Thus the proposed traits can provide basic manipulation over the UI of the dev tools. To demonstrate the capabilities of such an API, I suggest you consider creating a very simple layout in the form of a vertical list

Example (Vertical list plugin)

First, let's implement the plugin which will be responsible for creating and managing the vertical list:

pub struct DevToolsListPlugin;

impl Plugin for DevToolsListPlugin {
    fn build(&self, app: &mut App) {
        app.add_systems(Startup, init_dev_tools_list);
        app.add_systems(Update, register_dev_tool);


app.add_plugins(MainLayout<DevToolsList>); 
    }    
}

Next, let's create a vertical list of dev tools:

#[derive(Resource)]
pub struct DevToolsList {
    pub tools_nodes: HashMap<TypeId, Option<Entity>>,
    pub tools_root_node: Entity,
}

impl  LayoutEngine for  DevToolsList {
    fn register_dev_tool(&mut self, type_id: TypeId) {
        self.tools_nodes.insert(type_id, None);
    }    
}

The function which updates the dev tools list

fn register_dev_tool(
    mut commands: Commands,
    mut list: ResMut<DevToolsList>,
    mut e_new_tool: EventReader<NewToolUiRoot>,
) {
    for NewToolUiRoot { id, type_id } in e_new_tool.read() {
        list.tools_nodes.insert(type_id, Some(id));
    }

    e_new_tool.clear();

    let children: Vec<_> = list
        .tools_nodes
        .values()
        .filter( |&x| x != None)
        .map(|id| *id.unwrap())
        .collect();

    //rebuild the dev tools list
    commands.entity(list.tools_root_node).replace_children(&children);
}

The function which initializes an empty vertical list with a root node and adds it to the app state

fn init_dev_tools_list(mut commands: Commands) { //just for dummy example
    let id = commands.spawn(NodeBundle {
        style: Style {
            flex_direction: FlexDirection::Column,
            size: Size::new(Val::Percent(100.0), Val::Percent(100.0)),
            ..default()
        },
        ..default()
    }).id();

    commands.insert_resource(DevToolsList {
        tools_nodes: HashMap::new(),
        tools_root_node: id,
    });
}

As you can see in a few lines the proposed approach allows you to make a custom layout with arbitrary features via a unified api in a small number of lines.

Summary

The main idea is to propose the following concepts:

• Unified trait for showing/hiding dev tools
• New event for registering a bevy ui root node of dev tools
• Unified UI registry for dev tools
• New trait for manipulating position and size of non-bevy_ui dev tools
• Layout engine is a plugin. Only one layout engine can be used at a time, as it will manage all dev tool UIs.

[codercommand]

Can you expand on the layout engine a little, you keep talking about it without mentioning what it does.

From what I understand it's responsible for deciding where on the screen stuff is rendered.

[rewin123]

Good question! I've rewritten the discussion post so that it's clear what is meant by layout engine and simplified the api a bit. You can see the new Layout engine section

[codercommand]

Something that doesn't make sense with the layout engine is who provides it?

Is it a set of traits and there can be multiple implementations of the layout engine allowing for different editor layout/workflows? The way you've written this implies to me that tools implement their own versions of the layout engine which would be an issue since that wouldn't make different tools compatible and if you do that then there is no point in a layout engine.

I imagine a there being the layout engine API which is used by tools to be compatible with different layout engines, and the layout engine API is implemented by different parties allowing for tailored editor experiences.

[rewin123]

Something that doesn't make sense with the layout engine is who provides it?
Yes. It is assumed that there may be many different implementations of the layout engine that can be made outside of the bevy repository. For example the layout engine could emulate the unity/godot engine UI, and these could be standalone repositories

The way you've written this implies to me that tools implement their own versions of the layout engine which would be an issue since that wouldn't make different tools compatible and if you do that then there is no point in a layout engine.
No. Each dev tool is supposed to allow you to set the position and size of its ui. And layout engine will manipulate these positions and sizes

I imagine a there being the layout engine API which is used by tools to be compatible with different layout engines, and the layout engine API is implemented by different parties allowing for tailored editor experiences.
А. I have my doubts that I'm understanding this correctly, correct me if I'm wrong.

In my version, Layout Engine accesses dev tools for information and it also manipulates the state via root node style (for bevy_ui) or by directly setting the boundin box for the element.

You are suggesting to reverse this. And have the tools access the api layout editor? So for example, register itself, request position and size for display?

Or can you describe in more detail how you see the construction of the api?

[codercommand]

I thought it'd work where the dev tool(s) would implement the traits like GenericUiModalTool, then the layout engine would call those trait APIs to tell the dev tools where to display, how big/scale, and which window.

[rewin123]

I think that's what I'm suggesting 😅

[codercommand]

I need to try the bevy ui since I haven't tried it yet. But I have a concern, you suggest having all the bevy ui from tools as children of a single parent node.

How are regions defined? GenericUiModalTool has location and rectangle width & height. ModalDevUI doesn't have that, how do you enforce UI to fit within a region/zone at a certain location like with GenericUiModalTool?

[rewin123]

ModalDevUI doesn't have that, how do you enforce UI to fit within a region/zone at a certain location like with GenericUiModalTool?
The bevy Style component implements most of the basic css style fields, including the ability to set the exact location and size of an element. I envision that the layout engine will either directly set the position and size of the bevy ui node, by overwriting its style component, or layout the tool nodes into flexible containers such as grid and flex, without setting a rigid position and size

Style docs - https://docs.rs/bevy/latest/i686-pc-windows-msvc/bevy/prelude/struct.Style.html

[rewin123]

How are regions defined?
Regions are determined by the specific implementation of the layout engine