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:

plCVarBool
plCVarFloat
plCVarInt
plCVarString

Accessing and Modifying CVars

CVars are exposed in multiple ways.

plEditor

In Plasma Editor 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.

plInspector

plInspector 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

TypeScript

CVars can also be accessed through the TypeScript API.

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 plCVarFlags::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.

There is also plCVarFlags::RequiresRestart which means that modifying that variable will take no effect unless you restart the application. This can be used for things like screen resolutions and other initial values.

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>

plCVarBool cvar_DebugDisplay("Game.DebugDisplay", false, plCVarFlags::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)
{
  plDebugRenderer::DrawLineSphere(m_pMainWorld, plBoundingSphere(plVec3::ZeroVector(), 1.0f), plColor::Orange);
}

2.0 Help