## General Notes

gsQuery is a PHP library that allows you to query various game servers for things like number of players, the players itself, current map etc. The main goal of this class is to support as many games as possible. So some game specific thinks cannot be fetched with this class yet.

The current version of gsQuery is 0.1.2. You can get it here. The API documentation and an example is included.

The previous release is 0.1.1. You can get it here.

The unstable version can be downloaded from cvs.terragate.net. You can do this with the CVS command: `cvs -d:pserver:anonymous@cvs.terragate.net:/var/lib/cvs co gsQuery` or with WinCVS (here is a small howto). You can browse the CVS here.

This library was part of the PHPNuke Gameserver module, but has been seperated from it with version 0.0.4

Please post any suggestions, comments, and bug reports to the gsQuery Forum on this site.

## License

This library is free Software. It is licensed under the GNU Lesser General Public License (LGPL).

## Supported games

Currently the following games are known to work:

- Unreal Tournamnet and most mods (gameSpy)
- Unreal Tournamnet 200x and most mods (gameSpy)
- Battlefield 1942 and most mods (gameSpy)
- Halflife and most Mods (hlife)
- America's Army (armyGame)
- Quake 3 and some Mods (q3a)
- Star Trek: Elite Force (q3a)
- Medal of Honor Allied Assault (q3a)
- MoHAA: Spearhead/Breakthrough (mohs)
- Return to Castle Wolfenstein (q3a)
- Vietkong (vietkong)
- Rainbow Six: Raven Shield (rvnshld)
- Call of Duty (q3a)
- Battlefield Vietnam (gameSpyQ)
- Quake 2 and most mods (q2)
- Kingpin (q2)
- Sin (q2)
- Farcry (farCry)
- IGI2: Covert Strike (igi2)
- Jedi Knight 3 (q3a)
- Solider of Fortune 2 (sof2)
- Far Cry (farCry)
- Quake 2 (q2)
- Kingpin (q2)
- Heretic 2 (q2)
- Halo (halo)
- Deus Ex (deuxEX)
- Doom 3 (d3)
- Halflife 2 (hlife2)
- CS:Source (hlife2)
- Savage: The Battle For Newerth (savage)
- StarWars BattleFront (gameSpy)
- And probably more

If your game isn't listed here but is based on the same engine as one of the above chances are good that it can be queried with this library. Futhermore you can try it with the gameSpy protocol which many games support.

## Requirements

- PHP >= 4.2
- PHP Socket support
- A provider that allows inbound/outbound UDP traffic

If your provider does not allow UDP traffic but HTTP is allowed (often the case) try out TerraGate's game server query service

## Installation

Upload the contents of the src folder to your desired location on your web server (e.g. /gsQuery). You can test gsQuery with the example ( http://mydomain.com/path/to/gsQuery/examples/ ).

## Usage

For infos about how to use gsQuery take a look into the API documentation which can be found in the doc directory of the gsQuery package. An example is also included. Alternativly you can use the example and adjust the HTML and CSS to fit your needs.

## About the query port

If you want to add a server that is talking the gsqp (Game Server Query Protocol) you have to know the query port for it. Sometimes it can be hard to figure out that. Here is a small overview of games where the query port is known:

Game name | Rule
--- | ---
Unreal Tournament | queryport=gameport+1 (e.g. 7777+1=7778)
Unreal Tournament 200x | queryport=gameport+10 (e.g. 7777+10=7787)
Battlefield 1942 | Default queryport is 23000 (no rule found yet)
America's Army | queryport=gameport+1 (e.g. 1716+1=1717)
Ravenshield | queryport=gameport+1000

In most cases you can use the same query port (or better: the same rule) for games based on the same engine, but not always e.g. Americas Army is based on the UT2003 Engine and is using gameport+1 (1716+1=1717) as the default query port (UT2003 has changed the default query port after the first patch from 7778 to 7787). If you figure out more query ports please let us know about it and post them to the mailing list.

In case of the Halflife (hlife) and the Quake III (q3a) protocol the query port is identicial to the game port.

## Donation

You can make a donation for this project to help paying web server costs if you like

## Changelog

### Changes in 0.1.2:

- Native Support for MoHAA: SpearHead added
- Support for Quake 2 added
- Support for Farcry added
- Support for IGI2 added
- Support for Halo added
- Support for Deus Ex added
- Support for Doom 3 added
- Support for Halflife 2 / CS:Source added
- Support for Savage added
- rvnshld: More data fetched
- hlife: Process more than one packet
- hlife: player code clean up
- Instance can be used for multiple querys now
- Hex dump generation of received data possible
- Various other minor fixes

### Changes in 0.1.1:

- Support for Call of Duty added
- Support for Battlefield Vietnam added
- Support for Solider of Fortune 2 added
- Colortags in the q3a protocol can be converted to html
- UT2004 colortags can be converted to html
- hlife nextmap does work now
- hlife gameversion added
- q2a maplist fix
- q3a and hlife rcon command support
- Preventing some uninitialized values
- Added a simple example
- Added serialization/deserialization methods
- Fetching serialized objects via HTTP
- Various other minor fixes

### Changes in 0.1.0:

- New API
- Completly Refactored
- Library can be easily extended now
- Support for Vietkong added
- Support for Rainbow Six: Raven Shield added
- Support for America's Army new protocol added
- GameJoiner link creation (allows to join the game)
- Nextmap should work for hlife now
- API documentation written
- Added an example

### Changes in 0.0.5:

- Added support for games based on the q3a engine (including MoHAA and RtCW)
- Sorting incoming gsqp packets now
- Support for more player infos like deaths, team, frags, score, time etc...
- password has 3 states at least (-1=unknown, 0/False=no password, 1/True=locked)
- sortPlayers added (You can sort by various keys)
- All available gsqp player infos are fetched
- Fixed hlife maxplayers bug
- Removed deprecated fsockopen call

### Changes in 0.0.4:

- Public/Private state is correctly returned