Do you know where your variables are? PerlMonks

Released - Acme::Dice

by boftx (Deacon)
 on Oct 16, 2013 at 00:34 UTC Need Help??

I plan on releasing this on the unsuspecting masses in a few days. It was partly inspired by the knowledge that there will soon be a coding contest at work that will involve writing a program to simulate a popular dice game. (No, it is NOT craps!)

Before doing so, I would like input from the denizens of the Monastery as to the quality of the documentation, the humor factor (i.e. does it live up to the spirit of Acme?) and of course completeness of functionality. (Yes, that last is begging for problems, especially since I have already thought of one or two enhancements such as "best x of y rolls.")

The full proposed release can be found here: http://github.com/boftx/Acme-Dice

And here is the output from pod2text:

```NAME
Acme::Dice - The finest in croo ..., uhhh, precision dice!

SYNOPSIS
use Acme::Dice qw(roll_dice roll_craps);

my \$total = roll_dice( dice => 3, sides => 6, favor => 6, bias =>
+ 30 );
my @dice = roll_dice( dice => 3, sides => 6, favor => 6, bias =>
+30 );

my \$craps_roll = dice_craps( bias => 30 );
my @craps_dice = dice_craps( bias => 30 );

DESCRIPTION
Acme knows that sometimes one needs more flexibility in one's roll
+s than
using normal dice normally allows. Here at last is a package that
+gives
one exactly the flexibility that has been lacking.

With Acme::Dice, not only can one specify the number and type of d
+ice to
be rolled, not only can one choose to have just the total number o
+r the
individual die results returned, but one can exert some amount of
influence over the outcome as well!

FUNCTIONS
The following functions are available as imports.

roll_dice
This is the primary function. It accepts the parameters listed bel
+ow to
control behavior and will return either the sum of the rolls or an
+ array
containing the results of individual dice rolls depending upon con
+text.

my \$total = roll_dice( dice => 3, sides => 6, favor => 6, bias =>
+ 30 );
my @dice = roll_dice( dice => 3, sides => 6, favor => 6, bias =>
+30 );

The two examples above both roll three six-sided dice with a 30% b
+ias in
favor of rolling a six (6) on each die. The first returns the tota
+l of
the three dice in a scalar, and the second returns an array with t
+he
individual rolls.

All parameters are optional, and if the function is called with no
parameters it will roll a single 6-sided die with no bias.

The parameters are as follows:

dice
This is an integer specifying the number of dice to roll. Defa
+ult: 1

An exception will be thrown if it is less than 1 or greater th
+an
100.

sides
This is an integer specifying how many sides are on the dice t
+o be
rolled. Default: 6

An exception will be thrown if it is less than 1. (Huh? A 1-si
+ded
die? Nothing is impossible for Acme!)

favor
This integer specifies which number (if any) should be favored
+ and
must be between 0 and the value specified for "sides". A value
+ of 0
disables any bias even if a value for "bias" is given. Default
+: 0

bias
This is an integer between 0 and 100 that determines how much
"weight" to place on the favored side. A value of 20 says to
increase the chance of rolling the favored number by 20%. A va
+lue of
100 would mean to always roll the favored number. A value of 0
+ will
disable favoring completely, even if a value for "favor" is gi
+ven.
Default: 0

An exception will be thrown if the value is less than 0 or gre
+ater
than 100.

roll_craps
This function is sugar for "roll_dice" that automatically rolls tw
+o
6-sided dice. It will also automatically adjust the "favor" parame
+ter
for "3" and "4" as appropriate if a value for "bias" is given,

Like "roll_dice", the return value depends upon context.

my \$total = roll_craps( bias => 30 );
my @dice = roll_craps( bias => 30 );

It will only accept a single, optional parameter: "bias"

The "bias" parameter behaves the same as described above for
"roll_dice". Any other parameters, including those that are otherw
+ise
legal for "roll_dice", will cause an exception to be thrown.

The default is an un-biased roll of two 6-sided dice.

BUGS
Bugs? In an Acme module?!? Yeah, right.

SUPPORT
Support is provided by the author. Please report bugs or make feat
+ure
requests to the author or use the GitHub repository:

http://github.com/boftx/Acme-Dice

AUTHOR
Jim Bacon <jim@nortx.com>

This program is free software; you can redistribute it and/or modi
+fy it
under the same terms as Perl itself. The full text of the license
+can be
found in the LICENSE file included with this module.

DISCLAIMER
Finding a way to use this module, and the consequences of doing so
+, is
the sole responsibility of the user!

NOTE
Acme employs the finest technology available to ensure the quality
+ of
its products. There are no user-servicable parts inside. For your
+own
safety, DO NOT EXAMINE THE CONTENTS OF THIS PACKAGE!

I should mention that if you examine the code (despite the warning!) and wonder why I have put a random chance to always roll a "7" for the craps roll, that such a chance is a distinct advantage on a "come out" roll and a distinct disadvantage on a "point" roll. Of course, it would be up to the actual simulation software to know what kind of roll is being made.

The answer to the question "Can we do this?" is always an emphatic "Yes!" Just give me enough time and money.

Replies are listed 'Best First'.
Re: RFC - Acme::Dice
by kcott (Chancellor) on Oct 16, 2013 at 04:37 UTC

G'day Jim,

Generally, the doco looks fine, inasmuch as it was easy to read and conveyed how to use the module.

There is a problem in the SYNOPSIS: two instances of dice_craps should be roll_craps; or, alternatively, four instances of roll_craps (in various parts of the doco) should be dice_craps. Given you wrote "No, it is NOT craps!", at the start of the post, I was a little surprised to find any functions referring to craps.

I don't know if you were planning to upload this to CPAN. Just be aware that there's already a lot of dice-related modules on CPAN. I'll leave you to check whether your proposed module adds any functionality not already covered: if it does, it would be worth adding an indication of whatever that might be to the doco.

Something I often look for in module documentation is whether anything is exported by default. As yours doesn't: consider adding a note to this effect (possibly right before "The following functions are available as imports.").

I had a very brief look at the code: nothing leapt out at me as being particularly wrong.

-- Ken

Hi, Ken. Good catch on dice_craps, I've changed those lines to roll_craps.

I checked several of the other dice modules, and most of them I saw used the RPG notation (3d6, etc.) to specify the conditions. I felt that people outside the RPG community might not immediately recognize that, and those within it would not have a problem with distinct params. I also checked one that allows for "loaded" dice and felt it was a little too hard for one without a math or statistics background to grasp. Mine is more of a "gut-feel" approach, but given this is Acme, it seemed appropriate. :)

I've also added an explicit statement that nothing is EXPORTed by default as you suggested.

Thanks for the great input!

The answer to the question "Can we do this?" is always an emphatic "Yes!" Just give me enough time and money.
Re: RFC - Acme::Dice
by syphilis (Chancellor) on Oct 16, 2013 at 04:29 UTC
Huh? A 1-sided die? Nothing is impossible for Acme!

Nor in reality.

Looks good ;-)

Cheers,
Rob
Re: RFC - Acme::Dice
by hdb (Prior) on Oct 16, 2013 at 07:05 UTC
Re: RFC - Acme::Dice
by Your Mother (Chancellor) on Oct 16, 2013 at 16:50 UTC

If I were actually going to use this, for RPGs or whatever, I’d prefer a “magical” overloaded interface. Not that I’ve had time for RPGs since I wrote dice rolling code in BASIC on a TRaSh 80… anyway, maybe more like–

```print four();
my \$four = four();
say \$four + \$four;
say six() x 3;

