Items

Making items do things

actions: makes an item do something when it is used: play a sound, send a message, give an effect, run a command. You pick a trigger (such as a right-click) and list the steps to run, in order. Placed models and custom blocks take the same actions:.

wand:
  material: STICK
  model: wand
  actions:
    right_click:
      - cooldown: 5
      - message: "&bWhoosh."
      - sound: mypack:chime
      - effect: SPEED 10 2
      - console: "effect give {player} minecraft:levitation 3"

Each step is one key with its own -.

One key per dash

Two keys in one list entry means a dash is missing. YAML accepts it, so RP Engine reports it as a load error naming both keys, and that step is skipped.

Triggers#

Trigger	When
`right_click`	Right-clicked, on a block or in the air
`left_click`	Left-clicked
`attack`	Used to hit an entity
`consume`	Eaten or drunk
`drop`	Dropped
`pickup`	Picked up off the ground
`block_break`	Used to break a block
`shoot`	Shot, for a bow or crossbow
`break`	Ran out of durability
`place`	Put down, as a placed model or a custom block
`interact`	Right-clicked where it stands, as a placed model or a custom block
`remove`	Punched out or mined by a player, as a placed model or a custom block

break runs after the item is already gone, so it cannot be cancelled. It is still useful for a sound or a message.

There is no trigger for putting armour on or taking it off, and none for a player joining the server. For something on join, have a join-command plugin run the /rp command you want.

The thing in the world#

place, interact and remove are about a placed model or custom block standing in the world, rather than the item in someone's hand. A doorbell:

doorbell:
  material: PAPER
  model: doorbell
  place: { surface: wall }
  actions:
    interact:
      - cooldown: 2
      - sound: minecraft:block.bell.use
      - console: "say {player} is at the door"

A custom block takes the same actions: in its own definition.
On interact, cancel stops what the click would otherwise do: nobody sits, nothing opens, and nothing is placed against the block.
place and remove run once the piece is down or gone, so they cannot be cancelled.
take does nothing in these three, because the click is on the piece, not the item in the player's hand.
On an item with no place: block, these triggers are a load warning, since they can never fire.

Steps#

Step	What it does
`message`	A line of chat to whoever used it. `&` colour codes
`broadcast`	The same, to everybody
`actionbar`	A line above their hotbar
`console`	Runs a command as the console
`run`	Runs a command as the player, with their own permissions
`sound`	`mypack:chime`, or a vanilla key like `minecraft:block.anvil.land`. Optional volume and pitch after it
`effect`	`SPEED 10 2`: type, seconds, level. Level 1 is the first level
`particle`	`flame 12 0.3`: type, count, spread. See below
`give`	`mypack:ruby 3`. What will not fit drops on the floor
`take`	Takes this many off the stack
`cancel`	Cancels the item's vanilla use
`cooldown`	Seconds. Stops the rest of the list if it has not been that long
`permission`	Stops the rest of the list unless the player has this permission
`dialog`	`mypack:menu`, then any `name=value` pairs. Opens a dialog for the player. Needs Minecraft 1.21.6

console or run. console can do things the player is not allowed to do themselves. run acts as the player and checks their permissions.

cooldown stops the list, so put a message before it if you want the refusal to say something:

    right_click:
      - message: "&7You steady yourself..."
      - cooldown: 30
      - message: "&bAgain!"

cancel stops the vanilla use. Without it, a wand built on a bucket still fills with water.

particle takes the game's own names, such as flame or happy_villager; names from before Minecraft 1.20.5 renamed them work too. Count defaults to 8 (up to 200) and spread to 0.3 blocks. Particles appear at the block or piece the action is about, or at the player for a held item. A particle that needs extra data, such as a colour or a block, draws nothing.

A step that cannot run is skipped and the rest still run, so a misspelled potion costs only that line.

Text#

Any text can include {player}, {uuid}, {world}, {x}, {y}, {z}, and any PlaceholderAPI placeholder if that plugin is installed.

      - broadcast: "&e{player} found the shrine at {x} {y} {z}"

Going further#

Actions have no conditions, variables or branching, and that is deliberate. For anything more, write a small plugin that listens for ItemUseEvent, which carries the item ID, the stack, the click and the block. Cancelling that event cancels the vanilla use and stops the item's own actions running.