########################################################################

Program: Gslist
Author:  Luigi Auriemma
e-mail:  aluigi@autistici.org
web:     http://aluigi.altervista.org

########################################################################


1) Introduction
2) Features
3) Installation
4) Options
5) Conclusion


########################################################################

===============
1) Introduction
===============


Gslist is a command-line game servers browser and heartbeats sender with
multiple options and functions.
It supports an incredible amount of games (over 700 continuely and
officially updated) because it is based on the Gamespy master server
master.gamespy.com that is ever fully updated with the latest games in
the world... this is one or probably the only advantage of the Gamespy's
monopoly for multiplayer games.

The tool naturally is open source (released under GPL) and can be
compiled on a lot of systems.
Its usage is suggested moreover for advanced people that play a lot with
the console (aka terminal), testers, admins and anyone who needs
something to see the servers list of a specific game and only that,
without automatic pings and other useless things.
This tool gives you the list of online servers, that is its main job.

Note that the ports you see when retrieve the servers list are usually
the query ports, not the game ports (also if often they are the same).
The query port is an UDP port used to send server's informations and the
game port is usually a parameter contained in these replies.

If you have ideas about new options or functions contact me!


########################################################################

===========
2) Features
===========


Some features of Gslist:

- tons of games supported, it is probably the only application in the
  world that supports a so long list of games (thanx to the Gamespy's
  monopoly naturally)
- an useful filter lets users to receive the list of servers that match
  specific requirements like no empty servers or servers located in a
  specific country and more
- an output option permits to create front-ends for Gslist or to
  implement Gslist in any enviroment where other applications must read
  the data contained in the files created by the program or from its
  direct output (stdout)
- can be used also to query the online servers using the old and new
  Gamespy query plus a lot of other queries available with the -d option
- you can launch a specific application for each game server found
- heartbeat sender, so your IP can be put in the online servers list and
  other players can find your server
- optimized for speed and resources
- portable and opensource
- Gslist is supported and open to new ideas and features
- others...


########################################################################

===============
3) Installation
===============


*nix:
- make
- make install
  (the file gslist will be put in /usr/local/bin)
- when launched for the first time the tool automatically creates its
  working directory .gslist in the home directory of the current user
  (~/.gslist). In this location will be stored the configuration file
  called gslist.cfg and the other 2 temporary files needed to update the
  games database

Windows:
- copy gslist.exe in a directory (c:\gslist for example)
- the tool uses the current directory from which it is launched, so
  launch it ever from the directory in which you have placed it


########################################################################

==========
4) Options
==========


-e             
 this option shows some quick examples to use Gslist and some of its
 features.
 Useful if you don't remember the syntax of a command or what you are
 doing wrong.


-N GAMENAME
 you can retrieve the servers list of a specific game simply specifying
 its gamename.
 Gamename is a text string identifying a game, for example aoe for Age
 of Empires, ut2004 for Unreal Tournament 2004, doom3 for Doom 3, mohaa
 for Medal of Honor Allied Assault and so on.
 All the available gamenames can be seen through the -s and -l options.
 Example: -N doom3


-n NUM
 just as above but instead of specifying the gamename you must specify
 the number at the left of the game of which you want to retrieve the
 servers list.
 This option is now considered obsolete because the number often changes
 when you update the game database (-u option) so -N is preferred.


-l
 lists the entire database of supported games.
 From version 0.6 of Gslist, the database is contained in a text file
 called gslist.cfg. This file is just the same data showed by this
 option so you can read the file also with a normal text editor.


-s PATTERN
 the most needed function to use Gslist. In fact it must be used to
 search a specific game, gamename, gamekey or any other thing contained
 in the file gslist.cfg.
 The function is case insensitive, that means is not important if the
 pattern you search is in lower, higher of both cases because the
 function finds it ever.
 Example: -s unreal, -s UNREAL, -s uNrEaL
          the result is ever the same for all the 3 examples


