Item actions

This page describes how to configure item actions.

What is an action?

In CraftVentory, an item action is a behavior executed when a player clicks on an item. An item may have as many actions as you want.

Item actions are fully configurable and each action has its own set of customizable properties. In an item configuration, actions are declared as a list in the actions property.

close:
  # Item configuration section.
  # See the 'Item configuration' chapter of this tutorial.
  item:
    type: BARRIER
  # Symbol of the item to place it in the inventory.
  symbol: "C"
  # Set of actions executed when a player clicks on the item.
  actions:
      # Action name.
    - action: "CLOSE"
      # Additionnal properties may be listed below depending on the action.

Available actions

In the list below, you can find all the actions provided by default by the library.

Close

Close the opened inventory.

actions:
    # Action name.
  - action: "CLOSE"

Message

Send a message to the inventory viewer.

actions:
    # Action name.
  - action: "MESSAGE"
    # List of messages to send.
    # Features supported:
    # - Placeholders
    # - Color codes prefixed by the character '&' (ex: &e)
    # - Hexadecimal color codes prefixed by the character '#' (ex: #FFFFFF)
    messages: 
      - "message 1"
      - "message 2"
      - "message 3"

Broadcast

Broadcast a message in the chat.

actions:
    # Action name.
  - action: "BROADCAST"
    # List of messages to broadcast.
    # Features supported:
    # - Placeholders
    # - Color codes prefixed by the character '&' (ex: &e)
    # - Hexadecimal color codes prefixed by the character '#' (ex: #FFFFFF)
    messages:
      - "message 1"
      - "message 2"
      - "message 3"

Player command

Make the inventory viewer execute a list of commands.

actions:
    # Action name.
  - action: "PLAYER_COMMAND"
    # List of commands to execute without slash.
    # Supported placeholders:
    # - %player_name%: Name of the player who executes the action.
    # - %player_uuid%: UUID of the player who executes the action.
    commands: 
      - "command_1"
      - "command 2 arg1"
      - "command 3 arg1 arg2 arg3"

Console command

When performed, this action makes the server execute a command.

actions:
    # Action name.
  - action: "CONSOLE_COMMAND"
    # List of commands to execute without slash.
    # Supported placeholders:
    # - %player_name%: Name of the player who executes the action.
    # - %player_uuid%: UUID of the player who executes the action.
    commands: 
      - "command_1"
      - "command 2 arg1"
      - "command 3 arg1 arg2 arg3"

Sound

Play a sound to the inventory viewer.

actions:
    # Action name.
  - action: "SOUND"
    # Sound name to play.
    sound: "<name>"
    # How far the sound can be heard.
    volume: <float>
    # How fast the sound is played.
    pitch: <float>

Update content

Trigger an update of the content of an opened inventory.

actions:
    # Action name.
  - action: "UPDATE_CONTENT"

Update paginations

Trigger an update of the paginations in an opened inventory.

actions:
    # Action name.
  - action: "UPDATE_PAGINATIONS"
    # The ids of the paginations to update.
    pagination-ids:
      - <pagination-id-1>
      - <pagination-id-2>
      - <pagination-id-3>

Open inventory

Open a new inventory.

actions:
    # Action name.
  - action: "OPEN_INVENTORY"
    # The id of the inventory to open.
    inventory-id: "<id>"
    # If true, a new history will be created for the inventory.
    # If false, the inventory will be appended at the end of it. 
    new-history: <true|false>

Home

Open the root inventory in the viewer's history.

actions:
    # Action name.
  - action: "HOME"

Backward

Open a previously opened inventory in the history which is before the current one in the history.

actions:
    # Action name.
  - action: "BACKWARD"
    # This property is optional. When set, the action opens the previously opened inventory before the current
    # one which has the specified id. When not set, the inventory just before the current one in the history is opened.
    inventory-id: ""

Forward

Open a previously opened inventory in the history which is after the current one in the history.

actions:
    # The action name.
  - action: "FORWARD"
    # This property is optional. When set, the action opens the previously opened inventory after the current
    # one which has the specified id. When not set, the inventory just after the current one in the history is opened.
    inventory-id: ""

Click type

CraftVentory enables to configure the type of click a user must do to execute an action by adding the click-types property.

# List of click types to execute the action.
# Allowed click types:
# - LEFT: Left click
# - RIGHT: Right click
# - MIDDLE: Middle click
# You can use a combination of the above values.
# When this property is not set, all the click types are allowed.
click-types:
  - "LEFT"
  - "RIGHT"

Example:

actions:  
  - action: "MESSAGE"
    click-types:
      - "LEFT"
    messages: 
      - "left click"
      
  - action: "MESSAGE"
    click-types:
      - "RIGHT"
    messages: 
      - "right click"
  
  - action: "MESSAGE"
    click-types:
      - "MIDDLE"
    messages: 
      - "middle click"
      
  - action: "MESSAGE"
    messages: 
      - "message sent for each click"