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` surface). In battle, item use\nis the `use_item` declaration instead. First meaningful use identifies the\nitem, and reveals its curse.\n\nModes:\n    `exploring`, `encounter`\n\nRejections:\n    - `session.command.wrong_mode` - the session is in town, in battle, or\n      over.\n    - `session.command.unknown_member` - `character_id` names no party member.\n    - `session.command.member_incapacitated` - the member cannot act.\n    - `exploration.item.not_carried` - the member carries no magic item with\n      that instance id.\n    - `items.use.not_usable` - 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`). A read is judged against a caster at\n      the scroll's own level, the level\n      `cast_from_scroll` resolves it\n      at, so a 6th-level reader of a *magic missile* scroll supplies one\n      target and is refused three. The refusal comes before the scroll is\n      spent.\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` naming what happened\n    (drunk, read, activated, or mixed potions, or a cursed scroll), with\n    `ItemIdentifiedEvent` and\n    `CurseRevealedEvent` at first\n    meaningful use, then the item's own resolution: healing, saving throws,\n    damage, effect attachments, and a scroll's\n    `SpellCastEvent`, 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",
      "description": "The wire discriminator. Each subclass fixes it to its own snake_case literal, like\n`\"move_party\"` or `\"open_door\"`, so you never set it yourself: constructing the subclass\ndoes. It's what `parse_command` and the\n`AnyCommand` union read to rebuild the right class\nfrom a serialized mapping, and it stays the same across releases."
    },
    "source": {
      "anyOf": [
        {
          "minLength": 1,
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Source",
      "description": "An annotation naming the authored object (a trigger or quest id) or the game\nsystem on whose behalf the command was issued. Execution never reads it: a stamped\ncommand does exactly what the same command unstamped does. It is logged and replayed\nwith the command, so the log alone answers \"why did this happen\". Absent is `None`,\nand the empty string is not a value."
    },
    "character_id": {
      "title": "Character Id",
      "type": "string",
      "description": "The member using the item, by `MemberView.id`. They\nhave to be carrying it, and for a device their class has to be able to use it."
    },
    "item_id": {
      "title": "Item Id",
      "type": "string",
      "description": "The magic item to use, by its per-instance id from\n`MemberView.inventory`. Only magic items are\nusable here, so a mundane item comes back as `exploration.item.not_carried`: the member\ncarries no magic item with that id."
    },
    "target_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Target Id",
      "description": "Who the item is used on, for an item that reaches somebody: a party member's id for a\ntouch, or an encounter group's\n`EncounterGroupView.id` for a device that\ncovers an area. Leave it `None` for a potion the user drinks."
    },
    "spell_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Spell Id",
      "description": "Which spell to read off a scroll that has more than one, from\n`load_spells` (see the spell id index). Leave it\n`None` for anything that isn't a scroll."
    },
    "mode": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Mode",
      "description": "Which of the read spell's usages to cast, by that usage's\n`SpellMode.key`. `None` casts the spell's first usage,\nwhich is what a single-usage scroll wants."
    },
    "targets": {
      "default": [],
      "items": {
        "type": "string"
      },
      "title": "Targets",
      "type": "array",
      "description": "The read spell's targets, named exactly as in\n`CastSpell.targets`. When it's empty `target_id`\nstands in as the single target, so a one-target scroll needs only the one field."
    }
  },
  "required": [
    "character_id",
    "item_id"
  ],
  "title": "UseItem",
  "type": "object"
}