# evennia.contrib.rpg.dice.dice

## Dice

Rolls dice for roleplaying, in-game gambling or GM:ing

Evennia contribution - Griatch 2012

This module implements a a dice-roller and a dice/roll command to go with it. It uses standard RPG ‘d’-syntax (e.g. 2d6 to roll two six-sided die) and also supports modifiers such as 3d6 + 5.

> > roll 1d20 + 2

One can also specify a standard Python operator in order to specify eventual target numbers and get results in a fair and guaranteed unbiased way. For example a GM could (using the dice command) from the start define the roll as 2d6 < 8 to show that a roll below 8 is required to succeed. The command will normally echo this result to all parties (although it also has options for hidden and secret rolls).

## Installation:

Add the CmdDice command from this module to your character’s cmdset (and then restart the server):

    # in mygame/commands/default_cmdsets.py

    # ...
    from evennia.contrib.rpg import dice  <---

    class CharacterCmdSet(default_cmds.CharacterCmdSet):
        # ...
        def at_object_creation(self):
            # ...
            self.add(dice.CmdDice())  # <---

## Usage:

> roll 1d100 + 10

To roll dice in code, use the roll function from this module:

    from evennia.contrib.rpg import dice
    dice.roll_dice(3, 10, ("+", 2))  # 3d10 + 2

`evennia.contrib.rpg.dice.dice.``roll`(dicenum, dicetype, modifier=None, conditional=None, return_tuple=False)

  This is a standard dice roller.

  Parameters

    - dicenum (int) – Number of dice to roll (the result to be added).

    - dicetype (int) – Number of sides of the dice to be rolled.

    - modifier (tuple) – A tuple (operator, value), where operator is one of “+”, “-”, “/” or “*”. The result of the dice roll(s) will be modified by this value.

    - conditional (tuple) – A tuple (conditional, value), where conditional is one of “==”,**”<”,”>”,”>=”,”<=**” or “!=”. This allows the roller to directly return a result depending on if the conditional was passed or not.

    - return_tuple (bool) – Return a tuple with all individual roll results or not.

  Returns

    roll_result (int) –

    The result of the roll + modifiers. This is the

      default return.

    condition_result (bool): A True/False value returned if conditional

      is set but not return_tuple. This effectively hides the result of the roll.

    full_result (tuple): If, return_tuple** is True, instead

      return a tuple (result, outcome, diff, rolls). Here, result is the normal result of the roll + modifiers. outcome and diff are the boolean result of the roll and absolute difference to the conditional input; they will be will be None if conditional is not set. rolls is itself a tuple holding all the individual rolls in the case of multiple die-rolls.

  Raises

    TypeError if non-supported modifiers or conditionals are given. –

  Notes

  All input numbers are converted to integers.

  Examples

  print roll_dice(2, 6) # 2d6 <<< 7 print roll_dice(1, 100, (‘+’, 5) # 1d100 + 5 <<< 34 print roll_dice(1, 20, conditional=(‘<’, 10) # let’say we roll 3 <<< True print roll_dice(3, 10, return_tuple=True) <<< (11, None, None, (2, 5, 4)) print roll_dice(2, 20, (‘-’, 2), conditional=(‘>=’, 10), return_tuple=True) <<< (8, False, 2, (4, 6)) # roll was 4 + 6 - 2 = 8

