Cvars (console variables or configuration variables) are a simple way to store settings you want to change at runtime without restarting your program.

They 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. There is also minimal 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.

Usage

```rust use cvars::SetGet;

// This struct contains all your config options.

[derive(SetGet)]

pub struct Cvars { grocketlauncherammomax: i32, grocketlauncher_damage: f32, }

// 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();

// 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(); ```

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 (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.

See cvars/examples/stdin.rs for a small runnable example.

For a real-world example, look at games using cvars:

• RecWars - uses the Macroquad console, every aspect of the gameplay is configurable, you can test it in your browsser
• RustCycles - uses the Fyrox console

Enums

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;

[derive(Debug, Clone, SetGet)]

pub struct Cvars { pub cl_splitscreen: Splitscreen, }

[derive(Debug, Clone, Copy, PartialEq, Eq, Display, EnumString)]

[strum(asciicaseinsensitive)]

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.

Skipping fields

If a field is not meant to be configurable, mark it with #[cvars(skip)].

Features

• [x] Derive macro SetGet to create settters and getters for cvars based on their name
  • [x] Statically typed (set, get)
  • [x] As string (set_str, get_string)
• [x] Function like cvars! macro to declare type and initial value on one line
• [ ] Save config to and load it from files - useful if your game has multiple balance presets
• [x] In-game console for the Fyrox engine
• [x] In-game console for the Macroquad engine
• [ ] Autocompletion for consoles / GUI

Features I am not planning - I might accept a PR if it's simple and maintainable but it's probably better if you implement them in your own crate:

• In-game console for the Bevy engine
• In-game console for the Egui UI toolkit
• Browser GUI for games without a console

Alternatives

• inline_tweak
  • Uses hashmaps - overhead on every access
  • Can't be used in some contexts (e.g. in a const)
  • Veloren switched to it from const-tweaker
• const-tweaker
  • Web GUI
  • Only supports a few stdlib types, no custom types
  • Has soundness issues according to tuna's author
  • Uses hashmaps - overhead on every access
• tuna
  • Web GUI
  • Unclear if it supports enums
  • Uses hashmaps - overhead on every access
• cvar
  • Uses a trait instead of a macro. The trait seems to need to be implemented manually so more boilerplate.
  • Has additional features (lists, actions) which 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 (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 players.

Development

Fast compiles (optional)

Use nightly, lld and -Zshare-generics

• Enable rust-toolchain-example.toml and .cargo/config-example.toml:
  • Run this in project root: ln -s rust-toolchain-example.toml rust-toolchain.toml; cd .cargo; ln -s config-example.toml config.toml; cd -

This can provide a 5x speedup on some projects, the other tips are less important.

Prevent rust-analyzer from locking the target directory

If you're using RA with clippy instead of check, add this to your VSCode config (or something similar for your editor):

json "rust-analyzer.server.extraEnv": { "CARGO_TARGET_DIR": "target/ra" }

Explanation: Normally, if rust-analyzer runs cargo clippy on save, it locks target so if you switch to a terminal and do cargo run, it blocks the build. This will make rust-analyzer use a separate target directory so that it'll never block a build at the expense of slightly more disk space. Alternatively, you could disable saving when losing focus, disable running check on save or use the terminal inside VSCode to build the project.

On linux, use the mold linker

• Get it here
• Run cargo commands like this: ~/your/path/to/mold -run cargo build

This gives a 10% reduction in build times on some projects. Might not be worth it for you.

License

AGPL-v3 or newer