# Custom Mechanic

## How does it work?

This mechanic is for items only and does not work with blocks/furniture.\
For that check the [clickAction mechanic](/mechanics/clickaction-mechanic.md). The mechanics let you create subsections composed of 3 parts:

* **Event**: when is this mechanic triggered? e.g. when you right-click on a block
* **Conditions**: a set of conditions that must be satisfied. e.g. having a permission
* **Actions**: a set of actions to perform. e.g. send a command or a message

{% hint style="info" %}
An optional settings called one\_usage allows you to imitate the use of an item at 1.
{% endhint %}

## A comprehensive example

```yaml
myitem:
  Mechanics:
    custom:
      test:
        one_usage: false
        event: "CLICK:right:all"
        conditions:
          - '#player.hasPermission("example.permission")'
        actions:
          - "[console] give <player> cooked_beef 1"
```

In this example, the subsection `test` defines a custom mechanic triggered when someone right click (on a block or in the air).\
If this player has the permission `example.permission`, the console will perform the give command and replace \<player> by the player name.\
The item won't be consumed (one\_usage: false).

## Available events

### CLICK:click\_type:target\_type[^1],

### INV\_CLICK:click\_type:context\_type[^2]

### DROP[^3], PICKUP[^4], BREAK[^5], EQUIP[^6], UNEQUIP[^7], INV\_CLICK[^8], DEATH[^9], DROP\_ALL[^10]

## Available conditions

### Permission-Condition

```yaml
myitem:
  Mechanics:
    custom:
      mycustom:
        conditions:
          - "HAS_PERMISSION:some.permission"
```

## Available actions

### Command-Action

This action lets you run a command either from console or as the player

```yaml
myitem:
  Mechanics:
    custom:
      mycustom:
        event: "CLICK:right:all"
        actions:
          - "[console] minecraft:give <player> minecraft:paper 2"
          - "[player] minecraft:give <player> minecraft:paper 2"
```

### Message-Action

```yaml
myitem:
  Mechanics:
    custom:
      mycustom:
        event: "CLICK:right:all"
        actions:
          - "[message] <red>some message <gradient:red:blue>with MiniMessage support"
```

### ActionBar-Action

```yaml
myitem:
  Mechanics:
    custom:
      mycustom:
        event: "CLICK:right:all"
        actions:
          - "[actionbar] <red>some message <gradient:red:blue>with MiniMessage support"
```

### Sound-Action

This action lets you play a sound at a location or at a target with customizable values

**source -** The source of the sound ([List of sources](https://jd.advntr.dev/api/4.21.0/net/kyori/adventure/sound/Sound.Source.html))\
**volume** - The volume to play the sound with\
**pitch** - The pitch to play the sound with\
**self** - If the sound sound be played at the Player and not at a location

Followed by the sound-key to play

```yaml
myitem:
  Mechanics:
    custom:
      mycustom:
        event: "CLICK:right:all"
        actions:
          - "{source=AMBIENT volume=0.1 pitch=1} [sound] namespace:soundkey"
```

[^1]: Called when you click with the item.\
    \
    If either of the below is unspecified, it will default to "all" handling\\

    **mouse\_click\_type**: `[ right, left, all ]`\
    **target\_type**: `[ block, air, all ]`

[^2]: Called when you click an item in a GUI.\
    \
    If either of the below is unspecified, it will default to "all" handling\\

    **click\_type**: `[ right, left, all ]`\
    **context\_type**:

    `[ shift, all ]`

[^3]: Called when you drop the item.

[^4]: Called when you pick up the item.

[^5]: Called when a player breaks an item.

[^6]: Called when a player equips an item.

[^7]: Called when a player unequips an item.

[^8]: Called when a player clicks an item in an inventory.

[^9]: Called when a player dies and would normally drop the given item.

[^10]: Called when a player drops an item and no longer has any similar items in their inventory.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nexomc.com/mechanics/custom-mechanic.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.