Skip to content

Add standalone bevy_entity_inspector and bevy_transform widget for drawing on the UI#215

Open
jbuehler23 wants to merge 26 commits intomainfrom
investigate-brp-usage
Open

Add standalone bevy_entity_inspector and bevy_transform widget for drawing on the UI#215
jbuehler23 wants to merge 26 commits intomainfrom
investigate-brp-usage

Conversation

@jbuehler23
Copy link
Contributor

@jbuehler23 jbuehler23 commented Jun 20, 2025

Add Entity Inspector with Component Grouping and Event-Driven Updates

Objective

Bevy currently lacks a comprehensive, user-friendly entity inspector for runtime debugging and development. Developers need a way to:

  • Inspect entities and components in real-time during development
  • Understand component organization by seeing which crates contribute which components
  • Connect to remote applications for debugging without modifying the target application
  • Navigate large entity hierarchies efficiently with expandable tree views
  • See only relevant data with clear visual indicators of what can be expanded

The bevy_entity_inspector crate provides a first-party entity inspector with modern UX patterns, designed specifically for Bevy's component model and reflection system.

Solution

Component Grouping by Crate

Components are automatically organized by their crate origin for better comprehension:

Entity (42)
├── bevy_transform
│   ├── Transform (expandable - has field data)
│   │   ├── translation: Vec3(0.0, 0.0, 0.0) 
│   │   ├── rotation: Quat(0.0, 0.0, 0.0, 1.0)
│   │   └── scale: Vec3(1.0, 1.0, 1.0)
│   └── GlobalTransform
├── bevy_render
│   ├── Visibility (dimmed - no expandable data)
│   └── ViewVisibility (dimmed - no expandable data)
└── my_game
    └── Player
        ├── health: f32(100.0)
        └── level: u32(1)

Property Panel Features

When you select a component (e.g., Transform), the property panel immediately displays:

  • Component header: Clear component name and type
  • All reflected fields: Instantly visible without drilling down
  • Color-coded display: Field names in light blue, values in white
  • Structured layout: Each field in its own container for readability

