> ## Documentation Index
> Fetch the complete documentation index at: https://items.lodemc.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Events and actions

> Run commands, messages, effects and sounds when an item, block or prop is used.

Any item, block or prop can have `events:`. Each event lists actions to run when it happens.

```yaml theme={null}
magic_wand:
  material: blaze_rod
  texture: wand.png
  events:
    right-click:
      - "[sound] entity.blaze.shoot 1 1.2"
      - "[particle] flame 20"
      - "[launch] 1.5"
```

## Options

The short form is just a list of actions. For more control, use a section:

```yaml theme={null}
events:
  right-click:
    cooldown: 3s
    cooldown-message: "<red>Not yet!"
    conditions: ["permission:myserver.vip", "!sneaking", "chance:0.5"]
    consume: 1                       # items used up from the stack each time
    actions:
      - "[effect] speed 5s 2"
      - "[delay] 1s"
      - "[console] give <player> diamond"
```

## Events

**While holding or using the item:**

| Event | When |
| - | - |
| `right-click`, `right-click-air`, `right-click-block` | Right-click, anywhere / at the air / on a block. |
| `left-click`, `left-click-air`, `left-click-block` | The same for left-click. |
| `attack` | Hitting a mob or player with it. |
| `kill` | Killing a mob or player with it. |
| `mine` | Breaking a block with it. |
| `consume` | Eating or drinking it. |
| `drop`, `pickup` | Dropping or picking it up. |
| `equip`, `unequip` | Putting it on or taking it off as armour. |
| `item-break` | It runs out of durability. |
| `hold` | Switching to it in the hotbar. |
| `inventory-click` | Clicking it in an inventory. |
| `death` | The holder dies. |

**For placed blocks and furniture:**

| Event | When |
| - | - |
| `interact` | A player right-clicks it. |
| `place` | It is placed. |
| `break` | It is broken. |

## Actions

Each action is `[type]` followed by its arguments.

| Action | Example | Does |
| - | - | - |
| `[message]` | `[message] <green>Hello <player>` | Chat message to the player. |
| `[broadcast]` | `[broadcast] <gold><player> found a ruby!` | Chat message to everyone. |
| `[actionbar]` | `[actionbar] <red>Charged` | Action bar text. |
| `[title]` | `[title] <gold>Victory \| <gray>well played` | Title and subtitle, split by `\|`. |
| `[console]` | `[console] give <player> diamond` | Command run by the console. |
| `[player]` | `[player] spawn` | Command run by the player. |
| `[op]` | `[op] gamemode creative` | Command run by the player **with op** for that one command. Be careful what you put here. |
| `[sound]` | `[sound] entity.player.levelup 1 1.5` | Sound, with optional volume and pitch. |
| `[effect]` | `[effect] speed 10s 2` | Potion effect: name, duration (default 5s), level. |
| `[remove-effect]` | `[remove-effect] poison` | Removes an effect. |
| `[heal]` | `[heal] 4` | Heals this much health (2 = one heart). |
| `[feed]` | `[feed] 6` | Fills hunger. |
| `[damage]` | `[damage] 2` | Hurts the player. |
| `[give]` | `[give] lodeitems:ruby 2` | Gives an item (LodeItems or vanilla). |
| `[particle]` | `[particle] heart 5` | Particles, with an optional count. |
| `[launch]` | `[launch] 1.5` | Pushes the player the way they're looking. |
| `[xp]` | `[xp] 50` | Gives experience points. |
| `[dialog]` | `[dialog] rules` | Opens one of your [dialogs](https://items.lodemc.net/translations-and-dialogs.md#dialogs). |
| `[close]` | `[close]` | Closes the open inventory. |
| `[delay]` | `[delay] 1s` | Waits before running the actions after it. |
| `[lode-skill]` | `[lode-skill] lightning_strike power=3` | Runs a [LodeEntities](https://items.lodemc.net/integrations.md#lodeentities) skill, with optional values for it. |
| `[lode]` | `[lode] <effect line>` | Runs one [LodeEntities](https://items.lodemc.net/integrations.md#lodeentities) effect line. |

Effect, particle, sound, item and dialog names are checked when the config loads, so a typo shows as an error instead of failing silently later.

## Placeholders

Messages and commands can use:

| Placeholder | Is |
| - | - |
| `<player>` | The player's name. |
| `<uuid>` | The player's UUID. |
| `<world>` | The world name. |
| `<x>` `<y>` `<z>` | Where it happened. |
| `<target>` | The mob or player that was hit or killed. |

With [PlaceholderAPI](https://items.lodemc.net/integrations.md#placeholderapi) installed, `%placeholders%` work too.

## Conditions

All conditions have to be true for the actions to run. Put `!` in front of one to turn it around.

| Condition | True when |
| - | - |
| `permission:<node>` | The player has the permission. |
| `world:<name>` | In that world. |
| `gamemode:<mode>` | In that game mode: `survival`, `creative`, `adventure`, `spectator`. |
| `chance:<0-1>` | Random: `chance:0.25` is one time in four. |
| `sneaking` | The player is sneaking. |
| `sprinting` | The player is sprinting. |
| `flying` | The player is flying or gliding. |
| `day`, `night` | Time of day. |
| `raining` | It is raining or storming. |
| `in-water` | The player is in water. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.