UseItem

Use a magic item: drink a potion, read a scroll, activate a device (one round).

Full documentation: UseItem. Wire type: use_item.

Legal session modes: encounter, exploring

JSON Schema

{
  "description": "Use a magic item: drink a potion, read a scroll, activate a device (one round).\n\nOne round is the RAW activation cost (drinking is one round). `target_id`\nnames a character (the staff of healing's touch) or an encounter group (a\ndevice's area); `spell_id`, `mode`, and `targets` select the inscribed spell\nand its targets when reading a multi-spell scroll (the\n[`CastSpell`][osrlib.crawl.commands.CastSpell] surface). In battle, item use\nis the `use_item` declaration instead. First meaningful use identifies the\nitem \u2014 and reveals its curse.\n\nModes:\n    `exploring`, `encounter`\n\nRejections:\n    - `session.command.wrong_mode` \u2014 the session is in town, in battle, or\n      over.\n    - `session.command.unknown_member` \u2014 `character_id` names no party member.\n    - `session.command.member_incapacitated` \u2014 the member cannot act.\n    - `exploration.item.not_carried` \u2014 the member carries no magic item with\n      that instance id.\n    - `items.use.not_usable` \u2014 the item has no usable action, or the class\n      cannot use the device.\n    - Scrolls: `exploration.action.requires_light` (reading needs real light),\n      `items.scroll.spent`, `items.scroll.no_such_spell`,\n      `items.scroll.wrong_caster`, and the cast validation codes\n      (`magic.cast.unknown_target`, `magic.cast.unknown_mode`,\n      `magic.cast.target_count`, `magic.cast.out_of_range`,\n      `magic.cast.caster_incapacitated`, `magic.cast.caster_restrained`,\n      `magic.cast.anti_magic_shell`).\n    - Devices: `items.device.inert` (no charges left),\n      `items.use.target_required`, `items.use.unknown_target`, and\n      `items.use.battle_only` (a striking effect is a battle declaration).\n\nEvents:\n    [`ItemUsedEvent`][osrlib.crawl.events.ItemUsedEvent] naming what happened\n    (drunk, read, activated \u2014 or mixed potions, or a cursed scroll), with\n    [`ItemIdentifiedEvent`][osrlib.crawl.events.ItemIdentifiedEvent] and\n    [`CurseRevealedEvent`][osrlib.crawl.events.CurseRevealedEvent] at first\n    meaningful use, then the item's own resolution \u2014 healing, saving throws,\n    damage, effect attachments, a scroll's\n    [`SpellCastEvent`][osrlib.core.events.SpellCastEvent] \u2014 each its own\n    event. One round passes (in an encounter, the round beat follows instead).",
  "properties": {
    "command_type": {
      "const": "use_item",
      "default": "use_item",
      "title": "Command Type",
      "type": "string"
    },
    "character_id": {
      "title": "Character Id",
      "type": "string"
    },
    "item_id": {
      "title": "Item Id",
      "type": "string"
    },
    "target_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Target Id"
    },
    "spell_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Spell Id"
    },
    "mode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Mode"
    },
    "targets": {
      "default": [],
      "items": {
        "type": "string"
      },
      "title": "Targets",
      "type": "array"
    }
  },
  "required": [
    "character_id",
    "item_id"
  ],
  "title": "UseItem",
  "type": "object"
}