Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 25 commits into
base: main
Choose a base branch
from

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 <[email protected]>
@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
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
3 participants