NAME

Dice::Roller - Roll RPG-style polyhedral dice

SYNOPSIS

use Dice::Roller;

my $dice = Dice::Roller.new("2d6 + 1");
$dice.roll;
say $dice.total;    # 4. Chosen by fair dice roll.
$dice.set-max;
say $dice.total;    # 13

DESCRIPTION

Dice::Roller is the second of my forays into learning Raku. The aim is simple - take a "dice string" representing a series of RPG-style dice to be rolled, plus any modifiers, parse it, and get Raku to virtually roll the dice involved and report the total.

It is still under development, but in its present form supports varied dice expressions adding and subtracting fixed modifiers or additional dice, as well as the "keep highest n" notations.

METHODS

new

my $dice = Dice::Roller.new('3d6 + 6 + 1d4');

.new takes a single argument (a dice expression) and returns a Dice::Roller object representing that collection of dice.

The expression syntax used is the shorthand that is popular in RPG systems; rolls of a group of similar dice are expressed as d, so 3d6 is a set of 3 six-sided dice, numbered 1..6. Additional groups of dice with different face counts can be added and subtracted from the total, as well as fixed integer values.

Preliminary support for some "selectors" is being added, and are appended to the dice identifier; rolling '4d6:kh3' stands for roll 4 d6, then keep the highest 3 dice. Selectors supported are:

• :kh - keep the highest n dice from this group.

• :kl - keep the lowest n dice from this group.

• :dh - drop the highest n dice from this group.

• :dl - drop the lowest n dice from this group.

Selectors can be chained together, so rolling '4d6:dh1:dl1' will drop the highest and lowest value dice.

roll

$dice.roll;

Sets all dice in the expression to new random face values. Returns the Dice::Roller object for convenience, so you can do:

say $dice.roll.total;

total

my $persuade-roll = Dice::Roller.new('1d20 -2').roll;
my $persuade-check = $persuade-roll.total;

Evaluates the faces showing on rolled dice including any adjustments and returns an Int total for the roll.

ERROR HANDLING

Dice::Roller.new throws an exception if the string failed to parse.

This behaviour might change in a future release.

DEBUGGING

You can get the module to spew out a bit of debugging text by setting Dice::Roller::debug = True. You can also inspect the Match object ini a given roll: say $roll.match.gist;

AUTHOR

James Clark

COPYRIGHT AND LICENSE

Copyright 2016 - 2017 James Clark

Copyright 2024 Raku Community

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.