Games::Dice::Roller - a full featured dice roller system
Version 0.01
use Games::Dice::Roller; my $dice = Games::Dice::Roller->new(); # simple dice expressions my @simple = (qw( 3d6 4d8+4 1d100-5 )); # average results my @average = (qw(4d4avg 4d8avg+2 4d12avg-7)); # reroll if equal (default), lesser than or greater than N my @reroll = (qw(6d4r1 5d6rlt3 5d6rgt4 6d4r1+10 6d4r1-5)); # explode if equal (default), lesser than or greater than N my @explode = (qw( 3d6x6 3d6xlt3 3d6xgt4 3d6x6+3 3d6x6-4 )); # just count succesful rolls my @succes = (qw( 3d6cs1 3d6cslt3 3d6csgt4 )); # keep and drop dice from final results my @keep_and_drop = (qw( 4d6kh3 4d6kh2 4d6kl2+3 4d6kl2-3 4d12dh1 4d12dl3 4d12dl3+3 4d12dl1-4 )); foreach my $dice_expression ( @simple , @average, @reroll, @explode, @succes, @keep_and_drop ){ my ($res, $descr) = $dice->roll( $dice_expression ); print "$res [$dice_expression] $descr\n"; } # 10 [3d6] 5 2 3 # 22 [4d8+4] 7 7 1 3 +4 # 14 [1d100-5] 19 -5 # 10 [4d4avg] 2.5 2.5 2.5 2.5 # 20 [4d8avg+2] 4.5 4.5 4.5 4.5 +2 # 19 [4d12avg-7] 6.5 6.5 6.5 6.5 -7 # 18 [6d4r1] 4 (1r) 3 2 3 (1r) 2 4 # 19 [5d6rlt3] 3 4 3 4 (2r) (2r) (2r) 5 # 11 [5d6rgt4] 2 4 1 (5r) 2 (5r) 2 # 25 [6d4r1+10] (1r) 2 (1r) 2 2 4 3 2 +10 # 13 [6d4r1-5] (1r) (1r) 2 (1r) 2 4 4 (1r) 4 2 -5 # 7 [3d6x6] 1 1 5 # 17 [3d6xlt3] 6 5 1x 1x 1x 3 # 11 [3d6xgt4] 4 3 4 # 11 [3d6x6+3] 2 2 4 +3 # 8 [3d6x6-4] 5 3 4 -4 # 1 [3d6cs1] (5) (3) 1 # 1 [3d6cslt3] 2 (6) (6) # 2 [3d6csgt4] 6 (3) 5 # 14 [4d6kh3] (2) 6 4 4 # 9 [4d6kh2] 3 6 (2) (2) # 8 [4d6kl2+3] (6) 4 1 (6) +3 # 1 [4d6kl2-3] (5) 1 3 (3) -3 # 13 [4d12dh1] 2 6 5 (6) # 12 [4d12dl3] (9) (10) (9) 12 # 9 [4d12dl3+3] (1) 6 (3) (6) +3 # 26 [4d12dl1-4] 9 (1) 9 12 -4
The constructor accept only one option, an anonymous hash and the only valid key is sub_rand holding as value an anonymous sub to be invoked instead of the core function rand
sub_rand
This method expects a single string to be passed as argument. This string can be a single dice expression or a dice pool (see below).
single dice expression
dice pool
It returns the final result and a string representing the roll.
my $result = $dice->roll('3d6+3'); print "result of the dice roll was: $result"; # result of the dice roll was: 16 my ($res, $descr) = $dice->roll('3d6+3'); print "$descr\nResult: $res"; # 5 2 6 +3 # Result: 16
In the descriptive string some die result can be modified by modifiers: dropped ones will be inside parens, rerolled dice result will be inside parens and with a r following them and exploded dice results will be marked by a x
r
x
A third element is returned too: a hash reference intended to be used mainly internally and for debug purposes, with the internal carateristics of the dice expression. Dont rely on this because it can be changed or removed in future releases.
No dice are rolled, but the die average will be used instead. For 1d6 the average will be 3.5 so 4d6avg will always result in 14
1d6
3.5
4d6avg
14
Reroll dice equal, lesser than (lt) or greater than (gt) n as in 3d6r1 3d6rlt3 3d6rgt4 Each die rerolled will be not part of the final result and in the descriptive string will be inside parens and followed by r as in (1r)
lt
gt
n
3d6r1 3d6rlt3 3d6rgt4
(1r)
Each die roll equal, lesser than (lt) or greater than (gt) n (as in 3d6x6 3d6xlt3 3d6xgt4) will add another die of the same type. An exploded die will be added to final result and will be marked with x as in 6x in the descriptive string.
3d6x6 3d6xlt3 3d6xgt4
6x
For example 8d6xgt4 can lead to a result of 42 and a description like: 6x 4 6x 4 5x 3 5x 3 2 2 1 1
8d6xgt4
42
6x 4 6x 4 5x 3 5x 3 2 2 1 1
If a die roll is equal, lesser than (lt) or greater than (gt) n (as in 3d6cs1 3d6cslt3 3d6gt4) then it will count as a success. The final result will be the succes count. In the decription string unsuccesfull rolls will be inside parens.
3d6cs1 3d6cslt3 3d6gt4
With the result modifiers kh kl dh dl you can choose how many dice will be used to compute the final result, keeping or dropping highest or lowest n dice. For example 4d6kh3 will roll 4d6 but only best three ones will be used. The descriptive string in this case will be always ordered in ascending or descending order, without representing the real occurence of numbers.
kh kl dh dl
4d6kh3
4d6
An optional sum n can be added to the final result as positive or negative modifier. This must be the last element of the dice expression like in: 3d8+4 This option cannot be used with cs
3d8+4
cs
If to the roll method is passed a string containing different things (separated by spaces) this string will be treated as a dice pool
roll
A dice pool must contain at least two elements. It can contains one or more dice expression (explained above), no or one and only one bare number and no, one and only one global result modifier ( kh for keep highest or kl for keep lowest).
dice expression
bare number
global result modifier
kh
kl
All results of dice expressions are computed and compared each other and with an eventual bare number and the result of the dice pool will be the highest (if no global result modifier then kh will be the default) or lowest one (if kl is specified) roll among them.
dice expressions
For example: $dice->roll('4d4+6 3d6+2 2d8+1 12') can lead to the following results (default global result modifier is kh):
$dice->roll('4d4+6 3d6+2 2d8+1 12')
# Result: 14 # Description: 4d4+6 = 1 2 1 4 +6, ( 3d6+2 = 4 3 4 +2 = 13 ), ( 12 ), ( 2d8+1 = 1 8 +1 = 10 )
As you can see descriptions of discarded dice expression or eventual bare numbers (12 in the example) lower than the higher result are represented inside parens.
bare numbers
12
Some ancient perl on some unfortunate OS has proven to have problem with the core rand even if nowadays this is very rare to appear. In this case you can provide your own rand function during the constructor, for example using Math::Random::MT as in the following example:
rand
my $gen = Math::Random::MT->new(); my $mt_dicer = Games::Dice::Roller->new( sub_rand => sub{ my $sides = shift; return $gen->rand( $sides ); }, );
See the thread at perlmonks where this argument was discussed.
This module can produce debug informations if DICE_ROLLER_DEBUG environment variable is set to 1
DICE_ROLLER_DEBUG
1
Under debug rolling a dice expression will produce something like:
Evaluating [12d6kh4+3] original : [12d6kh4+3] type : [dice_expression] dice expression : [12d6] result modifier : [kh] result val modifier: [4] result sum : [+3] Cleaning the expression to spot garbage: removing: 12d6 removing: kh removing: 4 removing: +3 Left in the expression: [] Description: 6 6 5 5 (4) (4) (3) (3) (2) (2) (1) (1) +3 Result : 25
LorenzoTa, <LORENZO at cpan.org>
<LORENZO at cpan.org>
Please report any bugs or feature requests to bug-games-dice-roller at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Games-Dice-Roller. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-games-dice-roller at rt.cpan.org
The main support site for the present module is https://perlmonks.org where I can be found as Discipulus
You can find documentation for this module with the perldoc command.
perldoc Games::Dice::Roller
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
https://rt.cpan.org/NoAuth/Bugs.html?Dist=Games-Dice-Roller
Search CPAN
https://metacpan.org/release/Games-Dice-Roller
Copyright 2021 LorenzoTa.
This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:
http://www.perlfoundation.org/artistic_license_2_0
Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.
If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.
This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.
This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.
Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
To install Games::Dice::Roller, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Games::Dice::Roller
CPAN shell
perl -MCPAN -e shell install Games::Dice::Roller
For more information on module installation, please visit the detailed CPAN module installation guide.