# 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.

```yaml
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.

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

#### Message

Send a message to the inventory viewer.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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.

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

#### Update paginations

Trigger an update of the paginations in an opened inventory.

```yaml
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.

<pre class="language-yaml"><code class="lang-yaml"><strong>actions:
</strong>    # Action name.
  - action: "OPEN_INVENTORY"
    # The id of the inventory to open.
    inventory-id: "&#x3C;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: &#x3C;true|false>
</code></pre>

#### Home

Open the root inventory in the viewer's history.

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

#### Backward

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

```yaml
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.

```yaml
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.

```yaml
# 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:**

<pre class="language-yaml"><code class="lang-yaml"><strong>actions:  
</strong>  - 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"
</code></pre>