NAME

NetHack::NAOdash - Analyze NetHack xlogfiles and extract statistics

SYNOPSIS

use NetHack::NAOdash;
my $stats = naodash_user 'mgv'; # Retrieve and analyze mgv's xlogfile from alt.org
my @checks = @{$stats->{checks}}; # List of 'achievements' obtained by mgv
my %checks = map { $_ => 1 } @checks;
say 'mgv has ascended an orcish rogue' if $checks{combo_rog_orc_cha};
say 'mgv has ascended an atheist character' if $checks{conduct_atheist};
my %numbers = %{$stats->{numbers}};
say "mgv has ascended $numbers{ascensions} out of $numbers{games} games";
say "mgv has spent $numbers{totalrealtime} seconds playing NetHack on NAO";

$stats = naodash_user {include_versions => ['3.6.0']}, 'mgv';
say 'mgv has ascended an orcish rogue in 3.6.0' if $checks{combo_rog_orc_cha};
$stats = naodash_user {exclude_versions => ['3.6.0']}, 'mgv';
say 'mgv has ascended an atheist character pre-3.6.0' if $checks{conduct_atheist};

use File::Slurp;
$stats = naodash_xlog read_file 'path/to/my/xlogfile';
%checks = map { $_ => 1 } @{$stats->{checks}};
say 'I have ascended a survivor' if $checks{uconduct_survivor};

DESCRIPTION

NetHack::NAOdash analyzes a NetHack xlogfile and reports statistics. There are two types of statistics: checks, which are flags (booleans) and numbers which are integers.

The checks are tracked across all games. That is, a check will be true in the statistics if it is true in at least one game. Except for checks in the Achievements category, only games that end in an ascension are considered for awarding a check.

The checks, sorted by category, are:

Achievements

These start with achieve_ and represent significant milestones in a game. They are usually relevant only for users who never ascended, as a game that ends in an ascension generally meets all of them.

achieve_sokoban  achieve_luckstone   achieve_medusa achieve_bell
achieve_gehennom achieve_candelabrum achieve_book   achieve_invocation
achieve_amulet   achieve_endgame     achieve_astral achieve_ascended

Starting Combos

These look like combo_role_race_alignment and represent role/race/alignment combinations in ascended games. The starting alignment, not the alignment at the end of the game is considered. For example, cav_gno_neu is true if the user ascended at least one gnomish caveman.

Conducts

These start with conduct_ and represent the 12 officially tracked conducts.

conduct_foodless     conduct_vegan        conduct_vegetarian
conduct_atheist      conduct_weaponless   conduct_pacifist
conduct_illiterate   conduct_genocideless conduct_polypileless
conduct_polyselfless conduct_wishless     conduct_artiwishless

Unofficial Conducts

These start with uconduct_ and represent conducts that are not officially tracked by the game.

uconduct_survivor uconduct_bones uconduct_minscore

The numbers are:

totalrealtime

The total time spent playing NetHack on NAO, in seconds.

games

The number of games played.

ascensions

The number of games played that ended in an ascension.

maxhp

The highest maxHP at the end of an ascension.

maxpoints

The highest score obtained at the end of an ascension.

maxconducts

The maximum number of conducts at the end of an ascension.

minturns

The minimum turns across ascended games.

minrealtime

The minimum realtime across ascended games, in seconds.

This module exports two functions:

naodash_xlog([\%args], @lines)

naodash_xlog([\%args], $xlog)

Takes an optional hashref followed by the contents of an xlogfile and returns the results of the analysis. The contents are joined together then split by the newline character, so they can be specified as a single string, as a list of lines, or as a combination thereof.

The following keys are recognised in the optional hashref:

include_versions

The associated value is an arrayref of NetHack versions that should be considered. Any game that was played on a version that is not in this arrayref will be ignored. If this key is not present or the value is an empty arrayref, all versions are considered.

exclude_versions

The associated value is an arrayref of NetHack versions that should not be considered. Any game that was played on a version that is in this arrayref will be ignored. If a version is both included and excluded at the same time, it will not be considered (in other words, exclude_versions overrides include_versions).

The return value is of the following form:

{ checks => ['achieve_sokoban', 'achieve_luckstone', ...],
  numbers => {totalrealtime => 12345, games => 2, ...} }

In other words, @{$result->{checks}} is an array of checks that are true and %{$result->{numbers}} is a hash of numbers.

naodash_user([\%args], $nao_username)

Retrieves the xlogfile of a user from NAO and gives it to naodash_xlog. Dies if no xlogfile is found or if the server cannot be contacted.

An optional hashref can be passed as a first argument. In this case it will be supplied as a first argument to naodash_xlog, see that function's documentation for an explanation of useful keys.

This method caches the downloaded xlogfiles for one day in the directory named by the NAODASH_CACHE environment variable.

ENVIRONMENT

NAODASH_CACHE

Path to a directory that should be used to cache xlogfiles downloaded from NAO, or the special value 'none' (case-insensitive) to disable caching.

By default a directory named 'naodash' in the default temporary directory (File::Spec->tmpdir) is used.

SEE ALSO

App::NAOdash, App::Web::NAOdash, http://alt.org/nethack/

AUTHOR

Marius Gavrilescu, <marius@ieval.ro>

COPYRIGHT AND LICENSE

Copyright (C) 2015 by Marius Gavrilescu

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.20.2 or, at your option, any later version of Perl 5 you may have available.