Bevy Simple Subsecond System

Hotpatch your Bevy systems, allowing you to change their code while the app is running and directly seeing the results! This is a intermediate solution you can use until Bevy has implement this feature upstream.

Powered by Dioxus' subsecond
Please report all hotpatch-related problems to them :)

⚠️ Should work on Windows somehow, but I haven't yet figured out how! Let me know if you made it!

https://github.com/user-attachments/assets/a44e446b-b2bb-4e10-81c3-3f20cccadea0

First Time Installation

First, we'll install cargo-binstall. It's not strictly required, but it will make the setup much quicker. Click your OS below on instructions for how to do this

Set-ExecutionPolicy Unrestricted -Scope Process; iex (iwr "https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.ps1").Content

brew install cargo-binstall

or, if you don't use brew, same as on Linux.

curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash

cargo install cargo-binstall

Now, we need to install the Dioxus CLI of the newest alpha build:

cargo binstall dioxus-cli@0.7.0-alpha.0

Then make sure you're not using LD as your linker. Click your OS below on instructions for how to do this

In case you already configured a linker, setting rustflags = ["-C", "link-arg=-fuse-ld=/path/to/your/linker"] is surprisingly not enough!

Sorry friend, I didn't test this. All I know is that you can install rust-lld.exe by running

cargo binstall cargo-binutils
rustup component add llvm-tools-preview

You're in luck! The default linker on macOS is already something other than LD. You don't have to change a thing :)

Download clang and mold for your distribution, e.g.

sudo apt-get install clang mold

Then, replace your system ld with a symlink to mold. The most brutal way to do this is:

cd /usr/bin
sudo mv ld ld-real
sudo ln -s mold ld

On NixOS you can do this in a shell by replacing:

pkgs.mkShell {
    # ..
}

with:

pkgs.mkShell.override {
    stdenv = pkgs.stdenvAdapters.useMoldLinker pkgs.clangStdenv;
} {
    # ..
}

Usage

Add the crate to your dependencies:

cargo add bevy_simple_subsecond_system

Then add the plugin to your app:

use bevy::prelude::*;
use bevy_simple_subsecond_system::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(SimpleSubsecondPlugin::default())
        // rest of the setup
        .run();
}

Now you can annotate your systems with #[hot] to enable hotpatching for them:

use bevy_simple_subsecond_system::prelude::*;

#[hot]
fn greet() {
    info!("Hello from a hotpatched system! Try changing this string while the app is running!")
}

Note that greet is a regular Bevy system, so use whatever parameters you'd like.

After adding the system to your app, run it with

dx serve --hot-patch

Now try changing the string and saving the file while the app is running. If all goes well, it should print your new string!

use bevy::prelude::*;
use bevy_simple_subsecond_system::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(SimpleSubsecondPlugin::default())
        .add_systems(Update, greet)
        .run();
}

#[hot]
fn greet() {
    info!("Hello from a hotpatched system! Try changing this string while the app is running!")
}

Setup Methods

UI is often spawned in Startup or OnEnter schedules. Hot-patching such setup systems would be fairly useless, as they wouldn't run again. For this reason, the plugin supports automatically rerunning systems that have been hot-patched. To opt-in, replace #[hot] with #[hot(rerun_on_hot_patch = true)]. See the rerun_setup example for detailed instructions.

Examples

Run the examples with

dx serve --hot-patch --example name_of_the_example

e.g.

dx serve --hot-patch --example rerun_setup

Features

• Change systems' code and see the effect live at runtime
• Change system signatures at runtime, e.g. by adding a new query or modifying an existing one
• If your system calls other functions, you can also change those functions' code at runtime
• Rerun setup systems automatically when changing them
• Extremely small API: You only need the plugin struct and the #[hot] attribute
• Automatically compiles itself out on release builds and when targetting Wasm. The #[hot] attribute does simply nothing on such builds.

Known Limitations

• Cannot combine mold as your Rust linker with a global target dir
• Using this breaks dynamic linking
• A change in the definition of structs that appear in hot-patched systems at runtime will result in your query failing to match, as that new type does not exist in World yet.
  • Practically speaking, this means you should not change the definition of Resources and Components of your system at runtime
• All hotpatched systems run as exclusive systems, meaning they won't run in parallel
• Only the topmost binary is hotpatched, meaning your app is not allowed to have a lib.rs or a workspace setup.
• Attaching a debugger is problaby not going to work. Let me know if you try!
• I did not test all possible ways in which systems can be used. Does piping work? Does bevy_mod_debugdump still work? Maybe. Let me know!
• Some signatures are not supported, see the tests. Some have #[hot] commented out to indicate this
• Only functions that exist when the app is launched are considered while hotpatching. This means that if you have a system A that calls a function B, changing B will only work at runtime if that function existed already when the app was launched.
• Does nothing on Wasm. This is not a technical limitation, just something we didn't implement yet.

Compatibility