Visual Design System

  • Color-coded hierarchy: Different colors for entities, crate groups, components, and fields
  • Expand Indication: Reduced opacity for components without field data
  • Disclosure triangles: Clear expand/collapse indicators
  • Responsive design: Scrollable interface with hover effects (though mouse wheel doesn't work...)

Remote Inspection Support

  • bevy_remote integration: Connect to any Bevy app with remote plugin enabled
  • Reflection-based: Works with any component that implements Reflect and ReflectDeserialize
  • Graceful degradation: Components without reflection support still appear in tree

Testing

Basic Inspector Example

# Run basic inspector (empty until data source configured)
cargo run --example inspector -p bevy_entity_inspector

Remote Inspection Testing

# Terminal 1: Start target application with remote plugin
cargo run --example cube_server -p bevy_entity_inspector --features remote

# Terminal 2: Start inspector connected to remote app  
cargo run --example inspector -p bevy_entity_inspector --features remote

More Verifcation and Testing

Component Coverage Verified:

  • Transform hierarchy: Transform, GlobalTransform, TransformTreeChanged
  • Rendering components: Mesh3d, MeshMaterial3d, RenderEntity, SyncToRenderWorld
  • Lighting components: DirectionalLight, PointLight, SpotLight, ShadowSettings
  • Camera components: Camera, Camera3d, CameraRenderGraph, Projection
  • Visibility components: Visibility, ViewVisibility, InheritedVisibility
  • Custom components: User-defined components with reflection support

Performance Testing:

  • Large entity counts: Tested with 1000+ entities in remote mode
  • Component field expansion: Deep component field hierarchies
  • Real-time updates: Live component value changes during gameplay

UI/UX Validation:

  • Expansion indicators: Clear visual feedback for expandable vs non-expandable components
  • Crate grouping: Proper organization of Bevy engine vs user components
  • Tree navigation: Smooth expand/collapse with state preservation
  • Performance: Responsive UI even with large component trees

Showcase

With reflectable fields:
image

Just entity data:
image

No reflectable fields on the selected component:
image

@MiniaczQ
Copy link
Contributor

I couldn't get down to the exact issue, but server code gets stuck on this line:
https://github.com/bevyengine/bevy/blob/e9418b3845c1ffc9624a3a4003bde66a2ad6566a/crates/bevy_remote/src/http.rs#L399C8-L399C52

I think the issue may be caused by running sync requests in systems, effectively blocking the executor, so first step forward would be to rewrite it as async.

…plement a polling mechanism. Also will update the "Component Viewer" UI with the latest entity data based on the currently selected entity as well!
@jbuehler23

This comment was marked as outdated.

@alice-i-cecile alice-i-cecile added the S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged label Jun 25, 2025
…ty_inspector (using original bevy_component_viewer functionality). idea is to make this modular, so that it can be used for any bevy app
@jbuehler23 jbuehler23 changed the title [WIP] Add bevy_remote integration with a Component Viewer Pane [WIP] Add standalone bevy_entity_inspector and bevy_transform widget for drawing on the UI Jun 26, 2025
…nd Component Grouping

- Introduced an event-driven architecture replacing hash-based change detection with granular `InspectorEvent` system.
- Organized components by crate name in the tree UI for better clarity.
- Implemented a visual styling system with distinct colors for entities, crate groups, components, and fields.
- Enhanced UI organization to resemble professional ECS inspectors like Flecs.
- Improved change tracking efficiency by separately tracking added, removed, and updated entities.
- Updated `EntityInspectorRow` to include a `data_hash` field for change detection.
- Simplified component names to "crate::Type" format for remote inspection.
- Added comprehensive documentation for all public APIs and performance notes.
- Fixed runtime panic issues and improved memory efficiency.
- Created a theme configuration for the inspector with dark and light themes.
- Developed disclosure triangle UI components for collapsible tree nodes.
- Implemented a tree view UI for displaying hierarchical data with selection and expansion features.
- Added inspector panel and field widgets with customizable properties.
- Established integration tests for the inspector plugin functionality.
- Implemented a property panel example for displaying entity components.
- Created event system for entity inspector updates, including entity and component events.
- Developed reflection utilities for extracting and formatting component data.
- Built tree structures for the inspector UI, grouping components by crate.
- Designed a property panel UI for displaying detailed component information.
- Established UI management systems for handling inspector events and tree updates.
- Added camera setup for inspector rendering.
- Implemented tree node selection handling to update the property panel.
@alice-i-cecile alice-i-cecile added the C-Feature Make something new possible label Jul 9, 2025
@jbuehler23 jbuehler23 marked this pull request as ready for review July 9, 2025 19:00
@jbuehler23 jbuehler23 changed the title [WIP] Add standalone bevy_entity_inspector and bevy_transform widget for drawing on the UI Add standalone bevy_entity_inspector and bevy_transform widget for drawing on the UI Jul 9, 2025
@jbuehler23 jbuehler23 added S-Needs-Review Needs reviewer attention (from anyone!) to move forward and removed S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged labels Jul 9, 2025
/// These events are typically emitted by data source plugins (like the remote inspection plugin)
/// and consumed by the main event handler to update the tree UI.
#[derive(Event, BufferedEvent, Debug, Clone)]
pub enum InspectorEvent {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A comment here about why this is an enum, rather than multiple distinct events would be useful. I think it will probably make serde a bit nicer, and it's more discoverable, and they all fit together because they force a rebuild but I was initially quite confused.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, totally agree - I've gone back and added much more in-depth documentation.

Copy link
Member

@alice-i-cecile alice-i-cecile left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very nice! I still need to try this out hands-on. I would prefer if the two tools were split into distinct PRs, but I won't block on it.

I've left a few suggestions, but nothing blocking at this stage. Overall quality is good: this is something I'm comfortable refining.

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
@jbuehler23
Copy link
Contributor Author

jbuehler23 commented Jul 10, 2025

Very nice! I still need to try this out hands-on. I would prefer if the two tools were split into distinct PRs, but I won't block on it.

I've left a few suggestions, but nothing blocking at this stage. Overall quality is good: this is something I'm comfortable refining.

Nice! Thank you for the review. There's definitely some UX improvements we need to refine, and also there is some flickering happening every time we get the latest updates from BRP. I'll collate a list of refinements we should make as well as separate issues

I've also removed the bevy_transform widget stuff as that was mostly just early stage development really.

@alice-i-cecile alice-i-cecile added S-Needs-Review Needs reviewer attention (from anyone!) to move forward and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels Jul 10, 2025
* Add advanced entity outline calculations (#222)

* Add advanced entity outline calculations

The changes add sophisticated AABB (Axis-Aligned Bounding Box)
calculations for accurately drawing outlines around selected entities,
handling various entity types like meshes and sprites, and properly
accounting for hierarchies and transformations.

* minor changes

* Extract outline gizmo queries into SystemParam struct

The change extracts multiple queries used in the outline gizmo system
into a dedicated `OutlineGizmoQueries` struct that implements
`SystemParam`

* fmt

* Rename outline gizmo plugin to selection box plugin

* Rename outline gizmo to selection box

The changes are focused on renaming the outline gizmo functionality to
selection box, which includes renaming the module, component, functions
and UI text for better clarity and consistency.

* Launcher code quality improvements (#223)

* Simplify `selection_box::transform_aabb` (#224)

* Fix panel layout exploding when panels overflow (#227)

* Fix 3d viewport picking passthrough and camera input (#226)

* Fix 3d viewport picking passthrough and camera input

* Adjust docs

* Update to rust edition 2024 (#228)

* `cargo fix --edition` minus some unwanted changes

* Change edition to 2024

* `cargo format --all`

* Allow loading gltf/glb files from outside the assets directory (#231)

* Improve selection (#230)

* Improve selection

* Update crates/bevy_editor_core/src/selection.rs

Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>

---------

Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>

* Update .gitignore (#229)

* Depend on cart's BSN branch (#232)

* Update to `0294fa89db4e213ac8e186eed6966a7ea7459d1a`

This is the commit right before cart's BSN PR

* Depend on cart's BSN branch

* argh

* this time for real

* Update to latest commit + enable bevy_feathers + remove unintended changes to Cargo.toml

I'm keeping the `resolver = "3"` >:D

* Humble Beginnings for the `ActionRegistry` (#234)

* Port Viewport Panes to BSN and feathers (#233)

* Port Properties Pane to BSN and Feathers (#235)

* Port Properties Pane to BSN and Feathers

* Adjust editor core prelude

* Use Theme Colors for Viewgizmo (#237)

* Use theme colors for viewgizmo

* clipperry

* Vendor `bevy_transform_gizmo` (#236)

* Vendor `bevy_transform_gizmo`

Co-authored-by: Aevyrie <aevyrie@gmail.com>

* Remove stub

* Rename

* It compiles

* Kinda working + cleanup

* cleanup + fix parenting example

* bundle to required components

* Switch to observers + Finally working properly now :)

* refactoring + cleanup + docs

* more refactoring + finish writing docs

* refactor

* Delete `.gitignore`

* fixes

* Cleanup unwraps and errors + Add proper docs to crate root + auto add `MeshPickingPlugin` + add back `With<GizmoTransformable>`

* typooo

---------

Co-authored-by: Aevyrie <aevyrie@gmail.com>

* Document the Lucide placeholder icon font (#241)

* docs: add `styles.md` to design book

calling it the "Themes and Styles" page after this:
https://m3.material.io/styles

please feel free to change it if you want :)

* docs(styles.md): add info about icon set (Lucide)

* Update Bevy dependency (#242)

* Add support for selecting multiple entities (#240)

* Add support for selecting multiple entities

* Switch to `UniqueEntityVec`

* Rework removal

* Add `FromIterator` impl

* Add tests

* Fix up tests

* Remove brittle id gen in tests

* Enable Transform Gizmo (#244)

* Rework action keybinding (#243)

* Rework keybindings

* Reorder keybinding constructor parameters

* Update Bevy (#245)

* Update Bevy

* Fix Rust 1.89 Lints

* Reduce the amount of debug info generated in CI

* Switch back to cart's branch

* Trigger CI

* Remove Manual Type Registrations (#246)

* Transform Gizmo/UX updates (#247)

* Implement comprehensive Bevy editor features including toolbar, scene tree, and properties pane enhancements

* Enhance Bevy toolbar and transform gizmos integration with improved UI elements, keyboard shortcuts, and snapping features

* remove readme

* Remove IMPLEMENTATION_PLAN.md from .gitignore

* refactor: add a simple shared color theme system for usage throughout the editor. this should be easy to bring in line with bevy_feathers

* fix: remove broken test

* refactor: update doc comment

* cargo format result

* Added basic sorting for asset browser (#256)

* Added basic sorting for asset browser

* Remove Ord implementation for Entry and move ordering to seperate functions

* Remove temporary fix I accidentally made permenant

* Prevent crash due to malformed heirarchy (#254)

* Removed unwrap from `update_render_target_size` to prevent crash on startup

* Removed unnecessary import

* Fix ci out of space (#263)

* Update ci.yaml

* Make sure no error throw

* Try a more aggressive fix

* Pass all checks

* default config looks fine

* swatinem not cache worksapce, need rebuild everytime

* Revert "swatinem not cache worksapce, need rebuild everytime"

This reverts commit e6552c1.

* Revert "default config looks fine"

This reverts commit 3cb2853.

* Upgrade to 0.17 (#262)

* A minimal upgrade

* Correct the dependencies

* Continue

* Copy from @viridia (cart/bevy@ab73319)

* Continue

* target() -> event().event_target()

* EventWriter/Reader -> MessageWriter/Reader & add_event -> add_message

* Fix display issue

* Pass all checks

* I hope this work

---------

Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>

* Moved projects.ron to comply with XDG base directory standards (#265)

* Moved projects.ron to comply with XDG base directory standards

* Changed unwrap_or to unwrap_or_else to avoid panic when XDG_DATA_HOME exists but HOME is not set

* Fixed issues with clippy

* fix: update to workspace version of bevy

* fix: doc links using rust paths instead of web links where possible

---------

Co-authored-by: okhai <57156589+okhaimie-dev@users.noreply.github.com>
Co-authored-by: Tim <JustTheCoolDude@gmail.com>
Co-authored-by: JMS55 <47158642+JMS55@users.noreply.github.com>
Co-authored-by: Aevyrie <aevyrie@gmail.com>
Co-authored-by: Barrett Ray <66580279+onkoe@users.noreply.github.com>
Co-authored-by: Joe Buehler <jbuehler23@gmail.com>
Co-authored-by: Freyja-moth <156322843+Freyja-moth@users.noreply.github.com>
Co-authored-by: Sieluna <seele.peng@gmail.com>
Co-authored-by: Alice Cecile <alice.i.cecile@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

C-Feature Make something new possible S-Needs-Review Needs reviewer attention (from anyone!) to move forward

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Investigate usage of BRP in order to remotely inspect a running bevy application

4 participants