File: qstatdoc.html

package info (click to toggle)
qstat 2.3g-1
links: PTS
area: main
in suites: potato
size: 496 kB
ctags: 558
sloc: ansic: 5,421; makefile: 99
file content (871 lines) | stat: -rw-r--r-- 35,271 bytes
<html>

<head>
<title>QStat 2.3g documentation</title>
</head>

<BODY bgcolor=#543540 text=#e5e5e5 link=#ccffff vlink=#90e0e0>

<dl>
<H3><dt>NAME</H3>
<dd>
	qstat - Get statistics from on-line game servers

<H3><dt>SYNOPSIS</H3>
<dd>
        <b>qstat</b> [<i>options</i> ...]
		[<b>-f</b> <i>file</i>]
		[<b>-<i>server-option</i></b> <i>host</i>[:<i>port</i>]]
<br>
		[<b>-raw</b> <i>delimiter</i>]
		[<b>-default</b> <i>server-type</i>]
		<i>host</i>[:<i>port</i>] ...

<H3><dt>Version 2.3g</H3>

<H3><dt>DESCRIPTION</H3>
<dd><p>
        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.
<p>
	Games supported include Quake, QuakeWorld, Hexen II,
	Quake II, HexenWorld, Unreal, Half-Life, Sin, Shogo,
	Tribes, Quake III: Arena, BFRIS, Kingpin, and
	Heretic II.
<p>
	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 <b>-uns</b> flag.  Unreal Tournament is also
	supported by the <b>-uns</b> 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).
<p>
	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.
<p>
	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.
<p>
	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 <b>-f</b> option, a text file.

<H3><dt>DISPLAY MODES</H3>
<dd><p>
	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.
<p>
	QStat supports two additional display modes: <i>raw</i> and
	<i>templates</i>.  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 <b>-raw</b> option and template
	output is enabled using <b>-Ts</b>.

<H3><dt>GAME OPTIONS</H3>

<dd><p>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 <b>-f</b>.)  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.
<p>
The following table shows the command-line option and type strings
for the supported game types.  The type string is used with the
<b>-default</b> option and in files with the <b>-f</b> option.
<p>
<table border=1 cellspacing=1>
<tr><th width=70>Option<th width=80>Type String<th>Default Port<th>Game Server
<tr><td>-qs<td>qs<td>26000<td>Quake
<tr><td>-h2s<td>h2s<td>26900<td>Hexen II
<tr><td>-qws<td>qws<td>27500<td>QuakeWorld
<tr><td>-hws<td>hws<td>26950<td>HexenWorld
<tr><td>-q2s<td>q2s<td>27910<td>Quake II
<tr><td>-uns<td>uns<td>7777<td>Unreal
<tr><td>-hls<td>hls<td>27015<td>Half-Life
<tr><td>-sns<td>sns<td>22450<td>Sin
<tr><td>-sgs<td>sgs<td>27888<td>Shogo: Mobile Armor Division
<tr><td>-tbs<td>tbs<td>28001<td>Starsiege: Tribes
<tr><td>-qwm<td>qwm<td>27000<td>QuakeWorld master
<tr><td>-q2m<td>q2m<td>27900<td>Quake II master
<tr><td>-hlm<td>hlm<td>27010<td>Half-Life master
<tr><td>-tbm<td>tbm<td>28000<td>Tribes master
<tr><td>-q3s<td>q3s<td>27960<td>Quake III
<tr><td>-q3m<td>q3m<td>27950<td>Quake III master
<tr><td>-bfs<td>bfs<td>44001<td>BFRIS
<tr><td>-kps<td>kps<td>31510<td>Kingpin
<tr><td>-hrs<td>hrs<td>28910<td>Heretic II
<tr><td>-sfs<td>sfs<td>28910<td>Soldier of Fortune
</table>
<p>
The command-line options can be specified multiple times, one for
each server to be queried.

