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 => [ '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');
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.
/examples
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:
-dbi
An anonymous array of a DSN (data source name), username, and password for connecting to the database. See the DBI docs for an explanation and syntax of a DSN. An error will be thrown if this option is not found or invalid.
[ 'DBI:mysql:database=test;host=localhost', 'devuser', 'devpass' ]
-table
Name of the database table to use for this set of statistics. If stats are being kept for multiple game servers, each one should have its own seperate table. An error will be thrown if this option is not found or invalid.
-create
Indicate whether the given table should be created if it does not already exist. A true value creates the table if necessary, while a false value throws an error if the table doesnt exist. The default is to create the table.
-logfile
Source of the log entries. This is not a required parameter unless you plan on calling the process method. If a scalar value is passed, it is assumed to be a filename. If a scalar reference is passed, it is assumed to be the contents of the log, and will be dereferenced and processed. If a glob reference is passed, it is assumed to be an open filehandle to the logfile (note that it should be opened for read and write operations).
process
-history
Length of time to keep records, specified in a format similar to that used by the CGI module, with a numeric quantity followed by a one-letter unit indicator:
86400s # 1 day specified in seconds 1440m # 1 day specified in minutes 24h # 1 day specified in hours 90d # 3 months specified in days 12M # 1 year specified in months 2y # 2 years specified in years
The default is to keep them forever, and this can be specified by passing an empty or undefined scalar, or a value of zero.
-truncate
Indicate whether the source log should be truncated to zero bytes (and in effect emptied). This is useful if you are reading from a live log file and don't want to waste resources reprocessing old log entries. Note, of course, that if a logfile is already locked by the server process, any attempted writes to it will fail. A non-zero value turns on log truncating, and a zero value turns it off. The default is off.
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.
truncate
history
logfile
$log_obj->process();
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
time()
{ $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:
OFFSET
How many records into the start of a resultset to begin retrieving results, akin to a SQL OFFSET clause. The default is 0.
0
LENGTH
How many records to retrieve from a resultset, akin to a SQL LIMIT clause. The default is 0 which is interpreted as 'no limit'.
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.
ABCD-EFGH-IJKL-MNOP-QRST
f00eeddcb4a079de173b673a3d45fcfc
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.
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
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 cpan.org>
<evank at cpan.org>
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.
bug-games-fear-log at rt.cpan.org
The fine folks at PerlMonks.org, 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.
To install Games::FEAR::Log, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Games::FEAR::Log
CPAN shell
perl -MCPAN -e shell install Games::FEAR::Log
For more information on module installation, please visit the detailed CPAN module installation guide.