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 the inventory configuration, each action is declared in a subsection of the actions section of an item.

# Global item section.
# You can use the name your want, but explicit names are encouraged.
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 configuration section.
    # You can use the name your want, but explicit names are encouraged.
    close:
      # Action type.
      # It is required to identify and load the corresponding action.
      type: "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.

close:
  # Action type.
  type: "CLOSE"

Message

Send a message to the inventory viewer.

message:
  # Action type.
  type: "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.

# Broadcast messages in the chat.
broadcast:
  # Action type.
  type: "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.

player-command:
  # Action type.
  type: "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.

console-command:
  # Action type.
  type: "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.

sound:
  # Action type.
  type: "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.

update-content:
  # Action type.
  type: "UPDATE_CONTENT"

Update paginations

Trigger an update of the paginations in an opened inventory.

update-paginations:
  # Action type.
  type: "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.

open-inventory:
  # Action type.
  type: "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.

home:
  # Action type.
  type: "HOME"

Backward

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

backward:
  # Action type.
  type: "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.

forward:
  # The action type.
  type: "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
# - ALL: All clicks
# You can use a combination of the above values.
# When this property is note set, the ALL value is used by default.
click-types:
  - "LEFT"
  - "RIGHT"

Example:

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