CVars

CVars are global variables used for configuring the runtime. They are used for development to enable or modify hidden features.

Types of CVars

Only a strictly limited set of CVar types is supported:

ezCVarBool
ezCVarFloat
ezCVarInt
ezCVarString

Accessing and Modifying CVars

CVars are exposed in multiple ways.

ezEditor

In ezEditor you can open Panels > CVars to show a panel that allows you to modify CVars. Be aware that some CVars only have an effect when simulating the scene, and some even only when using Play-the-Game mode. The latter mostly happens when the effect of a CVar is implemented by a Game State.

ezInspector

ezInspector allows you to modify CVars of the connected process using the same UI as the editor.

In-Game Console

In-game a convenient way to modify CVars is the console.

Press TAB to list all CVars
Type the beginning of a CVar name and press TAB to list CVars with just that prefix name.
Type CVarName = value to modify the CVar's value.
```
cvar_bool = true
cvar_bool =
cvar_int = 3
cvar_string = "test"
```
For boolean CVars, typing 'var =' will toggle the variables value, which can be very handy, especially combined with using F2 to repeat the previous console command.

You can also do basic arithmetic like so:
```
cvar_bool = not cvar_bool
cvar_int = cvar_int + 1
```

Script Code Access

CVars can also be accessed from script code.

Command Line

CVars can be set through command line arguments using this syntax:

MyGame.exe -CvarName Value

For example:

MyGame.exe -Game.DebugDisplay true -fmod_MasterVolume 0.1

Values specified through the command line take precedence over stored values.

Saving State

The value of a CVar is typically discarded when the program closes, however, if the CVar uses ezCVarFlags::Save, it will be saved and restored in the next run. Be careful with this flag, as it can be very confusing when it is used to toggle subtle behavior. Be especially careful keeping this flag in for production code.

Only values that differ from the CVar's default value are written to disk. Thus, if the default value changes later (for instance through a project default), it still takes effect for everyone who hasn't modified that CVar.

Game applications store these user specific values in the CVars folder of the application's user data directory (:appdata). ezPlayer uses a separate folder for every project, so modifying a saved CVar in one project doesn't affect other projects.

There is also ezCVarFlags::RequiresRestart which means that modifying that variable will take no effect unless you restart the application.

Project Default Values

The default value of a CVar is specified in code. A project can override these defaults with configuration files in its RuntimeConfigs folder:

RuntimeConfigs/CVars.cfg: Default values for all platforms.
RuntimeConfigs/CVars_<Profile>.cfg: Default values for a specific asset profile, for instance CVars_PC.cfg. Values in this file take precedence over the ones in CVars.cfg.

This allows a project to ship with different defaults, for instance for rendering quality settings, and to use different defaults for each platform.

Values from these files replace the default value of the CVar. When a CVar is reset to its default value, it is reset to the project default.

Saving Project Defaults

To create such a file, run the game, change the CVars to the desired values, and then call the console function SaveProjectCVars(). This writes the profile specific file (CVars_<Profile>.cfg) for the currently active asset profile. It contains every CVar whose value differs from its default, as well as the values that this file already contained before. Afterwards copy or rename the file to CVars.cfg, if the values should apply to all platforms.

This function is only available in development builds, and only works when the project folder is writable.

Callbacks

You can subscribe to events for either all CVars or specific ones, to be informed when a CVar is modified.

Example Code

You create a CVar simply by instantiating it as a global variable somewhere in a cpp file:

#include <Foundation/Configuration/CVar.h>

ezCVarBool cvar_DebugDisplay("Game.DebugDisplay", false, ezCVarFlags::Default, "Whether the game should display debug geometry.");

Then you can just treat it like a regular variable to read or write its value:

if (cvar_DebugDisplay)
{
  ezDebugRenderer::DrawLineSphere(m_pMainWorld, ezBoundingSphere::MakeFromCenterAndRadius(ezVec3::MakeZero(), 1.0f), ezColor::Orange);
}

Table of Contents