7 unstable releases (3 breaking)
0.4.0-alpha.3 | Aug 17, 2024 |
---|---|
0.4.0-alpha.0 | Aug 16, 2024 |
0.3.0 | Jul 4, 2024 |
0.2.0 | Feb 18, 2024 |
0.1.0 | Feb 18, 2024 |
#345 in Build Utils
28 downloads per month
Used in dexterous_developer
83KB
1K
SLoC
Dexterous Developer
A modular hot-reload system for Rust.
Docs for the latest release are available at: https://lee-orr.github.io/dexterous_developer/
You can also find docs for the latest pre-release and docs for the main branch
Features
- A CLI for building & running reloadable rust projects, including over the network (cross-device)
- Works directly with Binary crates!
- The ability to serialize/deserialize elements, allowing the evolution of schemas over time
- Only includes any hot reload capacity in your build when you explicitly enable it - such as by using the CLI launcher
- The capacity to create adapters for additional frameworks, allowing you to use Dexterous Developer tooling with other tools.
- Includes a first-party Bevy adapter
- Works on Windows, Linux, and MacOS
- On Linux, can be used to develop within a dev container while running on the main OS, enabling use of dev containers for games & other GUI apps.
Bevy Specific
- Define the reloadable areas of your game explicitly - which can include systems, components, events and resources (w/ some limitations)
- Reset resources to a default or pre-determined value upon reload
- Serialize/deserialize your reloadable resources & components, allowing you to evolve their schemas so long as they are compatible with the de-serializer (using rmp_serde)
- Mark entities to get removed on hot reload
- Run systems after hot-reload
- Create functions to set up & tear down upon either entering/exiting a state or on hot reload
Future Work
- Cross-platform hot reload - run a "hot reload server" on a development environment, and execute the application on a different OS
- Mobile support
- Browser-based WASM support
- WASI support
- Patching running libraries with intermediate compilation results
- Supporting the use of inter-process communication in addition to the current dynamic-library approach
- GUI-based launchers should be added, especially for mobile
- Supporting ECS hooks and observers in bevy
Installation
Install the CLI by running: cargo install dexterous_developer_cli@0.4.0-alpha.3
. This installs 2 command line utilities:
dexterous_developer_cli
- used to build the project, potentially running it at the same timedexterous_developer_runner
- used to run the project on another device
Setup
You'll also need to add the appropriate dexterous developer adapter to your library's dependencies, and set up the "hot" feature. For example, if you are using bevy:
[features]
hot = ["bevy_dexterous_developer/hot"]
[dependencies]
bevy = "0.14"
bevy_dexterous_developer = { version = "0.4.0-alpha.3"}
serde = "1" # If you want the serialization capacities
Finally, you'll need to set up a Dexterous.toml
file, that helps define some of the necessary elements - such as which folders should be watched for changes, and what features should be enabled. See the example file in this repository or the book for more info.
Bevy Setup
In your main.rs
, your main function should become:
reloadable_main!((initial_plugins) {
App::new()
.add_plugins(initial_plugins.initialize::<DefaultPlugins>()) // You can use either DefaultPlugins or MinimnalPlugins here, and use "set" on this as you would with them
// Here you can do what you'd normally do with app
// ... and so on
});
If you have a plugin where you want to add reloadable elements, add the following in the file defining the plugin:
impl Plugin for MyPlugin {
fn build(&self, app: &mut App) {
app
.setup_reloadable_elements::<reloadable>();
}
}
reloadable_scope!(reloadable(app) {
app
.add_systems(Update, this_system_will_reload);
})
The Simple Visual example shows the basic use of the library, and the book has more info as well.
Running with Hot Reload
To run a hot-reloaded app locally, cargo install and run dexterous_developer_cli
(optionally passing in a specific package or example).
To run the app on a different machine (with the same platform), cargo install dexterous_developer_cli
on both machines, and then:
- run the
dexterous_developer_cli --serve-only
on the development machine - run the
dexterous_developer_runner --server http://*.*.*.*:4321
command, ideally in a dedicated directory, on the target machine
Running or Building Without Hot Reload
To build or run the non-hot-reloadable version of your app, just remember to avoid including the hot
feature, since it's designed to work only inside a reloadable library!.
Inspiration
Initial inspiration came from DGriffin91's Ridiculous bevy hot reloading
Bevy Version Support
Bevy | Dexterous Developer |
---|---|
0.14 | >= 0.3 |
0.13 | = 0.2 |
0.12 | 0.0.12, 0.1 |
0.11 | <= 0.0.11 |
Dependencies
~43–83MB
~1.5M SLoC