Documentation

Support

Multiplay Clanforge

Open Clanforge

Multiplay Clanforge

QStat reference

Documentation for QStat reference
Read time 7 minutesLast updated 8 hours ago
QStat is an open source command-line program that retrieves and displays information from game servers that have implemented a game server query protocol. It supports reporting information such as the state of the game server, the server name, the map name, the number of connected players, the ping response time, game server rules, and player information. The basic syntax for QStat is 
qstat [options] [-f file] [-of | -af output-file] [-server-option host[:port]]
.

General variables

Variable

Description

$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 '
\&lt
;', '
\&gt
;', and '
\&amp
;'. Use this variable after in the header template.
$CLEARNEWLINES
Convert line feeds and carriage returns into spaces. Applies to all variables that output strings. Use this variable after in the header template.
$RULENAMESPACES
Allow spaces in rule names. Use this variable after 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
. Refer to 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.
$TOTALMAXPLAYERS
The sum of the maximum player values for all servers.
$TOTALUTILIZATION
The ratio of 
$TOTALPLAYERS
 to 
$TOTALMAXPLAYERS
 expressed as a percentage (a number between 0 and 100). Reports how full the servers are.
$
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
.

Server variables

Variable

Description

$HOSTNAME
Output the hostname of the server if known, otherwise the server address as given to QStat.
$SERVERNAME
Output the name of the server.
$PING
The time in milliseconds 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. Doesn't include the port number.
$PORT
The port the server is running on.
$ARG
The server address as given to QStat.
$TYPESTRING
The server's type string (refer to Game options table.)
$TYPEPREFIX
The server's type prefix (same as 
$TYPESTRING
 but in all-caps.)
$RULE:name
The value of a server rule. If the rule isn't returned by the server, nothing is output. Must be used with the 
-R
 flag. Server rule names can include any alpha-numeric character plus '*', '_', '.', or ' ' (space). The use of space in a rule name requires using the parenthesized format: 
$(RULE:name)
$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 after for each player on the server. Must be used with the 
-P
 flag.
$RULETEMPLATE
Invoke the rule template. The rule template is output after for each server rule.

Player variables

Variable

Description

$PLAYERNAME
The name of the player. If 
-htmlnames
 or 
$HTML
 is used, then HTML color font tags will be added for Quake 3 and Tribes 2 player names. If 
$HTML
 is used but 
-nohtmlnames
 is set, then player names will not be colorized.
$HTMLPLAYERNAME
The name of the player with HTML color font tags. Only Quake 3 and Tribes 2 are supported.
$FRAGS
The number of frags scored.
$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.
$PLAYERSTATID
The player's global statistics ID. This value is only available from Unreal Tournament 2003 servers.
$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.

Rule variables

Variable

Description

$RULENAME
The server rule name.
$RULEVALUE
The server rule value.

Conditional options

Option

Description

GAME
True if the server is running a "mod."
PLAYERS
True if the server has one or more players.
UNREAL
True if the server is running Unreal.
RULE(name)
True if the rule name is set on the server. Server rule names can include any alpha-numeric character plus '*', '_', or '.'. If 
$RULENAMESPACES
 is enabled, then rule names may contain a ' ' (space).
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.
ISMASTER
True if this is a master server.
ISFULL
True if the server has the maximum players.
ISTEAM
True if the player is a team. Only available with Tribes and Tribes 2 servers. Only applies to the player template.
ISBOT
True if the player is a bot. Only available with Tribes 2 servers. Only applies to the player template.
ISALIAS
True if the player is using an alias. Only available with Tribes 2 servers. Only applies to the player template.
TRIBETAG
True if the player has a tribe tag. Only available with Tribes 2 servers. Only applies to the player template.
RULENAME
True if the rule name matches the variable argument. For example, 
$(IF:RULENAME(version))
 is true when the rule template is outputing a "version" server rule. Only applies to the rule template.
RULEVALUE
True if the rule value matches the variable argument. For example, 
$(IF:RULEVALUE(1))
 is true when the rule template is outputing a server rule whose value is "1". Only applies to the rule template.
