QSmack Config File Setup

Here is an example config file:

quakeserver            kitty1.stanford.edu:26789
player_name            C9_AutoAdmin
shirt_color            0
pants_color            0
log_file               26789.log
ban_impulse            220
init_impulse           32
init01_impulse         99
init02_impulse         96
init03_impulse         253
init04_impulse         254
banfile                ban.26789
stats_file             stats.log

listen_port            26789
password               testing123

The format of the config file is pretty simple. Lines beginning with a hash mark ("#") are comments, and blank lines and whitespace are ignored. Config parameters should appear on lines by themselves. Here's a description of what the example config file is doing, line by line:

quakeserver            kitty1.stanford.edu:26789

This specifies which Quake server to connect to. It can be either a DNS name or an IP address, so "" would also have worked. The port number must be specified, even if it is the default port (26000).

player_name            C9_AutoAdmin

Specify what the QSmack client will be named in the game. The maximum length of a Quake name is 15 characters. Our policy on names is as follows: In general we want QSmack to be as low-key as possible, so for our 26000 and 26001 servers, we make the name nothing, as in:


In this way, when a player presses tab (or whatever they have bound to the "showscores" command) they won't see QSmack in the game. However, we also don't like it when players have this "nothing" name, so our server code will rename a player who has more than zero frags and "nothing" for a name to "Nameless Dork". :-) We really like this feature. Since QSmack never gets any frags (we hope), it never gets renamed.

On a ClanRing server, you have to use an actual name (like "C9_AutoAdmin"). This is because the ClanRing code already kicks players that have "nothing" for a name at the beginning of every level. (Unless you modify the ClanRing code to not do that.)

If you want your QSmack name to have the funky Quake characters in it, check out the special characters page.

shirt_color            0
pants_color            0
This specifies the shirt and pants color of QSmack. The valid colors are 0 to 13. Some servers, like ClanRing or CTF, will assign a player colors when they enter the game. QSmack is smart enough to recognize those commands and respond to them. In these cases, don't expect the colors you set for QSmack in the config file to be the ones that QSmack has in the game.

log_file               26789.log

This specifies the name of the log file. The log file contains useful information that QSmack spits out. Everytime a banned player is kicked, a message is printed to the log. It also contains useful debugging info that we could use to help fix a problem that you might be having using QSmack. This is also the only parameter that can be usefully left out of the config file. If the log_file parameter is missing, the output will go to stderr (if you're not conversant with that jargon, this generally just means that it will spew to your screen instead of to a file). This is useful when you first start running QSmack and you just want to see if its doing anything without having to check the log file.

ban_impulse            220
This number serves two purposes. First, it is the impulse sent once a second to ensure that the server doesn't kick the wrong player. (See the server changes description for why this could happen, if you're curious.) Second, this number serves as a base to identify which impulse to use to kick which player. When a player enters the game, he is assigned a player number from 1 to 16. A unique impulse command is sent to indicate which player to kick. That impulse is composed of the "ban_impulse" plus the player number. For our servers, then, those impulses are 221 to 236. Important: If you are using the server code we provide, these are the impulses you must use, unless you change the server code as well as the config file. The server and QSmack must agree on which impulses are to be used, otherwise QSmack will not function correctly.

init_impulse           32
init01_impulse         99
init02_impulse         96
init03_impulse         253
init04_impulse         254
These five impulses specify the secret password used by QSmack to automatically gain admin privileges. Make sure you choose impulses that aren't being used for any other purpose on your server. You will need to specify these same five impulses in the QuakeC of your server code. This is described on the server code page, and in more detail in the server changes description.

banfile                ban.26789
This specifies the name of the file containing the names and IP addresses to ban. You should read how to set up your ban file if you haven't already. Also read about how you can dynamically update the ban file from within the game.

