DetectionRolledEvent

A referee-rolled detection die: a search, a listen, a lock, or a trap trigger.

Full documentation: DetectionRolledEvent. Wire type: detection_rolled.

Default visibility: referee

Message codes: exploration.detection.rolled

JSON Schema

{
  "$defs": {
    "Visibility": {
      "description": "Who is allowed to see an event.\n\nEvery event has one of these two values, and the split exists because B/X keeps some rolls behind the\nreferee's screen. Filter a log on it before you show anything to a player, or call\n`GameSession.view`, which builds the player's and the referee's\nviews for you. A narrator playing referee reads both.\n\nThe values are the lowercase strings and they serialize into every event, so a renamed value is a\n`schema_version` bump.\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 referee-rolled detection die: a search, a listen, a lock, or a trap trigger.\n\nEmitted alongside the player-facing result of\n`Search`,\n`ListenAtDoor`,\n`PickLock`,\n`InspectTreasure`, and\n`RemoveTreasureTrap`, and whenever a\ntrap gets its chance to spring.\n\nThe die is rolled whether or not there's anything to find, so that a failure and\nan empty cell look the same from the table. That is why this event is referee\nvisibility: showing it to players would leak the answer the roll was hiding. A\nreferee front end, or an LLM running the game, reads it to know what actually\nhappened.",
  "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 B/X keeps behind the screen."
    },
    "event_type": {
      "const": "detection_rolled",
      "default": "detection_rolled",
      "title": "Event Type",
      "type": "string",
      "description": "The wire discriminator, `detection_rolled`."
    },
    "character_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Character Id",
      "description": "The member who rolled, or `None` for a check nobody made, like a trap's own 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. A failed check and a nothing-there cell are deliberately\nindistinguishable from the player's side."
    }
  },
  "required": [
    "kind",
    "chance",
    "passed"
  ],
  "title": "DetectionRolledEvent",
  "type": "object"
}