A library for doing live-reloading game development.

This is inspired by the article "Interactive Programming in C" by Chris Wellons, and the video "Loading Game Code Dynamically" from Handmade Hero by Casey Muratori.

The general idea is that your main host program is a wrapper around a dynamic library that does all the interesting work of your game. This means that you can simply reload the library while the game is still running, and have your game update live. As a consequence however, you can't have any global state in your library, everything must be owned by the host in order to avoid getting unloaded with the library.

Currently, this library doesn't provide a good solution for calling back into the wrapper code, which you want to do for things like allocating memory. That will hopefully come in a new version of the crate very soon.

See the Host Example and Library Example sections for instructions on how to build a reloadable application.

Host Example

A program that hosts a reloadable library will need to load the library, and then periodically reload it. The Reloadable automatically installs a filesystem watcher for you so that it knows when the library file has been updated or replaced, and the reload method will only actually perform a reload if the file has changed. The core of your main loop will therefore usually look something like this:

use std::thread;

fn main() {
    let mut prog = live_reload::Reloadable::new("target/debug/libreload.dylib")
        .expect("Should successfully load");
    'main: loop {
        if prog.update() == live_reload::ShouldQuit::Yes {
            break 'main;
        }
        prog.reload().expect("Should successfully reload");
    }
}

Library Example

A live-reloadable library needs to register its entry-points so that the host program can find them. The [live_reload!][] macro lets you do this conveniently.

The lifecycle of your reloadable library will happen in a few stages:

• init gets called at the very beginning of the program, when the host starts for the first time.
• reload gets called on each library load, including the first time. This should be usually empty, but when you're in development, you might want to reset things here, or migrate data, or things like that. The pointer you're passed will refer to the same struct that you had when the previous library was unloaded, so it might not be properly initialized. You should try to make your struct be #[repr(C)], and only add members at the end to minimize the problems of reloading.
• update gets called at the host program's discretion. You'll probably end up calling this once per frame. In addition to doing whatever work you were interested in, update also returns a value indicating whether the host program should quit.
• unload gets called before a library unloads. This will probably be empty even more often than reload, but you might need it for some debugging or data migration purpose.
• deinit gets called when the host program is actually shutting down--it's called on the drop of the Reloadable.

Here's an example of a live-reloadable library that handles a counter.

#[macro_use] extern crate live_reload;
# fn main() {}
use live_reload::ShouldQuit;

live_reload! {
    state: State;
    init: my_init;
    reload: my_reload;
    update: my_update;
    unload: my_unload;
    deinit: my_deinit;
}

struct State {
    counter: u64,
}

fn my_init(state: &mut State) {
    state.counter = 0;
    println!("Init! Counter: 0.");
}

fn my_reload(state: &mut State) {
    println!("Reloaded at {}.", state.counter);
}

fn my_update(state: &mut State) -> ShouldQuit {
    state.counter += 1;
    println!("Counter: {}.", state.counter);
    ShouldQuit::No
}

fn my_unload(state: &mut State) {
    println!("Unloaded at {}.", state.counter);
}

fn my_deinit(state: &mut State) {
    println!("Goodbye! Reached a final value of {}.", state.counter);
}