Skip to content

ItemUsedEvent

A magic item was used: a potion drunk, a scroll read, a device fired.

Full documentation: ItemUsedEvent. Wire type: item_used.

Default visibility: player

Message codes: items.device.activated, items.potion.drunk, items.potion.mixed, items.scroll.cursed, items.scroll.read

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 magic item was used: a potion drunk, a scroll read, a device fired.\n\nEmitted by `UseItem` outside battle and by\n`ResolveBattleRound` for an item used\nin a battle. Whatever the item does follows in the same result as kernel events. A member\ncan give a potion to another member to drink, and `target_id` is then the drinker's id.\n\nUsing an item for the first time identifies it, so an\n`ItemIdentifiedEvent`, and a\n`CurseRevealedEvent` for a cursed item,\ncome just before this one. Using a device that has no charges left emits no event:\nthe session refuses the command with `items.device.inert`, and the party loses\nnothing. Charges never appear on any event, because only the referee knows how many\nuses an item has left.",
  "properties": {
    "code": {
      "title": "Code",
      "type": "string",
      "description": "What happened, like `combat.attack.hit`: two or more lowercase parts separated by dots. The first part is\nthe area of the rules the event comes from, like `combat` or `magic`.\n\nBranch on it, and pass the event to `format_message` to turn it into English.\nBuilding an event with a code in any other format raises a pydantic `ValidationError`."
    },
    "visibility": {
      "$ref": "#/$defs/Visibility",
      "default": "player",
      "description": "Player visibility: the party watched it happen."
    },
    "event_type": {
      "const": "item_used",
      "default": "item_used",
      "title": "Event Type",
      "type": "string",
      "description": "The event type, `item_used`, which identifies this class in serialized form."
    },
    "character_id": {
      "title": "Character Id",
      "type": "string",
      "description": "The member who used the item. For a potion, that's the member who carried it, whoever drank it."
    },
    "instance_id": {
      "title": "Instance Id",
      "type": "string",
      "description": "The session-scoped id of the item used, never its catalog id, so an event about an item the\nparty hasn't identified doesn't reveal what the item is."
    },
    "manual": {
      "default": [],
      "items": {
        "type": "string"
      },
      "title": "Manual",
      "type": "array",
      "description": "The item's printed text, for an item whose effect the engine doesn't resolve, like a treasure\nmap, or the curse's text for a cursed scroll whose curse the engine doesn't apply. A use of the\nstaff of power or wizardry that strikes no group has the staff's text too, because the use is\none of the staff's other powers, like the cone of cold. Empty when the engine resolved the\neffect itself, as it does a staff's strike. Show these lines to the players and rule on them\nyourself."
    },
    "target_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Target Id",
      "description": "The member who drank the potion, on `items.potion.drunk` and `items.potion.mixed`, when the\nmember in `character_id` gave it to another member to drink. The potion's effect, and the sickness\nof mixed potions, land on this member.\n\nIt's `None` when the member who used the potion drank it, and on every other code. Name the drinker\nin `UseItem.target_id`, or in the one id of a `use_item`\ndeclaration's `targets`."
    }
  },
  "required": [
    "code",
    "character_id",
    "instance_id"
  ],
  "title": "ItemUsedEvent",
  "type": "object"
}