---
# System prepended metadata

title: Entity Inspector

---

# Entity Inspector

## Prior art

| Inspector Name | Author | Approach | GUI Framework |
|----------------|---------|------------------|--------------------|
| [bevy_inspector_egui](https://github.com/jakobhellermann/bevy-inspector-egui) | Jakob Hellermann | Direct use of reflection APIs | egui |
| [obsidian_ui_inspect](https://github.com/viridia/bevy_reactor_2/blob/main/crates/obsidian_ui_inspect/src/default_factory.rs#L19) | Viridia | Direct use of reflection APIs | Experimental reactive UI |
| [Joe's BRP-based inspector](https://github.com/bevyengine/bevy/pull/20189) | Joe Buehler | BRP | bevy_ui + text output |
| [Splo's Bevy Inspector for VSCode](https://marketplace.visualstudio.com/items?itemName=splo.vscode-bevy-inspector) | Splo | BRP | Web-stack rendering |
| [space_editor](https://github.com/rewin123/space_editor) | rewin123 | Full-fledged editor using reflection APIs | egui |
| [bevy_remote_inspector](https://github.com/notmd/bevy_remote_inspector) | notmd | BRP | Web-stack rendering (fully remote) |
| [birp](https://github.com/doup/birp) | doup | BRP | Dioxus |

## Architecture

Instead of building a single monolothic inspector, we intend to create a clean front-end/back-end split.
This allows us to reuse this infrastructure across various inspectors and custom dev-tools to meet the needs of each team without excessive work duplication.

The back-end interfaces with the Bevy world, presenting cleaned up, ready-to-use inspection results driven by a shared API.
This API is defined in Rust code, but can be called via BRP to support more diverse frontend clients (e.g. fully remote, web-based UIs).

Each front-end makes its own decisions for how to present the inspection results and allows users to refine what they would like to inspect.

## Features

Functionality is split into three major milestones:

1. Building a text-based frontend and the core backend infrastructure.
2. Building a read-only GUI inspector.
3. Adding value editing functionality to the GUI inspector.

Within these, features are prioritized based on complexity and importance.
Not all items from each milestone need be complete before starting work on the next, although all items in the "minimal" category and most in the "basic" category should be finished.

Items in the "hypothetical" categories may not be possible, feasible or even desirable!

### Text-based frontend

A text-based front-end will be used to quickly develop backend functionality,
while also creating helpful println-style debugging tools and presenting a screen-reader-friendly output.

Any functionality that *can* be prototyped with the text-based approach will be.

#### Text: Minimal

This milestone focuses on getting the core infrastructure

- methods for `Commands`/`EntityCommands`/`World` for:
    - inspecting specific entities
    - inspecting individual components of entities
    - inspecting all entities
    - inspecting resources
- read values
- store values as a string
- display values in a pretty text output

#### Text: Basic

- show entities in hierarchy
- API-driven customization output from inspections
    - show related entities when inspecting an entity
    - search filters
- component-driven customization of display output
    - report information about assets
- report summary stats when inspecting multiple entities
- infer names of entities from `Name` components, falling back to some combination of the components that they have
- show entity spawn details: location and tick
- group related entities together based on:
    - spawn location
    - archetype
- inspect the `RenderWorld`
- store values in structured form (e.g. RON) for easier parsing
- `Inspection` result types impl `Serialize` and `Deserialize`

#### Text: Advanced

- regex search filters
- value-range search filters
- works with dynamic components and resources
- inspect `Scenes`
- colored text output

#### Text: Hypothetical

- track and report spawn time
- `NonSend` support
- dev console integration

### GUI

Most users will prefer using a graphical solution for passively reporting and interactively debug problems.

This frontend will be built using `bevy_ui` + `bevy_feathers`, using the same backend as the text-based solution.

#### GUI: Minimal

- show entities
    - name (using name resolution from above)
    - entity ID
- show components of entities
- display via a node that users can place in their application as they please
- entities from the inspector do not show up in the inspector itself

#### GUI: Basic

- show entities in hierarchy
- fold entities / hierarchies / components
- display summary stats
- search filters
- multiple tabs
    - user spawned entities
    - engine/library spawned entities
    - resources
    - render world entities
    - render world resources
- display in a window
- convenient hotkey-based toggling via a plugin
- some form of pagination to avoid performance problems

#### GUI: Advanced

- select entities from game via picking
- visualize color data
- asset previews
    - materials
    - meshes
    - sprites
    - sounds
- temporarily favorite entities in inspector
- persist inspector settings (e.g. favorited entities, search filters) between runs
- display warning for invalid (e.g. NaN) data
- copy-paste support
- component/resource definitions and docs

#### GUI: Hypothetical

- value plotting: show evolution of tracked values over time
- integration with system stepping
- track specific entities, showing changes
- system graph inspection
- render graph inspection

### Editing

With a basic read-only GUI in place, we should allow users to edit the values interactively.

#### Editing: Minimal

- modify component and resource values using reflcection
- widgets for editing:
    - enums
    - text entry
    - number spinners

#### Editing: Basic

- easily toggle visibility
- easily toggle enabled/disabled
- spawn and delete entities
- add and remove components
- reparent entities

#### Editing: Advanced

- reset to default value
- fancy widgets:
    - color picker

#### Editing: Hypothetical

- reset to originally spawned value
- persist changes made to entities via:
    - hotpatching
    - writing back to asset files
- enable and disable specific components
- bulk value editing

