Cvars (console variables or configuration variables) are a simple way to store settings you want to change at runtime without restarting your program.
Consoles are the most ergonomic way to set cvars but you can write your own UI or read them from stdin if you want.
These crates are inspired by the idTech (Doom, Quake) and Source family of game engines but they can be useful outside games. Cvars allow you to iterate faster by letting you test certain gameplay changes without recompiling. They also make your game more moddable if you expose (a subset of) them to players.
TL;DR: Set and get struct fields based on the field's name as a string. User writes the cvar's name and new value into the console, it sets the appropriate field in your config struct and the game now behaves differently. Your gamecode uses cvars as regular staticly typed values.
Usage example video worth 15*1000 words per second
Zero boilerplate - there are no traits to implement manually and no setup code to call per cvar.
Minimal performance cost - just struct field access vs hardcoded constant. Keep everything configurable even after you're done finding the best values - you can keep things tweakable in your released game for players to experiment themselves.
Cargo.toml:shell
cargo add cvars
SetGet:```rust use cvars::SetGet;
// This struct contains all your config options.
pub struct Cvars { grocketlauncherammomax: i32, grocketlauncher_damage: f32, // more cvars ... }
// Here you set default values. impl Cvars { pub fn new() -> Self { Self { grocketlauncherammomax: 20, grocketlauncher_damage: 100.0, } } }
// Store this in your game state. let mut cvars = Cvars::new(); ```
```rust // These normally come from the user // (from stdin / your game's console / etc.) let cvarname = "grocketlauncherdamage"; let new_value = "150";
// This looks up the right field and sets it to the new value. cvars.setstr(cvarname, new_value).unwrap(); ```
A modder wants rockets to do more damage. He types g_rocket_launcher_damage 150 into the game's console or stdin. You get both the cvar name and new value as strings so you can't do cvars.g_rocket_launcher_damage = 150. You need to look up the correct field based on the string - this is what cvars does - it generates set_str (and some other useful methods). You call cvars.set_str("g_rocket_launcher_damage", "150"); which looks up the right field, parses the value into its type and updates the field with it. From then on, rockets do 150 damage.
The important thing is that in the rest of your application, you can still access your cvars as regular struct fields - e.g. player.health -= cvars.g_rocket_launcher_damage;. This means you only need to use strings when the user (player or developer when debugging or testing a different balance) is changing the values. The rest of your gamelogic is still statically typed and using a cvar in gamecode is just a field access without any overhead.
A typical game will have hundreds or thousands of tunable parameters. With cvars and a console you can keep them all configurable for advanced players, modders and your-gamedev-self via a simple TUI while also exposing common settings to normal players in your game's GUI.
See cvars/examples/stdin.rs for a small runnable example.
For a real-world example, look at games using cvars:
The Fyrox console is a separate crate in this repo. To use it in your game, add it to your Cargo.toml and call its methods on the relevant engine events.
See the crates.io page or its docs for more information.
The Macroquad console is a separate crate in this repo. To use it in your game, add it to your Cargo.toml and call its update method every frame.
See the crates.io page or its docs for more information.
SetGet to create settters and getters for cvars based on their name
set, get)set_str, get_string)cvars! macro to declare type and initial value on one lineFeatures I am currently not planning to implement myself but would be nice to have. I might accept a PR if it's clean and maintainable but it's probably better if you implement them in your own crate:
const)cvars currently doesn't.Compared to these, cvars either has no overhead at runtime or requires less setup code. The downside currently might be slightly increased incremental compile times (by hundreds of milliseconds).
Cvars also serves a slightly different purpose than inline_tweak and const-tweaker. It's meant to stay in code forever, even after releasing your game, to enable modding by your game's community.
AGPL-v3 or newer