libq2packet

version 1 (c) viciouz.co.uk

---

About

libq2packet is a PHP library which can parse network packets from the game Quake 2 and deriviatives, allowing programmers to extract information from demo files.

---

License

The libq2packet code is Copyright Steve Cox 2010, and is made available under the GNU General Public License Version 3

---

Using libq2packet

Creating an instance of the q2Packet class is easy!

$q2Packet = new q2Packet((optional)$packetData,(optional)$debugMode)

The parameters are fairly simple: $packetData is incase you want to add some data to the packet buffer now, instead of having to call the instance's NewPacket method later. $debugMode is a boolean value incase you want libq2packet to output debug information about every message it parses.

If you've already parsed one packet and want to parse another, you can quickly replace the packet buffer with the NewPacket method.

$q2Packet->NewPacket($packetData)

There is only one parameter, which is required, and represents the packet data which will replace the current packet buffer.

As it is rarely needed to process all the data from every packet, libq2packet will only return data when the programmer specifies it is necessary. This is done by adding handlers for certain types of server message. These can be dynamically added and removed during parsing. When a handler function is added, it is called whenever a server message that it is registered to handle is parsed. The handler function is called with an associative array of the data that libq2packet decoded. Here follows a list of returned information for each packet type. There can only be one handler for each type of server message at a time.

$q2Packet->AddHandler($svc_type,$function_name)

This adds the function $function_name to the handlers array, to handle the $svc_type message type.

$q2Packet->RemoveHandler($svc_type)

This removes the current handler for $svc_type from the array.

Now to actually extract the data - to do this we use the ParsePacket method.

$q2Packet->ParsePacket($fastParse)

This function actually does the work. It parses through the buffer and calls any set handlers where appropriate. There is one parameter, $fastParse, which determines whether or not to speed up parsing by skipping unnecessary packets. Currently this is recommended to be set to "true" for deployment usage as it speeds up processing by many seconds for long demos.

---

Example

// Create instance of q2Packet - $packetData is quake2 packet data, minus size header
$packet = new q2Packet($packetData);

// Add a handler for "svc_serverdata" messages
$packet->AddHandler(svc_serverdata,"ServerDataHandler");

// Parse through the $packetData we provided earlier, 
// calling user function ServerDataHandler to handle svc_serverdata messages.
// Fast parse is enabled.
$packet->ParsePacket(true);

// Remove "svc_serverdata" handler
$packet->RemoveHandler(svc_serverdata);

// Remove instance of q2Packet
unset($packet);

---

Reference

This section documents the parameters passed to handlers for each server message type. Note that due to delta compression, some fields may not appear in the actually array returned.

svc_bad
svc_nop
svc_disconnect
svc_reconnect
svc_deltapacketentities

No parameters.

svc_centerprint
svc_stufftext
svc_layout

The received string.

svc_muzzleflash

Array:
[entity]
[weapon]

svc_muzzleflash2

Array:
[entity]
[flash_num]

svc_tempentity

Array:
[type]
[direction]
[position]
[position1] - used as a start for lines
[position2] - used as an end for lines
[colour]
[entity]
[id]
[magnitude]
[count]
[duration]

svc_inventory

An array of 256 short integers representing entities.

svc_sound

Array:
[soundindex]
[volume]
[attenuation]
[offset]
[channel]
[entity]
[position]

svc_print

Array:
[level] - int denoting priority/type of message
[string] - the print message itself

svc_configstring

Array:
[index] - index in the configstrings array
[string] - configstring

svc_serverdata

Array:
[protocol]
[servercount]
[attractloop] - is this a demo
[gamedir]
[player_entity_num]
[maptitle]

svc_playerinfo

Array:
[pm_type]
[pmove_origin]
[pmove_velocity]
[pmove_time]
[pmove_flags]
[pmove_gravity]
[pmove_delta_angles]
[viewoffset]
[viewangles]
[kickangles]
[gunindex]
[gunframe]
[gunoffset]
[gunangles]
[blend]
[fov]
[rdflags]
[statsbits]
[stats]

For frame and entity data, take a look at the source code.

---

Contact

You can contact me at viciouz[at]viciouz[dot]co[dot]uk via email