Expand dice contrib readme

docs/source/Contribs/Contrib-Dice.md

@@ -1,9 +1,9 @@
 # Dice roller
 
-Contribution by Griatch, 2012
+Contribution by Griatch, 2012, 2023
 
 A dice roller for any number and side of dice. Adds in-game dice rolling
-(`roll 2d10 + 1`) as well as conditionals (roll under/over/equal to a target)
+(like `roll 2d10 + 1`) as well as conditionals (roll under/over/equal to a target)
 and functions for rolling dice in code. Command also supports hidden or secret
 rolls for use by a human game master.
 
@@ -44,14 +44,14 @@ unbiased way.  For example:
 
 Rolling this will inform all parties if roll was indeed below 8 or not.
 
-    > roll/hidden
+    > roll/hidden 1d100
 
 Informs the room that the roll is being made without telling what the result
 was.
 
-    > roll/secret
+    > roll/secret 1d20
 
-Is a hidden roll that does not inform the room it happened.
+This a hidden roll that does not inform the room it happened.
 
 ## Rolling dice from code
 
@@ -93,9 +93,38 @@ Here's how to roll `2d6 - 1 >= 10` (you'll get back `True`/`False` back):
 roll(2, 6, modifier=("-", 1), conditional=(">=", 10))
 ```
 
-You can only roll one set of dice. If your RPG requires you to roll multiple
+### Dice pools and other variations
+
+You can only roll one set of dice at a time. If your RPG requires you to roll multiple
 sets of dice and combine them in more advanced ways, you can do so with multiple
-`roll()` calls.
+`roll()` calls. Depending on what you need, you may just want to express this as
+helper functions specific for your game.
+
+Here's how to roll a D&D advantage roll (roll d20 twice, pick highest):
+
+```python
+    from evennia.contrib.rpg.dice import roll
+
+    def roll_d20_with_advantage():
+        """Get biggest result of two d20 rolls"""
+        return max(roll("d20"), roll("d20"))
+
+```
+
+Here's an example of a Free-League style dice pool, where you roll a pile of d6
+and want to know how many 1s and sixes you get:
+
+```python
+from evennia.contrib.rpg.dice import roll
+
+def roll_dice_pool(poolsize):
+    """Return (number_of_ones, number_of_sixes)"""
+    results = [roll("1d6") for _ in range(poolsize)]
+    return results.count(1), results.count(6)
+
+```
+
+
 
 ### Get all roll details