Table of Contents
The engine provides a CVar (configuration variable) system in <runtime/config.h>, that is used heavily in the engine to configure its various features.
Creating CVars
CVars are created with one of the RT_CVAR_ macros in <runtime/config.h>. These take a name, the description string and the default value respectively.
The convention used in the engine is to define CVars at the top of the file that uses them.
CVars use a tagged union to store values of different types. The macro used to define the cvar also sets the type.
At the time of writing this, the following types are available:
| Type | Creation macro | Union member |
|---|---|---|
| int | RT_CVAR_I |
.i |
| float | RT_CVAR_F |
.f |
| string | RT_CVAR_S |
.s |
| size_t | RT_CVAR_SZ |
.sz |
| unsigned int | RT_CVAR_UI |
.ui |
CVars must be registered to be able to retrieve them from other parts of the code (including changing them from configuration files).
This is done via rtRegisterCVAR.
The game provides a callback to launcher called RegisterCVARs that is called before initialization.
After registering the game cvars, the launcher loads and parses the game-config file, which then can modify these variables.
In the engine, each subsystem (runtime, renderer, asset_compiler, ...) handles its own CVars. Aside from the runtime, the launcher program makes sure to register these in the correct order and loads the associated configuration files.
Config-Files
Config files, by convention, are placed in the 'cfg' directory and use the file extension '.cfg'. They use INI file syntax. Currently, the system ignores sections.
Config files are loaded using the function rtProcessConfigFiles which takes a number of files, loads them and parses their contents.
Currently, the following configuration files are used by the engine:
| File | Purpose |
|---|---|
| cfg/engine_early.cfg | Configures the basic runtime systems (AIO, resource system, asserts, ...) |
| cfg/launcher.cfg | Configures the launcher executable (Window mode, renderer to use, game-lib, ...) |
| cfg/renderer.cfg | Configures render parameters |
| cfg/game.cfg | Game-specific configuration |
Listening to changes
The cvar system allows the user to register "change event handlers" for particular CVars.
This is done via rtRegisterCVARChangeEventHandler, which takes a callback of the form: void ChangeEventHandler(rt_cvar *cvar, void *userdata).
Whenever the system is notified of a cvar change (rtNotifyCVARChange) all registered callbacks for the changed cvar are called.
CVar naming convention
CVar names follow the pattern "systemCode_NameInPascalCase".
The system code is one of:
| System | Code | Example |
|---|---|---|
| runtime | rt | rt_AsssetEnabled |
| renderer | r | r_MaxRenderResources |
| vulkan-backend | r_Vk<Name> | r_VkPhysDeviceName |
| launcher | l | l_WindowTitle |