CVars are global variables that are used for configuring the engine. More...

#include <CVar.h>

Inheritance diagram for ezCVar:

[legend]

Public Types
using	CVarEvents = ezEvent< const ezCVarEvent &, ezMutex, ezStaticsAllocatorWrapper >

Public Member Functions
virtual void	SetToDelayedSyncValue ()=0
	Copies the 'DelayedSync' value into the 'Current' value. More...

ezStringView	GetName () const
	Returns the (display) name of the CVar.

virtual ezCVarType::Enum	GetType () const =0
	Returns the type of the CVar.

ezStringView	GetDescription () const
	Returns the description of the CVar.

ezBitflags< ezCVarFlags >	GetFlags () const
	Returns all the CVar flags.

ezStringView	GetPluginName () const
	Returns the name of the plugin which this CVar is declared in.

Static Public Member Functions
static void	SetStorageFolder (ezStringView sFolder)
	Sets the path (folder) in which all CVar setting files should be stored. More...

static ezCVar *	FindCVarByName (ezStringView sName)
	Searches all CVars for one with the given name. Returns nullptr if no CVar could be found. The name is case-insensitive.

static void	SaveCVars ()
	Stores all CVar values in files in the storage folder, that must have been set via 'SetStorageFolder'. More...

static void	SaveCVarsToFile (ezStringView sPath, bool bIgnoreSaveFlag=false)
	Stores all CVar values into the given file. More...

static void	LoadCVars (bool bOnlyNewOnes=true, bool bSetAsCurrentValue=true)
	Calls LoadCVarsFromCommandLine() and then LoadCVarsFromFile()

static void	LoadCVarsFromFile (bool bOnlyNewOnes=true, bool bSetAsCurrentValue=true, ezDynamicArray< ezCVar * > *pOutCVars=nullptr)
	Loads the CVars from the settings files in the storage folder. More...

static void	LoadCVarsFromFile (ezStringView sPath, bool bOnlyNewOnes=true, bool bSetAsCurrentValue=true, bool bIgnoreSaveFlag=false, ezDynamicArray< ezCVar * > *pOutCVars=nullptr)
	Loads all CVars from the given file. Does not account for any plug-in specific files. More...

static void	LoadCVarsFromCommandLine (bool bOnlyNewOnes=true, bool bSetAsCurrentValue=true, ezDynamicArray< ezCVar * > *pOutCVars=nullptr)
	Similar to LoadCVarsFromFile() but tries to get the CVar values from the command line. More...

static void	ListOfCVarsChanged (ezStringView sSetPluginNameTo)
	Call this after creating or destroying CVars dynamically (not through loading plugins) to allow UIs to update their state. More...

Static Public Member Functions inherited from ezNoBase
static const ezRTTI *	GetStaticRTTI ()

Public Attributes
CVarEvents	m_CVarEvents
	Code that needs to be execute whenever a cvar is changed can register itself here to be notified of such events.

Static Public Attributes
static ezEvent< const ezCVarEvent & >	s_AllCVarEvents
	Broadcasts changes to ANY CVar. Thus code that needs to update when any one of them changes can use this to be notified.

Protected Member Functions
	ezCVar (ezStringView sName, ezBitflags< ezCVarFlags > Flags, ezStringView sDescription)

Additional Inherited Members
Protected Attributes inherited from ezEnumerable< ezCVar >
ezEnumerable *	m_pNextInstance

Detailed Description

CVars are global variables that are used for configuring the engine.

The state of a CVar can be automatically stored when the application is shut down, and during reloading of plugins. It will be restored again when the application starts again. This makes it possible to use them to tweak code that is work in progress or to change global settings. CVars are enumerable, which is why it is easy to present them in a console or a GUI at runtime, to allow modifying them while the application is running. It is very easy and convenient to temporarily add a CVar while some code is in development, to be able to try out different approaches. However, one should throw out all unnecessary variables after such work is finished. CVars are stored in one settings file per plugin. That means plugins can easily contain additional CVars for their own use and their states are restored at plugin loading time, as well. For the storage of CVars to work, the 'StorageFolder' must have been set. Also at startup the application should explicitly load CVars via 'LoadCVars', once the filesystem is set up and the storage folder is configured. The CVar system listens to events from the Plugin system, and it will automatically take care to serialize and deserialize CVar values whenever plugins are loaded or unloaded. CVars additionally allow to only change their visible value after a certain subsystem has been 'restarted', i.e. a user can change the CVar value at runtime, but when the 'current' value is read, it will not have changed. It will change however, once the application is restarted (such that code can initialize the engine with the correct values) or after the corresponding subsystem explicitly sets the CVar to the updated value. This is useful, e.g. for a screen resolution CVar, as changing this at runtime might be possible in a GUI, but the engine might not support that without a restart. Finally all CVars broadcast events when their value is changed, which can be used to listen to certain CVars and react properly when their value changes.

Member Function Documentation

◆ ListOfCVarsChanged()

void ezCVar::ListOfCVarsChanged ( ezStringView sSetPluginNameTo )

static

Call this after creating or destroying CVars dynamically (not through loading plugins) to allow UIs to update their state.

Broadcasts ezCVarEvent::ListOfVarsChanged.

◆ LoadCVarsFromCommandLine()

