Use PPF for Gaming Clans

Use PPF for Gaming Clans

figs/moderate.gif figs/hack46.gif

Many online gamers hang out together on IRC. Extend the IRC bot PPF with plug-ins to support these communities and provide various game-related tools.

PPF is a great tool for gamers using IRC, especially for clans. It has plug-ins for querying some online game systems, game servers, searching, and even for customizing your own triggers. This hack shows you how to go about configuring and using PPF from a clan's perspective. PPF stands for PircBot Plug-in Framework—it is an IRC bot based on the PircBot framework and uses plug-ins to facilitate easy addition of features.

1 Get PPF

PPF can be downloaded from It is available in two versions:

  • A version containing just the bot, which is recommended if you already have Java installed.

  • A version containing the bot and the Java Runtime Environment. This allows you to use a single installer to set up Java and PPF.

After PPF is installed, the directory will look similar to Figure.

A complete installation of PPF

Within the PPF directory are the startup files and the main bot configuration files. The plugins directory contains subdirectories relevant to each plug-in that is installed. The default plug-ins are shown in Figure.

Default plug-ins supplied with PPF

If the plug-in has a configuration file, it will be found within the relevant subdirectory and be named <plugin_name>Config.xml-e.g., the Say plug-in will have a config file called SayConfig.xml.

2 PPF Core

The core is where the main IRC configuration, bot info, and plug-ins are managed. The bot alone is pretty useless—adding the plug-ins creates the functionality of the bot. Plug-ins can be loaded, configured and reloaded, or unloaded even while PPF is running.

The main config file is PPFConfig.xml and is stored in the root of the PPF installation. Let's quickly go over some of the settings to get you started.

Auth levels are used to control access to the bot's commands. There are currently three levels: bot owner, bot master, and trusted. The owner can do things like manage the plug-ins, move the bot to other channels, change its name, or even kill the bot. Each plug-in allows the use of certain commands, and each plug-in gets to control which auth level is needed for these. The password for each auth level is set in adminPassword, masterPassword, and trustedPassword.

The servers, nicks, and channels sections are for telling the bot which server you want it to connect to, what nickname it should have, and what channels to join when it starts up.

One setting to take care with is the messageDelay setting. This defines how fast the bot will send messages to the IRC server. If it sends messages too rapidly, it will get kicked for flooding. Different networks have different tolerances, so you may have to play with that a little.

onJoinMessage is what the bot sends as a notice to anyone who joins the channel. By default, it will send a message telling people what the help command is. As a clan, you may want to give some useful clan information first and then say what the rest of the help is afterward.

Some of the core commands can be configured; for example, many other bots have !help as their help command, so you can change the PPF help command to something else if you want.

Finally, there is the plugins section. This is where the plug-ins that will be available to the bot are configured. The plug-ins can be configured here, and you can decide if you want them loaded at startup or not. Later on, if a new plug-in is made available, this is where the configuration is added, and then you will be able to load it.

3 Running PPF

PPF is written in Java, so it can be run on any system that has a Java Runtime available.

Once you have configured your bot, you are ready to run it:

C:\java\PPF> set CLASSPATH=%CLASSPATH%;.;PPF.jar;lib\pircbot.jar;lib\jaxen-\


C:\java\PPF> java net.sourceforge.ppf.PPF

Alternatively, Windows users can run the supplied run.bat file.

As soon as the bot is up and running, you can auth with it through your IRC client (assuming the bot is called PPF):

/msg PPF auth  adminPassword 

4 ChannelCentral

This plug-in gives some control or information about the channels that the bot is in. The configuration is stored in the file ChannelCentralConfig.xml.

Basic channel commands such as voice and op are available to someone with the correct auth level. This plug-in also allows topic showing and setting, channel stats, and the possibility to auto voice or op people based upon their auth level with the bot.

This plug-in also tracks statistics in a LiveStats.xml file, which contains current information about the channel. You could then do some simple XML parsing to create a web page that shows live information about the channel.

5 TriggerMessage

This plug-in lets the bot respond to things that are said in a channel. You can change settings for this plug-in in TriggerMessageConfig.xml.

Perhaps you would like people to know about the homepage, servers, or members in your clan? A trigger for the homepage could be !www. When this is typed in the channel, you could get the bot to respond with something like this:

<PPF> Homepage for Clan KsR is

To manage the triggers, you must auth with the bot as a trusted (or more powerful) user and type into the channel:

<Paul> !at "!www" "Homepage for Clan KsR is"

You may also want to tell everyone the IP address and port numbers of your servers. This is one way of doing it:

<Paul> !at "!server" "KsR BF server:

    :: Type !qf for status"

