QStat is a command-line program that displays information about Internet game servers. The servers are either down, non-responsive, or running a game. For servers running a game, the server name, map name, current number of players, and response time are displayed. Server rules and player information may also be displayed.
Games supported include Quake, QuakeWorld, Hexen II, Quake II, HexenWorld, Unreal, Half-Life, Sin, Shogo, Tribes, Quake III: Arena, BFRIS, Kingpin, and Heretic II.
Some games use query protocols compatible with an existing game. These servers can be queried using the flags for the compatible game. For instance, Turok2 should work using the -uns flag. Unreal Tournament is also supported by the -uns but is not really a different game. You can distinguish Unreal Tournament games with the "minnetver" server rule (standard Unreal servers have a "mingamever" server rule).
The Quake servers can be divided into two categories: POQS (Plain Old Quake Server) and QuakeWorld. Quake shareware, Quake commercial (from CD), winquake, winded, unixded, and Hexen II are all POQS. The various versions of QuakeWorld and Quake II use a QuakeWorld type server. The distinction is based on network protocol used to query the servers, and affects the kind of information available for display.
The different server types can be queried simultaneously. If QStat detects that this is being done, the output is keyed by the type of server being displayed. See DISPLAY OPTIONS.
The game server may be specified as an IP address or a hostname. Servers can be listed on the command-line or, with the use of the -f option, a text file.
One line will be displayed for each server queried. The first component of the line will be the server's address as given on the command-line or the file. This can be used as a key to match input addresses to server status. Server rules and player information are displayed under the server info, indented by one tab stop.
QStat supports two additional display modes: raw and templates. In raw mode, the server information is displayed using simple delimiters and no formatting. This mode is good for programs that parse and reformat QStat's output. The template mode uses text files to layout the server information within existing text. This is ideal for generating web pages. The raw mode is enabled using the -raw option and template output is enabled using -Ts.
These options select which servers to query and what game type they are running. Servers are specified by IP address (for example: 199.2.18.4) or hostname. Servers can be listed on the command-line or in a file (see option -f.) The game type of a server can be specified with its address, or a default game type can be set for all addresses that don't have a game type.
The following table shows the command-line option and type strings for the supported game types. The type string is used with the -default option and in files with the -f option.
| Option | Type String | Default Port | Game Server |
|---|---|---|---|
| -qs | qs | 26000 | Quake |
| -h2s | h2s | 26900 | Hexen II |
| -qws | qws | 27500 | QuakeWorld |
| -hws | hws | 26950 | HexenWorld |
| -q2s | q2s | 27910 | Quake II |
| -uns | uns | 7777 | Unreal |
| -hls | hls | 27015 | Half-Life |
| -sns | sns | 22450 | Sin |
| -sgs | sgs | 27888 | Shogo: Mobile Armor Division |
| -tbs | tbs | 28001 | Starsiege: Tribes |
| -qwm | qwm | 27000 | QuakeWorld master |
| -q2m | q2m | 27900 | Quake II master |
| -hlm | hlm | 27010 | Half-Life master |
| -tbm | tbm | 28000 | Tribes master |
| -q3s | q3s | 27960 | Quake III |
| -q3m | q3m | 27950 | Quake III master |
| -bfs | bfs | 44001 | BFRIS |
| -kps | kps | 31510 | Kingpin |
| -hrs | hrs | 28910 | Heretic II |
| -sfs | sfs | 28910 | Soldier of Fortune |
The command-line options can be specified multiple times, one for each server to be queried.
A broadcast query is specified by prefixing an address with a '+' (plus sign). The address should be 255.255.255.255 or a valid broadcast address for a local network. On Unixes, 'ifconfig -a' will display the broadcast address for all attached networks.
The QStat output should be self explanatory. However, the type of information returned is different between game types. If QStat queries multiple server types, then each server status line is prefixed with its type string. The GAME OPTIONS table lists the available type strings.
The response time is a measure of the expected playability of the server. The first number is the server's average time in milli-seconds to respond to a request packet from QStat. The second number is the total number of retries required to fetch the displayed information. More retries will cause the average response time to be higher. The response time will be more accurate if more requests are made to the server. For POQS, a request is made for each server rule and line of player information. So setting the -P and -R options will result in a more accurate response time. Quake and Hexen II are POQS. For most other game servers, QStat makes just one request to retrieve all the server status information, including server rules and player status. The -P and -R options do not increase the number of requests to the server. Half-Life supports three different requests for information; general status, players, and server rules. Each requires a separate request packet, so a total of three are used to retrieve player and rules.
Quake supports a number of control codes for special effects in player names. QStat normalizes the codes into the ASCII character set before display. The graphic codes are not translated except the orange brackets (hex 90, 10, 91, and 11) which are converted to '[' and ']'. Use the hex-player-names option -hpn to see the complete player name.
POQS do not return version information. But some small amount of info can be gathered from the server rules. The noexit rule did not appear until version 1.01. The Quake II server rules include a "version" key that contains the id build number. Recent releases of QuakeWorld have a "*version" key in the server rules. Unreal servers include a "gamever" key in the server rules that contains the server version without the decimal point. Most other game servers include some kind of version info in the server rules.
The following is an example address file that queries a QuakeWorld master, several Hexen II servers, some POQS, and a few Quake II servers.
QWM 192.246.40.12:27004 H2S 207.120.210.4 H2S 204.145.225.124 H2S 207.224.190.21 H2S 165.166.140.154 H2S 203.25.60.3 QS 207.25.198.110 QS 206.154.207.104 QS 205.246.42.31 QS 128.164.136.171 Q2S sm.iquest.net Q2S 209.39.134.5 Q2S 209.39.134.3
If the above text were in a file called QSERVER.TXT,
then the servers could be queried by running:
qstat -f QSERVER.TXT
QStat sends packets to each host and waits for return packets. After some interval, another packet is sent to each host which has not yet responded. This is done several times before the host is considered non-responsive. QStat can wait for responses from up to 20 hosts at a time. For host lists longer than that, QStat checks more hosts as results are determined.
The following applies only applies to POQS. If QStat exceeds the maximum number of retries when fetching server information, it will give up and try to move on to the next information. This means that some rules or player info may occasionally not appear. Player info may also be missing if a player drops out between getting the general server info and requesting the player info. If QStat times out on one rule request, no further rules can be fetched. This is a side-effect of the Quake protocol design.
The number of available file descriptors limits the number of simultaneous servers that can be checked. QStat reuses file descriptors so it can never run out. The macro MAXFD in qstat.c determines how many file descriptors will be simultaneously opened. Raise or lower this value as needed. The default is 20 file descriptors.
Operating systems which translate ICMP Bad Port (ICMP_PORT_UNREACHABLE) into a ECONNREFUSED will display some hosts as DOWN. These hosts are up and connected to the network, but there is no program on the port. Solaris 2.5 and Irix 5.3 correctly support ICMP_PORT_UNREACHABLE, but Solaris 2.4 does not. See page 442 of "Unix Network Programming" by Richard Stevens for a description of this ICMP behavior.
Operating systems without correct ICMP behavior will just report hosts without Quake servers as non-responsive. Windows NT and Windows 95 don't seem to support this ICMP.
For hosts with multiple IP addresses, QStat will only send packets to the first address returned from the name service.
QStat supports Unreal version 2.15 or greater.
UNIX - QStat has been compiled and tested on Solaris 2.x, Irix 5.3/6.2/6.3/6.4, FreeBSD 2.2/3.0, BSDi, HP-UX 10.20/11.0, and various flavors of Linux.
WINDOWS - The Windows version of QStat (win32/qstat.exe) runs on Windows 95 and Windows NT as a console application. On Windows 95 and NT 4.0, short-cuts can be used to set the arguments to qstat. On Windows NT 3.51, use a batch file.
OS/2 - An OS/2 binary is no longer included. Try contacting Per Hammer for an OS/2 Warp binary. per@mindbend.demon.co.uk.
VMS - The source includes a VMS patch from John Ross Hunt. This patch was tested on QStat 2.0b, but has not been tested on the current version. See COMPILE.txt for instructions.
This is QStat version 2.3g.
The QStat webpage is updated for each new version and
contains links to Quake server listings and pages about
the Quake and Unreal network protocols. The page can be found at
http://www.activesw.com/people/steve/qstat.html
Quake, Quake II, QuakeWorld, and Quake III created by id Software. Hexen II, HexenWorld, and Heretic II created by Raven Software. Unreal created by Epic Games. Half-Life created by Valve Software. Sin created by Ritual Entertainment. Shogo: Mobile Armor Division was created by Monolith Productions Inc. Tribes was created by Dynamix, Inc. BFRIS created by Aegis Simulation Technologies. Kingpin created by Xatrix Entertainment Inc.
Steve Jankowski
steve@activesw.com
Copyright © 1996,1997,1998,1999 by Steve Jankowski
Permission granted to use this software for any purpose you desire provided that existing copywrite notices are retained verbatim in all copies and derived works.
QStat output templates provide greater control of the appearance of server status information. The results of a server query can be organized, formatted, and wrapped within any other text. The most obvious use is to generate HTML for web pages. However, it could also generate custom output for redisplay within another tool.
There are four output templates:
| Template | Option | |
|---|---|---|
| server | -Ts | Output once for each server queried. (required) |
| player | -Tp | Output once for each player. Must be used with -P. Invoked by the $PLAYERTEMPLATE variable. |
| header | -Th | Output once before any servers are queried. |
| trailer | -Tt | Output once after all servers are queried. |
The server template must be specified to enable template output. The other templates are optional.
Each output template is a file containing text and QStat variables. The text is output unchanged by QStat, but the variables are processed and replaced by QStat. Most variables are replaced by values from a queried server. Some variables have hardcoded values, and some generate no output, but affect how the template is processed.
Variables are grouped according to the templates where they can be used. General variables may be used in any of the templates. Server variables may be used in the server template. Player variables may be used in the player template. Expression variables may only be used with the $IF and $IFNOT variables. If a variable is used where it doesn't make sense, it is ignored and generates no output.
Variables are specified using one of several syntaxes:
$VAR
$VAR:OPTION
$(VAR)
$(VAR:OPTION)
$(VAR:OPTION(ARGUMENT))
The syntax used does not affect the output. However using the $()
syntax is somewhat more readable when the text gets cluttered. If you
want the variable to be followed immediately by text, then the $()
syntax must be used.
| $QSTATURL | Output the web address of the QStat home page. | ||||||||||||||||||||
| $QSTATVERSION | Output the version of QStat being run. | ||||||||||||||||||||
| $QSTATAUTHOR | Output the name of the QStat programmer. | ||||||||||||||||||||
| $QSTATAUTHOREMAIL | Output the email address of the QStat programmer. | ||||||||||||||||||||
| $HTML | Enable HTML friendly string output. Server
results may
include characters that have special meaning in HTML. These are replaced
by equivalent SGML entities. QStat converts '<', '>',
and '&' to '<', '>', and
'&'. Use this variable once in the header template.
| $IF | Conditional output. If the variable option is "true,"
the template is output up to a matching $ENDIF variable. If the variable
option is "false," the template is ignored until after a matching
$ENDIF. See Conditional Options for a list of supported conditional
options.
| $IFNOT | Conditional output. Same as $IF, but the opposite
sense.
| $ENDIF | End conditional output. There must be one $ENDIF for
each $IF and $IFNOT within a template.
| $NOW | Output the current local time.
| $TOTALSERVERS | The total number of servers to be queried.
| $TOTALUP | The number of servers up and running.
| $TOTALNOTUP | The number of servers either DOWN or TIMEOUT.
| $TOTALPLAYERS | The number of players found on all servers.
| $\ | Ignore the next newline.
Not really a variable, but a way to curtail the output of extra newlines.
Saves space in the output while the template remains readable. Must be
the last thing on the line.
| $DEFAULTTYPE | The full name of the default server type specified
with -default.
| |
| $HOSTNAME | Output the host name of the server if known, otherwise the server address as given to QStat. |
| $SERVERNAME | Output the name of the server. |
| $PING | The time in milli-seconds to get a response from the server. If the server is DOWN or TIMEOUT, nothing is output. |
| $PLAYERS | The number of players on the server. |
| $MAXPLAYERS | The maximum number of players allowed on the server. |
| $MAP | The name of the map being played. |
| $GAME | The name of the game being played. This is usually the name of the "mod" run by the server. |
| $RETRIES | The number of retries needed to get the server status. This is a measure of packet loss. |
| $IPADDR | The IP address of the server. Does not include the port number. |
| $PORT | The port the server is running on. |
| $ARG | The server address as given to QStat. |
| $TYPE | Output one of the following depending on the server type:
Quake
Quake II
Quake II Master
QuakeWorld
QuakeWorld Master
Hexen II
HexenWorld
Unreal
Half-Life
Half-Life Master
Sin
Tribes
Tribes Master
Shogo: Mobile Armor Division
Quake III: Arena
Quake III Master
BFRIS
Kingpin
Heretic II
Soldier of Fortune
If the server type is not known, nothing is output.
|
| $TYPESTRING | The server's type string (see GAME OPTIONS table.) |
| $RULE:name | The value of a server rule. If the rule is not returned by the server, nothing is output. Must be used with the -R flag. |
| $ALLRULES | Output all the server rules in the format name=value separated by commas. Must be used with the -R flag. |
| $PLAYERTEMPLATE | Invoke the player template. The player template is output once for each player on the server. Must be used with the -P flag. |
| $PLAYERNAME | The name of the player. |
| $FRAGS | The number of frags scored. |
| $PLAYERPING | The player's ping time to the server. This value is not available from Half-Life servers. |
| $CONNECTTIME | How long the player has been playing. This value is only available from Quake, QuakeWorld, Hexen II, and Half-Life servers. |
| $SKIN | The name of the player's skin texture. This value is not available from ?? servers. |
| $MESH | The name of the player's mesh (model). This value is only available from Unreal servers. |
| $FACE | The name of the player's face texture. This value is only available from Unreal version 405+ servers. |
| $SHIRTCOLOR | Color of the player's shirt. This value is only available from Quake, QuakeWorld, and Hexen II servers. |
| $PANTSCOLOR | Color of the player's pants. This value is not available from Quake, QuakeWorld, and Hexen II servers. |
| $PLAYERIP | The IP address of the player's computer. This value is only available from Quake and Hexen II servers. |
| $TEAMNUM | The player's team number. This value is only available from Unreal and Tribes servers. |
| $TEAMNAME | The player's team name. This value is only available from Tribes servers. |
| $PACKETLOSS | The player's packet loss. This value is only available from Tribes servers. |
| $COLORNUMBERS | Display $SHIRTCOLOR and $PANTSCOLOR as numbers. Equivalent to -ncn command-line option. No output. |
| $COLORNAMES | Display $SHIRTCOLOR and $PANTSCOLOR using color names. Equivalent to -cn command-line option. No output. |
| $COLORRGB | Display $SHIRTCOLOR and $PANTSCOLOR using #rrggbb format. Equivalent to -hc command-line option. No output. |
| $TIMESECONDS | Display $CONNECTTIME as number of seconds. Equivalent to -ts command-line option. No output. |
| $TIMECLOCK | Display $CONNECTTIME in clock format (DhDDmDDs). Equivalent to -tc command-line option. No output. |
| $TIMESTOPWATCH | Display $CONNECTTIME in stop-watch format (DD:DD:DD). Equivalent to -tsw command-line option. No output. |
These options maybe used with the $IF and $IFNOT variables. For example, to display player information, the following could be used in the server template:
$(IF:PLAYERS)$(IF:FLAG(-P))
The server has $(PLAYERS) players:
$(PLAYERTEMPLATE)
$(ENDIF)$(ENDIF)
The template between the $IF and $ENDIF variables will only be
displayed if the server has one or more players and the -P
flag was given to QStat.
| GAME | True if the server is running a "mod." |
| PLAYERS | True if the server has one or more players. |
| QUAKE | True if the server is running Quake (the original). |
| QUAKE2 | True if the server is running Quake II. |
| Q2MASTER | True if the server is a Quake II master. |
| QUAKEWORLD | True if the server is running QuakeWorld. |
| QWMASTER | True if the server is a QuakeWorld master. |
| HEXEN2 | True if the server is running Hexen II. |
| HEXENWORLD | True if the server is running HexenWorld. |
| UNREAL | True if the server is running Unreal. |
| HALFLIFE | True if the server is running Half-Life. |
| HLMASTER | True if the server is a Half-Life master. |
| SIN | True if the server is running Sin. |
| TRIBES | True if the server is running Tribes. |
| TRIBESMASTER | True if the server is a Tribes master. |
| SHOGO | True if the server is running Shogo. |
| QUAKE3 | True if the server is running Quake III. |
| Q3MASTER | True if the server is a Quake III master. |
| BFRIS | True if the server is running BFRIS. |
| KINGPIN | True if the server is running Kingpin. |
| HERETIC2 | True if the server is running Heretic II. |
| SOLDIEROFFORTUNE | True if the server is running Soldier of Fortune. |
| RULE(name) | True if the rule name is set on the server. |
| FLAG(name) | True if the flag name was used on the QStat command-line. The only flag names supported are: -H, -P, and -R. Any other flag name returns false. |
| UP | True if the server is up and running. |
| DOWN | True if the server is known to be not running. This is true if the server computer returns an ICMP indicating that nothing is running on the port. Only supported by some operating systems. |
| TIMEOUT | True if the server never responded to a status query. |
| HOSTNOTFOUND | True if the host name lookup failed. |
| ISEMPTY | True if the server has no players. |
| ISFULL | True if the server has the maximum players. |
| ISTEAM | True if the player is a team. Only available with Tribes servers. Only applies to the player template. |