Dealing with Config Files
This guide assumes the engine used is CNQ3 but is valid no matter the mod.
Config structure, loading and saving:
- Configuration files have the
.cfgextension and contain one command per line.
- Lines that are empty or start with "//" are ignored by the engine.
- Loading a config is done with the
execcommand. It executes each line as a command as if it were typed at the console.
- Writing a config is done with the
writeconfigcommand. It writes commands to set variables and bind actions to keys.
Configs written by the engine (
writeconfig) contain 2 types of information:
- The value of variables, e.g.
seta r_fullscreen "1"to enable full-screen mode.
- The list of key/action bindings, e.g.
bind space "+moveup"for jumping with the space bar.
Every mention of a config file in this guide assumes the file sits in the mod's directory. For CPMA, the config files would be in
When CNQ3 starts up, it will:
exec default.cfg(in mod folder or
exec q3config.cfg(in mod folder only)
exec autoexec.cfg(in mod folder only)
When the CNQ3 1.50+ client shuts down, it will:
If you don't change anything, your up-to-date and automatically loaded/saved config file will be
Note that older CNQ3 clients didn't write back to
q3config.cfg on exit, meaning that you were forced to either use
writeconfig or edit your config file manually whenever you wanted to make changes.
This is the recommend way of dealing with configs:
- Give your config a name that is not
autoexec.cfg. Let's call our example config
my.cfg, where "my" could be replaced by e.g. your player name.
autoexec.cfgwith a single line in it:
- Optional: create an empty
q3config.cfgand mark it as read-only.
- Pro: less duplicated work for the engine on load. It's dumb to set every variable twice.
- Pro: if your config is manually created and doesn't set every cvar, it means
q3config.cfg's content actually matters and your "real" config is split among both files.
- Con: you don't have the latest changes saved anymore. If you ever forget to
writeconfig, you can no longer salvage the changes from
In practical terms:
- You can never accidentally change or mess up your config by executing another config.
- You update your config by either using
writeconfig myor manually editing
- Selecting your default/start-up config is changing 1 line in
While some players like to create nice looking config files (grouping cvars and binds, adding comment lines with explanations, etc) that they edit manually, we recommend against this practise. Use
writeconfig instead so that your config file is truly complete and doesn't rely on engine/mod default values (which can change) and/or the content of
q3config.cfg for any variable you forgot to set in your manually-edited config.
default.cfg should really only be found in .pk3 files and provide default binds in case the other 2 configs (
autoexec.cfg) don't set up any. Otherwise, launching the game without
autoexec.cfg, you wouldn't be able to perform any action in game.
CNQ3 will not read
autoexec.cfg from baseq3 to avoid config pollution. Sharing configs across mods is still possible:
- In each mod folder using the shared config, add
autoexec.cfgwith a single line:
Configs created by
writeconfig will contain 3 different commands:
|unbindall||1||Clears the entire bind list: no action will be bound to any key.|
|bind||1 per bound key||Binds an action (or multiple actions) to a key.|
|seta||1 per variable||Assigns a value to a variable.
If the variable doesn't exist, it is created with the archived flag.
Only archived variables get written to config files by
Dealing with vstr scripts
If you have special scripts setting temporary variables for vstr commands (e.g. connecting to servers, toggling values, etc), then here's how to deal with it:
- Put those in a secondary config file, say
- Use the
setcommand to create your own temporary cvars, not