UT2003area API reference

This version : 1.0 (UT2003area-api-1.0.html)
Lastest version : UT2003area-api.html
Last modified : 2002-10-14

Copyright (c) 2002 Guillaume Cocatre-Zilgien

Abstract

This document is a complete reference for the API of the UT2003area library, a set of tools for quering Unreal Tournament 2003 servers. The API provides variables and functions that make the set up of UT2003 server status pages easier. As of version 1.0, it is pretty stable and won't change anymore. It will probably be updated though (i.e. addition of new variables and / or functions) when Epic Games updates UT2003 server software.

Contents

• 1. The UT2003area_Server class
• 2. Functions
  • 2.1. The class constructor : UT2003area_Server()
  • 2.2. getBasicInfos()
  • 2.3. getSettings()
  • 2.4. getPlayersInfos()
  • 2.5. sortPlayers()
• 3. Variables
  • 3.1. Library related variables
  • 3.2. User provided variables
  • 3.3. Core variables
• 4. Ressources

1. The UT2003area_Server class

This class provides functions for quering UT2003 servers and extracting useful informations out of their answers. It uses the new binary protocol, used in the game itself. It is lightweight and more reliable than the usual GameSpy protocol. All of the extracted informations are available through a set of variables.

This class requires the latest version of PHP to be installed (versions 4.2.2 or 4.2.3 are highly recommended).

Extensions like map screenshots, HTML output are not provided. This library is restrained to its original purpose.

2. Functions

The following functions are public, meaning that they are part of the API. Other functions are private : they are the core functions of the library, and are not meant to be called directly.

2.1. The class constructor : UT2003area_Server()

object UT2003area_Server(string address, integer port [ , string timeout ])

It is the function that creates a UT2003area_Server object. It takes two mandatory arguments (server address, game port) and one optional argument (timeout). More informations about PHP constructors can be found here.

The server address can be either a hostname or an IP address. The timeout argument is composed of a number of seconds and a number of microseconds, separated by a coma (,). It defaults to "1,000000" (1 second, 0 microseconds).

Usage : $server = new UT2003area_Server("127.0.0.1", 7777);

2.2. getBasicInfos()

boolean getBasicInfos()

This function extracts basic informations about the server. It returns true on success, and stores the informations in the object's variables title, map_name, map_title, game_mode, num_players, max_players. It returns false on failure (i.e. server query failure).

Usage : $got_basic_infos = $server->getBasicInfos();

2.3. getSettings()

boolean getSettings()

This function extracts server settings. It returns true on success, and stores the informations in the object's variables settings, dedicated, private, stats, translocator, score_limit, time_limit, min_players. It returns false on failure (i.e. server query failure).

Usage : $got_settings = $server->getSettings();

2.4. getPlayersInfos()

boolean getPlayersInfos()

This function extracts informations about the players that are currently on the server. It returns true on success, and stores the informations in the object's variables player_names, player_pings, player_scores, player_stats_ids, num_players. It returns false on failure (i.e. server query failure).

Usage : $got_players_infos = $server->getPlayersInfos();

2.5. sortPlayers()

array sortPlayers([ string sort ] [ , string order ])

This functions returns a sorted list of the players that are currently on the server, based on the informations extracted by getPlayersInfos(). It takes two optional arguments, sort and order, determining how the returned list will be sorted. sort can be one of "scores" (default), "names", "pings" and "stats_ids". order can be one of "descending" (default) and "ascending".

Usage : $players = $server->sortPlayers();

3. Variables

All of the following variables are public, i.e. they may be accessed freely.

3.1. Library related variables

3.2. User provided variables

The following variables are directly influenced by the informations the user provided when creating a UT2003area_Server object.

3.3. Core variables

The following variables are modified by the public functions.

4. Ressources

• UT2003 Demo query packet by Chris Weiss (aka 'FragMe')
• UT2003 Server query protocol by Michiel 'El Muerte' Hendriks
• IpServer Package for Unreal v1.0 by Brandon Reinhart, Epic Games
• PHP : Hypertext Preprocessor downloads page
• Constructors by the PHP Documentation Group