Skip to content

RollDice

Referee: roll dice through the session, so the roll is seeded, logged, and replayed.

Full documentation: RollDice. Wire type: roll_dice.

Legal session modes: battle, encounter, exploring, game_over, town, victory

JSON Schema

{
  "description": "Referee: roll dice through the session, so the roll is seeded, logged, and replayed.\n\nUse it when the referee decides a chance outcome that osrlib doesn't model, like a\npuzzle, a bluff, or whether a frayed rope holds. A roll made through the session is\nlogged, replayed, and reported as an event, unlike a roll you make yourself.\nThis command is legal in every mode, `game_over` and `victory` included. The session draws the roll\nfrom the separate\n`ADJUDICATION_STREAM`, so a referee's roll\nnever changes what any other stream draws. A malformed `expression` fails validation with\npydantic's `ValidationError` when the command is constructed, as a malformed `count_dice` on\n`SpawnMonsters` does, so it never reaches the\nsession and makes no random roll.\n\nModes:\n    `town`, `exploring`, `encounter`, `battle`, `game_over`, `victory`\n\nRejections:\n    None.\n\nEvents:\n    `DiceRolledEvent` with the\n    expression, the total, and each die's result. The event has referee visibility.",
  "properties": {
    "command_type": {
      "const": "roll_dice",
      "default": "roll_dice",
      "title": "Command Type",
      "type": "string",
      "description": "The name that identifies the command class in serialized data. Each command class fixes\nit to a distinct snake_case string, like `\"move_party\"` or `\"open_door\"`, and constructing\nthe class sets it, so you never pass it yourself.\n`parse_command` and the\n`AnyCommand` union use it to rebuild the right class\nfrom a serialized mapping. A class's value never changes between releases."
    },
    "source": {
      "anyOf": [
        {
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Source",
      "description": "Who or what issued the command on whose behalf: an authored trigger or quest id, or the\nname of one of your game's systems. The engine never reads it, so a command with a\n`source` does exactly what the same command without one does. The session logs and\nreplays it with the command, so the log alone shows why something happened. Leave it\n`None` when there's nothing to record. An empty string fails validation when the command\nis constructed."
    },
    "expression": {
      "title": "Expression",
      "type": "string",
      "description": "The roll, in the notation `parse` accepts, like `\"1d20\"`,\n`\"3d6+2\"`, or `\"2d6+1x10\"`. A malformed expression fails validation when the command is\nconstructed rather than coming back as a rejection, so it never reaches the session and\ndraws nothing."
    }
  },
  "required": [
    "expression"
  ],
  "title": "RollDice",
  "type": "object"
}