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, simulating "loaded" dice. 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> COPYRIGHT 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.