|
1 |
| -# Remote Inspector Integration Status |
| 1 | +# Bevy Entity Inspector |
2 | 2 |
|
3 |
| -## Current Status: Work in Progress |
| 3 | +The Bevy Entity Inspector is a powerful debugging tool that allows you to inspect and monitor entities and components in real-time, both locally and remotely. It provides two distinct modes of operation: |
4 | 4 |
|
5 |
| -The remote inspector has been copied from `bevy_remote_inspector` into `bevy_dev_tools` but requires additional work to complete the integration. |
| 5 | +1. **Local Inspector** - An embedded, in-game inspector overlay |
| 6 | +2. **Remote Inspector** - An external application that connects to your game via `bevy_remote` |
6 | 7 |
|
7 |
| -## What Works |
| 8 | +## Local Inspector (In-Game Overlay) |
8 | 9 |
|
9 |
| -✅ **Original standalone inspector**: The original `bevy_remote_inspector` crate works perfectly: |
| 10 | +The local inspector provides an in-game overlay that can be toggled on/off during development. |
10 | 11 |
|
11 |
| -- High-performance virtual scrolling for thousands of entities |
12 |
| -- Real-time entity selection and component viewing |
13 |
| -- Static component data display |
14 |
| -- Connection status indicator |
15 |
| -- Comprehensive UI with scrollbars and responsive layout |
| 12 | +### Setup |
16 | 13 |
|
17 |
| -✅ **Target applications**: Demo applications work with `bevy_remote` |
| 14 | +Add the `InspectorPlugin` to your application: |
18 | 15 |
|
19 |
| -- Moving entities with changing component values |
20 |
| -- Auto-spawning entities for stress testing |
21 |
| -- Full bevy_remote integration |
| 16 | +```rust |
| 17 | +use bevy::dev_tools::inspector::InspectorPlugin; |
| 18 | +use bevy::prelude::*; |
22 | 19 |
|
23 |
| -## What Needs Work |
| 20 | +fn main() { |
| 21 | + App::new() |
| 22 | + .add_plugins(DefaultPlugins) |
| 23 | + .add_plugins(InspectorPlugin::debug()) // Use debug preset with F11 toggle |
| 24 | + .run(); |
| 25 | +} |
| 26 | +``` |
24 | 27 |
|
25 |
| -❌ **bevy_dev_tools integration**: The inspector code needs adaptation for bevy_dev_tools: |
| 28 | +### Usage |
26 | 29 |
|
27 |
| -- Import issues due to individual bevy crate dependencies vs full `bevy` crate |
28 |
| -- Missing `#[derive(Resource)]` and `#[derive(Component)]` annotations |
29 |
| -- System parameter type mismatches |
| 30 | +- Press **F11** to toggle the inspector overlay |
| 31 | +- Browse entities in the left panel |
| 32 | +- Click on entities to view their components in the right panel |
| 33 | +- Component values update in real-time |
30 | 34 |
|
31 |
| -❌ **Live streaming updates**: Currently only shows static snapshots |
| 35 | +### Example |
32 | 36 |
|
33 |
| -- Need to implement real SSE client for `bevy/get+watch` endpoint |
34 |
| -- Replace current polling simulation with true streaming |
35 |
| -- Add visual change indicators in UI |
| 37 | +Run the local inspector example: |
36 | 38 |
|
37 |
| -## Quick Start (Current Working Setup) |
| 39 | +```bash |
| 40 | +cargo run --example inspector --features="bevy_dev_tools" |
| 41 | +``` |
38 | 42 |
|
39 |
| -### 1. Run Target Application |
| 43 | +## Remote Inspector (External Application) |
40 | 44 |
|
41 |
| -```bash |
42 |
| -# From bevy_remote_inspector directory (original working version) |
43 |
| -cargo run --example moving_target_app |
| 45 | +The remote inspector runs as a separate application that connects to your game over HTTP using the `bevy_remote` protocol. This is particularly useful for: |
| 46 | + |
| 47 | +- Inspecting headless applications |
| 48 | +- Debugging without UI overlay interference |
| 49 | +- External tooling and automation |
| 50 | +- Multi-monitor setups |
| 51 | + |
| 52 | +### Setup |
| 53 | + |
| 54 | +#### Target Application (Your Game) |
| 55 | + |
| 56 | +Add `bevy_remote` plugins to enable external connections: |
| 57 | + |
| 58 | +```rust |
| 59 | +use bevy::prelude::*; |
| 60 | +use bevy::remote::{RemotePlugin, http::RemoteHttpPlugin}; |
| 61 | + |
| 62 | +fn main() { |
| 63 | + App::new() |
| 64 | + .add_plugins(DefaultPlugins) |
| 65 | + .add_plugins(RemotePlugin::default()) // Enable JSON-RPC |
| 66 | + .add_plugins(RemoteHttpPlugin::default()) // Enable HTTP transport |
| 67 | + // Your game systems here... |
| 68 | + .run(); |
| 69 | +} |
44 | 70 | ```
|
45 | 71 |
|
46 |
| -### 2. Run Inspector |
| 72 | +#### Inspector Application |
47 | 73 |
|
48 |
| -```bash |
49 |
| -# From bevy_remote_inspector directory (original working version) |
50 |
| -cargo run --bin bevy_remote_inspector |
| 74 | +Create a separate inspector app: |
| 75 | + |
| 76 | +```rust |
| 77 | +use bevy::prelude::*; |
| 78 | +use bevy::dev_tools::inspector::InspectorPlugin; |
| 79 | + |
| 80 | +fn main() { |
| 81 | + App::new() |
| 82 | + .add_plugins(DefaultPlugins) |
| 83 | + .add_plugins(InspectorPlugin) // Remote inspector (no debug preset) |
| 84 | + .run(); |
| 85 | +} |
51 | 86 | ```
|
52 | 87 |
|
53 |
| -## Migration Plan |
| 88 | +### Usage |
54 | 89 |
|
55 |
| -### Phase 1: Fix Compilation ✋ **Current Phase** |
| 90 | +1. **Start your target application** with `bevy_remote` enabled: |
| 91 | + ```bash |
| 92 | + cargo run --example server --features="bevy_remote" |
| 93 | + ``` |
56 | 94 |
|
57 |
| -- [ ] Fix bevy crate imports for bevy_dev_tools context |
58 |
| -- [ ] Add missing derive macros (`Resource`, `Component`) |
59 |
| -- [ ] Resolve system parameter type issues |
60 |
| -- [ ] Create working plugin example |
| 95 | +2. **Start the inspector** in a separate terminal/window: |
| 96 | + ```bash |
| 97 | + cargo run --example entity_inspector_minimal --features="bevy_dev_tools" |
| 98 | + ``` |
61 | 99 |
|
62 |
| -### Phase 2: Live Updates Implementation |
| 100 | +The inspector will automatically connect to `localhost:15702` and display your entities. |
63 | 101 |
|
64 |
| -- [ ] Replace HTTP client simulation with real SSE streaming |
65 |
| -- [ ] Implement `bevy/get+watch` endpoint client |
66 |
| -- [ ] Add visual change indicators to component viewer |
67 |
| -- [ ] Add connection management (start/stop per entity) |
| 102 | +### Features |
68 | 103 |
|
69 |
| -### Phase 3: Integration & Testing |
| 104 | +- **Real-time Updates**: Component values update live as they change |
| 105 | +- **Interactive UI**: Click to select entities, text selection with copy/paste |
| 106 | +- **Connection Resilience**: Auto-retry logic handles connection failures gracefully |
| 107 | +- **Performance**: Virtual scrolling efficiently handles large numbers of entities |
| 108 | +- **All Components**: Automatically discovers and displays all component types |
70 | 109 |
|
71 |
| -- [ ] Create plugin API for easy integration |
72 |
| -- [ ] Add comprehensive examples |
73 |
| -- [ ] Performance testing with large entity counts |
74 |
| -- [ ] Documentation and API polish |
| 110 | +### Connection Details |
75 | 111 |
|
76 |
| -## Technical Architecture |
| 112 | +- **Default Address**: `localhost:15702` |
| 113 | +- **Protocol**: HTTP with JSON-RPC 2.0 |
| 114 | +- **Endpoints**: |
| 115 | + - `/health` - Connection health check |
| 116 | + - `/jsonrpc` - Main JSON-RPC interface |
77 | 117 |
|
78 |
| -### High-Level Design |
| 118 | +## Component Registration |
79 | 119 |
|
80 |
| -```text |
81 |
| -Target App (bevy_remote) <--SSE--> Inspector Plugin <--> Bevy UI |
82 |
| - │ │ │ |
83 |
| - ├─ Component changes ├─ HTTP Client ├─ Entity List (Virtual Scrolling) |
84 |
| - ├─ Entity spawning/despawning ├─ SSE Streaming ├─ Component Viewer (Live Updates) |
85 |
| - └─ bevy/get+watch endpoint └─ Update Queue └─ Connection Status |
86 |
| -``` |
| 120 | +For components to be visible in the inspector, they must implement `Reflect`: |
87 | 121 |
|
88 |
| -### Files Structure |
89 |
| - |
90 |
| -```text |
91 |
| -src/inspector/ |
92 |
| -├── mod.rs # Plugin exports |
93 |
| -├── inspector.rs # Main plugin implementation |
94 |
| -├── http_client.rs # HTTP/SSE client for bevy_remote |
95 |
| -└── ui/ |
96 |
| - ├── mod.rs # UI module exports |
97 |
| - ├── entity_list.rs # Virtual scrolling entity list |
98 |
| - ├── component_viewer.rs # Live component display |
99 |
| - ├── virtual_scrolling.rs # High-performance scrolling |
100 |
| - ├── connection_status.rs # Connection indicator |
101 |
| - └── collapsible_section.rs # Reusable UI widget |
| 122 | +```rust |
| 123 | +use bevy::prelude::*; |
| 124 | +use serde::{Deserialize, Serialize}; |
| 125 | + |
| 126 | +#[derive(Component, Reflect, Serialize, Deserialize)] |
| 127 | +#[reflect(Component, Serialize, Deserialize)] |
| 128 | +struct Player { |
| 129 | + health: i32, |
| 130 | + speed: f32, |
| 131 | +} |
| 132 | + |
| 133 | +fn main() { |
| 134 | + App::new() |
| 135 | + .add_plugins(DefaultPlugins) |
| 136 | + .register_type::<Player>() // Required for reflection |
| 137 | + .run(); |
| 138 | +} |
102 | 139 | ```
|
103 | 140 |
|
104 |
| -## Implementation Details Available |
| 141 | +## Troubleshooting |
| 142 | + |
| 143 | +### Remote Inspector Issues |
| 144 | + |
| 145 | +**Inspector shows "Awaiting connection":** |
| 146 | +- Ensure target app is running with `bevy_remote` plugins enabled |
| 147 | +- Verify target app is listening on port 15702 |
| 148 | +- Check firewall/network connectivity |
105 | 149 |
|
106 |
| -📋 **Complete implementation plan**: See `LIVE_UPDATES_IMPLEMENTATION_PLAN.md` for detailed SSE streaming implementation with code examples. |
| 150 | +**Components not visible:** |
| 151 | +- Ensure components implement `Reflect` |
| 152 | +- Register component types with `.register_type::<YourComponent>()` |
| 153 | +- Verify components implement `Serialize`/`Deserialize` for remote inspection |
107 | 154 |
|
108 |
| -🎯 **Virtual scrolling**: Already implemented and working - handles 10,000+ entities efficiently. |
| 155 | +**Connection drops frequently:** |
| 156 | +- Check target application stability |
| 157 | +- Monitor network connectivity |
| 158 | +- The inspector will automatically retry connections |
109 | 159 |
|
110 |
| -🔧 **UI Components**: All UI components designed for upstream contribution to bevy_ui. |
| 160 | +### Local Inspector Issues |
111 | 161 |
|
112 |
| -## For Contributors |
| 162 | +**F11 doesn't toggle inspector:** |
| 163 | +- Ensure you're using `InspectorPlugin::debug()` not `InspectorPlugin` |
| 164 | +- Check if another system is handling F11 key input |
113 | 165 |
|
114 |
| -### To work on compilation fixes |
| 166 | +**UI elements not visible:** |
| 167 | +- Verify UI camera is present in your scene |
| 168 | +- Check for UI layer conflicts |
115 | 169 |
|
116 |
| -1. Focus on `src/inspector/inspector.rs` first - main plugin file |
117 |
| -2. Update imports to use individual bevy crates available in bevy_dev_tools |
118 |
| -3. Add missing derive macros where compilation errors indicate |
| 170 | +## Architecture |
119 | 171 |
|
120 |
| -### To work on live updates |
| 172 | +The inspector uses several key components: |
121 | 173 |
|
122 |
| -1. See `LIVE_UPDATES_IMPLEMENTATION_PLAN.md` for complete technical specification |
123 |
| -2. Start with `src/inspector/http_client.rs` - replace simulation with real SSE |
124 |
| -3. Test with `examples/moving_target_app.rs` for obvious component changes |
| 174 | +- **HTTP Client** (`crates/bevy_dev_tools/src/inspector/http_client.rs`): Manages remote connections and JSON-RPC communication |
| 175 | +- **UI Components** (`crates/bevy_dev_tools/src/inspector/ui/`): Entity list, component viewer, connection status |
| 176 | +- **Virtual Scrolling**: Efficient rendering for large entity lists |
| 177 | +- **Live Updates**: Real-time component value streaming |
125 | 178 |
|
126 |
| -## Current Workaround |
| 179 | +## Examples |
127 | 180 |
|
128 |
| -For immediate use of the remote inspector, use the original `bevy_remote_inspector` crate which is fully functional. The bevy_dev_tools integration can be completed over time while the working version remains available. |
| 181 | +| Example | Purpose | Command | |
| 182 | +|---------|---------|---------| |
| 183 | +| `inspector` | Local in-game overlay | `cargo run --example inspector --features="bevy_dev_tools"` | |
| 184 | +| `server` | Target app for remote inspection | `cargo run --example server --features="bevy_remote"` | |
| 185 | +| `entity_inspector_minimal` | Remote inspector client | `cargo run --example entity_inspector_minimal --features="bevy_dev_tools"` | |
0 commit comments