bevy_editor_prototypes icon indicating copy to clipboard operation
bevy_editor_prototypes copied to clipboard

Add standalone bevy_entity_inspector and bevy_transform widget for drawing on the UI

Open jbuehler23 opened this issue 7 months ago • 3 comments

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

jbuehler23 avatar Jun 20 '25 09:06 jbuehler23

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.

MiniaczQ avatar Jun 20 '25 13:06 MiniaczQ

Adding message from discord for visibility as well to show latest update:

So.....I've been playing around with polling usingbevy_remote every 100ms to retrieve transform data for the selected entity in the editor, and in the process built a separate "Components" pane - my thinking is that this would house the standard components like Transform data, etc. but obviously I'm happy to chop and change this.

The key takeaway with this is that I'm demoing it's possible to query the currently running app from the editor using bevy_remote, deserialize the JSON into a "TransformData" object and then add it to the UI. This gets us on the path of having a read-only scene viewer strictly using bevy_ui and bevy_remote (and technically uses serde and ureq crates but core bevy uses this anyway)

https://github.com/user-attachments/assets/f1cb79d5-16f3-41ea-b4ca-d10189759511

jbuehler23 avatar Jun 24 '25 15:06 jbuehler23

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.

jbuehler23 avatar Jul 10 '25 07:07 jbuehler23