Skip to content

GrantItem

Referee: put an item straight into a member's pack.

Full documentation: GrantItem. Wire type: grant_item.

Legal session modes: battle, encounter, exploring, game_over, town, victory

JSON Schema

{
  "description": "Referee: put an item straight into a member's pack.\n\nUse it to hand out a reward, a found item, a starting kit, or a potion the party buys\nfrom a shop your game runs. The command charges nothing. To charge a price, also send\n`RemoveCoins`. This command is legal in every mode,\n`game_over` and `victory` included.\n\nThe session creates a magic item the same way it creates treasure. The item arrives\nunidentified.\n`instantiate_magic_item` rolls whatever the\nitem's page leaves to chance, like a wand's charges, on\n`TREASURE_STREAM`. A mundane grant makes no draws.\n\nModes:\n    `town`, `exploring`, `encounter`, `battle`, `game_over`, `victory`\n\nRejections:\n    - `session.command.unknown_member` - `character_id` matches no party member.\n    - `session.command.unknown_item` - `item_id` matches no item in the session's\n      `effective_equipment`\n      catalog or the magic item catalog.\n\nEvents:\n    `ItemAcquiredEvent` with `origin`\n    `\"grant\"`. Its `item_ids` list a mundane item's catalog id once for each unit, and\n    each new magic item's instance id.",
  "properties": {
    "command_type": {
      "const": "grant_item",
      "default": "grant_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 who receives the item, by\n`MemberView.id`. A command you issue yourself has a\nmember id here, and the session refuses any other value with `session.command.unknown_member`.\nA consequence or a reward in an adventure document has a party selector instead,\n`\"@party\"` for every living member or `\"@first\"` for the first living member, because the\nsession assigns member ids when it starts. The trigger and quest interpreter replaces the selector\nwith member ids before it issues the command."
    },
    "item_id": {
      "title": "Item Id",
      "type": "string",
      "description": "Which item to create, by id. The session looks first in its\n`effective_equipment` catalog. That\ncatalog has the built-in ids from `load_equipment` (see the\n[equipment id index](https://mmacy.github.io/osrlib-python/reference/content-ids/equipment/))\nand the ids the adventure bundles. Then it looks in the magic item catalog from\n`load_magic_items` (see the\n[magic item id index](https://mmacy.github.io/osrlib-python/reference/content-ids/magic-items/))."
    },
    "quantity": {
      "default": 1,
      "minimum": 1,
      "title": "Quantity",
      "type": "integer",
      "description": "How many to place, counted as single items rather than as purchase lots.\n`quantity=6` grants six torches, the same number one lot of torches from\n`PurchaseEquipment` delivers. For a magic\nitem, it's the number of separate magic items to create, each with its own instance id\nand its own rolls. `quantity=2` of a bundle of arrows +1 grants two bundles."
    }
  },
  "required": [
    "character_id",
    "item_id"
  ],
  "title": "GrantItem",
  "type": "object"
}