stats_file             stats.log
If this line is in the config file, all server messages and statistics are dumped to the named file. If it is left out, no statistics are recorded. This file basically keeps a running account of what is going on in the game. This file is output so that people can keep track of who is playing on their server, how many frags they get, and what they say while they are in the game. Here is an excerpt from a stats.log that was taken from lithium.com:
server_mesg        VERSION 1.07 SERVER (39468 CRC)
date             Sun Aug 24 16:27:31 1997
mapname          the Installation
qsmack_num     4
player_frags   1 5
player_frags   2 8
player_frags   3 10
player_frags   4 0
player_frags   5 1
player_frags   6 4
player_frags   7 11
player_frags   8 5
player_enter   1   player
player_enter   2  happy camper
player_enter   3 dumbass
player_enter   4   foo
player_enter   5 the [TICK]
player_enter   6   ^_^
player_enter   7   *Mad Mole**
player_enter   8 **CHEWBACCA**
server_mesg      **CHEWBACCA** accepts player's shaft
player_frags   1 6
server_mesg      the [TICK] rides *Mad Mole**'s rocket
player_frags   7 12
server_mesg      player was gibbed by dumbass's rocket
player_frags   3 11
server_mesg      player got the rune of Regeneration.
server_mesg      **CHEWBACCA** was gibbed by *Mad Mole**'s rocket
player_frags   7 13
player_say     8 **CHEWBACCA**  : why is dumbass everywehre
player_say     6 ^_^            : cause he is a bot
server_mesg      player rides dumbass's rocket
player_frags   3 13
player_exit    5 0:07:22
player_name    4   foobar
Each line in the stats_file begins with one of nine keywords. The most general of these keywords is "server_mesg". Any message sent from the server that is not a 'say' will be output as a "server_mesg". This includes all death messages and whatever else your server decides to print to all players.
A "mapname" line simply specifies the name of the level and can be used to keep track of when levels change.
A "date" line gives the current date and time. It is printed with every level change.
A "player_say" is fairly self-explanatory. It is the probable player number followed by the name of the player and what they said. Note that two players could easily have the same name and then the player number could be wrong. It is impossible to reliably determine who said something because of this. Also note that any special characters in the player's name are mapped into a printable form. This means that a player with really weird quake characters in their name won't necessarily be recogizeable in the stats_file.
The keywords "player_enter" and "player_exit" can be used to assuredly determine when a player enters or leaves the game. Since QSmack does a status every second, it can reliably determine the player list (unlike regular clients which are fooled by the nothing name). A "player_enter" line will contain the player number, their IP address, and their name. Note that a player's name will not be set yet when they enter the game. However, when QSmack enters the game all the players have names, so the "player_enter" lines will all show the proper names.
A "player_exit" line is printed whenever a player leaves the game. This can be reliably determined from the status command. Whenever a player leaves the games, the total time that they were conntected to the server is also printed on this line.
The "player_name" line is printed whenever a player changes their name. Like the "player_say" line, special characters in the player's name are mapped into a printable form. Note that the server sets a player's name to the empty string (as in "") when a player leaves the game. Do not count on this behavior since can also change their name to the empty string while they are still connected and playing. The IP address of the player is also printed.
A "player_frags" line is printed whenever a player's frags change. Note that when a player leaves the game, the server can set a player's frags momentarily to either zero or their final frag count.
The "qsmack_num" keyword indicates QSmack's player number. This information could also be gleaned from the "player_enter", but why not just tell you. :-)

listen_port                26789
The "listen_port" option is only needed if you plan to connect to QSmack with the frontend. This specfies which port QSmack should listen for frontend connections.
The port you specify can be any integer between 1024 and 65536. It does not have to be the same port as the port that the quake server is listening. Even if QSmack and the server are running on the same machine, they can both use the same port. This is because quake uses the UDP protocol and QSmack uses the TCP protocol to communicate with its frontend(s).
If this option is not present, QSmack will not accept connections from frontend clients.

password                   testing123
The "password" option is only needed if you plan to connect to QSmack with the frontend. This option specifies the password that the frontend must send in order connect to QSmack. No spaces, tabs or non-printable characters are allowed in the password. A password must be specified if the "listen_port" option is present.