Py Die R E A D M E


Published on

pyDie is a library designed to simulate dice of various types and the random rolls of such. It has been designed to be reusable and with some intelligent decision making capabilities.

  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Py Die R E A D M E

  1. 1. pyDie I created pyDie as a re-usable die class program for games or for any program that need a random probabilities based upon dice or dice like entities. In order to use pyDie you must import the class just like any Python library. It contains two classes (die and cup). The die class can be initialized simply by passing a single parameter defining the number of sides (myDie = pyDie.die(6)) The library will then proceed to create a default die using the number of sides provided with values starting at 1 and incrementing by 1's till all sides are filled. You may also pass a second parameter for the low value and create a specialized die based upon the sides and the low value you assign (such as myDie = pyDie.die(6, 4) creates a die with values from 4 through 9). A third parameter can be use to set the high value but beware if you specify a low and high value that does not have a large enough range for the number of sides you specify pyDie will create the die with the right number of sides and try to make an intelligent decision about the range. Also if you mistakenly make the low value greater than the high value, pyDie will again attempt to make an intelligent decision regarding the layout of the die. The last possible parameter for initializing your die is the incrementation value. This allows you to create dice that increment greater than one number at a time. An example of this would be (myDie = pyDie.die(8, 1, 16, 2) results in a die with possible values of 1, 3, 5, 7, 9, 11, 13, 15). Once you have initialized your die you can call the roll method which will randomly choose a value from your list of possibilities. You can accomplish this by using myDie.roll(), you can then access this result using the newly created attribute called value (print myDie.value). The second class in pyDie is the cup class which allows you to store multiple dice and even roll them all at one time. You can create your cup simply by using myCup = pyDie.cup(). You would then add your die to the cup using myCup.add(myDie). You can then use the throw method to throw all dice in the cup (myCup.throw()). You would then access each die's value using the attribute for each die in the cup. The cup class also has an empty method which clears all dice from the cup, and a remove method which can be used to remove a single die from the cup simply by using myCup.remove(myDie). The following is an example of die and cup creation: import pyDie myDie = [] cup = pyDie.cup() # Create 4 standard die for i in range (1, 5): myDie.append(pyDie.die(6)) # Create one eight sided that starts with 10 # and increments by 5's myDie.append(pyDie.die(8, 10, 50, 5)) # Create one final die that is 10 sided # and begins with 0 and decrements by 2's myDie.append(pyDie.die(10, -20, 0, -2)) for die in myDie: cup.add(die) cup.throw() total=0
  2. 2. print "Die paramaters: (sides, low, high, [range])" for die in cup.dice: total = total + die.value print "(%i, %i, %i, %s)"%(die.sides, die.low, die.high, die.possible) print "Result of throw for this die: %i"%die.value print "--------------------------------------------" print "Total of all dice: %i"%total The first four die are standard followed by two non-standard configurations. In this example we create five standard dice: import pyDie myDie = [] cup = pyDie.cup() # Create 5 standard die for i in range (1, 6): myDie.append(pyDie.die(6)) for die in myDie: cup.add(die) cup.throw() for die in cup.dice: print die.value
  3. 3. Now we will look at some of the intelligent choices that pyDie makes when odd parameters are passed to it. This test script was used to test pyDie, and although not pretty, it does demonstrate the power and flexibility of this library. import pyDie print "A cup for the dice" cup = pyDie.cup() print "A standard die..." die1 = pyDie.die(6) print "Die sides=%i, low=%i, high=%i, range=%s"%(die1.sides, die1.low, die1.high, die1.possible) die1.roll() print "Result of roll %i"%die1.value print "Add die to cup" cup.add(die1) print "--------------------------------------n" print "A non-standard 8 sided die" die2 = pyDie.die(8) print "Die sides=%i, low=%i, high=%i, range=%s"%(die2.sides, die2.low, die2.high, die2.possible) die2.roll() print "Result of roll %i"%die2.value print "Add die to cup" cup.add(die2) print "--------------------------------------n" print "An 8 sided die with low > high" die3 = pyDie.die(8, 4, -3) print "Die sides=%i, low=%i, high=%i, range=%s"%(die3.sides, die3.low, die3.high, die3.possible)
  4. 4. die3.roll() print "Result of roll %i"%die3.value print "Add die to cup" cup.add(die3) print "--------------------------------------n" print "Parameters 6, 2, 8, 1" die4 = pyDie.die(6, 2, 8) print "Die sides=%i, low=%i, high=%i, range=%s"%(die4.sides, die4.low, die4.high, die4.possible) die4.roll() print "Result of roll %i"%die4.value print "Add die to cup" cup.add(die4) print "--------------------------------------n" print "An eight sided die starting at 10..." die5 = pyDie.die(8, 10) print "Die sides=%i, low=%i, high=%i, range=%s"%(die5.sides, die5.low, die5.high, die5.possible) die5.roll() print "Result of roll %i"%die5.value print "Add die to cup" cup.add(die5) print "--------------------------------------n" print "A six sided die (6, 0, -5, -1)" die6 = pyDie.die(6, 0, -5, -1) print "Die sides=%i, low=%i, high=%i, range=%s"%(die6.sides, die6.low, die6.high, die6.possible) die6.roll() print "Result of roll %i"%die6.value print "Add die to cup" cup.add(die6) print "--------------------------------------n" print "Roll all die in cup at once" cup.throw() for die in cup.dice: print die.value Note: Each highlighted line above illustrates different features of die creation
  5. 5. The first thing to note is that die1 = pyDie.die(6) is a simple default die creation. This is then followed by die2 = pyDie.die(8) which is a non-standard eight sided die. The interesting part occurs with the third die die3 = pyDie.die(8, 4, -3) which is created as an eight sided die but the low value is actually higher than the high value which additionally is a negative number (Note: pyDie ignores the high value and creates the die beginning with the low value and working up from there, and then sets the high value to the appropriate value).
  6. 6. The next die created die4 = pyDie.die(6, 2, 8) is a six sided die starting at two and going to eight (since the high value is outside of the range it is changed to the appropriate value). Following that is an eight sided die beginning with 10 die5 = pyDie.die(8, 10), this is then followed by a six sided die die6 = pyDie.die(6, 0, -5, -1) that starts at zero and decrements by one to -5. This is then followed by the throw of the cup. Roll all die in cup at once 3 8 7 4 16 -1 As you can see pyDie has been designed with simplicity in mind while still incorporating some intelligence in order to avoid potential errors.
  7. 7. Source Code The following is the pyDie source code. # Program: # Author: James D. Coen # Date: 2009.12.11 # Purpose: This program is used to create a generic # die roll class so that it can be imported # and re-used in various ways from random import randint, seed from time import time class die(object): """ A single die. """ def __init__(self, sides, low=1, high=6, incr=1): """ The first argument is the number of sides the second is the lowest # possible (default 1) the third is the highest # possible (default 6) the fourth is the number to increment by (default 1) """ self.sides = sides possible = [] if incr == 0: incr = 1 if incr < 0: if low < high: for i in range(high, low-1, incr): possible.append(i) elif low > high: for i in range(low, high-1, incr): possible.append(i) else: for i in range(0, sides+1*-1, incr): possible.append(i) possible.sort() while len(possible) > self.sides: possible.remove(possible[0]) low = possible[0] while len(possible) < self.sides: possible.append(possible[0] + incr) possible.sort() low = possible[0] else: if low < high: for i in range(low, high+1, incr): possible.append(i) else: for i in range(low, low+sides+1, incr): possible.append(i) possible.sort() while len(possible) > self.sides: possible.remove(possible[len(possible)-1]) high = possible[len(possible)-1]
  8. 8. while len(possible) < self.sides: possible.append(possible[len(possible)-1] + incr) high = possible[len(possible)-1] if low < high: self.high = high self.low = low elif low > high: self.low = high self.high = low else: self.low = possible[0] self.high = possible[len(possible)-1] self.possible = possible def roll(self): """ Role the die """ seed(time() * time() * self.sides) self.value = randint(self.low, self.high) if self.value not in self.possible: while self.value not in self.possible: self.value = randint(self.low, self.high) class cup(object): """ A cup full of dice. """ def __init__(self): self.dice = [] def empty(self): self.dice = [] def add(self, die): self.dice.append(die) def remove(self, die): self.dice.remove(die) def throw(self): for die in self.dice: die.roll() It must be noted that pyDie works extremely well on Linux but there seems to be a problem with the randomness on the Window's platform that I have not take time to analyze as I do not use this platform regularly.