Cvars (console variables or configuration variables) are a way to store settings which the user might want to change at runtime without restarting. They are inspired by the idSoftware family of game engines but they can be useful outside games.
TL;DR: Set and get struct fields based on the field's name as a string.
Cvars aims to minimize boiletplate - there are no traits to implement manually and no setup code to call per cvar. There is also be no extra performance cost for keeping everything configurable even after you're done finding the best values - you can (and are meant to) keep things tweakable for your players to experiment themselves.
Your game's config is in a struct like this:
```rust use cvars::SetGet;
pub struct Cvars { grocketlauncherammomax: i32, grocketlauncher_damage: f32, }
impl Cvars { pub fn new() -> Self { Self { grocketlauncherammomax: 20, grocketlauncher_damage: 100.0, } } } ```
The player wants to change a cvar and 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 (among other things). You call cvars.set_str("g_rocket_launcher_damage", "150"); which looks up the right field and parses the value into its type. 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 reading or writing 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.
See examples/stdin.rs for a small runnable example.
For a real-world example, look at how RecWars uses cvars.
Cvar values can have any type which implements the FromStr and Display traits. If you want to use enums, it's best to derive these traits automatically via [strum](https://crates.io/crates/strum).
```rust use strum_macros::{Display, EnumString};
use cvars::SetGet;
pub struct Cvars { pub cl_splitscreen: Splitscreen, }
pub enum Splitscreen { Vertical, Horizontal, } ```
Tip: use #[strum(ascii_case_insensitive)] so players don't need to pay attention to capilatization when changing cvars - both "Vertical" and "vertical" will parse into Splitscreen::Vertical.
The minimum supported Rust version is currently 1.54 because of #![doc = include_str!("README.md")]. It could be lowered to 1.36 or 1.31 if somebody was interested in using this lib but couldn't use latest Rust.
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 linecvars doesn't.AGPL-v3 or newer