What are console variables?

Console variables are a way to have dynamic variables that can be set by executing console script files (also named config files). They are for example used to store the login server address or the name of the last realm the player connected to.

Config files

A config file isn't really a config file in the first place. It is actually more like a batch script, where one line represents a console command. The main command for config files is the set command, which will set the value of a console variable. Note that the set command will also create new console variables if such a variable doesn't exists yet.

Creating a console variable by code

You can create console variables by code. This is useful to take full advantage of all the features that are available, such as observing a console variable.

For example, you might have a console variable for the screen resolution of the game client. You can watch for changes to that console variable and make the respective calls to the graphics api to apply those changes immediatly. This is useful because the user can also change console variables in the game by running the /script chat command like so:

/script set gxResolution 1920x1080

To create the named console variable, you would do something like this in the client:

#include "console_var.h"

static ConsoleVar* s_myConsoleVar = nullptr;

void MyInitializationFunction()
{
    s_myConsoleVar = ConsoleVarMgr::RegisterConsoleVar("myVarName", "This is a help message text.", "defaultValue");
    ASSERT(s_myConsoleVar);  // Shouldn't be really needed but you know...
}
void MyDestroyFunction()
{
    ConsoleVarMgr::UnregisterConsoleVar("myVarName");
    s_myConsoleVar = nullptr;
}

Keep in mind that you don't have to keep track of a ConsoleVar variable yourself. This is only done in the example above to speed things up a little bit. You can always use ConsoleVarMgr::FindConsoleVar("myVarName"); which will return a ConsoleVar* or nullptr if no such console variable exists. The cost is a lookup in a std::map by key.

Also keep in mind, that a registered ConsoleVar is never deleted, but gets a flag assigned named CVF_Unregistered if it is unregistered. This is to allow for safe references of ConsoleVar-pointers and references in the code. An unregistered console var will not trigger any changed-events when it is changed while being unregistered and won't appear in console var lists nor will it be serialized to config files when asked to do so.

Observing a ConsoleVar instance

After you have obtained a valid ConsoleVar-instance pointer or reference, you can add an observer like this:

connection observerConnection = myConsoleVar.Changed.connect([](ConsoleVar& var, const std::string& oldValue)
{
    // This code is executed, whenever myConsoleVar's value was changed.
    // var is a reference to myConsoleVar in this case (as you could use the same observer on multiple console vars, this might be useful!)
    // oldValue is the previous variable value as string in case you need it
});

When you no longer want to be notified about changes, call the disconnect method of the observerConnection variable in the sample above. Note that the connection can also be a scoped_connection which will automatically disconnect on descruction of the connection object.

scoped_connection observerConnectionScoped = myConsoleVar.Changed.connect([]()
{
    // Same as above, but observerConnectionScoped will automatically disconnect
    // from Changed as soon as it becomes out of scope
});