mirror of
https://git.code.sf.net/p/quake/quakeforge
synced 2024-11-22 12:31:10 +00:00
Do some work on the user documentation.
Also document part of the cvar api.
This commit is contained in:
Bill Currie
parent
e8e8dad535
commit
1e827485ef
5 changed files with 174 additions and 39 deletions
|
|
@ -3,7 +3,7 @@ AUTOMAKE_OPTIONS= foreign
|
|||
SUBDIRS= man
|
||||
|
||||
DOX=\
|
||||
bind.dox connect.dox cshifts.dox dirconf.dox faq.dox \
|
||||
bind.dox config.dox connect.dox cshifts.dox dirconf.dox faq.dox \
|
||||
filesystem.dox mapformat.dox property-list.dox qtv.dox quakeforge.dox \
|
||||
qw-cap-spec.dox qw-download-spec.dox surround-sound.dox timestamps.dox
|
||||
|
||||
|
|
|
|||
122
doc/config.dox
Normal file
122
doc/config.dox
Normal file
|
|
@ -0,0 +1,122 @@
|
|||
//unfortunately, have to wrap the docs in a C comment for doxygen
|
||||
/**
|
||||
\page run_config Runtime Configuration.
|
||||
|
||||
\li \subpage cvars
|
||||
\li \subpage filesystem
|
||||
\li \subpage dirconf
|
||||
\li \subpage tracklist
|
||||
\li \subpage key_binding
|
||||
\li \subpage cshift_cvars
|
||||
\li \subpage server_timestamps
|
||||
|
||||
*/
|
||||
|
||||
/**
|
||||
\page cvars Configuration variables
|
||||
|
||||
The core of \QF's configurabitly is the cvar.
|
||||
|
||||
\section cvar_value Cvar values.
|
||||
Depending how 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 cvarsing 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-glx +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.
|
||||
|
||||
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 command line. 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.
|
||||
|
||||
*/
|
||||
|
|
@ -7,6 +7,7 @@
|
|||
\li \ref git_compile_error
|
||||
\li \ref no_music
|
||||
\li \ref no_mp3
|
||||
\li \ref faq_cvar_rom
|
||||
|
||||
\section gfx_wad What does "W_LoadWadFile: unable to load gfx.wad" mean?
|
||||
The most common cause of this error is QuakeForge is unable to find
|
||||
|
|
@ -17,6 +18,8 @@ Linux (and other UNIX like operating systems), fs_userpath defaults to
|
|||
~/.quakeforge and fs_sharepath defaults to $prefix/share/games/quakeforge
|
||||
(distribution packages might alter the exact path).
|
||||
|
||||
See \ref filesystem for more details.
|
||||
|
||||
\section pak0_pak Where can I get pak0.pak?
|
||||
See \ref game_data
|
||||
|
||||
|
|
@ -60,4 +63,8 @@ the value appropriate for your system:
|
|||
Because they are not free. MP3 support is a patent minefield, and we really
|
||||
don't want to wind up with lawyers at ten paces, especially since we'd be
|
||||
unarmed with no armor, and they have rocket launchers and quad-damage.
|
||||
|
||||
\section faq_cvar_rom How do I set a read-only cvar (eg, snd_rate)?
|
||||
Read-only cvars can be set by creating them before the engine does. See
|
||||
\ref cvar_rom for details.
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -10,12 +10,5 @@ of players we can.
|
|||
|
||||
\li \subpage build-install
|
||||
\li \subpage faq
|
||||
\li \subpage key_binding
|
||||
\li \subpage cshift_cvars
|
||||
\li \subpage filesystem
|
||||
\li \subpage dirconf
|
||||
\li \subpage qw_cap_spec
|
||||
\li \subpage qw_download_spec
|
||||
\li \subpage server_timestamps
|
||||
\li \subpage qtv_overview
|
||||
\li \subpage run_config
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -38,42 +38,55 @@
|
|||
#include "QF/quakeio.h"
|
||||
|
||||
typedef struct cvar_s {
|
||||
const char *name;
|
||||
const char *string;
|
||||
const char *default_string;
|
||||
int flags;
|
||||
const char *name; ///< The name of the cvar.
|
||||
const char *string; ///< The current cvar value as a string.
|
||||
const char *default_string; ///< The default value of the cvar.
|
||||
int flags; ///< Cvar flags
|
||||
/** Callback for when the cvar value changes.
|
||||
|
||||
This allows for more flexibility in what happens when a cvar is
|
||||
nodifed than can be achieved with flags alone. While a similar could
|
||||
be done using commands, a cvar with a callback and CVAR_ARCHIVE set
|
||||
allows the setting to be saved automatically.
|
||||
|
||||
\param var This cvar.
|
||||
*/
|
||||
void (*callback)(struct cvar_s *var);
|
||||
const char *description; // for "help" command
|
||||
float value;
|
||||
int int_val;
|
||||
vec3_t vec;
|
||||
struct cvar_s *next;
|
||||
const char *description; ///< for "help" command
|
||||
float value; ///< The current cvar value as a float
|
||||
int int_val; ///< The current cvar value as an integer
|
||||
vec3_t vec; ///< The current cvar value as a vector
|
||||
struct cvar_s *next; ///< \internal Linked list of cvars.
|
||||
} cvar_t;
|
||||
|
||||
typedef struct cvar_alias_s {
|
||||
char *name;
|
||||
cvar_t *cvar;
|
||||
struct cvar_alias_s *next;
|
||||
char *name; ///< The name of the alias.
|
||||
cvar_t *cvar; ///< The cvar to which this alias refers
|
||||
struct cvar_alias_s *next; ///< \internal LInked list of aliases.
|
||||
} cvar_alias_t;
|
||||
|
||||
#define CVAR_NONE 0
|
||||
#define CVAR_ARCHIVE 1 // set to cause it to be saved to vars.rc
|
||||
// used for system variables, not for player
|
||||
// specific configurations
|
||||
#define CVAR_USERINFO 2 // sent to server on connect or change
|
||||
#define CVAR_SERVERINFO 4 // sent in response to front end requests
|
||||
#define CVAR_NOTIFY 32 // Will notify players when changed.
|
||||
#define CVAR_ROM 64 // display only, cannot be set by user at all
|
||||
#define CVAR_USER_CREATED 128 // created by a set command
|
||||
#define CVAR_LATCH 2048 // will change only when C code next does
|
||||
// a Cvar_Get(), so it can't be changed
|
||||
|
||||
// Zoid| A good CVAR_ROM example is userpath. The code should read "cvar_t
|
||||
// *fs_userpath = CvarGet("fs_userpath", ".", CVAR_ROM); The user can
|
||||
// override that with +set fs_userpath <blah> since the command line +set gets
|
||||
// created _before_ the C code for fs_basepath setup is called. The code goes
|
||||
// "look, the user made fs_basepath already", uses the users value, but sets
|
||||
// CVAR_ROM as per the call.
|
||||
/** \name cvar_flags
|
||||
Zoid| A good CVAR_ROM example is userpath. The code should read "cvar_t
|
||||
*fs_userpath = CvarGet("fs_userpath", ".", CVAR_ROM); The user can
|
||||
override that with +set fs_userpath \<blah\> since the command line +set
|
||||
gets created _before_ the C code for fs_basepath setup is called. The
|
||||
code goes "look, the user made fs_basepath already", uses the users value,
|
||||
but sets CVAR_ROM as per the call.
|
||||
*/
|
||||
//@{
|
||||
#define CVAR_NONE 0 ///< normal cvar
|
||||
#define CVAR_ARCHIVE 1 ///< set to cause it to be saved to
|
||||
///< config.cfg
|
||||
#define CVAR_USERINFO 2 ///< sent to server on connect or change
|
||||
#define CVAR_SERVERINFO 4 ///< sent in response to front end requests
|
||||
#define CVAR_NOTIFY 32 ///< Will notify players when changed.
|
||||
///< (not implemented)
|
||||
#define CVAR_ROM 64 ///< display only, cannot be set
|
||||
#define CVAR_USER_CREATED 128 ///< created by a set command
|
||||
#define CVAR_LATCH 2048 ///< will change only when C code next does
|
||||
///< a Cvar_Get(), so it can't be changed
|
||||
///< (not implemented)
|
||||
//@}
|
||||
|
||||
|
||||
// Returns the Cvar if found, creates it with value if not. Description and
|
||||
|
|
|
|||
Loading…
Reference in a new issue