VERC: Half-Life Server Protocol Last edited 3 months ago2024-09-01 20:10:10 UTC

Introduction

This article is a reference to a method of using the server protocol with PHP. If you are not familiar with PHP, see the tutorials on the PHP website. The method is compatible with Steam dedicated servers.

With the Half-Life server protocol, it is simple to send requests to the WON master servers, and standard game servers via almost any programming language. For this tutorial, I will be using PHP. We will send a request to a regular Half-Life game server and parse the data that can be used on a website for live server information.

Half-Life Server Protocol

With the Half-Life server protocol, all packets sent to the server must be sent with four consecutive bytes of 255, then a specific string command and end it with a byte with a zero value. To send a 255 byte value with PHP you will use the octal value in your string.

With the server protocol, there are several string commands you can send. For now, I will only explain one command. If you wish to use other commands, check out the Server Protocol.txt in the SDK.

The infostring command is not documented in the document provided in the SDK. I found this command by looking at the raw packets with a packet sniffer when the Half-Life server browser refreshed its list. The packets returned after you send the infostring command are nicely formatted with back slashes between values so they can easily be placed in an array using some common PHP functions.

Sending the Request

To send the request, we must first open a connection to the server. The Half-Life game sever uses a UDP port for client connections. You use the same port to the server as you would if you were connecting through Half-Life. For the example, the server is running on 127.0.0.1 (localhost) with 27016 as the port. To call a connection with PHP, you use the fsockopen function:

<?php
// IP address
$ServerIP = "127.0.0.1";
// Server port
$ServerPort = "27016";
// Create the variables of the info command to send to the server.
$ServerinfoCommand = "\377\377\377\377infostring\0";

// Open a connection to the server
$fp = fsockopen("udp://".$ServerIP, $ServerPort, $errno, $errstr);

//Send the request to the server.
fwrite($fp, $ServerinfoCommand);

//Remove the junk headers sent back
$JunkHead = fread($fp,24);

// Check to see if the server is running
$CheckStatus = socket_get_status($fp);
if($CheckStatus["unread_bytes"] == 0)
{
    die("Unable to connect to the server, ensure the IP and port is correct and that the server is running.");
}

// Read through the returned data and put in variable
$do = 1;
$HLServerStats= "";
while($do)
{
    $str = fread($fp,1);
    $HLServerStats.= $str;
    $status = socket_get_status($fp);
    if($status["unread_bytes"]  == 0) {$do = 0;}
}
//Close the connection
fclose($fp);
?>

With the above code, it sends the command to the server with the fwrite function. Then a while loop creates a variable with all the data returned from the server. When this code is run, you should receive the results of the infostring command.

Parsing the Data

Now, we have the raw data returned from the server. We should be able to parse the data to be used on a web page. Now, we will split the string into an array, then assign each returned value into another organized array for easy use.

<?php
// Explode the packet into an array.
$HLServerStats = explode("\\", $HLServerStats);

// Count the amount of keys in the array.
$count = count($HLServerStats);

// The amount of keys in the array MUST be an even number
if($count % 2 == 0)
{
    // Loop though all the keys and put them in the $ServerData array with the key values.
    $i = 0;
    while($count != $i)
    {
        $ServerData[$HLServerStats[$i]] = $HLServerStats[$i+1];
        $i = $i + 2;
    }
}
?>

Returned Values

Returned data from the code will return some commonly used information about the server. Here is a list of keys you can use use and a description of what they are:

address - IP Address of the server
players - Number of players currently playing
max - Max number of players that can connect
gamedir - Directory of the mod being played (IE: tfc)
map - Current map being played
type - Type of server: d for dedicated, l for listen.
os - OS the server is running on: w for Windows, l for Linux.

Now, if you're going to use the data in a webpage, the data is all stored in the $ServerData array. You can now use the following code snippet, simply changing "VALUENAME" to the key of the value you wish to display. simply use

<?php echo($ServerData["VALUENAME"]); ?>

This method is useful for Gaming websites; for example, displaying the status of a Clan's server. This is for you to do, so please do not email the author requesting custom scripts to be written.