Refactor dice contrib

docs/source/Contribs/Contrib-Dice.md

@@ -22,7 +22,7 @@ from evennia.contrib.rpg import dice  <---
 
 class CharacterCmdSet(default_cmds.CharacterCmdSet):
     # ...
-    def at_object_creation(self):
+    def at_cmdset_creation(self):
         # ...
         self.add(dice.CmdDice())  # <---
 
@@ -53,17 +53,73 @@ was.
 
 Is a hidden roll that does not inform the room it happened.
 
-### Rolling dice from code
+## Rolling dice from code
 
-To roll dice in code, use the `roll` function from this module:
+To roll dice in code, use the `roll` function from this module. It has two
+main ways to define the expected roll:
 
 ```python
+from evennia.contrib.rpg.dice import roll
 
-from evennia.contrib.rpg import dice
-dice.roll(3, 10, ("+", 2))  # 3d10 + 2
+roll(dice, dicetype=6, modifier=None, conditional=None, return_tuple=False,
+      max_dicenum=10, max_dicetype=1000)
 
 ```
 
+You can only roll one set of dice. 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 dice based on a string
+
+You can specify the first argument as a string on standard RPG d-syntax (NdM,
+where N is the number of dice to roll, and M is the number sides per dice):
+
+```python
+roll("3d10 + 2")
+```
+
+You can also give a conditional (you'll then get a `True`/`False` back):
+
+```python
+roll("2d6 - 1 >= 10")
+```
+
+### Explicit arguments
+
+If you specify the first argument as an integer, it's interpret as the number of
+dice to roll and you can then build the roll more explicitly. This can be
+useful if you are using the roller together with some other system and want to
+construct the roll from components.
+
+
+Here's how to roll `3d10 + 2` with explicit syntax:
+
+```python
+roll(3, 10, modifier=("+", 2))
+```
+
+Here's how to roll `2d6 - 1 >= 10` (you'll get back `True`/`False` back):
+
+```python
+roll(2, 6, modifier=("-", 1), conditional=(">=", 10))
+```
+
+### Get all roll details
+
+If you need the individual rolls (e.g. for a dice pool), set the `return_tuple` kwarg:
+
+```python
+roll("3d10 > 10", return_tuple=True)
+(13, True, 3, (3, 4, 6))  # (result, outcome, diff, rolls)
+```
+
+The return is a tuple `(result, outcome, diff, rolls)`, where `result` is the
+result of the roll, `outcome` is `True/False` if a conditional was
+given (`None` otherwise), `diff` is the absolute difference between the
+conditional and the result (`None` otherwise) and `rolls` is a tuple containing
+the individual roll results.
+
 
 ----