View on
Evan S Kaufman > Games-FEAR-Log-0.02 > Games::FEAR::Log



Annotate this POD


Open  1
View/Report Bugs
Module Version: 0.02   Source  


Games::FEAR::Log - Log analysis tool for F.E.A.R. dedicated servers


Version 0.02


    use Games::FEAR::Log;
    # instantiate new object, passing a hash reference of options
    my $log_obj = Games::FEAR::Log->new( {
      # database information: a dsn, username, and password
      -dbi => [ 
      # table to store info
      -table => 'deathmatch1',
      # create table if it doesnt exist
      -create => ,
      # full path to logfile
      -logfile => '/var/log/FEAR/mp_scores.log',
      # empty the source logfile after reading it
      -truncate => 1,
      # delete any records older than 30 days
      -history => '30d'
    } );
    # process log file, importing new entries
    $log_obj->process() or die 'processing failed';
    # get ID of first user
    my @uids = $log_obj->get_uids();
    # get playernames this user goes by
    my @names = $log_obj->get_playernames( $uid[0] );
    # get stats for this user
    my $stats = $log_obj->get_stats( $uid[0] );
    # get history for this user
    my $history = $log_obj->get_history( $uid[0] );
    my @gametimes = keys %{$history};
    # get information for a game played by said user
    my $game = $log_obj->get_game( $gametimes[0] );
    # get scoreboard-structured informatuon
    my @scores = build_scoreboard('player', 'asc');


This module allows the parsing of a F.E.A.R. multiplayer server log into a manageable database format, and provides an easy to use object-oriented interface to access that information. This information could then be used to create a CGI scoreboard application, such as the one included in the /examples directory.

The underlying system uses a SQL relational database to store and retrieve game information. Initially, this implimentation is built to use a MySQL or PostgreSQL database, but I can add support for other database systems if there is a demand.

Ideally, there could be two different 'pieces' to an application using this module, an administrative interface to import new log entries into the database, and a public interface to display and/or cross-reference already imported information.

If performance is not a concern, however, it could be a one-piece application where new entries are checked for and added every time the interface is viewed.



Creates and returns a new object. Takes a single argument, a hash reference containing configuration options. The available options are as follows:


Truncates log file if the truncate option is set to true, deletes expired records if history option is specified, and processes any new entries. Returns 1 on success. If a logfile option is not specified, an error will be thrown.



Returns an array of all unique UIDs found in the current database table. See the JARGON section for an explanation of UIDs in the FEAR server logs.

    @uids = $log_obj->get_uids();


Returns an array of all unique playernames found for the given UID. They are ordered by frequency of use.

    @names = $log_obj->get_playernames($uid);


Returns a hash reference containing averaged and totalled stats for the given UID. The data structure returned is as follows:

      game_count    => $game_count,
      tot_score     => $tot_score,
      avg_score     => $avg_score,
      tot_kills     => $tot_kills,
      avg_kills     => $avg_kills,
      tot_deaths    => $tot_deaths,
      avg_deaths    => $avg_deaths,
      tot_suicides  => $tot_suicides,
      avg_suicides  => $avg_suicides,
      tot_teamkills => $tot_teamkills,
      avg_teamkills => $avg_teamkills,
      tot_objective => $tot_objective,
      avg_objective => $avg_objective,


Returns a hashref of hashrefs of games played by the given UID, each keyed to the game time. Note that gametime is a unix timestamp as would be returned by the time() builtin. The data structure returned is as follows:

      $gametime => {
        gametime  => $gametime,
        team      => $team,
        player    => $player,
        score     => $score,
        kills     => $kills,
        deaths    => $deaths,
        teamkills => $teamkills,
        suicides  => $suicides,
        objective => $objective,


Returns a hashref of hashrefs of players in the game at the given game time, each keyed to a UID. Note that gametime is a unix timestamp as would be returned by the time() builtin. The data structure returned is as follows:

      $uid => {
        uid       => $uid,
        team      => $team,
        player    => $player,
        score     => $score,
        kills     => $kills,
        deaths    => $deaths,
        teamkills => $teamkills,
        suicides  => $suicides,
        objective => $objective,


Returns an array of hashrefs ideal for displaying a summary scoreboard. Takes two optional arguments:

The data structure returned is as follows:

        uid           => $uid,
        player        => $player,
        avg_score     => $avg_score,
        avg_kills     => $avg_kills,
        avg_deaths    => $avg_deaths,
        avg_suicides  => $avg_suicides,
        avg_teamkills => $avg_teamkills,
        avg_objective => $avg_objective,
        tot_score     => $tot_score,
        tot_kills     => $tot_kills,
        tot_deaths    => $tot_deaths,
        tot_suicides  => $tot_suicides,
        tot_teamkills => $tot_teamkills,
        tot_objective => $tot_objective,


The class destructor that, when called, closes the database connection and any open filehandles, and destroys the object.



Returns a list of the currently supported DBI drivers. This function can be called from an instantiated object, or directly.

    # called from an object
    @drivers = $log_object->supported_dbds();
    # called directly from the module namespace
    @drivers = Games::FEAR::Log::supported_dbds();


Here, a few of the terms used throughout this documentation are briefly defined.


The UID found in the FEAR multiplayer log is used to uniquely identify a user. It is calculated as a hexadecimal MD5 hash of their CD key. For example, the UID for a CD key of ABCD-EFGH-IJKL-MNOP-QRST would be f00eeddcb4a079de173b673a3d45fcfc.

Player Name

The player name is, as it suggests, a name picked by the user and is how they appear in-game. It is not suitable for tracking statistics since it can be changed at the user's discretion, so we use the UID for that purpose.

Game Time

The game time is a timestamp of precisely when a specific game ended. By matching up different players with the same game times, you can determine the participants of any specific game.


Test::More - Used by the test suite during make test

DBI - Used for database connectivity

File::Copy - Used to copy log during processing

File::Temp - Used to create temp file during processing


Evan Kaufman, <evank at>


Please report any bugs or feature requests to bug-games-fear-log at, or through the web interface at I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.


The fine folks at, always willing to lend a helping hand to a struggling programmer.


Copyright 2007 Evan Kaufman, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: