UseItem
Use a magic item: drink a potion, read a scroll, or activate a wand, staff, or rod (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, or activate a wand, staff, or rod (one round).\n\nIt's legal while exploring and during an encounter. In battle, use an item with a\n`use_item` `BattleDeclaration` instead. Name the\nmember in `character_id` and the item in `item_id`. Using an item identifies it and reveals\nany curse. A magic sword that can light up when its wielder says so turns its light on or off.\n\nA device is a wand, a staff, or a rod. `target_id` is the id of whoever the item is used on:\nthe party member who drinks a potion, a party member for a staff of healing's touch, or an\nencounter group for a device that covers an area. When the member reads a scroll with several\nspells on it, choose the spell and its targets with `spell_id`, `mode`, and `targets`. They\nwork like the same fields of `CastSpell`.\n\nA device whose powers the session doesn't resolve, like a staff of commanding, spends a charge,\nand its `ItemUsedEvent` has the device's text in `manual`\nfor the referee to rule on. The staves of power and wizardry strike only in a battle, so here\na use of either one is one of their other powers, like the cone of cold, the same way. The\nstaff of striking has no other power, so the session refuses it with `items.use.battle_only`.\n\nA member can give a potion they carry to another member to drink. The use is the carrier's,\nand so is the round it takes. The potion's effect lands on the drinker. Outside a battle the\nparty stands together, so any member can reach any other.\n\nA scroll casts its spell at the lowest level that can cast it, whatever the reader's level.\nThe session checks the read at that level. For example, a *magic missile* scroll fires one\nmissile, so it takes one target, even when a 6th-level magic-user reads it. The session\nrefuses a read before it uses up the scroll.\n\nModes:\n `exploring`, `encounter`\n\nRejections:\n Any item:\n\n - `session.command.wrong_mode` - the session is in town or in battle, or has\n ended.\n - `session.command.unknown_member` - `character_id` matches no party member.\n - `session.command.member_incapacitated` - the member can't 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 use, or the member's class can't\n use the device.\n\n By kind of item:\n\n - Potions: `items.use.target_not_allowed` when `target_id` isn't a party member's\n id, and `items.use.target_cannot_drink` when it's the id of a member who is dead or\n turned to stone. A member who is asleep or paralysed can be given a potion to drink.\n - Scrolls: `exploration.action.requires_light` (reading needs light, and\n infravision isn't enough), `items.scroll.spent`, `items.scroll.no_such_spell`,\n and `items.scroll.wrong_caster`. A read also gets the checks of a cast, at the\n scroll's level: `magic.cast.unknown_target`, `magic.cast.unknown_mode`,\n `magic.cast.target_count`, `magic.cast.target_must_be_creature`,\n `magic.cast.out_of_range`, `magic.cast.caster_incapacitated`,\n `magic.cast.caster_restrained`, and `magic.cast.anti_magic_shell`.\n - Devices: `items.device.inert` (no charges left),\n `items.use.target_required` (an area device used in an encounter needs a\n `target_id`), `items.use.unknown_target`, `items.use.target_cannot_be_healed` (a\n staff of healing used on a creature that's dead or turned to stone), and\n `items.use.battle_only` (a staff whose only power is its strike, like the staff of\n striking, works only as a battle declaration).\n\nEvents:\n `ItemIdentifiedEvent`, and\n `CurseRevealedEvent` for a cursed item,\n the first time the item is used. An\n `ItemUsedEvent` records what happened:\n a potion drunk, potions mixed, a scroll read, a device activated, or a cursed\n scroll's curse. The events of the item's effect follow: healing, saving throws,\n damage, effects attached, and a scroll's\n `SpellCastEvent`, each a separate event. While\n exploring, one round passes. During an encounter, the encounter round's events\n follow instead. During a pursuit, a `PursuitEvent`\n round follows, because the party keeps running.",
"properties": {
"command_type": {
"const": "use_item",
"default": "use_item",
"title": "Command Type",
"type": "string",
"description": "The name that identifies the command class in serialized data. Each command class fixes\nit to a distinct snake_case string, like `\"move_party\"` or `\"open_door\"`, and constructing\nthe class sets it, so you never pass it yourself.\n`parse_command` and the\n`AnyCommand` union use it to rebuild the right class\nfrom a serialized mapping. A class's value never changes between releases."
},
"source": {
"anyOf": [
{
"minLength": 1,
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Source",
"description": "Who or what issued the command on whose behalf: an authored trigger or quest id, or the\nname of one of your game's systems. The engine never reads it, so a command with a\n`source` does exactly what the same command without one does. The session logs and\nreplays it with the command, so the log alone shows why something happened. Leave it\n`None` when there's nothing to record. An empty string fails validation when the command\nis constructed."
},
"character_id": {
"title": "Character Id",
"type": "string",
"description": "The member using the item, by `MemberView.id`. The\nmember has to carry the item, and for a wand, staff, or rod, the member's class has to be\nable 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 can be\nused with this command, so the session refuses a mundane item's id with\n`exploration.item.not_carried`."
},
"target_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Target Id",
"description": "Who the item is used on, for a potion or a device: a wand, a staff, or a rod.\n\nFor a potion, pass the id of the party member who drinks it. The member in `character_id`\ngives it to them, and the potion's effect lands on them. Leave it `None`, or pass\n`character_id`, and the member who uses the potion drinks it. The session refuses an id that\nisn't a party member's with `items.use.target_not_allowed`, and a member who is dead or turned\nto stone with `items.use.target_cannot_drink`.\n\nFor a device, pass a party member's id for a device that heals by touch, or an encounter\ngroup's `EncounterGroupView.id` for a device that\ncovers an area. A healing device with `None` heals the member using it. The session refuses a\nhealing device on a creature that's dead or turned to stone with\n`items.use.target_cannot_be_healed`."
},
"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, by its id (see the\n[spell id index](https://mmacy.github.io/osrlib-python/reference/content-ids/spells/)).\n`None` reads the first spell left on the scroll. Leave it `None` for anything that isn't a\nscroll."
},
"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 right for a spell with one usage."
},
"targets": {
"default": [],
"items": {
"type": "string"
},
"title": "Targets",
"type": "array",
"description": "The read spell's targets, named as in\n`CastSpell.targets`. When it's empty, `target_id`\nis the single target, so a scroll spell with one target needs only `target_id`."
}
},
"required": [
"character_id",
"item_id"
],
"title": "UseItem",
"type": "object"
}