-u
 used to update the game database.
 New games are released almost each week so also the database is updated
 with the new games supported by Gamespy.
 This option lets you to contact the Gamespy webserver, retrieve the new
 database and create the file gslist.cfg that contains a compact and
 readable list of supported games, gamenames and gamekeys.
 The function doesn't delete the 2 temporary files downloaded from the
 webserver because I think you could find interesting informations in
 them also if they are useless for Gslist.
 If you are an avid gamer I suggest you to use this option each week.
 From version 0.6.3 the list is updated only when needed so you can use
 the -u option enough often without wasting time and bandwidth.


-i HOST PORT
 sends the \status\ query (known as the old Gamespy query protocol) to
 a specific server and port and then waits a reply.
 Naturally the game server must support this type of query (alsmost any
 game listed supports this or the -I query).
 Example: -i localhost 7787, -i 192.168.0.1 12203


-I HOST PORT
 just as above but instead of \status\ it sends the new Gamespy query
 composed by the bytes "fe fd 00 xx xx xx xx ff 00 00" where xxxxxxxx
 are replaced with a partially random value.
 Example: -I localhost 7787, -I 192.168.0.1 12203


-d T HOST PORT
 this is an option that can be used to query a server using different
 protocols, like that used by Quake 3, Half-Life, DirectPlay8, Doom3
 and so on.
 The parameter T is referred to the type of query to use, you can see
 the list of available queries simply without specifying any parameter
 or using ? as T parameter.
 Example: -d 1 127.0.0.1 27960, -d 5 localhost 6073
          -d   or -d ?   for details


-f FILTERS
 specify a filter to apply to the servers list before returning.
 This option is really very useful in some cases, in fact the Gamespy
 master server supports SQL queries to filter the servers list for
 example to avoid empty or full servers, or to receive only italian
 servers and many other things.

 The valid operators you can use are:
  <>, !=, >=, !<, <=, !>, =, <, >, (, ), +, -, *, /, %,
  AND, NOT, OR, LIKE, NOT LIKE, IS NULL, IS NOT NULL

 While the items are:
  hostaddr, hostport, gamever, country, hostname,
  mapname, gametype, gamemode, numplayers, maxplayers

 Is also possible to use the wildcard character %
 The delimiter for the text strings is the character '

 Some usage examples:
 - for servers with players: -f "(numplayers > 0)"
 - for empty servers only:   -f "(numplayers = 0)"
 - for finding the IP of the server with the name Jackass:
                             -f "(hostname LIKE 'Jackass')"
 - for all the server with a name containing the text ass:
                             -f "(hostname LIKE '%ass%')"
 - for italian servers:      -f "(country = 'IT')"
 - for servers on port 10    -f "(hostport = 10)"
 - for servers using the version 1.1 of the game:
                             -f "(gamever = '1.1')"

 ...all your fantasy, the filters are so useful and huges that you can
 do everything you want with them. However remember that the filters
 refers to the informations obtained by the Gamespy master server from
 the last query made by it to the game servers (usually a query for each
 heartbeat) so is possible that you are filtering old informations
 because heartbeats have a timeout of 5 minutes.
 Remember ever to delimit your filter with the char ", like in the above
 examples.
 Some useful links:
   http://www.gamespyarcade.com/support/filter.shtml
   http://www.gamespyarcade.com/support/help/filter.shtml
   http://www.gamespyarcade.com/helpers/workshop/filters/


-c
 an useful function to show all the available country codes for the
 "country" filter (like IT for Italy, US for USA, UK for England and so
 on).


-r "prog..."
 a cool and really original option. It lets you to execute a specific
 program for each server and port found.
 With "prog..." I mean the command to execute with all its arguments.
 There are 2 patterns that are substituited with the current IP and
 port of the server found in the servers list, they are #IP for the IP
 address of the server and #PORT for its query port.
 If for example I use:
   -r "echo the server #IP listens on port #PORT, nice"
 the program will execute the command:
   echo the server 127.0.0.1 listens on port 100, nice
   (if the IP and port in the list are 127.0.0.1 and 100, naturally).


