NAME
Games::Dice - a set of dice for rolling
VERSION
version 0.99_01
$Id: Dice.pm,v 1.6 2004/10/19 12:52:29 rjbs Exp $SYNOPSIS
my $hit_points = Games::Dice->new('2d8');
my $result = $hit_points->roll;
my $damage_dice = Games::Dice->new(dice => [6,6], adjust => +2);DESCRIPTION
A Games::Dice object represents a set of dice, which are represented by Games::Dice 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
Games::Dice->new(dice => $dice, adjust => $adjust)
This method creates and returns a new set of dice.
The dice parameter is an arrayref of dice or dice sides that make up the set. The dice may be numbers or objects that provide a roll method. Alternately, dice may be a string describing the dice set (see below).
The adjust 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(dice => [ 10, 10 ], adjust => -1);
Games::Dice->new(dice => [ 10, 10 ], adjust => sub { $_[0] - 1 });These two parameters can be combined in a traditional dice specification and passed as the dice parameter, as a string.
Games::Dice->new(dice => "3d6"); # same as: dice => [ 6, 6, 6 ]
Games::Dice->new(dice => "2d4+1"); # same as: dice => [ 4, 4 ], adjust => 1
Games::Dice->new(dice => "d8*2"); # same as: dice => [ 8 ],
adjust => sub { $_[0] * 2 }
If the only parameter you pass to new is dice, you can omit the name.
my $dexterity = Games::Dice->new("3d6+1")->roll;die_class and result_class parameters may be passed to Games::Dice to change the class that will be used to create individual dice or the result set. Any parameters intended for those constructors will be passed along. (See Class::Container for more information.)
$dice->dice()
This returns a list of the die objects in the set.
$dice->roll_result()
This method rolls the dice and returns a Result object.
$dice->roll()
This method rolls the dice and returns the value of the result. Generally, in scalar context, this returns the sum, in list context, returns the list of values that came up on each die. (Other result classes may change the behavior of the value method.)
$dice->result()
This method returns the last result of rolling the dice. (This method doesn't roll the dice, so you'll need to call roll first.)
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.
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.