/ 
Games-Dice-Roller-0.03
River stage zero No dependents
/ Games::Dice::Roller

NAME

Games::Dice::Roller - a full featured dice roller system

VERSION

Version 0.01

SYNOPSIS

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

METHODS

new

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

roll

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).

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

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.

die modifiers

avg - average

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

r - reroll

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)

x - explode

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.

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

cs - count successes

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.

result modifiers

keep and drop

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.

result sum

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

dice pools

If to the roll method is passed a string containing different things (separated by spaces) this string will be treated as a dice pool

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).

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.

For example: $dice->roll('4d4+6 3d6+2 2d8+1 12') can lead to the following results (default global result modifier is kh):

# 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.

about rand

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:

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.

DEBUG

This module can produce debug informations if DICE_ROLLER_DEBUG environment variable is set to 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

AUTHOR

LorenzoTa, <LORENZO at cpan.org>

BUGS

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.

SUPPORT

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:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

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.