-b PORT
 the heartbeats sender. Lets your IP address to be included in the
 online servers list located on the master server. PORT is the port used
 by your server (usually the query port).
 PORT is bound for some milliseconds to be able to reply to the master
 server's queries or to the possible validation requests that arrives
 when the heartbeat is sent, so during this short time your server will
 be not accessible by other users.
 The -b and -B options must be used with any of the options -n, -N or
 -y.
 Note: I consider this option a bit experimental because binding the
       port could cause some problems or packets loss to your server,
       so is preferred the option -B.
       Use it only for tests or for games that don't support the old
       Gamespy query (\status\).
 Example for UT2004: -b 7787 -N ut2004


-B PORT
 exactly as above but the PORT will not be bound.
 Use this option only if your server supports the old Gamespy protocol
 (\status\) and so it can reply to the master server query.
 Remember that if you don't reply to the query you will not be added in
 the servers list.


-x S[:P]
 you can choose a master server and a port different than
 master.gamespy.com:28900.
 This option is useful for tests or if you know a master server that
 uses the Gamespy master server protocol (like the EpicGames master
 server for Unreal Tournament).
 The port is optional and the default one is 28900.
 Example: -x localhost, -x localhost:12345


-o [OUT]
 used to dump the received servers list to files instead of screen or in
 a different format.
 You can choose between 5 types of outputs (OUT):

 1: the servers list is dumped in text format to a file that has the
    name of GAMENAME plus the extension gsl.
    The text output is composed by the IP, ':', the port and a line-feed
    (the byte 0x0a).
    Example of quake3.gsl if we have chosen the game Quake 3:
    1.2.3.4:1234
    11.22.33.44:4321

 2: exactly as above with the only difference that the output file is
    EVER gslist-out.gsl

 3: the servers list is dumped in binary format to a file that has the
    name of GAMENAME plus the extension gsl.
    With binary output I mean the network-byte format used for IPs and
    ports (just as received from the master server) so the data
    contained in this output is already ready to be used with sockets.
    An example of IP and port contained in hex format in the file:
    7F0000011E62 = 127.0.0.1 7778

 4: exactly as above with the only difference that the output file is
    ever gslist-out.gsl

 5: screen output using the classical format IP:port, like
    127.0.0.1:12345

 6: hex dump of the raw data received from the server. If you have
    used the -t 2 option you will see the encrypted raw data.
    Needed only for debugging.

 X: if OUT is not 1, 2, 3, 4, 5 or 6 it will be considered a filename to
    which send all the servers list output (just as what you seen
    normally on the screen)


-q
 quiet output, practically only the list of servers and nothing more


-y NAME KEY
 lets you to choose a specific GAMENAME and KEY.
 This option is very useful if you are interested to only one game and
 so you don't need or don't want the game database.
 Example for Quake 3 Arena: -y quake3 paYVJ7
 Or -y gslive Xn221z that is for Gamespy Arcade and is not contained in
 the game database.
 Naturally both the 2 required arguments are visible with the -l and the
 -s option (except some rare cases like that of Gamespy Arcade and
 possibly others).
 I HIGHLY suggest to check my list of add-on games that are not
 available in the updated configuration file:

   http://aluigi.altervista.org/papers/gshkeys.txt


-t NUM
 an almost useless option. Gslist supports both enctype 0 and 2.
 The only difference is that the servers list is encrypted (and
 automatically decrypted by Gslist) when you use enctype 2 while is in
 clear text for enctype 0.


-v
 shows the version of Gslist


########################################################################

=============
5) Conclusion
=============


As already said the program is open to new ideas and functions so let me
know your ideas, suggestions and feedback (moreover bug reports) or if
you have not understood something.


########################################################################