DEATHS
True if the player has recorded DEATHS in Descent 3 or if the player is dead in Ghost Recon. NOTE if the Ghost Recon player has spawns available they can go from dead to alive.

Info options

Option

Description

-R
Fetch and display server rules.
-P
Fetch and display player information.

Display options

Option

Description

-of \<file>
Write output to file instead of 
stdout
or the console. 
<file>
 is overwritten if it already exists.
-af \<file>
Like 
-of
, but append to the file. If 
<file>
doesn't exist, it's created.
-u
Only display hosts that are up and running a game server. Doesn't affect template output.
-nf
Don't display full servers. Doesn't affect template output.
-ne
Don't display empty servers. Doesn't affect template output.
-nh
Don't display the header line (doesn't apply to raw or template output).
-nx
Perform name transforms. Transform game-specific player and server name escape sequences into more readable text. This setting is ON by default.
-nnx
No name transforms. Don't transform player and server names. Option 
-utf8
 implies 
-nnx
.
-tc
Display time in clock format (
DhDDmDDs
). This is the default.
-tsw
Display time in stop-watch format (
DD:DD:DD
).
-ts
Display time in seconds. This is the default for 
-raw
 mode.
-sort \<sort-keys>
Sort servers and/or players. Servers and players are sorted according to 
<sort-keys>
. Lower case sort keys are for servers, and upper case keys are for players. The following sort keys are supported:
  • p
    : Sort by ping
  • g
    : Sort by game (mod)
  • i
    : Sort by IP address
  • h
    : Sort by hostname
  • n
    : Sort by number of players
  • l
    : Sort by list order
  • P
    : Sort by player ping
  • F
    : Sort by frags
  • T
    : Sort by team
The 'l' (ell) sort key displays servers in the order they were provided to QStat. For example, the order in which they're listed in the command-line or in a file. The 'l' sort key can't be combined with other server sort keys, but it can be combined with player sort keys. If the 'l' sort key is used with other sort keys, then the 'l' sort key is ignored.
-hpn
Display player names in hex.
-raw \<delimiter>
Display data in "raw" mode. The argument to 
-raw
 is used to separate columns of information. All information returned by the game server is displayed. Server rules are displayed on one line as 
rule-name=value
. 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.
-xml
Output server information wrapped in XML tags.
-utf8
Use the UTF-8 character encoding for XML output.
-showgameport
Always display the game port in QStat output. If the query port was different from the game port, then the query port will be saved in the 
\_queryport
server rule. This is the same as the 
showgameport
 server query argument but applies to all server queries.
-errors
Display errors.
-d
Enable debug options. By default, it enables printing of all received packets to 
stderr
.

Search options

Option

Description

-H
Resolve IP addresses to hostnames. Use with caution as many game servers don't have registered hostnames. 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 trying to query any servers.
-Hcache \<cache-file>
Cache hostname and IP address resolutions in 
<cache-file>
. If the file doesn't exist, it's created. If 
-Hcache
 is used without 
-H
, then the cache is only used for host to IP address resolution.
A host cache file should not 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. 
-interval \<seconds>
Interval in seconds between server retries. Specify as a floating-point number. The default interval is 0.5 seconds. This option doesn't apply to master servers (refer to 
-mi
.)
-mi \<seconds>
Interval in seconds between master server retries. Specify as a floating-point number. The default interval is 2 seconds.
-retry \<number>
The number of retries. QStat will send this many packets to a host before considering it non-responsive. The default is 3 retries.
-maxsimultaneous \<number>
The 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. These limits can be increased by minor changes to the code, but the change is different for each platform. The default is 20 simultaneous queries. This option may be abbreviated 
-maxsim
.
-timeout \<seconds>
Total run time in seconds before giving up. The default is no timeout.

Network options

Option

Description

-srcport \<port-number | port-range>
Specify the source ports for sending packets. The ports can be a single number or a range. A range is two numbers separated by a dash ('-'). The numbers should be positive and less than 65535. Use this option to get through a firewall that has source port restrictions. Set 
-srcport
 to the range of ports allowed by the firewall.
-srcip \<IP-address>
Specify a local IP address from which to send packets. This is useful on machines that have multiple IP addresses where the receiver checks the source IP of a packet. Normally this option is never needed.