Skip to content

Commit 9ae705e

Browse files
committed
ci: try and get passing builds for a final time :)
1 parent ca53d03 commit 9ae705e

17 files changed

+254
-289
lines changed
Lines changed: 143 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,128 +1,185 @@
1-
# Remote Inspector Integration Status
1+
# Bevy Entity Inspector
22

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:
44

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`
67

7-
## What Works
8+
## Local Inspector (In-Game Overlay)
89

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.
1011

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
1613

17-
**Target applications**: Demo applications work with `bevy_remote`
14+
Add the `InspectorPlugin` to your application:
1815

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::*;
2219

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+
```
2427

25-
**bevy_dev_tools integration**: The inspector code needs adaptation for bevy_dev_tools:
28+
### Usage
2629

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
3034

31-
**Live streaming updates**: Currently only shows static snapshots
35+
### Example
3236

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:
3638

37-
## Quick Start (Current Working Setup)
39+
```bash
40+
cargo run --example inspector --features="bevy_dev_tools"
41+
```
3842

39-
### 1. Run Target Application
43+
## Remote Inspector (External Application)
4044

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+
}
4470
```
4571

46-
### 2. Run Inspector
72+
#### Inspector Application
4773

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+
}
5186
```
5287

53-
## Migration Plan
88+
### Usage
5489

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+
```
5694

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+
```
6199

62-
### Phase 2: Live Updates Implementation
100+
The inspector will automatically connect to `localhost:15702` and display your entities.
63101

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
68103

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
70109

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
75111

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
77117

78-
### High-Level Design
118+
## Component Registration
79119

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`:
87121

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+
}
102139
```
103140

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
105149

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
107154

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
109159

110-
🔧 **UI Components**: All UI components designed for upstream contribution to bevy_ui.
160+
### Local Inspector Issues
111161

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
113165

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
115169

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
119171

120-
### To work on live updates
172+
The inspector uses several key components:
121173

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
125178

126-
## Current Workaround
179+
## Examples
127180

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

Comments
 (0)