1 unstable release

0.1.0 Oct 15, 2019

#895 in Game dev

MIT/Apache

36KB
604 lines

Latest release on crates.io Documentation on docs.rs

amethyst-console

A framework around cvar and imgui that allows you to easily modify system configurations at runtime in a user configurable way.

preview

Examples:

  • width 120 - Set width to 120
  • width - Print the current width
  • reset width - Reset width to its default value (100)
  • find a - Find all commands with a in their name
  • reset - Reset all variables to their defaults

Setup

Add this to your Cargo.toml

[dependencies]
amethyst-console = "0.1.0"

Basic Example

Create your config

Be sure it supports the default trait

#[derive(Default)]
pub struct MyConfig {
    pub height: f32,
    pub width: f32,
}

Implement the visit trait

impl IVisitExt for MyConfig {
    fn visit_mut_ext(&mut self, f: &mut dyn FnMut(&mut dyn cvar::INode), _console: &mut dyn IConsoleExt) {
        // You can add variables
        f(&mut cvar::Property("width", "Arena width", &mut self.width, 100);
        // Or callable functions
        f(&mut cvar::Action("color_test", "Test console colors", |_, _| color_test(console)));
    }
}

Create a system

  • Call create_system using a type parameter to specify the name of your config.
/// This will:
///    - Initialize the struct to its default value
///    - Add it to the world so other services can read in their run loops
///    - Create a console window with everything added by `visit_mut_ext`
let console_system = imgui_console::create_system::<MyConfig>();
  • Add the system to your app initialization.
let game_data = GameDataBuilder::default()
    .with_system_desc(console_system, "imgui_console", &[]) // <--- ADDED
    // ....

Use the config in your systems

impl<'s> System<'s> for ExampleSystem {
    // Use Read to grab the resource from the World
    type SystemData = (
            Read<'s, GameConfig>,
        );

    fn run(&mut self, (game_config, ): Self::SystemData) {
        // This print statement will change the moment a user types a set command,
        println!("width={}", &config.width);
    }
}

Add a console binding

Update your input.ron file. This will let users open/close the console.

(
    axes: {},
    actions: {
        "toggle_console": [[Key(Escape)]],
    },
)

Done

That's it. Your system is now configurable by the user intiated commands. Have fun!

See examples/demo_console.rs for a complete example with more comments.

Standalone usage

  • Disable the amethyst-system feature.
[dependencies.amethyst-console ]
version = "0.1.0"
default-features = false
features = []
  • Create a console window and your config
let mut console = imgui_console::create_console();

let mut config = MyConfig::default();
  • Call build in your render loop
let ui: imgui::Ui = ... ;

loop {
    // Some other redering code
    // ...

    // Draw the console.
    // Pass in the config you would like to be updated.
    let window = imgui::Window::new(im_str!("Console")).opened(&mut self.open);
    conosle.build(ui, window, &mut config);
}

Dependencies

~13–31MB
~457K SLoC