Shouldn’t be too hard to have all the die functions being object constructors with various overloading.

I always preferred standard RPG nomenclature here: "1d6", "3d6", "2d20+15" and then let my code pull that apart (simple regexes), roll the dice, and return it. A bias can be added either as a separate parameter (or two) or an extra "non-standard" addition to the above strings: "3d6>30%6" (3 6-sided dice, bias 30% toward 6). The nice thing about this is that it makes things so much easier to put into data files, e.g., "STR: 3d6>30%6" to make a monster that can't be any stronger than a standard human could be but does seem to average out a bit higher.

This also happens to be much less magical, and magic often bites me in the butt often enough as it is :)

As I mentioned above, I felt using the RPG notation would cumbersome for those who are not familiar with it. That, and I was too lazy to write the regex expressions. :)

The answer to the question "Can we do this?" is always an emphatic "Yes!" Just give me enough time and money.
Re: Released - Acme::Dice
by boftx (Deacon) on Oct 19, 2013 at 05:30 UTC

Thank you everyone who responded to this! It has now been uploaded to CPAN and (barring any problems) should be visible soon.

The answer to the question "Can we do this?" is always an emphatic "Yes!" Just give me enough time and money.
Re: RFC - Acme::Dice
by Tux (Abbot) on Oct 16, 2013 at 07:55 UTC

Nice :)

```\$section{DESCRIPTION} =~
s{individual die results returned,}
{individual dice results returned,};

Enjoy, Have FUN! H.Merijn

Nie to know. Still reads extremely weird (in a perl context) for non-native English people.

Enjoy, Have FUN! H.Merijn
Re: RFC - Acme::Dice
by davies (Parson) on Oct 16, 2013 at 15:33 UTC
bias This is an integer between 0 and 100 that determines how much "weight" to place on the favored side. A value of 20 says to increase the chance of rolling the favored number by 20%. A value of 100 would mean to always roll the favored number. A value of 0 will disable favoring completely, even if a value for "favor" is given.

Are negative values allowed? In other words, could one use this to reduce the throwing of low numbers rather than increase the throwing of high numbers? The documentation says "between 0 and 100" implying that you can't, but it isn't obvious to me why this should be the case.

Regards,

John Davies

You are correct that only non-negative integers in the stated range are allowed. That said, I am considering how to implement a "favor above" and/or "favor below" param to make it easier to "adjust" things such as "saving rolls".

The answer to the question "Can we do this?" is always an emphatic "Yes!" Just give me enough time and money.

Create A New User
Node Status?
node history
Node Type: perlmeditation [id://1058374]
Approved by ww
help
Chatterbox?
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others wandering the Monastery: (3)
As of 2017-08-19 04:08 GMT
Sections?
Information?
Find Nodes?
Leftovers?
Voting Booth?
Who is your favorite scientist and why?

Results (310 votes). Check out past polls.

Notices?