0. Table of Contents

  1. Introduction
  2. Requirements
  3. Installation
  4. Basic Usage
  5. Advanced Usage
    1. Setting Options
    2. Using Filters
    3. Creating Filters
    4. Creating A New Protocol
  6. Supported Games

1. Introduction

Note: the examples on this page are a bit out of date, check example.php in the .zip for a more recent one.

GameQ is a library to query one or more gameservers using UDP and return the formatted results in an array. It's object-oriented, and easily expandable.
GameQ has recently been completely rewritten, and is still in the alpha phase, so I'd appreciate any feedback and/or bugreports. You can contact me at tombuskens@users.sourceforge.net.

Currently over 170 games are supported.

Besides this page there is also the sourceforge project page.

toc

2. Requirements

You'll need PHP 5 to use the library. GameQ also needs permission to use UDP ports, since these are used to communicate with the gameservers.

toc

3. Installation

Make sure you've got the latest version, which can be found here. Once you've downloaded the file, simply extract it. Alternatively you can get a working version from the cvs repository.

toc

4. Basic Usage

Querying a server is pretty simple. First, you define the server(s) you want to query. For example, let's say we want to query a quake and a battlefield server. 

$servers['quakeserver'] = array('quake3', '192.168.0.1', '27962');
$servers['a bf server'] = array('bf', 'localhost');
As you can see, each entry consists of a game name, server address and optionally a query port. If you don't specify a port, the default port for the game will be used.
To check which game name to use, look in the configuration file, which is located at path/to/GameQ/games.ini.

Secondly, we initialize the main class and add the servers. 
require_once 'path/to/GameQ.php';

// Initialize the class
$gq = new GameQ;

// Add the servers we just defined
$gq->addServers($servers);
Now we're ready to request the data from the server, and process it. 
// Request the data, and display it
try {
    $data = $gq->requestData();
    print_r($data);
}

// Catch any errors that might have occurred
catch (GameQ_Exception $e) {
    echo 'An error occurred.';
}
The data returned would look like this: 
Array
(
    [quakeserver] => Array
        (
            [version] => Q3 1.32 linux-i386 Oct  7 2002
            [dmflags] => 0
            [fraglimit] => 35
            [timelimit] => 20
            [ggametype] => 4
            [protocol] => 68
            [mapname] => q3tourney6_ctf
            [svprivateClients] => 1
            [svhostname] => My local quakeserver
            [svmaxclients] => 17
            [svpunkbuster] => 0
            [svmaxRate] => 15000
            [svminPing] => 0
            [svmaxPing] => 0
            [svfloodProtect] => 1
            [svallowDownload] => 0
            [botminplayers] => 2
            [capturelimit] => 8
            [gamename] => baseq3
            [gmaxGameClients] => 0
            [gneedpass] => 0
            [players] => Array
                (
                    [0] => Array
                        (
                            [frags] => 20
                            [ping] => 0
                            [nick] => Bitterman
                        )

                    [1] => Array
                        (
                            [frags] => 28
                            [ping] => 0
                            [nick] => Razor
                        )

                    [2] => Array
                        (
                            [frags] => 5
                            [ping] => 0
                            [nick] => Patriot
                        )

                    [3] => Array
                        (
                            [frags] => 17
                            [ping] => 0
                            [nick] => Uriel
                        )

                )

            [game] => baseq3
            [punkbuster] => 0
            [pure] => 1
            [gametype] => 4
            [clients] => 4
            [address] => 192.168.0.1
            [port] => 27960
        )

    [a bf server] => Array
        (
            [hostname] => My local battlefield server
            [gamename] => battlefield2
            [gamever] => 1.1.2965-797.0
            [mapname] => Road To Jalalabad
            [gametype] => gpm_cq
            [gamevariant] => bf2
            [numplayers] => 2
            [maxplayers] => 32
            [gamemode] => openplaying
            [password] => 0
            [timelimit] => 3600
            [roundtime] => 2
            [hostport] => 16567
            [bf2dedicated] => 1
            [bf2ranked] => 1
            [bf2anticheat] => 1
            [bf2os] => linux
            [bf2autorec] => 0
            [bf2didx] => 
            [bf2ddl] => 
            [bf2voip] => 1
            [bf2autobalanced] => 1
            [bf2friendlyfire] => 1
            [bf2tkmode] => Punish
            [bf2startdelay] => 15
            [bf2spawntime] => 15.000000
            [bf2sponsortext] => Howdy
            [bf2scorelimit] => 0
            [bf2ticketratio] => 100
            [bf2teamratio] => 100.000000
            [bf2team1] => MEC
            [bf2team2] => US
            [bf2bots] => 0
            [bf2pure] => 1
            [bf2mapsize] => 64
            [bf2globalunlocks] => 1
            [bf2fps] => 33.000000
            [bf2plasma] => 0
            [bf2reservedslots] => 0
            [bf2coopbotratio] => 
            [bf2coopbotcount] => 
            [bf2coopbotdiff] => 
            [bf2novehicles] => 0
            [players] => Array
                (
                    [0] => Array
                        (
                            [player] => Bob
                            [score] => 36
                            [ping] => 30
                            [team] => 2
                            [deaths] => 6
                            [pid] => 47837808
                            [skill] => 11
                            [AIBot] => 0
                        )

                    [1] => Array
                        (
                            [player] => Jimmy
                            [score] => 36
                            [ping] => 28
                            [team] => 2
                            [deaths] => 7
                            [pid] => 68243063
                            [skill] => 9
                            [AIBot] => 0
                        )
                )

            [teams] => Array
                (
                    [0] => Array
                        (
                            [teamt] => MEC
                            [scoret] => 0
                        )

                    [1] => Array
                        (
                            [teamt] => US
                            [scoret] => 0
                        )

                )

            [address] => 192.168.0.1
            [port] => 29900
        )

)
The default timeout for the server response is 200 milliseconds. If you want to change this, see Setting Options.
That's all there is to it. Of course, you'll most likely need to display the received data in a proper way, instead of simply dumping the array, but I'll leave that to your imagination.

toc

5. Advanced Usage

5.1. Setting Options

Options currently supported are

You can set options using the GameQ::setOption() method. 

// Set server timeout to 500ms and return only raw data
$gq->setOption('timeout', 500);
$gq->setOption('raw', true);

5.2. Using Filters

You can add filters to modify results received from servers. Currently there are two filters included:

Filter classes are located in path/to/GameQ/Filter/. 

// To use a filter, call setFilter before requestData
$gq->setFilter('normalise');

// You can also remove the filters
$gq->removeFilter('normalise');

5.3. Creating Filters

TODO

5.4. Creating A New Protocol

TODO

toc

6. Supported Games

These games / game engines are currently supported:

(There is also support for the common voip servers Teamspeak 2 and Ventrilo)

If you feel there's a game missing, feel free to let me know, and I'll see what I can do.

toc