Code3Arena

PlanetQuake | Code3Arena | Articles | << Prev | Article 9 | Next >>

menu

  • Home/News
  • ModSource
  • Compiling
  • Help!!!
  • Submission
  • Contributors
  • Staff
  • Downloads

    Tutorials
    < Index >
    1. Mod making 101
    2. Up 'n running
    3. Hello, QWorld!
    4. Infinite Haste
    5. Armor Piercing Rails
    6. Bouncing Rockets
    7. Cloaking
    8. Ladders
    9. Favourite Server
    10. Flame Thrower
    11. Vortex Grenades
    12. Grapple
    13. Lightning Discharge
    14. Locational Damage
    15. Leg Shots
    16. Weapon Switching
    17. Scoreboard frag-rate
    18. Vortex Grenades II
    19. Vulnerable Missiles
    20. Creating Classes
    21. Scrolling Credits
    22. Weapon Dropping
    23. Anti-Gravity Boots
    24. HUD scoreboard
    25. Flashlight and laser
    26. Weapon Positioning
    27. Weapon Reloading
    28. Progressive Zooming
    29. Rotating Doors
    30. Beheading (headshot!)
    31. Alt Weapon Fire
    32. Popup Menus I
    33. Popup Menus II
    34. Cluster Grenades
    35. Homing Rockets
    36. Spreadfire Powerup
    37. Instagib gameplay
    38. Accelerating rockets
    39. Server only Instagib
    40. Advanced Grapple Hook
    41. Unlagging your mod


    Articles
    < Index >
    1. Entities
    2. Vectors
    3. Good Coding
    4. Compilers I
    5. Compilers II
    6. UI Menu Primer I
    7. UI Menu Primer II
    8. UI Menu Primer III
    9. QVM Communication, Cvars, commands
    10. Metrowerks CodeWarrior
    11. 1.27g code, bugs, batch


    Links

  • Quake3 Files
  • Quake3 Forums
  • Q3A Editing Message Board
  • Quake3 Editing


    Feedback

  • SumFuka
  • Calrathan
  • HypoThermia
  • WarZone





    Site Design by:
    ICEmosis Design


  •  
    ARTICLE 9 - Cvars, commands, and VM Communication
    by HypoThermia

    One of the most common questions I'm asked through e-mail is "How do I get the client to do something from the server code?"... or variations on the theme. The issue is made more complicated by the fact that client, server, and user interface each have their own methods and restrictions.

    This article aims to de-mystify the methods you can use to pass information between the three Virtual Machines (VM's). There are several complementary methods, and I'll outline the advantages and problems with each.

    We'll start with a desciption of the client/server/interface model in Quake3. Understanding the relationship between these components is at the core of the need to communicate between them. Some of the restrictions in the system are also clarified.

    We'll then move onto the main methods: the setting of variables, also called Cvars, and how they're related to configuration strings maintained by the server. We'll then look at the sending of console commands, and finish off by seeing how we can drive the server scripting engine.

    I've tried to write each main section as an overview and introduction to the sub-sections that follow. As the ideas and definitions can get confusing IT IS IMPORTANT THAT YOU READ AND UNDERSTAND EACH OF THESE OVERVIEWS before proceeding with the more specialized descriptions.

     

     

    1. Server, client, and user interface

    Whether you're compiling binaries or bytecode for the platform independant VMs, it's clear that the game is split into three parts: server (qagame), client (cgame), and user interface (ui). Each carries responsibility for implementing a separate part of the game. What isn't so obvious, and is often forgotten, is that there's a fourth part: the executable that runs the VMs.

    The server and client complement each other and carry just about everything needed to play the game. The server controls and arbitrates the game: it decides where a player is on the map, whether they've been hit by that rocket, and where the momentum kick sends their corpse. The final word in what happens in the game, the server makes sure that the game world remains consistant.

    On the other hand, the client has only a limited view of the world. It's given information by the server that it needs to present this localized view to the player... and little else.

    The client is responsible for drawing the screen, playing the sounds, and adding all those little meaty gibs. It also includes an understanding of the game physics so it can predict motion and make gameplay smoother over an Internet connection, but it doesn't settle the final position of the other players (or yourself).

    To make this clear with an example: the server concerns itself over who has the quad, applying the damage multiplier, and settling disputes when two players try to pick it up at the same time. The client is told who has the quad, plays announcements and damage sfx, and draws that blue glow that warns "something dangerous comes this way!"

    It's possible for the client and server to be on separate machines, this is how an Internet game is played. Communication has to occur over a time delay determined by the connection quality and latency (ping), so there will be a delay between a command being sent and received. There's nothing that can be done about that.

    The client and user interface are always on your local machine. Think of them as connected to your graphics and sound cards, and you won't go far wrong. Servers don't care about these things directly, the closest they get is sending out a command saying "play this sound" or "do this action".

    The user interface covers all of the menus and pages of controls used to set up personal preferences and game parameters. It is the user interface that draws the menu when you hit the Escape key while playing a game. Anything the behaves like a dialog box or page of controls is drawn (and interacted with) in the user interface.

    Finally, it's important to recognize that there's a fourth part to all this, hidden away from prying eyes because the source code isn't available: the binary executable. This runs the VMs required to play the game, manages the communication between the VMs, controls the network connection if there is one, and handles all the OpenGL drawing of the graphics.

    Any communication between VMs is going to have to pass through the binary executable. It's the only way.

     

    2. Cvars and configuration strings - passive changes of state

    Console variables (Cvars) store the current state of the game system in a way that can be accessed through the console while playing, and directly in the game code. Many Cvars are read only: you can't change their value. Some can only be modified when cheats are enabled. Most are saved for the next time you play Q3.

    As a variable a Cvar isn't a command that must be obeyed immediately. What usually happens is that your code will check the value the next time it needs to use it, and adjusts its behaviour depending on the value it finds stored.

    This is helped by the way a Cvar is updated. A copy of the Cvar is maintained in the source code, this can be read and used in any part of that source code module. This local copy is updated at regular intervals so you have both consistancy of value, and an (almost) up to date value.

    Note that we are accessing a "copy" in the source code, the original or "master" of the variable is stored and maintained by the executable. We'll talk about this in more detail when we look at how and when the Cvar copy is updated (section 2.2).

     

    2.1 Where to place your Cvar

    A Cvar is created in the code as a data structure. You need to provide a default initialization value, and flags that control access and if it will be saved in q3config.cfg for permanent storage.

    The Cvar that you access in your code is placed in either game/g_main.c, cgame/cg_main.c, or ui/ui_main.c. You need to choose the most appropriate place: there is no point in putting a Cvar that controls behaviour of the server in the user interface code!

    There are benefits to putting the Cvar in the correct place, described in section 2.2.

    You can place a Cvar in another source code file, but you won't get the benefit of automatic initialization and updating.

     

    Example - Setting up a Cvar

    We'll take a quick look at how you initialize a Cvar and make it available for the rest of your code to use. This example looks at the cg_drawFPS variable in the client that draws the frame rate counter on the screen.

    Although taken from cgame code it applies equally well to the ui in ui_main.c. Its done slightly differently in game, and we'll look at that in a moment.

    Taken from cg_main.c:

    vmCvar_t	cg_drawFPS;
    
    
    cvarTable_t		cvarTable[] = {
    	// earlier Cvars snipped
    
    	{ &cg_drawFPS, "cg_drawFPS", "0", CVAR_ARCHIVE  },
    
    	// following Cvars snipped
    };
    

    A variable of type vmCvar_t is created to store the current value. To take advantage of the automatic updating of the Cvar we need a reference in the array cvarTable[]. This reference takes four components, from left to right they are:

    &cg_drawFPS
    A pointer to the vmCvar_t that stores the Cvar value

    "cg_drawFPS"
    The name of the Cvar as typed into the console

    "0"
    The default initialization for the variable, this can be any string

    CVAR_ARCHIVE
    A flag controlling the behaviour of the variable

    You can find more of the CVAR_* flags in q_shared.h, they're quite well documented there.

    Finally, so that the Cvar can be accessed easily from within related source code files, you need to add a reference to the vmCvar_t into the local header file. For cgame this is cg_local.h, while the ui and game have their equivalent in ui_local.h and g_local.h respectively.

    For our example you'll find this in cg_local.h:

    extern	vmCvar_t		cg_drawFPS;
    

     

    I mentioned earlier that the server was slightly different. The change is in how the Cvar is linked into the list for automatic initialization. Here's what a typical Cvar looks like in g_main.c:

    vmCvar_t	g_gametype;
    
    cvarTable_t		gameCvarTable[] = {
    	// earlier Cvars snipped
    
    	// latched vars
    	{ &g_gametype, "g_gametype", "0", CVAR_SERVERINFO | CVAR_LATCH, 0, qfalse  },
    
    	// following Cvars snipped
    };
    

    The first four entries are identical to their cgame and ui counterparts, but there are two new entries at the end:

    0
    Always initialized as zero, this is the number of times the value of the variable has changed.

    qfalse
    If set to qtrue then an announcement (text message) is sent to all clients that this Cvar has been changed.

     

    2.2 When Cvars are updated

    Even though we can access the Cvars from within the source code, these are not the "master" or "primary" record of the Cvar value. This might sound surprising, but arises from the need to communicate these values between VMs.

    The authoritative value of each Cvar is stored within the executable running the client or server, and the Cvars within the source code are updated to reflect new values on a regular basis. This update might be slightly delayed, but ensures consistancy in use. More on this in a moment.

    In the situation where the client and server are running on separate machines, the client still has access to most of the server Cvars. They can only be read by the client, and not modified.

    The reverse situation where the server accesses a clients Cvars is complicated by the fact that the server can have multiple clients. The mechanism by which a server can access the client is covered in detail in section 2.3.3.

    The copy of the Cvars stored in each of the *_main.c is updated on a regular basis at a "convenient" point in the game play cycle. This point is usually slightly delayed from the time when it was modified in the primary record.

    For the client this update occurs just before the next screen is drawn by CG_DrawActiveFrame() in cg_view.c. This makes sense when you realize that these local copies can be accessed through the vmCvar_t data structure without reference to the primary record. For the entire frame that is about to be drawn you will get a consistant value for the Cvar if you use the value stored in a vmCvar_t variable structure.

    This is important. Go back, read and understand that last paragraph again. Even if the Cvar changes in the primary record while the client is rendering the screen, you get a consistant value to work with while drawing the entire screen. If you always grab the "most up to date value" with a trap_* call then you might get rendering errors for that frame. Also, if you change the value of a Cvar through a trap_* call then you won't see the new value until the next update.

    For the user interface this Cvar update occurs every time the screen is drawn in UI_Refresh() in ui_atoms.c. For the server code the update is triggered in G_RunFrame() in g_main.c, when the server updates the postion of each entity in the world.

    As you can see, the Cvars are updated frequently, but not so frequently as to disrupt a frame of activity. The benefit of these local copies is twofold: constancy and speed of access to a local data structure.

     

    2.3 Reading and setting a Cvar

    With the Cvar created, we need to look at how the value within it can be accessed and changed. The user interface and client behave in a similar way, while there are special considerations for the server.

    By using a trap_* function to set the variable the primary record is updated correctly. You MUST NOT change the value of the local copy of the Cvar - it won't be moved to the primary record, and will only be over-written at the next update. If the Cvar is archived in q3config.cfg then the new value won't be saved either.

    A Cvar data structure looks like this:

    typedef struct {
    	cvarHandle_t	handle;
    	int		modificationCount;
    	float		value;
    	int		integer;
    	char		string[MAX_CVAR_VALUE_STRING];
    } vmCvar_t;
    

    You can read the value of the Cvar by accessing the value, integer, or string fields. This is only possible when the Cvar is stored within the VM you are coding in. In this case it is the optimal method of access. For a Cvar from another VM refer to the methods described below.

    Although, in principle, you can read and modify Cvars from other VMs, the most cautious approach is to treat Cvars from a different VM as read-only. You might need to know a clients preferences to help make the server run more efficiently, but indiscriminantly changing a clients preferences from the server is anti-social.

     

    2.3.1 Cvars in the ui

    The method used to set the value of the Cvar happens to be the same in all three modules, treating the Cvar as a string value that can be changed:

    void trap_Cvar_Set( const char *var_name, const char *value );
    

    var_name
    The name of the Cvar as typed on the console

    value
    The new string that replaces the old one

    The ui also has an additional method that sets the string using a float value rather than a string:

    void trap_Cvar_SetValue( const char *var_name, float value );
    

     

    Retrieving the value of the string is done through the complementary methods:

    void trap_Cvar_VariableStringBuffer(const char *var_name, char *buffer, int bufsize );
    float trap_Cvar_VariableValue( const char *var_name );
    

    var_name
    The name of the Cvar as typed in the console

    buffer
    Pointer to the char array to store the current string value in

    bufsize
    The size of the buffer for storing the string, prevents memory overflow and corruption

     

    Special methods - Configuration Strings

    These are described in great detail in the discussion of client Cvars (section 2.3.2, Special methods - Configuration strings). They represent a method that allows the client and user interface to read a set of strings that the server has set: these strings being common to (and used by) all connected clients.

    You can access these strings through a call to the following function:

    int trap_GetConfigString( int index, char* buff, int buffsize );
    

    index
    type of string you want to retrieve

    buff
    pointer to the buffer to store the configuration string into

    buffsize
    size of the buff array, I'd recommend using MAX_INFO_STRING

    You can't change the value of the configuration strings from the user interface. Check below in the client and server sections on how to process and extract information from them.

    (The truth be told: I didn't find out that the user interface could access these strings until after I'd written the client description of them. I'm too lazy to re-write that description for here :)

     

    2.3.2 Cvars in cgame

    Setting the value of a Cvar in cgame occurs through the same function call as in ui:

    void trap_Cvar_Set( const char *var_name, const char *value );
    

    You can read a Cvar's string value by making a call into the following function:

    void trap_Cvar_VariableStringBuffer( const char *var_name, char *buffer, int bufsize );
    

    and this behaves in the same way as the identically named function in the ui module.

     

    Special methods - Configuration Strings

    For quick access to important Cvars stored in the server, there is a flexible and powerful method available for use. Strictly speaking not all of variables passed through these configuration strings are Cvars, neither are all the server Cvars accessible through this method. However just about all the important ones you'll need in the client are available.

    These configuration strings are set and maintained by the server, and replicated to each client when a connection is first made. When the server updates any of these configuration strings, each connected client gets an updated version.

    These configuration strings are also used to pass information about other clients connected to a server. This information is limited (but useful), and includes things like player name, choice of model, and railgun trail colour. Take a look in ClientUserinfoChanged() in game/g_client.c to see how this string is constructed by the server, and in CG_NewClientInfo() in cgame/cg_players.c for parsing of this info in the client.

    The most up to date version of the configuration strings known to the client can be read through a call to:

    const char *CG_ConfigString( int index );
    

    index
    takes a value related to the type of string(s) you want to retrieve

    Most of the values that index can take are documented in bg_public.h as the CS_* family of flags. You can extend these values by adding new CS_* flags, it looks like there are gaps before CS_MODELS available for expansion, and about 350 free slots after the current value of CS_MAX.

    When a change is made to one of these configuration strings, the client gets notification though CG_ConfigStringModified() in cg_servercmds.c. You can add or extend any processing of the changed configuration string here, or examine how existing strings are parsed to gain further understanding.

    Setting these strings is described in the next section about the server. You can also add strings using two of the existing values of index provided (described below).

    You shouldn't move any of the CS_* values around because comments about the sound values in the source code suggests optimizations within the executable for sending this information across the network. As you can't change the executable, don't mess with the CS_* flags too much!

    The pointer returned by CG_ConfigString() can currently take two forms, and you need to find out which by examining how these CS_* returned strings are used in the source code. Take a look in CG_ConfigStringModified() in cg_servercmds.c or do a GREP through the source code to find out where else they're used or set.

    The first form is a simple string that contains the current value. An index value of CS_MOTD, CS_WARMUP, and CS_MESSAGE behave in this way. You can then process them with an atoi() if they're numerical, or treat them as strings.

    The second form is a list of variable names and value pairs. These can be queried through the provided method:

    char *Info_ValueForKey( const char *string, const char *key );
    

    string
    the pointer returned by CG_ConfigString()

    key
    the name of the Cvar string found on the server, and located in string

    You'll find that the two most powerful values of index are CS_SYSTEMINFO, and CS_SERVERINFO. They contain the server Cvars that are described respectively by the CVAR_SYSTEMINFO and CVAR_SERVERINFO flags in g_main.c.

    You can add your own Cvars in the server using these flags, they'll then be sent to each client when they're updated by the server. Use CVAR_SERVERINFO to describe a string that characterizes the game playing on the server (gametype, fraglimit, mapname etc.). Typically these are the values that a program like GameSpy-3D queries and displays. For the remaining Cvars that describe the low-level state of the sytem, CVAR_SYSTEMINFO should be used (g_syncronousClients is an example).

    Don't put frequently changing values into the CVAR_SERVERINFO or CVAR_SYSTEMINFO flags as the entire string is resent for the change of one variable. Very network inefficient.

    How the server sets these configuration strings is described later in this article.

     

    Example - Using Info_ValueForKey()

    Taken from CG_DrawInformation(void) in cg_info.c, we'll get the short name of the map (q3dm10, q3tourney6 etc.) from CS_SERVERINFO and load an image of the level ready for drawing.

    const char	*s;
    const char	*info;
    qhandle_t	levelshot;
    
    info = CG_ConfigString( CS_SERVERINFO );
    
    s = Info_ValueForKey( info, "mapname" );
    levelshot = trap_R_RegisterShaderNoMip( va( "levelshots/%s.tga", s ) );
    if ( !levelshot ) {
    	levelshot = trap_R_RegisterShaderNoMip( "menu/art/unknownmap" );
    }
    

    Initialization of mapname is slightly unusual and occurs as part of the bot AI in ai_main.c instead of g_main.c. Nevertheless, it has been correctly registered and flagged as CVAR_SERVERINFO.

     

    2.3.3 Cvars in game

    Just as in ui and cgame, we have to set the new value of a Cvar through this function:

    void trap_Cvar_Set( const char *var_name, const char *value );
    

    There are two methods available for reading the value of a Cvar. These are

    int trap_Cvar_VariableIntegerValue( const char *var_name );
    void trap_Cvar_VariableStringBuffer( const char *var_name, char *buffer, int bufsize );
    

    The former takes a Cvar name and returns its integer value, and the latter is used in the way described in the ui (section 2.3.1), above.

     

    Special methods - accessing Cvars set in a client

    Of particular importance to the server is the ability to obtain some of the client parameters. Some of these parameters might be used to optimize the servers behaviour towards that client, others repackaged and sent on to the remaining clients for accurate representation.

    For a client Cvar to be forwarded to the server when it is changed, it must be described by the CVAR_USERINFO flag. The only example of this is the teamoverlay Cvar in the client: it's also a CVAR_ROM so it can only be changed from within the source code, not on the console. This Cvar controls whether the server sends bandwith sucking stats during team games. Other critical Cvars appear to be flagged as CVAR_USERINFO by the executable directly.

    When a client changes one of its Cvars, the updated value is sent to the server and notification arrives at ClientUserinfoChanged() in g_client.c. The information can be validated (if required), modified (if absolutely necessary), or repackaged as a configuration string and sent on for other clients to use.

    The client configuration is read and set through the following functions:

    void trap_GetUserinfo( int num, char *buffer, int bufferSize );
    void trap_SetUserinfo( int num, const char *buffer );
    

    num
    the index value identifying the client

    buffer
    pointer to the buffer string for storing/setting the user info. I'd recommend char buffer[MAX_INFO_STRING]

    bufferSize
    size of the buffer string, preventing overflow on read

    The client index is just the array index of the global server array level.clients that points to the gclient_t data structure representing that player. Look in ClientConnect() in g_client.c to see this. To obtain the client index given a gentity_t* use the following code (which relies on the properties of C pointer subtraction):

    int clientNum;
    gclient_t* client;
    gentity_t* ent;	// must point to a valid entity structure
    
    client = ent->client;	// must be non-zero for an entity that's a client
    clientNum = client - level.clients;
    

    Just like the configuration strings described earlier, you can access the value pairs using Info_ValueForKey(). This example checks whether cg_predictItems is enabled in the client. It's derived from ClientUserinfoChanged() in g_client.c:

    int clientNum;	// set in the argument to ClientUserinfoChanged()
    gentity_t *ent;
    char	*s;
    gclient_t	*client;
    char	userinfo[MAX_INFO_STRING];
    
    ent = g_entities + clientNum;
    client = ent->client;
    
    trap_GetUserinfo( clientNum, userinfo, sizeof( userinfo ) );
    
    // check the item prediction
    s = Info_ValueForKey( userinfo, "cg_predictItems" );
    if ( !atoi( s ) ) {
    	client->pers.predictItemPickup = qfalse;
    } else {
    	client->pers.predictItemPickup = qtrue;
    }
    

     

    In order to use the special parsing function Info_ValueForKey() when constructing your own configuration strings, you need to know how to build these strings.

    There's a working example in ClientUserinfoChanged() in g_client.c, but we'll take a trivial one for clarity. This is how the string would be constructed in the C source (note that the double slash as used in the source code is reduced to a single slash by the compiler).

    "string_one_key\\string_one_value\\string_two_key\\string_two_value"
    

    Values are paired up: each having a unique identifying name (key) and an associated value. The '\\' character is used to separate the values, and you shouldn't pass this character as part of a key name or value (this will prevent Info_ValueForKey() from working), nor a quote ("), or a semi-colon (;). I got these limitations from Info_Validate() in q_shared.c, but be wary of using non-standard characters, and never use a string termination '\0'.

    In this example string_one_key and string_two_key are the possible arguments to Info_ValueForKey(), and string_one_value and string_two_value will be returned.

    The key values shouldn't need to be Cvars, they're just a means of identifying the associated value uniquely. If you are only ever going to send a single string value, then you don't need to use this key/value pair system.

    You will almost certainly end up constructing these strings using the va() variable argument substitution strings, I deliberately avoided them to reduce the complexity of this explanation.

     

    Although there are no examples of the server over-riding the client settings using trap_SetUserinfo(), presumable you just need to send the variables you want changed using the key/value pairing described above. The best place for the server to do this is in ClientUserinfoChanged() in g_client.c

     

    Special methods - configuration strings in the server

    As already described earlier from the point of view of the client, configuration strings contain global information that is maintained by the server. It is transmitted to all the clients connected to the server, and updated when changes are made by the server. The client can't modify these strings, but can (and does) make use of the information.

    A configuration string is read or changed using these functions:

    void trap_GetConfigstring( int num, char *buffer, int bufferSize );
    void trap_SetConfigstring( int num, const char *string );
    

    num
    the index of the configuration string

    buffer
    destination buffer for copying the config stirng to. Use a char array of size MAX_INFO_STRING

    bufferSize
    the size of buffer, prevents overflow

    string
    new value for the configuration string

    Each configuration string is described by an index CS_*, a list of these values can be found in bg_public.h. Although there's space for MAX_CONFIGSTRINGS (1024) values, the smallest amount of change that can be transmitted across a network connection is a single string. This is a network efficient way of transmitting state changes in the server, and other global variables maintained by the server.

    Two special config strings are CS_SYSTEMINFO and CS_SERVERINFO. Described in more detail in the client section above, the Cvars that belong to this group are automatically updated when they're modified by the server using trap_Cvar_Set(). Try to avoid putting frequently changing values in here because it's almost certain that all Cvar strings in this group are transmitted in one go, and this is network inefficient. You can create your own specific CS_* flags and groups instead (like CS_FLAGSTATUS).

    For an example we'll take a look at how the server updates CS_FLAGSTATUS, this code is from g_team.c:

    void Team_SetFlagStatus( int team, flagStatus_t status )
    {
    	qboolean modified = qfalse;
    
    	switch (team) {
    	case TEAM_RED :
    		if ( teamgame.redStatus != status ) {
    			teamgame.redStatus = status;
    			modified = qtrue;
    		}
    		break;
    	case TEAM_BLUE :
    		if ( teamgame.blueStatus != status ) {
    			teamgame.blueStatus = status;
    			modified = qtrue;
    		}
    		break;
    	}
    
    	if (modified) {
    		char st[4];
    
    		st[0] = '0' + (int)teamgame.redStatus;
    		st[1] = '0' + (int)teamgame.blueStatus;
    		st[2] = 0;
    
    		trap_SetConfigstring( CS_FLAGSTATUS, st );
    	}
    }
    

    The flag status is sent as a two digit pair, one each for the red and blue flags. Sending the values as a pair of numbers is a limitation of strings: we must avoid sending anything that might prematurely terminate the string (a char value of '\0'), so its encoded based on the ASCII value for the character '0'.

    This code fragment shows how its decoded in the client, in the function CG_ConfigStringModified() in cg_servercmds.c:

    } else if ( num == CS_FLAGSTATUS ) {
    	// format is rb where its red/blue, 0 is at base, 1 is taken, 2 is dropped
    	cgs.redflag = str[0] - '0';
    	cgs.blueflag = str[1] - '0';
    }
    

    and you can see that the binary value of zero, if stored directly in str[0], would have prevented the rest of the string from being transmitted. The status of the blue flag would then be unknown.

     

    2.4 Some special Cvars

    There are some Cvars that have slightly unusual properties. There are only a few of these Cvars, and I'll only touch on them briefly.

    One reason for these special Cvars is so that one VM can control or influence another in a transparent manner. The three Cvars that fall into this category are sv_running, cl_paused, and g_syncronousClients.

     

    If sv_running is set then the server is running on your local machine. This is important as its presence enables some menu items in the ui that can be used to influence the local server.

    You can also check for this in the client code by accessing cgs.localServer (zero if we're connected to a remote server), it's set in the following manner:

    char var[MAX_TOKEN_CHARS];
    trap_Cvar_VariableStringBuffer( "sv_running", var, sizeof( var ) );
    cgs.localServer = atoi( var );
    

     

    cl_paused is used to indicate to the client that the user interface has drawn a menu on screen while the client is running. Setting this variable to a value of 1 (one) will pause the game if the server is local. This appears to be managed by the executable, stopping the server and client VM's temporarily, rather than in any of the VM code itself.

     

    The third variable is g_syncronousClients, this is set if the server allows demo recording, and it also plays a part in client side prediction. It is created in the server VM, and replicated to the client VM via the CS_SYSTEMINFO configuration string. The client can't modify this value, but it can be read in and acted upon.

    Note that the creation in the client of the vmCvar_t structure doesn't have any CVAR_* flags associated with it, this is because the server stored value is the one with the CVAR_ARCHIVE flag set. In other words, the server has control over the value, while the client contains only a reference.

     

    Another variable, apparently set by the executable, is bot_enable. If this is set to zero then bots aren't loaded onto the system. There is no corresponding copy stored in a VM, it appears to be managed by the executable running the server (but is available to the client). Again, some menu options depend on this value to determine whether they are enabled or not.

     

    3. Console commands - do this, now!

    With the large amount of ground covered by the Cvars and server configuration strings, you're going to find console commands has less content. Unfortunately the picture is made difficult to follow because of the possibility of confusion between the client and server consoles. In addition the server can issue commands to the client, in a way that looks like the console commands, but is in fact separate. I've tried to give the best description of these as I possibly can below.

    Client console commands, as their name suggests, can be typed in from the drop down console. There is also a way of executing these commands from within the source code. Whether the command originates from the console or code is irrelevant when it's acted upon. This means that these commands can't be hidden from the user in the same way as configuration strings can.

    A client console command can be handled in either the user interface, client, or server parts of the code. This makes it a very useful way of asking another VM to do something for you (for example: displaying a menu system using the user interface). We'll look at the client console in section 3.1.

    The server console is another matter. These commands control how the server behaves and they can only be accessed when the server is running on the same machine, or a particular client has the administrator privilige to change the setup of the server remotely. Some commands that fall into this category are addip and addbot, and we'll cover the server console in section 3.2.

    What is potentially confusing is that when the client and server are running on the same machine, both the client and server console commands are entered in the same way. The typing of commands through the drop down console is, at best, a confusing use of terminology.

    Apply this rule of thumb: A command typed in by the player is a client console command if is expected to behave the same whether the server is local (running on the same machine) or remote (on a LAN or across the Internet).

     

    3.1 Client console commands

    Once a console command has been recognized (Cvars are filtered out first), it arrives at the handler for each of the VM modules. For the user interface this handling function is UI_ConsoleCommand() in ui_atoms.c, the client has CG_ConsoleCommand() in cg_consolecmds.c, while the server uses ClientCommand() in g_cmds.c.

    Some pre-processing has already been done for you, and you can get at arguments for the command by using trap_Argv(int pos) (the argument at a given position), and trap_Argc() (the total number of arguments). The user interface and client have "wrappered" versions that can also be accessed through UI_Argv() and CG_Argv(). You'll find that Argv(0) is always the command string itself.

     

    3.1.1 Client console commands in the user interface

    There's no rocket science to adding a console command to the user interface: just add a Q_stricmp( cmd , "yourcmd")==0 comparison into UI_ConsoleCommand() and route it to you handling function.

    The most obvious use of a command in the user interface is to pull up a menu for the user to interact with, and there's an obvious example in the ui_teamOrders command. One thing to be cautious of if you're displaying a menu: you'll need to protect against repeatedly adding new menus until the menu stack is used up.

    Surprisingly there's no way of sending out a console command from the user interface, it has to go through Cvars or server scripting (see section 4). I would guess that's because it's possible for the user interface to be running when the client and server code aren't. Any Cvars that are important and stored outside the user interface are latched anyway - so any updated value is still passed correctly.

    You can get some information about the state of the client through a call to trap_GetClientState(uiClientState_t*). This data structure is described in ui_public.h, and includes (amongst other things) access to the connection state of the client. This might influence how you draw the menu: in a connected game you'll want to leave the background "transparent" so the player can see the game screen. This code fragment taken from UI_ConfirmMenu() in ui_confirm.c shows how this is done:

    uiClientState_t	cstate;
    
    trap_GetClientState( &cstate );
    if ( cstate.connState >= CA_CONNECTED ) {
    	s_confirm.menu.fullscreen = qfalse;	// no black background
    }
    else {
    	s_confirm.menu.fullscreen = qtrue;
    }
    

    See my articles on the user interface menu for more information on how and why ths works.

     

    Special treatment - The In Game (ESC) Menu

    When you press the Escape key while playing a game you get the In Game Menu that allows you to change teams, add bots, change game settings etc. This menu is unusual: it doesn't use a console command to activate it.

    The ESC key is recognized in the executable and passed into the user interface VM through vmMain() in ui_main.c. Although several menus are created by this method, and all pass through UI_SetActiveMenu() in ui_atoms.c I haven't been able to find a way for the user to extend this and add their own menus.

    The good news is that you can use console commands to create your own menus. Just make sure that the commands in UI_SetActiveMenu() don't overwrite your menu, and that UIMENU_NONE is always honoured.

     

    3.1.2 Client console commands in cgame

    Once again, adding a client console command is straight forward. It's made even easier by the use of an array of console commands and associated function handlers in cg_consolecmds.c.

    As the code fragment below shows, just add an new entry into the the commands[] array, with your command name and your handling function. This handling function must be of type void function_name(void) for the array to work.

    typedef struct {
    	char	*cmd;
    	void	(*function)(void);
    } consoleCommand_t;
    
    static consoleCommand_t	commands[] = {
    	{ "testgun", CG_TestGun_f },
    	{ "testmodel", CG_TestModel_f },
    
    	// code snipped
    
    	{ "tcmd", CG_TargetCommand_f },
    	{ "loaddefered", CG_LoadDeferredPlayers }	// spelled wrong, but not changing for demo...
    };
    

     

    You can send out a client command to another VM by calling trap_SendConsoleCommand(const char* cmd_string). You can add arguments with additional information so long as you separate each of them with a space. When they arrive at the VM that handles them they'll already be processed so each argument is easily accessible.

    There is also a similarly named (and possibly confusing) function called trap_SendClientCommand(const char* cmd_string). This sends the command string directly to the server, without a chance being given to the user interface to act upon it. Use it as part of exclusively client-server issues.

    When the command string arrives at the server, whether it came from trap_SendConsoleCommand() or trap_SendClientCommand(), it is handled in ClientCommand() in g_cmds.c.

    This example shows how the tell_target client console command is broken down into a single tell command. Ultimately this will be processed in the server for distribution to the victim under the crosshair.

    static void CG_TellTarget_f( void ) {
    	int		clientNum;
    	char	command[128];
    	char	message[128];
    
    	clientNum = CG_CrosshairPlayer();
    	if ( clientNum == -1 ) {
    		return;
    	}
    
    	trap_Args( message, 128 );
    	Com_sprintf( command, 128, "tell %i %s", clientNum, message );
    	trap_SendClientCommand( command );
    }
    

     

    If you create a command in the server and you want TAB completion to work in the client, then you should also register the server command in the client. This is done in CG_InitConsoleCommands() in cg_consolecmds.c by adding another trap_AddCommand() to the list.

    Why do it this way? Well if the server is running on another machine then you don't want TAB completion to depend on the availability of the network connection.

     

    3.1.3 Client console commands in the server

    There are two types of command that the server can accept, so it's important to put your command into the right place. Go back and read the start of section 3 to understand the difference. We'll look at the client console commands here, while dealing with the server console in section 3.2.

    Since we're looking at client console commands we need to work in ClientCommand() in g_cmds.c. Each command that you add is just a straight forward Q_stricmp() comparison that passes control to your handler if passed.

    Note that there is a watershed between commands that can be executed at any point, and those commands which don't make any sense during the intermission (when a level is over and the scoreboard is displayed, but before the next level is loaded).

    If you want TAB completion of the command name in the client, then you'll need to add the name of the command as described at the end of section 3.1.2, above.

     

    I've not found a way for the server to send a client console command to a particular client (such a command could reach either the ui or cgame). However, there is a way that the server can send a command to the client (cgame), and this is covered in section 3.3. Although this seems to be the reciprocal method for sending a client console command from the server, the commands it sends can't be typed into the client - they can only be sent by the server.

     

    3.2 Server console commands

    Notice the change of subject!

    We're now talking about commands that get to the server console, described and defined at the start of section 3.

    These are the commands that can be typed on a client drop down console when the server is running on the same machine, or if the client has administrative privilige on a remote machine. Usually these commands have a drastic effect on gameplay or the behaviour of the server. You want to be careful who you let use these commands, and many of them might be made available through the voting system.

    All of these commands arrive in ConsoleCommand() in g_svcmds.c for processing (note that console in this case means server console). You don't need to do anything special to separate them from the client console commands, this is done for you automatically (and is outside your control!)

    As this snipped version of ConsoleCommand() shows, you need to return qtrue if you do handle the server command. Trace through the code to Svcmd_AddBot_f() in g_bot.c to see how trap_Argv() is used to grab the arguments to addbot.

    qboolean	ConsoleCommand( void ) {
    	char	cmd[MAX_TOKEN_CHARS];
    
    	trap_Argv( 0, cmd, sizeof( cmd ) );
    
    	// code snipped
    
    	if (Q_stricmp (cmd, "addbot") == 0) {
    		Svcmd_AddBot_f();
    		return qtrue;
    	}
    
    	// code snipped
    
    	return qfalse;
    }
    

     

    3.3 Commands issued to the client from the server

    When the server needs to send a command to one or all clients then it uses the following function:

    trap_SendServerCommand(int clientNum, const char* command_string)
    

    The clientNum is the identifying index of the client, look in section 2.3.3 for an example of how to get a clientNum if it isn't provided for you. clientNum may also be -1, in which case the command is broadcast to all connected clients.

    The command will arrive in the client in CG_ServerCommand() in cg_servercmds.c, all ready for the client to deal with.

    In an attempt to make this clear to a possibly confused reader, try the following experiment: start up Q3 and get a map going. Pull down the console and type in "/cp test" (without the quotes of course!). It will show an error message.

    Now look at CG_ServerCommand() in cg_servercmds.c for the cp command. It draws some text in the centre of the screen (cp - center print) and is sent by the server. Can you now see that commands sent by the server aren't connected to the client console?

     

    4. Server scripting - play the game

    The last method of control is aimed purely at the server. You can send a list of commands to the server (to be accurate, the binary executable running the game VM), that are equivalent to running a script. These commands remain in memory and are used (for example) to set up a map rotation. Think of this method as having the same effect as using the /exec command in the drop down console.

    You can add these commands from the user interface part of the source code, or as part of the game code. You are effectively limited to setting up and controlling a server on your machine only, or having a server manipulate its own script. It shouldn't be possible for a local user interface to manipulate a remote server using these functions.

    From within the user interface code:

    void trap_Cmd_ExecuteText( int exec_when, const char *text );
    

    and from within the server code:

    void trap_SendConsoleCommand( int exec_when, const char *text );
    

    Don't be confused by the fact it carries the same name as a function that's used in the client, its behaviour isn't the same. Think of it as acting on the server console only.

    The text argument is easy enough: it's the text string that contains a command or sets a variable. You should add a newline character '\n' when you issue a single command, or you can put a group of commands together in the same string, separated by a semi-colon, and terminated with a newline. If you don't put the newline in then you'll get two commands running together and confusing the executable's script engine.

    The other argument, exec_when, is a bit more difficult to understand from just code reading and without access to the source code for the executable. Here's the allowed values and what I've been able to glean:

    EXEC_NOW
    The string is executed immediately and control won't return to the VM until it's completed. Use with extreme caution in case a command that you use causes the VM to unload and then reload.

    EXEC_INSERT
    This flag causes a command to be "forgotten" about after it's executed. Control will return immediately while the command is queued for execution in the immediate future.

    EXEC_APPEND
    Think of this as appending text to a script file that's stored by the server. Control returns immediately, and values will remain stored for future reference. This is the most commonly used option.

    Although the EXEC_NOW flag is clear enough, it's possible for the other two to be confused. If you start with the idea that EXEC_APPEND is building a script (list of commands) within the executable running the server, then you can see that this script will always be present until the server is shut down. Although you can add new commands and have them executed, you would use the EXEC_INSERT so that it wasn't permanently added to the script being built by EXEC_APPEND.

    It appears that the EXEC_INSERT command isn't used in the user interface, possibly because the server can't be guaranteed to be running. If you do try to use EXEC_INSERT in the user interface, use it with caution.

     

    Example - setting up a server from the ui

    Taken from ServerOptions_Start() in ui_startserver.c, this code fragment shows the bots selected for a map being added to the server script through the use of EXEC_APPEND. This code is run when you create a server from the multiplayer menu, or have a skirmish from the single player menu.

    Notice that each string for the addbot command is finished off with the '\n' character.

    The wait command is interesting: some of the server parameters are set through trap_Cvar_SetValue(), and this allows their value to propagate through to the binary executable. As this code is run when we set up a server on our local machine, the time delay only needs to be a short one.

    int		skill;
    int		n;
    char	buf[64];
    
    // add bots
    trap_Cmd_ExecuteText( EXEC_APPEND, "wait 3\n" );
    for( n = 1; n < PLAYER_SLOTS; n++ ) {
    	if( s_serveroptions.playerType[n].curvalue != 1 ) {
    		continue;
    	}
    	if( s_serveroptions.playerNameBuffers[n][0] == 0 ) {
    		continue;
    	}
    	if( s_serveroptions.playerNameBuffers[n][0] == '-' ) {
    		continue;
    	}
    	if( s_serveroptions.gametype >= GT_TEAM ) {
    		Com_sprintf( buf, sizeof(buf), "addbot %s %i %s\n",
    			s_serveroptions.playerNameBuffers[n], skill,
    			playerTeam_list[s_serveroptions.playerTeam[n].curvalue] );
    	}
    	else {
    		Com_sprintf( buf, sizeof(buf), "addbot %s %i\n",
    			s_serveroptions.playerNameBuffers[n], skill );
    	}
    	trap_Cmd_ExecuteText( EXEC_APPEND, buf );
    }
    

     

    5. The end of the road...

    We've come a long way with this article, and covered a lot of ground that turned out to be more complex that even I'd originally thought. So long as you keep a clear picture in your mind of the differences and relationships between the user interface, the client, the server, and the executable, then you should be able to use this information to the full.

    When I originally planned this article I was going to talk about manipulating information stored in entities too - I'll have to save that for another time as this article is now far too long to do entities justice.

    There are also some bot commands for setting variables, but I've left them out for reasons of space and specialization. The ideas that govern the use of these bot commands are going to be very similar to the conventional methods I've described in this article.

    Let me know if there are any problems with the article, and if it's been of help to you.

    HypoThermia

     

    PlanetQuake | Code3Arena | Articles | << Prev | Article 9 | Next >>