Skip to content

DetectionRolledEvent

A hidden die roll for a search, a listen, a thief skill, or a trap's chance to spring.

Full documentation: DetectionRolledEvent. Wire type: detection_rolled.

Default visibility: referee

Message codes: exploration.detection.rolled

JSON Schema

{
  "$defs": {
    "Visibility": {
      "description": "Who may see an event: the players, or only the referee.\n\nEvery event has one of these values, because in B/X the referee makes some rolls behind a screen. Filter\na log on it before you show anything to a player, or call\n`GameSession.view`, which builds the players' view and the referee's\nview for you. A narrator that plays the referee reads every event.\n\nA serialized event contains the lowercase value. The values stay fixed within a `schema_version`, the version\nstamp of the saved format.\n\nExamples:\n    ```python\n    from osrlib.core.events import DamageDealtEvent, HitPointsReportedEvent, Visibility\n\n    log = [\n        DamageDealtEvent(target_id=\"monster-0001\", amount=5),\n        HitPointsReportedEvent(target_id=\"monster-0001\", current_hp=2, max_hp=7),\n    ]\n    shown = [event.code for event in log if event.visibility is Visibility.PLAYER]\n    assert shown == [\"combat.damage.dealt\"]  # the goblin's remaining hit points stay hidden\n    ```",
      "enum": [
        "player",
        "referee"
      ],
      "title": "Visibility",
      "type": "string"
    }
  },
  "description": "A hidden die roll for a search, a listen, a thief skill, or a trap's chance to spring.\n\nEmitted by `Search`,\n`ListenAtDoor`,\n`PickLock`,\n`InspectTreasure`, and\n`RemoveTreasureTrap`, ahead of any\nplayer-visible result, and whenever a trap gets its chance to spring.\n\nThe session rolls the die for a search or a listen whether or not there's anything to\nfind, so a failed roll and an empty cell look the same to the players. That is why this\nevent has referee visibility: showing it to players would tell them whether the roll\nfailed. A referee front end, or an LLM running the game, reads it to know what happened.",
  "properties": {
    "code": {
      "default": "exploration.detection.rolled",
      "title": "Code",
      "type": "string",
      "description": "The message code, always `exploration.detection.rolled`."
    },
    "visibility": {
      "$ref": "#/$defs/Visibility",
      "default": "referee",
      "description": "Referee visibility: the roll is the part the referee keeps hidden from the players."
    },
    "event_type": {
      "const": "detection_rolled",
      "default": "detection_rolled",
      "title": "Event Type",
      "type": "string",
      "description": "The event type, `detection_rolled`, which identifies this class in serialized form."
    },
    "character_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Character Id",
      "description": "The member who rolled, or `None` for a check that isn't a member's, like a trap's chance to\ngo off."
    },
    "kind": {
      "title": "Kind",
      "type": "string",
      "description": "What was being checked: `\"listening\"`, one of the search kinds\n(`\"secret_doors\"`, `\"room_traps\"`, `\"construction\"`), `\"open_locks\"`, `\"treasure_traps\"`, or\n`\"trap_spring\"` for a trap's chance to fire."
    },
    "chance": {
      "title": "Chance",
      "type": "integer",
      "description": "The number the roll had to come in at or under. The listening, search, and trap-spring\nkinds are X-in-6 chances rolled on a d6. The thief skills `open_locks` and `treasure_traps`\nare percentages rolled on d100."
    },
    "roll": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Roll",
      "description": "What came up, or `None` when the chance was zero and no die was rolled, as for a character\nwith no chance at all of noticing construction tricks."
    },
    "passed": {
      "title": "Passed",
      "type": "boolean",
      "description": "Whether the check succeeded. From the player's side, a failed check and a cell with nothing\nin it look the same."
    }
  },
  "required": [
    "kind",
    "chance",
    "passed"
  ],
  "title": "DetectionRolledEvent",
  "type": "object"
}