3.3 Action

There are five options which are directly related to actions:

• Action
• PrimaryAction
• SecondaryAction
• PrimaryShiftAction
• SecondaryShiftAction

Action

The value of the option determines what will happen when a player clicks an item. For example:

Action {
  Command = "cost: 10; console: give %player_name% minecraft:wheat 9"
  KeepInventoryOpen = true
}

The KeepInventoryOpen option determines if the inventory will be closed immediately after the target player clicks the item. The default value is false.

The Command option defines several actions which will be done orderly. The actions are separated by semicolons (;) and in the example shown above, there are two actions: cost: 10, and console: give %player_name% minecraft:wheat 9. The Command option supports PlaceholderAPI, and the %player_name% will be replaced by the name of the player who clicks the item.

An action in the Command option can have a prefix, and different prefixes represents different action types. The prefix and the main part of the action are separated by a colon (:). Please refer to Available Action Prefixes.

There is another option which is not in the example shown above: HandheldItem. HandheldItem specifies the type and quantity of items which should be held in the mouse cursor. For example:

PrimaryAction {
  Command = "cost-item: 9; cost: -8"
  HandheldItem {
    ItemType = "minecraft:wheat"
    UnsafeDamage = 0
    Count = 9
  }
  KeepInventoryOpen = true
}

It rules that the player must hold at least 9 wheats to click the item in order to trigger actions. The UnsafeDamage option is not required, and if it is absent, it means that any meta matches. This feature is often used to make chest shop menus, in which a player can hold something for selling them.

The value of PrimaryAction could also be a list rather than an object. If it is a list, elements of the list will be used to match items in order by identifing their HandheldItems. For example:

PrimaryAction = [{
  Command = "cost-item: 9; cost: -8"
  HandheldItem {
    ItemType = "minecraft:wheat"
    UnsafeDamage = 0
    Count = 9
  }
  KeepInventoryOpen = true
}, {
  Command = "cost-item: 1; cost: -8"
  HandheldItem {
    ItemType = "minecraft:hay_block"
    UnsafeDamage = 0
    Count = 1
  }
  KeepInventoryOpen = true
}]

Not only wheats but also hay bales could be identified if players click the slot with any of two items held in the mouse cursor.

For more information about HandheldItems, please refer to Identifing Items.

PrimaryAction and SecondaryAction

PrimaryAction and SecondaryAction are both similar to Action, but they will only be triggered when the player clicks the left or right button respectively. In common cases, PrimaryAction corresponds to left button while SecondaryAction corresponds to right button. If not set, either PrimaryAction or SecondaryAction will behave the same as Action.

PrimaryShiftAction and SecondaryShiftAction

PrimaryShiftAction and SecondaryShiftAction are similar to PrimaryAction and SecondaryAction respectively, but they will be trigger when target players click the item with their shift key pressed. If not set, PrimaryShiftAction will behave the same as PrimaryAction (or Action if PrimaryAction is also not set), and correspondingly, SecondaryShiftAction will behave the same as SecondaryAction (or Action if SecondaryAction is also not set).