196 lines
8.3 KiB
Plaintext
196 lines
8.3 KiB
Plaintext
//unfortunately, have to wrap the docs in a C comment for doxygen
|
|
// vim:tw=74:formatoptions-=l
|
|
/**
|
|
\page run_config Runtime Configuration
|
|
|
|
\li \subpage cmdline
|
|
\li \subpage cvars
|
|
\li \subpage cmdcvarlist
|
|
\li \subpage filesystem
|
|
\li \subpage dirconf
|
|
\li \subpage sound
|
|
\li \subpage tracklist
|
|
\li \subpage key_binding
|
|
\li \subpage cshift_cvars
|
|
\li \subpage server_timestamps
|
|
*/
|
|
|
|
/**
|
|
\page cmdline Command Line
|
|
The \QF servers (\c nq-server, \c qw-server, and \c qtv), and clients
|
|
(\c nq-x11, \c nq-sdl, \c qw-client-x11, \c qw-client-sdl etc) all parse
|
|
the program command line looking for console commands.
|
|
|
|
Console commands on the command line are marked with a \c + that follows
|
|
whitespace. They continue until the next \c + or \c - that follows
|
|
whitespace. This allows commands and arguments to contain \c + and \c - so
|
|
long as the preceeding character is not whitespace, but also prevents
|
|
command line switches (eg \c -nosound) from becoming part of the console
|
|
command. Using careful quoting, it is even possible for a command or
|
|
argument to beging with \c + or \c -.
|
|
|
|
The following command line will fail to set m_pitch because the -0.022
|
|
will not be part of the console command. <code>usage: setrom \<cvar\>
|
|
\<value\></code> will be displayed instead.
|
|
\verbatim
|
|
nq-x11 +setrom m_pitch -0.022
|
|
\endverbatim
|
|
|
|
The following command line will successfully set m_pitch to \c -0.022
|
|
because \QF will see the quotation mark before the \c - and thus \c -0.022 will be
|
|
part of the console command.
|
|
\verbatim
|
|
nq-x11 +setrom m_pitch \"-0.022\"
|
|
\endverbatim
|
|
\note The above works in bash. Other shells may vary.
|
|
*/
|
|
|
|
/**
|
|
\page cvars Config Variables (Cvars)
|
|
|
|
The core of \QF's configuration is the cvar.
|
|
|
|
\section cvar_value Cvar values.
|
|
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".
|
|
|
|
\section cvar_type Cvar types.
|
|
From the user's perspective, there are three types of cvar:
|
|
\li plain cvar: the value can be displayed or set, but will not be
|
|
automatically saved.
|
|
\li archive cvar: like a plain cvar, the value can be displayed or set, but
|
|
the cvar will be automatically saved to \c config.cfg by the engine on
|
|
shutdown or gamedir change (QuakeWorld).
|
|
\li read-only cvar: the value can be displayed but not changed in any way
|
|
(value or flags). If the cvar also happens to be an archive cvar (the
|
|
archive flag was set before the read-only flag), then the cvar will be
|
|
saved to \c config.cfg.
|
|
|
|
\section cvar_cmds Cvar related commands.
|
|
<code>\<cvar\> [value]</code><br>
|
|
Display the current value of the specified cvar. If \c value is given, set
|
|
the cvar to \c value. Does not create a new cvar.
|
|
|
|
<code>set \<cvar\> \<value\></code><br>
|
|
Set the specified cvar to the specified value. If the cvar does not already
|
|
exist, a new cvar will be created.
|
|
|
|
<code>seta \<cvar\> \<value\></code><br>
|
|
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 \c config.cfg by the clients.
|
|
|
|
<code>setrom \<cvar\> \<value\></code><br>
|
|
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 \c reset or \c resetall).
|
|
|
|
<code>toggle \<cvar\></code><br>
|
|
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).
|
|
\note values smaller than 1 will be treated as off.
|
|
|
|
<code>cvarlist [foo]</code><br>
|
|
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.
|
|
|
|
<code>cycle \<cvar\> \<value list\></code><br>
|
|
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.
|
|
|
|
<code>inc \<cvar\> [amount]</code><br>
|
|
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
|
|
(<code>inc \<cvar\> -1</code>), this can be used as a \c dec command.
|
|
|
|
<code>reset \<cvar\></code><br>
|
|
Reset the specified cvar to its default (engine specified) value.
|
|
|
|
<code>resetall</code><br>
|
|
Reset all cvars to their default (engine specified values).
|
|
|
|
\section cvar_rom Read-only cvars
|
|
Many cvars in \QF are read-only because changing them at runtime would
|
|
either have little meaning or be difficult to implement. However, there
|
|
<em>is</em> a way to change even a read-only cvars: using the \c 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:
|
|
\li the command line (eg <code>nq-x11 +set snd_rate 48000</code>)
|
|
\li the global configuration file specified by the \c fs_globalcfg cvar.
|
|
\li the user configuration file specified by the \c fs_usercfg cvar.
|
|
|
|
\c fs_globalcfg defaults to \c /etc/quakeforge.conf on Linux and other
|
|
UNIX like systems, and <code>~/quakeforge.conf</code> on Windows (\QF will
|
|
expand <code>~</code> to the value of the HOME environment variable if it
|
|
is set, or WINDOWS if not).
|
|
|
|
\c fs_usercfg defaults to either <code>~/.quakeforgerc</code> or
|
|
<code>~/.config/quakeforge/quakeforge.conf</code> on Linux and other UNIX
|
|
like systems, and \c ~/quakeforgerc on Windows.
|
|
|
|
The global and user configuration files are normal Quake scripts, but only
|
|
\c set, \c seta, and \c setrom commands are executed.
|
|
|
|
It might seem strange to have the global and user configuration files
|
|
specified by cvars, but \QF's startup sequence is quite intense:
|
|
\li Execute any \c set commands given on the \ref cmdline. This way, \c
|
|
fs_globalcfg can be set.
|
|
\li Execute any \c set commands in the global configuration file. This way,
|
|
\c fs_usercfg can be set.
|
|
\li Re-execute any \c set commands given on the command line. Thus it is
|
|
possible to override \c fs_usercfg if it is set by the global configuration
|
|
file (unless \c setrom is used: BOFH).
|
|
\li Execute any \c set commands in the user configuration file. Any cvars
|
|
set in the user configuration file override those set in the global
|
|
configuration file.
|
|
\li Once again, re-execute any \c 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 \c
|
|
fs_globalcfg (just before reading the global configuration file) and \c
|
|
fs_usercfg (just before reading the user configuration file). Thus, it is
|
|
possible to set <em>any</em> cvar in \QF.
|
|
|
|
The above means that:
|
|
\li The \ref cmdline can be used to set any cvar in \QF.
|
|
\li The global config file can be used to set any cvar but \c
|
|
fs_globalcfg.
|
|
\li The user config file can be used to set any cvar but \c fs_globalcfg
|
|
or \c fs_usercfg.
|
|
\li The user config file can be used to override settings made in the
|
|
global config file, unless those settings have been made read-only by the
|
|
global config file (by using \c setrom instead of \c set).
|
|
\li The command line can be used to override settings made in either the
|
|
user config file or the global config file. If \c setrom is used on the
|
|
command line, even \c setrom in the config files can be overridden.
|
|
|
|
*/
|
|
|
|
/**
|
|
\page cmdcvarlist Command and Cvar Lists
|
|
Lists of commands and cvars by program.
|
|
|
|
For now, only nq-x11, qw-client-x11 and qw-server are covered (using the
|
|
ALSA sound plugin).
|
|
|
|
Commands:
|
|
\li <a href="/doc_cmds.php?program=nq-x11">nq-x11</a>
|
|
\li <a href="/doc_cmds.php?program=qw-client-x11">qw-client-x11</a>
|
|
\li <a href="/doc_cmds.php?program=qw-server">qw-server</a>
|
|
|
|
Cvars:
|
|
\li <a href="/doc_cvars.php?program=nq-x11">nq-x11</a>
|
|
\li <a href="/doc_cvars.php?program=qw-client-x11">qw-client-x11</a>
|
|
\li <a href="/doc_cvars.php?program=qw-server">qw-server</a>
|
|
*/
|