README.md in games_dice-0.1.3 vs README.md in games_dice-0.2.0

- old
+ new

@@ -1,36 +1,36 @@ # GamesDice [![Build Status](https://travis-ci.org/neilslater/games_dice.png?branch=master)](http://travis-ci.org/neilslater/games_dice) -A library for simulating dice, intended for constructing a variety of dice systems as used in -role-playing and board games. +A library for simulating dice. Use it to construct dice-rolling systems used in role-playing and board games. ## Description -GamesDice is a gem to automate or simulate a variety of dice rolling systems found in board games and -role-playing games. +GamesDice can emulate a variety of rules-driven dice systems that are used to generate integer results +within a game. -GamesDice is designed for systems used to generate integer results, and that do not require the -player to make decisions or apply other rules from the game. There are no game mechanics implemented -in GamesDice (such as the chance to hit in a combat game). +The main features of GamesDice are: -The main features of GamesDice are - * Uses string dice descriptions, the basics of which are familiar to many game players e.g. '2d6 + 3' - * Supports common features of dice systems automatically: + * Supports some common features of dice systems: * Re-rolls that replace or modify the previous roll * Counting number of "successes" from a set of dice * Keeping the best, or worst, results from a set of dice * Can explain how a result was achieved in terms of the individual die rolls - * Can calculate probabilities and expected values (experimental feature) + * Can calculate probabilities and expected values (with some limitations) +There are no game mechanics implemented in GamesDice, such as the chance to hit in a fantasy combat +game. There is no support for player interaction within a roll, such as player choice on whether or +not to re-roll a specific die within a combined set. These things are of course possible if you use the +gem as-is, and add them as features within your project code. + ## Special Note on Versions Prior to 1.0.0 -The author is using this code as an exercise in gem "best practice". As such, the gem -will have a limited set of functionality prior to version 1.0.0, and there should be -many small release increments before then. +As of version 0.2.0, the gem has the same feature set as planned for version +1.0.0. Versions between 0.2.0 and 1.0.0 are being used mainly to improve +code quality, documentation and performance. ## Installation Add this line to your application's Gemfile: @@ -89,10 +89,21 @@ dice.result # => nil dice.roll dice.result # => 12 +#### dice.explain_result + +Returns a string that attempts to show how the result from the last call to roll was composed +from individual results. This will be nil if no roll has been made yet. + + dice.explain_result # => nil + dice.roll # => 12 + dice.explain_result # => "3d6: 4 + 2 + 6 = 12" + +The exact format is the subject of refinement in future versions of the gem. + #### dice.max Returns the maximum possible value from a roll of the dice. Dice with the possibility of rolling progressively higher and higher values will return an arbitrary high value. @@ -253,17 +264,17 @@ * REROLL_TYPE is one of * replace (default) - use the new value in place of existing value for the die * add - add result of reroll to running total, and ignore any subtract rules * subtract - subtract result of reroll from running total, and reverse sense of any further add results * use_best - use the new value if it is higher than the existing value - * use_worst - use the new value if it is higher than the existing value + * use_worst - use the new value if it is lower than the existing value * LIMIT is an integer that sets the maximum number of times that the rule can be triggered, the default is 1000 Examples: 1d6r:1. # Same as "1d6r1" - 1d10r:10,replace,1. # + 1d10r:10,replace,1. # Roll a 10-sided die, re-roll a result of 10 and take the value of the second roll 1d20r:<=10,use_best,1. # Roll a 20-sided die, re-roll a result if 10 or lower, and use best result #### Maps You can specify that the value shown on each die is converted to some other set of values. If @@ -273,10 +284,28 @@ 3d10m6 When rolled, this will score from 0 to 3 - the number of the ten-sided dice that scored 6 or higher. +The full version of this modifier, allows you to specify from 1 to 3 parameters: + + 3d10m:[VALUE_COMPARISON],[MAP_VALUE],[DESCRIPTION]. + +Where: + + * VALUE_COMPARISON is one of >, >= (default), ==, <= < plus an integer to set conditions on when the map should occur + * MAP_VALUE is an integer that will be used in place of a result from a die, default value is 1 + * maps are tested in order that they are declared, and first one that matches is applied + * when at least one map has been defined, all unmapped values default to 0 + * DESCRIPTION is a word or character to use to denote the map in any explanation + +Examples: + + 9d6x.m:10. # Roll 9 six-sided "exploding" dice, and count 1 for any result of 10 or more + 9d6x.m:10,1,S. # Same as above, but with each success marked with "S" in the explanation + 5d10m:>=6,1,S.m:==1,-1,F. # Roll 5 ten-sided dice, count 1 for any result of 6 or more, or -1 for any result of 1 + #### Keepers You can specify that only a sub-set of highest or lowest dice values will contribute to the final total. @@ -285,24 +314,51 @@ 5d10k2 When rolled, this will score from 2 to 20 - the sum of the two highest scoring ten-sided dice, out of five. +The full version of this modifier, allows you to specify from 1 to 2 parameters: + + 5d10k:[KEEP_NUM],[KEEP_TYPE]. + +Where: + + * KEEP_NUM is an integer specifying the number of dice to keep. + * KEEP_TYPE is one of + * best - keep highest values and add them together + * worst - keep lowest values and add them together + +Examples: + + 4d6k:3.r:1,replace,1. # Roll 4 six-sided dice, re-roll any 1s, and keep best 3. + 2d20k:1,worst. # Roll 2 twenty-sided dice, return lowest of the two results. + +#### Combinations + + * When there are many modifiers, they are applied in strict order: + * First by type: re-rolls, maps, keepers + * Then according to the order they were specified + * A maximum of one re-roll modifier, and one map modifier are applied to each individual die rolled + * Only one keepers modifier is applied per dice type. Specifying a second one will cause an error + #### Aliases Some combinations of modifiers crop up in well-known games, and have been allocated single-character short codes. This is an alias for "exploding" dice: 5d10x # Same as '5d10r:10,add.' -When rolled, this will score from 5 to theoretically any number, as results of 10 on any die mean that -die rolls again and the result is added on. +When rolled, this will score from 5 to theoretically any higher number, as results of 10 on any +die mean that die rolls again and the result is added on. ## Contributing 1. Fork it 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am 'Add some feature'`) 4. Push to the branch (`git push origin my-new-feature`) 5. Create new Pull Request + +I am always interested to receive information about dice rolling schemes that this library could or +should include in its repertoire.