<Paul> !at "!ip" "KsR BF server:

    :: Type !qf for status"

As you can see, you can have triggers for whatever you like and even make different triggers for showing the same info to make it easier to use. Users can get the IP address by saying either !server or !ip. The !qf command will be covered in the ServerQuery plug-in section later in this hack.

You can set up a trigger to announce the members of the clan:

<Paul> !at "!members" "Plexor, Mad_Bear, Saint, Deady, Buscape, 

Deadly Style, TaN, Mark Gor, Qball, Blackhawk, Lostworld, Godfather, 

Sicillian, Aggressor, Sisu, DeadEd, Heavens Gate, Sgt.Mac, Goateh, Sidewinder, Seeker"

Now that there are some triggers, the list can be seen by sending a private message to the bot:

/msg PPF !st

The bot will request a DCC chat session with you and then send the list of the triggers and the responses. Each trigger can then be removed using the !rt command in the channel:

<Paul> !rt !server

This will result in the !server trigger being removed. The bot will no longer respond to that command.

Finally, a new trigger can be made to tell users how to get info about your clan:

<Paul> !at "!claninfo" "Commands are: !www - !ip - !members - !help"

The onJoinMessage in the main configuration file (PPFConfig.xml) could now be changed to "Welcome to Clan KsR". Type !claninfo for help. Users entering the channel will then receive the message telling them what commands are available to get further information.

6 ServerQuery

With this plug-in, you can currently query Half-Life and Battlefield 1942-based servers for basic server and player information. You can also manage a list of shortcuts so that you don't need to remember IP addresses and port numbers. The commands and output styles can be configured by editing ServerQueryConfig.xml.

Add the IP address of your clan server as a defaultServers in the configuration file. Default servers can be queried by just typing !qf, which returns the server details and scores ("frags"). By adding the Battlefield 1942 server (with default query port of 23000), typing !qf would show something like this:

<Paul> !qf

<PPF> -=Kingsize Rizla=- [KsR] :: IP: :: BF1942 :: Map:

    stalingrad :: Players: 3/32 [LK]Fubar [12,10,6], [KsR]DeadEd [10/2/3],

    Jibbler [2/2/2]

To query a different server, you can specify the IP address and port number after the !qf command. To see only "frag" information, you can type !f. To just query the server details, you can use the !q command:

<Paul> !q

<PPF> The Gory Grave of -GG- :: IP: :: Counter-Strike ::

    Map:de_inferno :: Players: 1/15

This can be made easier by adding a shortcut (shortcut management requires trusted or higher auth level):

!sc gg 27015

This now means that you can use gg when querying:

<Paul> !q gg

<PPF> The Gory Grave of -GG- :: IP: :: Counter-Strike :: 

Map:de_inferno :: Players: 1/15

A list of the shortcuts can be seen by sending a private message to the bot:

/msg PPF !ssc

The bot will then request a DCC chat session with you and send the list of shortcuts, with the IP address and port number for each one. The shortcuts can then be removed with the !rsc command:

<Paul> !rsc gg

7 ServerAdminShouter

With this plug-in, you can monitor game servers for certain names or for large negative scores and receive alerts via private messages on IRC. It can be configured by editing the file ServerAdminShouterConfig.xml. You can currently monitor Half-Life and Battlefield 1942 servers with this plug-in.

You can become one of the people who gets notified in two ways. One is to have your nickname listed in the admins section of the configuration file. The other is to auth and then give the "on duty" command. The default for this is !onDuty.

Add the servers that you want to monitor to the servers section in the configuration file. Set the checkTimer to the interval, in seconds, that you want the bot to check for the names or score that you set in the triggers section. If there is a problem on a game server and there isn't an administrator around to fix it at the time, players will often change their name to something that indicates the need for an administrator, in the hope that someone will see it in the log file or game browser. Names such as adminneeded could be added as triggers, and then a server message or message of the day (MOTD) can be added to the server, telling people how to grab the attention of an administrator.

Now, when someone in the server changes her name to adminneeded or a score goes below the allowed limit, administrators will receive a private message telling them which server help is needed on.

8 CBFinder