<H4>Master Servers</H4>
Master server addresses don't change very often, but some times they
go off-line.  The following is a list of some of the master servers
I know about.
<ul>
<li>QuakeWorld - satan.idsoftware.com (ports 27000, 27002, 27003,
27004, 27006), 204.182.161.2, 194.217.251.40, 203.34.140.1, 200.245.221.200,
194.87.251.3
<li>Quake II - satan.idsoftware.com, q2master.planetquake.com, www.telefragged.com
<li>Half-Life - half-life.west.won.net (128.11.20.143), half-life.east.won.net
<li>Tribes - tribes.dynamix.com
<li>Quake III - master3.idsoftware.com (192.246.40.56), q3master.splatterworld.de [German]
</ul>

<H4>Broadcast Queries</H4>
<dd>QStat has limited support for broadcast queries.  Broadcast queries
use one network packet to find all the game servers on a local
network.  A broadcast returns servers of one type on one port.
You may only broadcast to networks to which you computer is
directly attached (ie. local networks).  <b>In this release, broadcast
queries are only supported for: Quake II servers.</b>
<p>
A broadcast query is specified by prefixing an address with a '<tt>+</tt>'
(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.

<H4>Option Usage</H4>

<dl compact>
<dt><b>-<i>server-option</i></b> <i>host</i>[:<i>port</i>]<dd>
	Query game server <i>host</i> for status.  The GAME OPTIONS
	table lists the available <i>server-options</i> and their default
	port.

<dt><b>-<i>master-server-option</i></b> <i>host</i>[:<i>port</i>]<dd>
	Query a game master for its server list and then query all
	the servers.  The GAME OPTIONS
	table lists the available <i>master-server-options</i>
	and their default port.

<dt><b>-<i>master-server-option</i>,outfile</b> <i>host</i>[:<i>port</i>],<i>file</i><dd>
	Query a game master for its server list and store it
	in <i>file</i>.  If the master cannot be contacted, then
	<i>file</i> is not changed.  If <i>file</i> is <b>-</b> (a
	single dash), then stdout is used.
	The GAME OPTIONS table lists the available
	<i>master-server-options</i> and their default port.

<dt><b>-f</b><i> file</i><dd>
	Read host addresses from the given file.  If <i>file</i> is <b>-</b>,
	then read from stdin.  Multiple <b>-f</b> options may be
	used.  The file should contain host names or IP
	addresses separated by white-space (tabs, new-lines,
	spaces, etc).  If an address is preceded by a server
	type string, then QStat queries the address according
	to the server type.  Otherwise QS is assumed, unless <b>-default</b>
	is used.  The GAME OPTIONS table lists the available server
	type strings and their default port.

<dt><b>-default</b><i> type-string</i><dd>
	Set the default server type for addresses where the type is not
	obvious.  This affects the addresses at the end of the qstat
	command-line and those in a file not prefixed by a server type
	(see <b>-f</b>).
	The GAME OPTIONS table lists the available server
	type strings and their default port.

</dl>

<H3><dt>INFO OPTIONS</H3>

<dl compact><dt><b>-R</b><dd>
		Fetch and display server rules.

<dt><b>-P</b><dd>
		Fetch and display player information.
</dl>

<H3><dt>DISPLAY OPTIONS</H3>

<dd><p>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.

<p>
<dl compact><dt><b>-u</b><dd>
                Only display hosts that are up and running a game server.
		Does not affect template output.
 
<dt><b>-nf</b><dd>
                Do not display full servers.  Does not affect template
		output.

<dt><b>-ne</b><dd>
                Do not display empty servers.  Does not affect template
		output.

<dt><b>-nh</b><dd>
                Do not display header line (does not apply to raw or
		template output.)

<dt><b>-cn</b><dd>
		Display color names instead of numbers.  This is
		the default.

<dt><b>-ncn</b><dd>
		Display color numbers instead of color names.  This is
		the default for <b>-raw</b> mode.

<dt><b>-hc</b><dd>
		Display colors in #rrggbb format.  This is nice for
		HTML output.

<dt><b>-tc</b><dd>
		Display time in clock format (DhDDmDDs).  This is the default.

<dt><b>-tsw</b><dd>
		Display time in stop-watch format (DD:DD:DD).

<dt><b>-ts</b><dd>
		Display time in seconds.  This is the default for
		<b>-raw</b> mode.
 
<dt><b>-pa</b><dd>
		Display player addresses.  This is the default for
		<b>-raw</b> mode.  Only available for Quake and Hexen II.

<dt><b>-sort</b><i> sort-key</i><dd>
		Sort servers before display.  Servers are sorted
		according to the <i>sort-key</i> which is one or
		more of:<br>
		<li>p - Sort by ping
		<li>g - Sort by game

<dt><b>-hpn</b><dd>
		Display player names in hex.

<dt><b>-old</b><dd>
		Use pre-qstat 1.5 display style.

<dt><b>-raw</b><i> delimiter</i><dd>
	Display data in "raw" mode.  The argument to
	<b>-raw</b> is used to separate columns of
	information.  All information returned by the game
	server is displayed.
<br>
	<b>POQS output</b> -- General server information is
	displayed in this order: command-line arg (IP address
	or host name), server name, server address (as returned
	by Quake server), protocol version, map name, maximum
	players, current players, average response time,
	number of retries.  Server rules are displayed on one
	line as <i>rule-name</i>=<i>value</i>.  If significant packet
	loss occurs, rules may be missing.  Missing rules are
	indicated by a "?" as the last rule.  Player information
	is displayed one per line: player number, player name,
	player address, frags, connect time, shirt color, pants
	color.  A blank line separates each set of server
	information.
<br>
	<b>QuakeWorld and HexenWorld server output</b> -- General server information is
	displayed in this order: command-line arg (IP address
	or host name), server name, map name, maximum
	players, current players, average response time,
	number of retries.  Server rules are displayed on one
	line as <i>rule-name</i>=<i>value</i>. Player information
	is displayed one per line: player number, player name,
	frags, connect time, shirt color, pants
	color, ping time (milliseconds), skin name.  A blank line
	separates each set of server information.
<br>
	<b>All master server output</b> -- Master server information is
	displayed in this order: command-line arg (IP address
        or host name), number of servers.  No other information
	is displayed about master servers.
<br>
	<b>Quake II, Quake III, Half-Life, Sin, BFRIS, Kingpin, Heretic II, Unreal, and Shogo server output</b> -- General server information and
	server rules are the same as a QuakeWorld server.
	The player information varies for each game:
<ul>
<li>Quake II/III, Sin, Kingpin, Heretic II, Shogo: player name, frags, ping time
<li>Half-Life: player name, frags, connect time
<li>Tribes: player name, frags, ping time, team number, packet loss
<li>Unreal: player name, frags, ping time, team number, skin, mesh, face
<li>BFRIS: player number, ship, team name, ping time, score, frags, player name
</ul>
	Ping time is in milli-seconds.  Connect time is in seconds.
	A blank line separates each set of server information.

<dt><b>-raw-arg</b><dd>
	When used with <b>-raw</b>, always display the server address
	as it appeared in a file or on the command-line.  Note that
	when <b>-H</b> is used with <b>-raw</b>, the first field of the
	raw output could be a hostname if the server IP address was resolved.
	This can make matching up input servers addresses with raw output
	lines fairly difficult.  When <b>-raw-arg</b> is also used, an
	additional field, the unresolved server address, is added at the
	beginning of all raw output lines.

<dt><b>-progress</b><dd>
	Print a progress meter.  Displays total servers processed,
	including timeouts and down servers.  The meter is just a
	line of text that writes over itself with &lt;cr&gt;.  Handy
	for interactive use when you are redirecting output to
	a file (the meter is printed on stderr).

<dt><b>-Tserver</b><i> file</i><br>
<dt><b>-Tplayer</b><i> file</i><br>
<dt><b>-Theader</b><i> file</i><br>
<dt><b>-Ttrailer</b><i> file</i><dd>
	Output templates.  Each template should be a text file containing
	QStat variables that are substituted for results from the server
	query.  The <b>-Tserver</b> flag must present to enable template
	output.  The other <b>-T</b> flags are optional.  The server template
	is output once for each server queried.  The player template,
	if present, is output once for each player (if <b>-P</b> is also
	used).  The header template is output once before any servers
	are output.  The trailer template is output once after all servers
	are processed.  See <a href="#APPENDIXA">Appendix A</a> for the
	output template formatting and variables.<br>
	NOTE: All of of the <b>-T</b> flags may be abbreviated with two
	characters: <b>-Ts</b>, <b>-Tp</b>, <b>-Th</b>, and <b>-Tt</b>.

<dt><b>-errors</b><dd>
	Display errors.

</dl>

<H3><dt>SEARCH OPTIONS</H3>

<dl compact><dt><b>-H</b><dd>
	Resolve IP addresses to host names.  Use with caution
	as many game servers do not have registered host
	names.  QStat may take up to a minute to timeout
	on each unregistered IP address.  The duration of
	the timeout is controlled by your operating system.  Names
	are resolved before attempting to query any servers.

<dt><b>-Hcache</b><i> cache-file</i><dd>
	Cache host name and IP address resolutions in <i>cache-file</i>.
	If the file does not exist, it is created.  If <b>-Hcache</b> is used
	without <b>-H</b>, then the cache is only used for host to IP address
	resolution.  <b>WARNING </b> A host cache file should <i>not</i> be
	shared by QStat programs running at the same time.  If you run several
	QStats at the same time, each should have its own cache file.

<dt><b>-interval</b><i> seconds</i><dd>
	Interval in seconds between server retries.  Specify as a
	floating point number.  Default interval is 0.5 seconds.
	This option does not apply to master servers (see <b>-mi</b>.)
 
<dt><b>-mi</b><i> seconds</i><dd>
	Interval in seconds between master server retries.  Specify as a
	floating point number.  Default interval is 2 seconds.
 
<dt><b>-retry</b><i> number</i><dd>
	Number of retries.  QStat will send this many packets
	to a host before considering it non-responsive.  Default
	is 3 retries.

<dt><b>-maxsimultaneous</b><i> number</i><dd>
	Number of simultaneous servers to query.  Unix systems
	have an operating system imposed limit on the number of
	open sockets per process.  This limit varies between
	32 and 100 depending on the platform.  On Windows 95 and
	Windows NT, the "select" winsock function limits the number of
	simultaneous queries to 64.  These limits can be increased
	by minor changes to the code, but the change is different
	for each platform.  Default is 20 simultaneous queries.
	This option may be abbreviated <b>-maxsim</b>.

<dt><b>-timeout</b><i> seconds</i><dd>
        Total run time in seconds before giving up.  Default is
	no timeout.

</dl>

<H3><dt>NOTES</H3>

<dd><p>
	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 <b>-P</b> and
	<b>-R</b> 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 <b>-P</b> and <b>-R</b> 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.

<p>
	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 <b>-hpn</b> to see the complete player name.

<p>
	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 "<tt>version</tt>" key that
	contains the id build number.  Recent releases of QuakeWorld
	have a "<tt>*version</tt>" key in the server rules.  Unreal
	servers include a "<tt>gamever</tt>" 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.

<H3><dt>EXAMPLES</H3>

<dd><p>The following is an example address file that queries a QuakeWorld
master, several Hexen II servers, some POQS, and a few Quake II servers.
</p>
<pre>
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
</pre>
<p>If the above text were in a file called <code>QSERVER.TXT</code>,
then the servers could be queried by running:
<br>
	<code>qstat -f QSERVER.TXT</code>

<H3><dt>IMPLEMENTATION NOTES</H3>
<dd><p>
        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.
<p>
	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.
<p>
        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.
<p>
	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.
<p>
	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.
<p>
	For hosts with multiple IP addresses, QStat will only send
	packets to the first address returned from the name service.
<p>
	QStat supports Unreal version 2.15 or greater.


<H3><dt>BUGS</H3>
<dd><p>

<H3><dt>PORTABILITY</H3>
<dd><p>
        <b>UNIX</b> - 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.
<p>

        <b>WINDOWS</b> - The Windows version of QStat (<tt>win32/qstat.exe</tt>) 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.
<p>
	<b>OS/2</b> - An OS/2 binary is no longer included.  Try contacting Per Hammer
	for an OS/2 Warp binary.
	<a href="mailto:per@mindbend.demon.co.uk">per@mindbend.demon.co.uk</a>.
<p>
	<b>VMS</b> - 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.
</p>

<H3><dt>VERSION</H3>
<dd><p>
	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
<br>
	<a href="http://www.activesw.com/people/steve/qstat.html">
	http://www.activesw.com/people/steve/qstat.html</a>
</p>
<p>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.
</p>

<H3><dt>AUTHOR</H3>
<dd><p>
	<a href="http://www.activesw.com/people/steve/">Steve Jankowski</a>
<br>
	<a href="mailto:steve@activesw.com">steve@activesw.com</a>

<H3><dt>COPYRIGHT</H3>
<dd><p>
	Copyright &copy; 1996,1997,1998,1999 by Steve Jankowski
</p>
<p>
	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.
</p>
</dl>

<hr>

<a name="APPENDIXA">
<H3><dt>APPENDIX A - Output Templates</H3>
<p>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.
<p>
There are four output templates:
<table border=1 cellspacing=1>
<tr><th>Template<th>Option<th>&nbsp;
<tr><td>server<td>-Ts<td>Output once for each server queried. (required)
<tr><td>player<td>-Tp<td>Output once for each player.  Must be used with <b>-P</b>.
Invoked by the <b>$PLAYERTEMPLATE</b> variable.
<tr><td>header<td>-Th<td>Output once before any servers are queried.
<tr><td>trailer<td>-Tt<td>Output once after all servers are queried.
</table>
<p>
The server template must be specified to enable template output.  The
other templates are optional.
<p>
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.
<p>
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
<b>$IF</b> and <b>$IFNOT</b> variables.  If a variable is used where it
doesn't make sense, it is ignored and generates no output.
<p>
Variables are specified using one of several syntaxes:<br>
<pre>
    $VAR
    $VAR:OPTION
    $(VAR)
    $(VAR:OPTION)
    $(VAR:OPTION(ARGUMENT))
</pre>
The syntax used does not affect the output.  However using the <b>$()</b>
syntax is somewhat more readable when the text gets cluttered.  If you
want the variable to be followed immediately by text, then the <b>$()</b>
syntax must be used.

<H4>Download considerations</H4>
If you are generating output to be downloaded, then you'll want to make
your output as small as possible.  In the case of HTML, you can reduce
the size of your pages by excluding stuff.
<li>Remove unneeded spaces (indenting and newlines)
<li>Remove unneeded end tags.  The HTML spec says the following tags can
always be left out: &lt;/TD&gt; &lt;/TR&gt; &lt;/TH&gt;
<li>When creating a table, "width" modifiers are only needed on one
cell of a column.  Put them on the cells of the first row of the
table.

<H4>Display options</H4>
The display options <b>-u</b>, <b>-ne</b>, and <b>-nf</b> have no
affect on template output.  Use the $IF:UP, $IF:ISEMPTY,
and $IF:ISFULL conditions to accomplish the same thing.


<H4>General Variables</H4>
<table border=1 cellspacing=1>
<tr><td width=150>$QSTATURL<td>Output the web address of the QStat home page.
<tr><td>$QSTATVERSION<td>Output the version of QStat being run.
<tr><td>$QSTATAUTHOR<td>Output the name of the QStat programmer.
<tr><td>$QSTATAUTHOREMAIL<td>Output the email address of the QStat programmer.
<tr valign=top><td>$HTML<td>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 '<tt>&lt;<tt>', '<tt>&gt;<tt>',
and '<tt>&amp;<tt>' to '<tt>&amp;lt;<tt>', '<tt>&amp;gt;<tt>', and
'<tt>&amp;amp;<tt>'.  Use this variable once in the header template.
<tr valign=top><td>$IF<td>Conditional output.  If the variable option is "true,"
the template is output up to a matching <b>$ENDIF</b> variable.  If the variable
option is "false," the template is ignored until after a matching
<b>$ENDIF</b>.  See Conditional Options for a list of supported conditional
options.
<tr><td>$IFNOT<td>Conditional output.  Same as <b>$IF</b>, but the opposite
sense.
<tr valign=top><td>$ENDIF<td>End conditional output.  There must be one <b>$ENDIF</b> for
each <b>$IF</b> and <b>$IFNOT</b> within a template.
<tr><td>$NOW<td>Output the current local time.
<tr><td>$TOTALSERVERS<td>The total number of servers to be queried.
<tr><td>$TOTALUP<td>The number of servers up and running.
<tr><td>$TOTALNOTUP<td>The number of servers either DOWN or TIMEOUT.
<tr><td>$TOTALPLAYERS<td>The number of players found on all servers.
<tr valign=top><td>$\<td>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.
<tr><td>$DEFAULTTYPE<td>The full name of the default server type specified
with <b>-default</b>.
</table>

<H4>Server Variables</H4>
<table border=1 cellspacing=1>
<tr valign=top><td width=150>$HOSTNAME<td>Output the host name of the server if known,
otherwise the server address as given to QStat.
</tr>
<tr><td>$SERVERNAME<td>Output the name of the server.
</tr>
<tr valign=top><td>$PING<td>The time in milli-seconds to get a response from
the server.  If the server is DOWN or TIMEOUT, nothing is output.
</tr>
<tr><td>$PLAYERS<td>The number of players on the server.
</tr>
<tr><td>$MAXPLAYERS<td>The maximum number of players allowed on the server.
</tr>
<tr><td>$MAP<td>The name of the map being played.
</tr>
<tr><td>$GAME<td>The name of the game being played.  This is usually the
name of the "mod" run by the server.
</tr>
<tr><td>$RETRIES<td>The number of retries needed to get the server status.
This is a measure of packet loss.
</tr>
<tr><td>$IPADDR<td>The IP address of the server.  Does not include the
port number.
</tr>
<tr><td>$PORT<td>The port the server is running on.
</tr>
<tr><td>$ARG<td>The server address as given to QStat.
</tr>
<tr valign=top><td>$TYPE<td>Output one of the following depending on the server type:
<pre>    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
</pre>
If the server type is not known, nothing is output.
</tr>
<tr valign=top><td>$TYPESTRING<td>The server's type string (see GAME OPTIONS table.)
</tr>
<tr valign=top><td>$RULE:<i>name</i><td>The value of a server rule.  If the
rule is not returned by the server, nothing is output.  Must be used with
the <b>-R</b> flag.
</tr>
<tr valign=top><td>$ALLRULES<td>Output all the server rules in the format
<i>name</i>=<i>value</i> separated by commas.  Must be used with
the <b>-R</b> flag.
</tr>
<tr valign=top><td>$PLAYERTEMPLATE<td>Invoke the player template.  The player
template is output once for each player on the server.  Must be used with
the <b>-P</b> flag.
</tr>

</table>

<H4>Player Variables</H4>
The player template is only invoked if <b>$PLAYERTEMPLATE</b> is used in the
server template.<p>
<table border=1 cellspacing=1>
<tr><td width=150>$PLAYERNAME<td>The name of the player.
</tr>
<tr><td>$FRAGS<td>The number of frags scored.
</tr>
<tr><td>$PLAYERPING<td>The player's ping time to the server.
This value is not available from Half-Life servers.
</tr>
<tr valign=top><td>$CONNECTTIME<td>How long the player has been playing.
This value is only available from Quake, QuakeWorld, Hexen II, and
Half-Life servers.
</tr>
<tr><td>$SKIN<td>The name of the player's skin texture.
This value is not available from ?? servers.
</tr>
<tr valign=top><td>$MESH<td>The name of the player's mesh (model).
This value is only available from Unreal servers.
</tr>
<tr valign=top><td>$FACE<td>The name of the player's face texture.
This value is only available from Unreal version 405+ servers.
</tr>
<tr valign=top><td>$SHIRTCOLOR<td>Color of the player's shirt.
This value is only available from Quake, QuakeWorld, and Hexen II servers.
</tr>
<tr valign=top><td>$PANTSCOLOR<td>Color of the player's pants.
This value is not available from Quake, QuakeWorld, and Hexen II servers.
</tr>
<tr valign=top><td>$PLAYERIP<td>The IP address of the player's computer.
This value is only available from Quake and Hexen II servers.
</tr>
<tr><td>$TEAMNUM<td>The player's team number.  This value is only
available from Unreal and Tribes servers.
<tr><td>$TEAMNAME<td>The player's team name.  This value is only
available from Tribes servers.
<tr><td>$PACKETLOSS<td>The player's packet loss.  This value is only
available from Tribes servers.
<tr><td>$COLORNUMBERS<td>Display $SHIRTCOLOR and $PANTSCOLOR as
numbers.  Equivalent to <b>-ncn</b> command-line option.  No output.
<tr><td>$COLORNAMES<td>Display $SHIRTCOLOR and $PANTSCOLOR using
color names.  Equivalent to <b>-cn</b> command-line option.  No output.
<tr><td>$COLORRGB<td>Display $SHIRTCOLOR and $PANTSCOLOR using
#rrggbb format.  Equivalent to <b>-hc</b> command-line option.  No output.
<tr><td>$TIMESECONDS<td>Display $CONNECTTIME as number of seconds.
Equivalent to <b>-ts</b> command-line option.  No output.
<tr><td>$TIMECLOCK<td>Display $CONNECTTIME in clock format (DhDDmDDs).
Equivalent to <b>-tc</b> command-line option.  No output.
<tr><td>$TIMESTOPWATCH<td>Display $CONNECTTIME in stop-watch format (DD:DD:DD).
Equivalent to <b>-tsw</b> command-line option.  No output.
</tr>

</table>

<H4>Conditional Options</H4>
<p>
These options maybe used with the <b>$IF</b> and <b>$IFNOT</b> variables.
For example, to display player information, the following could be used
in the server template:
<pre>
    $(IF:PLAYERS)$(IF:FLAG(-P))
    The server has $(PLAYERS) players:
    $(PLAYERTEMPLATE)
    $(ENDIF)$(ENDIF)
</pre>
The template between the <b>$IF</b> and <b>$ENDIF</b> variables will only be
displayed if the server has one or more players and the <b>-P</b>
flag was given to QStat.
<p>

<table border=1 cellspacing=1>
<tr><td width=150>GAME<td>True if the server is running a "mod."
<tr><td>PLAYERS<td>True if the server has one or more players.
<tr><td>QUAKE<td>True if the server is running Quake (the original).
<tr><td>QUAKE2<td>True if the server is running Quake II.
<tr><td>Q2MASTER<td>True if the server is a Quake II master.
<tr><td>QUAKEWORLD<td>True if the server is running QuakeWorld.
<tr><td>QWMASTER<td>True if the server is a QuakeWorld master.
<tr><td>HEXEN2<td>True if the server is running Hexen II.
<tr><td>HEXENWORLD<td>True if the server is running HexenWorld.
<tr><td>UNREAL<td>True if the server is running Unreal.
<tr><td>HALFLIFE<td>True if the server is running Half-Life.
<tr><td>HLMASTER<td>True if the server is a Half-Life master.
<tr><td>SIN<td>True if the server is running Sin.
<tr><td>TRIBES<td>True if the server is running Tribes.
<tr><td>TRIBESMASTER<td>True if the server is a Tribes master.
<tr><td>SHOGO<td>True if the server is running Shogo.
<tr><td>QUAKE3<td>True if the server is running Quake III.
<tr><td>Q3MASTER<td>True if the server is a Quake III master.
<tr><td>BFRIS<td>True if the server is running BFRIS.
<tr><td>KINGPIN<td>True if the server is running Kingpin.
<tr><td>HERETIC2<td>True if the server is running Heretic II.
<tr><td>SOLDIEROFFORTUNE<td>True if the server is running Soldier of Fortune.
<tr><td>RULE(<i>name</i>)<td>True if the rule <i>name</i> is set on
the server.
<tr valign=top><td>FLAG(<i>name</i>)<td>True if the flag <i>name</i> was used
on the QStat command-line.  The only flag names supported are:
<b>-H</b>, <b>-P</b>, and <b>-R</b>.  Any other flag name returns
false.
</tr>
<tr><td>UP<td>True if the server is up and running.
</tr>
<tr valign=top><td>DOWN<td>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.
</tr>
<tr><td>TIMEOUT<td>True if the server never responded to a status query.
<tr><td>HOSTNOTFOUND<td>True if the host name lookup failed.
<tr><td>ISEMPTY<td>True if the server has no players.
<tr><td>ISFULL<td>True if the server has the maximum players.
<tr valign=top><td>ISTEAM<td>True if the player is a team.  Only available
with Tribes servers.  <b>Only applies to the player template.<b>
</tr>

</table>

</body>
 
 
</html>