From cc20ee9fb53beacd43b700015f2acba46134b982 Mon Sep 17 00:00:00 2001 From: Kevin Trogant Date: Thu, 1 Aug 2024 08:51:58 +0200 Subject: [PATCH] Update CVar system --- CVar-system.md | 47 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 45 insertions(+), 2 deletions(-) diff --git a/CVar-system.md b/CVar-system.md index 84e8d08..e2a5bee 100644 --- a/CVar-system.md +++ b/CVar-system.md @@ -1,6 +1,49 @@ -The engine provides a CVar (configuration variable) system in , that is used heavily in the engine to configure its various features. +The engine provides a CVar (configuration variable) system in ``, that is used heavily in the engine to configure its various features. -**TODO: In depth description** +## Creating CVars + +CVars are created with one of the `RT_CVAR_` macros in ``. 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` | + +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](https://en.wikipedia.org/wiki/INI_file). +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