`evennia.contrib.rpg.dice.dice.``roll_dice`(dicenum, dicetype, modifier=None, conditional=None, return_tuple=False)

  This is a standard dice roller.

  Parameters

    - dicenum (int) – Number of dice to roll (the result to be added).

    - dicetype (int) – Number of sides of the dice to be rolled.

    - modifier (tuple) – A tuple (operator, value), where operator is one of “+”, “-”, “/” or “*”. The result of the dice roll(s) will be modified by this value.

    - conditional (tuple) – A tuple (conditional, value), where conditional is one of “==”,**”<”,”>”,”>=”,”<=**” or “!=”. This allows the roller to directly return a result depending on if the conditional was passed or not.

    - return_tuple (bool) – Return a tuple with all individual roll results or not.

  Returns

    roll_result (int) –

    The result of the roll + modifiers. This is the

      default return.

    condition_result (bool): A True/False value returned if conditional

      is set but not return_tuple. This effectively hides the result of the roll.

    full_result (tuple): If, return_tuple** is True, instead

      return a tuple (result, outcome, diff, rolls). Here, result is the normal result of the roll + modifiers. outcome and diff are the boolean result of the roll and absolute difference to the conditional input; they will be will be None if conditional is not set. rolls is itself a tuple holding all the individual rolls in the case of multiple die-rolls.

  Raises

    TypeError if non-supported modifiers or conditionals are given. –

  Notes

  All input numbers are converted to integers.

  Examples

  print roll_dice(2, 6) # 2d6 <<< 7 print roll_dice(1, 100, (‘+’, 5) # 1d100 + 5 <<< 34 print roll_dice(1, 20, conditional=(‘<’, 10) # let’say we roll 3 <<< True print roll_dice(3, 10, return_tuple=True) <<< (11, None, None, (2, 5, 4)) print roll_dice(2, 20, (‘-’, 2), conditional=(‘>=’, 10), return_tuple=True) <<< (8, False, 2, (4, 6)) # roll was 4 + 6 - 2 = 8

class `evennia.contrib.rpg.dice.dice.``CmdDice`(**kwargs)

  Bases: `evennia.commands.default.muxcommand.MuxCommand`

  roll dice

  Usage:

    dice[/switch] <nr>d<sides> [modifier] [success condition]

  Switch:

    hidden - tell the room the roll is being done, but don’t show the result secret - don’t inform the room about neither roll nor result

  Examples

  dice 3d6 + 4 dice 1d100 - 2 < 50

  This will roll the given number of dice with given sides and modifiers. So e.g. 2d6 + 3 means to ‘roll a 6-sided die 2 times and add the result, then add 3 to the total’. Accepted modifiers are +, -, * and /. A success condition is given as normal Python conditionals (<,>,<=,>=,==,!=). So e.g. 2d6 + 3 > 10 means that the roll will succeed only if the final result is above 8. If a success condition is given, the outcome (pass/fail) will be echoed along with how much it succeeded/failed with. The hidden/secret switches will hide all or parts of the roll from everyone but the person rolling.

  `key` = 'dice'
  `aliases` = ['@dice', 'roll']
  `locks` = 'cmd:all()'
  `func`()

    Mostly parsing for calling the dice roller function

  `help_category` = 'general'
  `lock_storage` = 'cmd:all()'
  `search_index_entry` = {'aliases': '@dice roll', 'category': 'general', 'key': 'dice', 'no_prefix': ' dice roll', 'tags': '', 'text': "\n roll dice\n\n Usage:\n dice[/switch] <nr>d<sides> [modifier] [success condition]\n\n Switch:\n hidden - tell the room the roll is being done, but don't show the result\n secret - don't inform the room about neither roll nor result\n\n Examples:\n dice 3d6 + 4\n dice 1d100 - 2 < 50\n\n This will roll the given number of dice with given sides and modifiers.\n So e.g. 2d6 + 3 means to 'roll a 6-sided die 2 times and add the result,\n then add 3 to the total'.\n Accepted modifiers are +, -, * and /.\n A success condition is given as normal Python conditionals\n (<,>,<=,>=,==,!=). So e.g. 2d6 + 3 > 10 means that the roll will succeed\n only if the final result is above 8. If a success condition is given, the\n outcome (pass/fail) will be echoed along with how much it succeeded/failed\n with. The hidden/secret switches will hide all or parts of the roll from\n everyone but the person rolling.\n "}

class `evennia.contrib.rpg.dice.dice.``DiceCmdSet`(cmdsetobj=None, key=None)

  Bases: `evennia.commands.cmdset.CmdSet`

  a small cmdset for testing purposes. Add with @py self.cmdset.add(“contrib.dice.DiceCmdSet”)

  `at_cmdset_creation`()

    Called when set is created

  `path` = 'evennia.contrib.rpg.dice.dice.DiceCmdSet'