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

Download:
Games-FEAR-Log-0.02.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.02   Source  

NAME ^

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

VERSION ^

Version 0.02

SYNOPSIS ^

    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 => [ 
                'DBI:mysql:database=scoreboard;host=localhost;port=3306',
                'scoreboard_admin',
                'scoreboard_password'
              ],
      # 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');

DESCRIPTION ^

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.

METHODS ^

new()

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

process()

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.

    $log_obj->process();

get_uids()

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();

get_playernames(UID)

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);

get_stats(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,
    }

get_history(UID)

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,
      },
    }

get_game(GAMETIME)

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,
      }
    }

build_scoreboard(OFFSET,LENGTH)

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,
      }
    )

DESTROY()

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

FUNCTIONS ^

supported_dbds()

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();

JARGON ^

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

UID

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.

DEPENDANCIES ^

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

AUTHOR ^

Evan Kaufman, <evank at cpan.org>

BUGS ^

Please report any bugs or feature requests to bug-games-fear-log at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Games-FEAR-Log. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS ^

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

COPYRIGHT ^

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: