bevy_xray 0.1.0

TUI tool to visualize Bevy state hierarchies, plugin dependencies, and schedule configurations
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91

<img src="https://raw.githubusercontent.com/morgenthum/bevy_xray/main/logo.png" alt="Bevy X-Ray" width="480">

[![CI](https://github.com/morgenthum/bevy_xray/actions/workflows/ci.yml/badge.svg)](https://github.com/morgenthum/bevy_xray/actions/workflows/ci.yml)
[![crates.io](https://img.shields.io/crates/v/bevy_xray.svg)](https://crates.io/crates/bevy_xray)
[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE-MIT)
[![Rust: 1.85+](https://img.shields.io/badge/rust-1.85%2B-orange.svg)](https://www.rust-lang.org)

A static analysis tool that visualizes <a href="https://bevyengine.org/">Bevy</a> game engine internals — state hierarchies, plugin dependencies, schedule configurations, and system set ordering.

## Screenshots

<figure>
  <img src="https://raw.githubusercontent.com/morgenthum/bevy_xray/main/tui_states.png" alt="TUI — State Hierarchies" width="720">
  <figcaption><em>TUI — State hierarchy with sub-states, computed states, and related plugins (source: Wild Spikes, theme: rose-pine)</em></figcaption>
</figure>

<figure>
  <img src="https://raw.githubusercontent.com/morgenthum/bevy_xray/main/tui_plugins.png" alt="TUI — Plugin Dependencies" width="720">
  <figcaption><em>TUI — Plugin details with sub-plugins, schedule usage, and system ordering (source: <a href="https://github.com/bevyengine/bevy">Bevy</a>, theme: dawn)</em></figcaption>
</figure>

<figure>
  <img src="https://raw.githubusercontent.com/morgenthum/bevy_xray/main/html_systemsets.jpg" alt="HTML — System Sets" width="720">
  <figcaption><em>HTML export — System set ordering with chain constraints and schedule grouping (source: <a href="https://github.com/avianphysics/avian">Avian Physics</a>, theme: moon)</em></figcaption>
</figure>

## Features

- **State Hierarchies** — Extracts `States`, `SubStates`, and `ComputedStates` with their relationships
- **Plugin Dependencies** — Maps plugin registrations, sub-plugins, and plugin groups
- **Schedule Configurations** — Parses `Update`, `FixedUpdate`, and custom schedules with system ordering
- **System Sets** — Tracks set definitions and ordering constraints (`before`, `after`, `chain`)
- **Multiple Output Formats** — Interactive TUI, JSON export, and self-contained HTML visualization

## Installation

```sh
cargo install bevy_xray
```

## Usage

Point `bevy-xray` at a Bevy workspace:

```sh
# Launch interactive TUI
bevy-xray --path /path/to/bevy/workspace

# Export as JSON
bevy-xray --path /path/to/bevy/workspace --json

# Export as self-contained HTML
bevy-xray --path /path/to/bevy/workspace --html > output.html

# Use a different theme (rose-pine, moon, dawn)
bevy-xray --path /path/to/bevy/workspace --theme dawn
```

### CLI Options

| Flag | Description | Default |
|------|-------------|---------|
| `--path` | Path to Bevy workspace root | `.` |
| `--json` | Export as JSON | — |
| `--html` | Export as self-contained HTML | — |
| `--theme` | Color theme: `rose-pine`, `moon`, `dawn` | `rose-pine` |

## Compatibility

| bevy_xray | bevy   |
|-----------|--------|
| 0.1       | 0.18   |

> **Note:** bevy_xray uses static analysis using `syn`, so it may need updates when Bevy introduces new API patterns.

## Project Structure

```
crates/
├── bevy_xray/          # TUI application and CLI
└── bevy_xray_parser/   # Static analysis and parsing library
```

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)

at your option.