/ 
Games-Dice-0.999_01
River stage one • 2 direct dependents • 2 total dependents
/ Games::Dice

NAME

Games::Dice - a set of dice for rolling

VERSION

version 0.099_01

$Id: Dice.pm 1501 2007-07-29 19:50:56Z rjbs $

SYNOPSIS

my $die_pool = Games::Dice->new('2d8');

my $hit_points = $die_pool->roll->total;

my $damage_dice = Games::Dice->new('2d6+2');

my $result = Games::Dice->roll(
  [
    Games::Die->new({ sides => 6 }),
    6,
    Games::Die::Weighted->new({ sides => 6 }),
  ],
  {
    drop_bottom => 1
  },
);

print "You rolled: ", $result->as_string, "\n";

DESCRIPTION

A Games::Dice object represents a set of dice, which are represented by Games::Die objects. A set of dice can be rolled, and returns a Games::Dice::Results object. The default behavior of dice and dice sets is simple, but can easily be augmented with subclassing.

METHODS

new

my $dice = Games::Dice->new($dice, \%arg);

This method creates and returns a new set of dice.

The simplest kind of value for $dice is a string describing the dice in the usual RPG format: XdY+Z

X, the number of dice, is optional. Y, the sides on each die, is mandatory, and must be a positive integer, or the percent sign, which stands in for 100. +Z, the modifier, is optional, and may be a positive or negative integer.

Instead of a string, you can provide an arrayref of individual dice. Each entry in the arrayref must be an integer (in which case it's used to create a new Games::Die object with that many sides) or a Games::Die object.

Valid arguments (to pass in %arg) are:

adjust

This parameter may be either a number to add to the rolled total or a coderef that is called on the total. The result of that call is then returned as the total. In other words, the following two calls are functionally equivalent:

Games::Dice->new('2d10', { adjust => -1 });
Games::Dice->new('2d10', { adjust => sub { $_[0] - 1 } });

In a case like the following, the net result is an adjust of +2:

Games::Dice->new("3d6+1", { adjust => 1 });
drop_bottom
drop_top

These parameters indicate that the higher and lowest n values should not be considered toward the total and should not be returned in the normal set of results. (See the "results" method, below.)

In other words, this set of dice rolls four six-sided dice, then drops the lowest value:

my $dark_sun_dice = Games::Dice->new("4d6", { drop_bottom => 1 });

dice

my @dice = $dice->dice;

This returns a list of the die objects in the set.

roll

my $result = $dice->roll;
my $result = Games::Dice->roll(@args_for_new);

This method rolls the dice and returns a Result object.

die_class

This method returns the class to be used for die objects.

result_class

This method returns the class to be used for results.

TODO

  • White Wolf dice (diff/successes)

  • roll-more-on-high-roll (Feng Shui, etc)

  • faces (roll things other than 1 .. $n)

  • per-die adjustments

  • backward-compatible functional interface

AUTHOR

Ricardo SIGNES <rjbs@cpan.org>

HISTORY

Games::Dice was originally uploaded by Philip Newton (pne@cpan.org) in 1999 and provided a simple function-based interface to die rolling.

Andrew Burke (burke@bitflood.org) and Jeremy Muhlich (jmuhlich@bitflood.org) uploaded Games::Die::Dice in 2002, which provided a simple object-oriented interface to dice sets.

Ricardo SIGNES (rjbs@cpan.org) took maintainership of Games::Die::Dice in 2004, and really did mean to get around to overhauling it. In 2005 he got a round tuit and rewrote the code to be more flexible and extensible for all the silly things he wanted to do. He also took maintainership of Games::Dice, and merged the two distributions. In 2007, he really, really overhauled it again, getting rid of the insane things he had done in a long-standing developer-only release.

LICENSE

Copyright 2005, Ricardo SIGNES.

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