void ezCVar::LoadCVarsFromCommandLine	(	bool	bOnlyNewOnes = `true`,
		bool	bSetAsCurrentValue = `true`,
		ezDynamicArray< ezCVar * > *	pOutCVars = `nullptr`
	)

static

Similar to LoadCVarsFromFile() but tries to get the CVar values from the command line.

The CVars are loaded into the global system and thus automatically available everywhere after this call. Optionally they are returned via pOutCVars, so the caller knows which CVars have actually been loaded in this very step.

Note: A CVar will only ever be loaded once. This function should be called before LoadCVarsFromFile(), otherwise it could get flagged as 'already loaded' even if the value was never taken from file or command line.

◆ LoadCVarsFromFile() [1/2]

void ezCVar::LoadCVarsFromFile	(	bool	bOnlyNewOnes = `true`,
		bool	bSetAsCurrentValue = `true`,
		ezDynamicArray< ezCVar * > *	pOutCVars = `nullptr`
	)

static

Loads the CVars from the settings files in the storage folder.

The CVars are loaded into the global system and thus automatically available everywhere after this call. Optionally they are returned via pOutCVars, so the caller knows which CVars have actually been loaded in this very step.

This function has no effect, if the storage folder has not been set via 'SetStorageFolder' yet or it has been set to be empty.

If bOnlyNewOnes is set, only CVars that have never been loaded from file before are loaded. All other CVars will stay unchanged. If bSetAsCurrentValue is true, variables that are flagged as 'RequiresRestart', will be set to the restart value immediately ('SetToDelayedSyncValue' is called on them). Otherwise their 'Current' value will always stay unchanged and the value from disk will only be stored in the 'DelayedSync' value. Independent on the parameter settings, all CVar changes during loading will always trigger change events.

See also: LoadCVarsFromCommandLine()

◆ LoadCVarsFromFile() [2/2]

void ezCVar::LoadCVarsFromFile	(	ezStringView	sPath,
		bool	bOnlyNewOnes = `true`,
		bool	bSetAsCurrentValue = `true`,
		bool	bIgnoreSaveFlag = `false`,
		ezDynamicArray< ezCVar * > *	pOutCVars = `nullptr`
	)

static

Loads all CVars from the given file. Does not account for any plug-in specific files.

The CVars are loaded into the global system and thus automatically available everywhere after this call. Optionally they are returned via pOutCVars, so the caller knows which CVars have actually been loaded in this very step.

This function works without setting a storage folder.

If bOnlyNewOnes is set, only CVars that have never been loaded from file before are loaded. All other CVars will stay unchanged. If bSetAsCurrentValue is true, variables that are flagged as 'RequiresRestart', will be set to the restart value immediately ('SetToDelayedSyncValue' is called on them). Otherwise their 'Current' value will always stay unchanged and the value from disk will only be stored in the 'DelayedSync' value. Independent on the parameter settings, all CVar changes during loading will always trigger change events. If bIgnoreSaveFlag is set all CVars are loaded whether they have the ezCVarFlags::Save set or not.

See also: LoadCVarsFromCommandLine(); LoadCVarsFromFile()

◆ SaveCVars()

void ezCVar::SaveCVars ( )

static

Stores all CVar values in files in the storage folder, that must have been set via 'SetStorageFolder'.

This function has no effect, if 'SetStorageFolder' has not been called, or the folder has been set to be empty. This function is also automatically called whenever plugin changes occur, or when the engine is shut down. So it might not be necessary to call this function manually at shutdown.

◆ SaveCVarsToFile()

void ezCVar::SaveCVarsToFile	(	ezStringView	sPath,
		bool	bIgnoreSaveFlag = `false`
	)

static

Stores all CVar values into the given file.

This function works without setting a storage folder. If bIgnoreSaveFlag is set all CVars are saved whether they have the ezCVarFlags::Save set or not.

See also: LoadCVarsFromFile()

◆ SetStorageFolder()

void ezCVar::SetStorageFolder ( ezStringView sFolder )

static

Sets the path (folder) in which all CVar setting files should be stored.

The path is used by SaveCVars and LoadCVars. However those functions will create one settings file per plugin, so szFolder must not be a file name, but only a path to a folder.

After setting the storage folder, one should immediately load all CVars via LoadCVars.

◆ SetToDelayedSyncValue()

virtual void ezCVar::SetToDelayedSyncValue ( )

pure virtual

Copies the 'DelayedSync' value into the 'Current' value.

This change will not trigger a 'delayed sync value changed' event, but it might trigger a 'current value changed' event. Code that uses a CVar that is flagged as 'RequiresDelayedSync' for its initialization (and which is the reason, that that CVar is flagged as such) should always call this BEFORE it uses the CVar value.

Implemented in ezTypedCVar< Type, CVarType >.

The documentation for this class was generated from the following files:

/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Configuration/CVar.h
/home/runner/work/ezEngine/ezEngine/Code/Engine/Foundation/Configuration/Implementation/CVar.cpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ ListOfCVarsChanged()

◆ LoadCVarsFromCommandLine()

◆ LoadCVarsFromFile() [1/2]

◆ LoadCVarsFromFile() [2/2]

◆ SaveCVars()

◆ SaveCVarsToFile()

◆ SetStorageFolder()

◆ SetToDelayedSyncValue()