The core of QuakeForge's configuration is the cvar.
Depending on the engine's use of the cvar, the value will be treated as a string, a floating point value, an integer value or even a vector value.
If a space is needed in the value, the value must be "quoted".
From the user's perspective, there are three types of cvar:
config.cfg
by the engine on shutdown or gamedir change (QuakeWorld). config.cfg
.<cvar> [value]
Display the current value of the specified cvar. If value
is given, set the cvar to value
. Does not create a new cvar.
set <cvar> <value>
Set the specified cvar to the specified value. If the cvar does not already exist, a new cvar will be created.
seta <cvar> <value>
Set the specified cvar to the specified value. If the cvar does not already exist, a new cvar will be created. Sets the cvar's archive flag so it will be automatically saved to config.cfg
by the clients.
setrom <cvar> <value>
Set the specified cvar to the specified value. If the cvar does not already exist, a new cvar will be created. Sets the cvar's read-only flag so it can no longer be modified in any way (not even by reset
or resetall
).
toggle <cvar>
Treat the cvar as a boolean value, changing it from off to on, or on to off. Any non-zero integer value is considered to be on, while zero and any string that parses as zero (does not start with a non-zero number) will be treated as off. The new value will always be either one (1) or zero (0).
cvarlist [foo]
Print a list of all cvars known to the engine (engine created or user created). If the foo parameter is given (any value), then extra information (cvar description, flags) will also be printed.
cycle <cvar> <value list>
Cause the cvar to cycle through the list of values. Each time this command is executed, the cvar will change to the value immediately after the cvar's current value in the list, cycling back to the beginning when the current value is the last value in the list. If the current value is not in the list, the cvar will be set to the first value in the list.
inc <cvar> [amount]
Add one (1) to the cvar's current numeric value. If the optional amount is given, add that value to the cvar's current numeric value. Using -1 (inc <cvar> -1
), this can be used as a dec
command.
reset <cvar>
Reset the specified cvar to its default (engine specified) value.
resetall
Reset all cvars to their default (engine specified values).
Many cvars in QuakeForge are read-only because changing them at runtime would either have little meaning or be difficult to implement. However, there is a way to change even a read-only cvars: using the set
command, the cvar can be created with the desired value before the engine creates the cvar (and sets its read-only flag). There are exactly three places where the cvar can be created before the engine does:
nq-x11 +set snd_rate 48000
) fs_globalcfg
cvar. fs_usercfg
cvar.fs_globalcfg
defaults to /etc/quakeforge
.conf on Linux and other UNIX like systems, and ~/quakeforge.conf
on Windows (QuakeForge will expand ~
to the value of the HOME environment variable if it is set, or WINDOWS if not).
fs_usercfg
defaults to either ~/.quakeforgerc
or ~/.config/quakeforge/quakeforge.conf
on Linux and other UNIX like systems, and ~/quakeforgerc
on Windows.
The global and user configuration files are normal Quake scripts, but only set
, seta
, and setrom
commands are executed.
It might seem strange to have the global and user configuration files specified by cvars, but QuakeForge's startup sequence is quite intense:
set
commands given on the Command Line. This way, fs_globalcfg
can be set. set
commands in the global configuration file. This way, fs_usercfg
can be set. set
commands given on the command line. Thus it is possible to override fs_usercfg
if it is set by the global configuration file (unless setrom
is used: BOFH). set
commands in the user configuration file. Any cvars set in the user configuration file override those set in the global configuration file. set
commands given on the command line. Thus cvars set on the command line override those set in either the user configuration file or the global configuration file (or both).During the above process, the only cvars created by the engine are fs_globalcfg
(just before reading the global configuration file) and fs_usercfg
(just before reading the user configuration file). Thus, it is possible to set any cvar in QuakeForge.
The above means that:
fs_globalcfg
. fs_globalcfg
or fs_usercfg
. setrom
instead of set
). setrom
is used on the command line, even setrom
in the config files can be overridden.