This plug-in lets you find out information about a clan from the ClanBase system ( This can be configured by editing CBFinderConfig.xml.

Querying the ClanBase system can reveal details such as a clan's ladder ranking, what ladders they are in, the last five wars they played, whom the wars were against, on which map they played, and what the scores were. To search ClanBase for the Battlefield 1942 clan KsR, you would type the following:

<Paul> !cb BF KsR

If the bot can find the requested information, it will generate a quite lengthy reply:

<PPF> Clan Information: 

<PPF>    Name: Kingsize Rizla *

<PPF>    Tag: [KsR]

<PPF>    CB Home:

<PPF>  Ladder Information: 

<PPF>    Name: Battlefield1942 Conquest  (Europe)

<PPF>    Rank: 28 :: Points: 1,206 

<PPF>    Match Information (last 5 played): 

<PPF>      Date, Opponent, Maps, Clan score, Opponent score

<PPF>      19 Feb, reborn, stalinggrad/wake island, 126, 407

<PPF>      11 Feb, DW, stalinggrad/berlin, 288, 40

<PPF>      4 Jan, BFD, stalinggrad/el alamein, 258, 254

<PPF>      14 Dec \ 03, DerQ, stalinggrad/el alamein, 130, 262

<PPF>      7 Dec \ 03, FTA, stalinggrad/wake island, 349, 218


<PPF>       Name: Battlefield1942 Battlefield 1942 Conquest Cup 

<PPF>    Rank: N/A :: Points: N/A

<PPF>    Match Information (last 0 played): 

<PPF>    No match information available


<PPF>    Name: Battlefield1942 Battlefield 1942 Conquest Cup 

<PPF>    Rank: N/A :: Points: N/A

<PPF>    Match Information (last 5 played): 

<PPF>      Date, Opponent, Maps, Clan score, Opponent score

<PPF>      26 Nov \ 03, PIRATAS, stalingrad/operation battl, 403, 472

<PPF>      17 Nov \ 03, IP, el alamein/kursk, 940, 222

<PPF>      29 Oct \ 03, wb, operation marke/, 662, 74

<PPF>      26 Oct \ 03, SSS, operation aberd/, 539, 0

<PPF>      15 Oct \ 03, BuD, iwo jima/, 433, 501

It can take some time for the bot to output everything due to the flood protection features, so there is also a DCC chat version available. This allows you to create a connection directly to the bot, letting it send the data as fast as it can:

!cbdcc BF KsR

Your own clan details can be added to the default settings so that you only need to type !cb.

9 BFTracks

This plug-in lets you find information about players who are being tracked with the BFTracks system ( You can get static information about players, or even live information showing where they are playing. The commands, output of the commands, and number of lines returned can be configured by editing BFTracksConfig.xml.

To request information about a player (with the results being sent to the channel), you can use the !bf command, followed by the name:

<Paul> !bf deaded

<PPF> [KsR]DeadEd :: [4535](620 points) ::

Information about a clan yields a longer set of results, so these are sent to you via private messages:

<Paul> !bfclanlist [KsR]

<PPF> [KsR]Heavens :: [767](837 points) ::

<PPF> [KsR]Sidewinder :: [-](799 points) ::

<PPF> [KsR]Mark Gor :: [1289](776 points) ::

<PPF> [KsR]**Sgt.Mac** :: [2626](687 points) ::

<PPF> [KsR]Qball :: [3514](653 points) ::


<PPF> [KsR]Seeker :: [-](378 points) ::

<PPF> [KsR]Buscape[AWOL] :: [-](294 points) ::

You can get live information about players with the !bflive command:

<Paul> !bflive [KsR]

<PPF> [KsR]Heavens[7/5/4] :: Server: EAUK 04 - Western Front IP: Map: bocage

<PPF> [KsR]TaN[5/5/2] :: Server: EAUK 04 - Western Front IP: Map: bocage


This plug-in lets you find out information about a clan from the Enemy Down system (

This !ed command gives you some basic information about a clan and a link into the system:

<Paul> !ed roffs

<PPF> Clan Information: 

<PPF>    Name: -=ROFFS=-

<PPF>    Tag: ROFFS

<PPF>    ED Home:

<PPF>    Website:

<PPF>    IRC Channel: #roffs

<PPF>    Server IP:

Once again, it can take some time to output everything due to the flood protection, so a DCC chat version—!eddcc—is also available.


Everyone loves Google. Just type !google and some search phrase and the top result will be given as a link to the channel:

<Paul> !google PPF bot framework

<PPF> [PPF bot framework] ( - PPF (Pircbot

    Plugin Framework) and MatchEd IRC Bot ...)

Other Plug-ins

Several other plug-ins are available for PPF. New and existing plug-ins are being constantly developed. Some of the other plug-ins are: Advertiser, BadWords, EightBall, MySQLQuery, Say, Seen, ServerAuth, and Translate1337.

Alex North

     Python   SQL   Java   php   Perl 
     game development   web development   internet   *nix   graphics   hardware 
     telecommunications   C++ 
     Flash   Active Directory   Windows