Handlers and Actions

This page is for advanced users. If you're just getting started, we recommend that you use the in-game GUI to create your item! Just type /cui create <item name> to get started!

What are Handlers and Actions?

Handlers and actions are a way of telling your item to do something (run an action) when something happens with the item (the handler). For example, you could use handlers and actions to run a console command every time a player right-clicks your custom block with one of your custom items.

Handlers are things that are handled, or things that trigger actions to happen, like rightClickAir — when a player right clicks air with this item, or drop — when a player drops this item, and lots more!

Actions are the things that happen when one of your handlers gets triggered. For example, sendMessage — send the player a message, consoleRunCommand — run a command from the console, or damageItemUsed — damage the item the player used, and many many more!

Conditions are ways of making sure certain conditions are met before an action runs. For example, ifHasPermission — if the player has the given permission, ifSneaking — if the player is sneaking, and so many more! You can even use Operators in conditions

You can use {placeholders} to tell the plugin to insert information somewhere. For example, {player.name} is replaced with the player's name, and {player.location.world} is replaced with the world the player is currently in.

There's also Special action parameters that let you do things like give actions a certain chance of running (like, make this action run 10% of the time, and make this one run 90% of the time), or giving actions a cooldown (like, only let this action happen every 10 minutes).

Lastly, you can use Variables and Globals to store information on items (or globally). For example, you could use variables to store how many times the player has hit a creeper with your custom sword, and then reward them once they've hit 100 creepers by running an action that gives them a diamond! You could use globals to make a quest book that gives players a gold ingot for every 10 wood they mine with your custom pickaxe.

You can read more about how you format Handlers, Actions, and Conditions in your item yml files by reading below! There's also a long list of all of the possible handlers, actions, and conditions you can use, which you can scan through to find what you're looking for!

If you want to reference an item (to drop an item, give a player an item, etc.) that isn't a default Minecraft material or CustomItem, just install ItemBridge on your server!

Make sure you read the examples below to get a good grasp of how to write your own handlers, actions, and conditions!

Handlers

The handler is what should happen for your actions to run. For example, we could use the handler rightClickAir to run actions when a player right-clicks air

handlers:
  rightClickAir: # when a player right-clicks air with this item
    actions: # run these actions 
      - # make sure everything is indented correctly!
        action: # ... (there's a list of possible actions below)
        # the rest of action 1 ...
      -
        action: # ...
        # the rest of action 2 ...

List of handlers

The handler is what should happen for your actions to run.

Handler Name	Alias	Uses	Description
blockBreak	breakBlock	For Blocks Only	When a player breaks this block
blockHit	hitBlock	For Blocks Only	When a player hits this block
blockInteract	interactBlock , interactWithBlock	For Blocks Only	When a player interacts with this block (right-clicks it)
blockPlace	placeBlock	For Blocks Only	When a player places this block
blockStep	stepOnBlock	For Blocks Only	When a player steps onto this block (called only when they switch to a new block)
bowShoot	shootBow	For Bow Only	When a player shoots this bow
projectileShoot	shoot	Arrow Only As of 3.8.1 also supports eggs, snowballs, ender pearls	When a player shoots this projectile
projectileHitBlock		Arrow Only As of 3.8.1 also supports eggs, snowballs, ender pearls	When this projectile hits a block
projectileHitMob	projectileHitLivingEntity	Arrow Only As of 3.8.1 also supports eggs, snowballs, ender pearls	When this projectile hits a mob
projectileHitPlayer		Arrow Only As of 3.8.1 also supports eggs, snowballs, ender pearls	When this projectile hits a player
consume	eat , consumed		When a player eats this item
craft	crafted		When a player crafts this item
drop	dropped		When a player drops this item
hitMob	hitEntity , hitLivingEntity		When a player hits a mob with this item
hitPlayer	leftClickPlayer		When a player hits another player with this item
inMainHand	inPlayerMainHand , inHand , inPlayerHand	Check below for Interval	While item is in a player's main hand
inInventory	inPlayerInventory	Check below for Interval	While item is in a player's inventory
inOffHand	inPlayerOffHand	Check below for Interval	While item is in a player's off hand (Shield slot)
itemBreak			When this item breaks after all durability is gone
itemDamage			When this item is damaged by being used
leftClick	leftClicks		When a player hits air or block with this item. Actions in this handler will happen BEFORE the actions in leftClickAir and leftClickBlock
leftClickAir			When a player hits air with this item
leftClickBlock			When a player hits a block with this item
mine			When a player mines a block with this item
itemPickUp	pickUp		When a player picks up this item
rightClick	rightClicks		When a player right-clicks air or block with this item. Actions in this handler will happen BEFORE the actions in rightClickAir and rightClickBlock
rightClickAir			When a player right-clicks air with this item
rightClickBlock			When a player right-clicks a block with this item
rightClickEntity	rightClickMob		When a player right-clicks a mob with this item
rightClickPlayer			When a player right-clicks another player with this item
slayMob	killMob , killEntity , slayEntity		When a player slays a mob using this item
slayPlayer	killPlayer		When a player slays a player using this item
shearEntity	shearMob		When a player shears a mob (like a sheep or mooshroom) with this item in their hand
wearing	playerWearing	Check below for Interval	While a player is wearing this item

inMainHand

Actions under this trigger will happen every tick while the player has the item in their main hand. If you want to change how often it happens, you could set interval either above your actions or inside one of your actions.

Example

handlers:
  inMainHand:
    interval:  10 #run once every 10 ticks (every ½ of a second). This is 1 tick (1/20 of a second) by default
    actions: # run these actions 
      - # make sure everything is indented correctly!
        action: sendMessage
        message:  "You'll get this message every half second!"
      -
        interval:  5  # run this action every 5th time the handler runs (on every 5th handler interval, or 10 * 5 = 50 ticks = 2.5 seconds
        action: sendMessage
        message:  "&cYou'll get this message every 2.5 seconds!"

inOffHand

Actions under this trigger will happen every tick while the player has the item in their OFF hand. If you want to change how often it happens, you could set interval either above your actions or inside one of your actions.

Example

handlers:
  inOffHand:
    interval:  20 #run once every 20 ticks (every second). This is 1 tick (1/20 of a second) by default
    actions: # run these actions 
      - # make sure everything is indented correctly!
        action: sendMessage
        message:  "You'll get this message every half second!"
      -
        interval:  5  # run this action every 5th time the handler runs (on every 5th handler interval, or 10 * 5 = 50 ticks = 2.5 seconds
        action: sendMessage
        message:  "&cYou'll get this message every 2.5 seconds!"

inInventory

Actions under this trigger will happen every tick while this item in the player's inventory (in their hotbar or in their storage contents). If you want to change how often it happens, you could set interval either above your actions or inside one of your actions.

Example

handlers:
  inInventory:
    interval:  400 # run once every 400 ticks (every 20 seconds second). This is 1 tick (1/20 of a second) by default
    actions: # run these actions 
      - # make sure everything is indented correctly!
        action: playerAddEffects
        effects:
          -
           type: "NIGHT_VISION"
           time: 20 # 20 seconds
           strength: 1
           particles: false

wearing

Actions under this trigger will happen every tick while the player is wearing the item. If you want to change how often it happens, you could set interval either above your actions or inside one of your actions.

Example

handlers:
  wearing:
    interval:  400 #run once every 400 ticks (every 20 seconds second). This is 1 tick (1/20 of a second) by default
    actions: # run these actions 
      - # make sure everything is indented correctly!
        action: playerAddEffects
        effects:
          -
           type: "NIGHT_VISION"
           time: 20 # 20 seconds
           strength: 1
           particles: false

If you want, you can check the slot the item is in using the ifSlot condition

Variables and Globals

Conditions and actions related to variables and globals aren't listed here. For more info about the actions, conditions, and placeholders related to variables and globals, check out the Variables and Globals page!

Conditions

Conditions are optional. For each action, you can add one or more conditions. The action will only run if your conditions are satisfied.

For example, let's make it so that when a player right-clicks air with this item (the handler rightClickAir), the first action will run only if they right-clicked a diamond block or gold block, and the second action will run only if they have the permission "customitems.action.superPlayer"

handlers:
  rightClickAir: # when a player right-clicks air with this item
    actions: # run these actions 
      -
        ifBlockTypes: # if the block type is a diamond block or a gold block
          - "minecraft:DIAMOND_BLOCK"
          - "minecraft:GOLD_BLOCK"
        action: # ...
        # ... the rest of action 1 ...
      -
        ifHasPermission: "superPlayer" # if the player has the permission customitems.action.superPlayer
        action: # ...
        # ... the rest action 2 ...

As of version 3.8 there is a new format for doing conditions, and also makes conditions way more powerful

handlers:
  rightClickAir: # when a player right-clicks air with this item
    actions: # run these actions 
     -
       if:
         playerHasPermission: "myPermission"
         targetHasPermission: "myPermission"
         if:
           playerHasPermission: "anotherPermission"
           targetHasPermission: "anotherPermission"
           combine: AND
         combine: OR
       action: sendMessage
       message: "Either the you or the target has the permission 'cui.action.myPermission', or, you both have the permission 'cui.action.anotherPermission'"

Of course, you can still use the old version of conditions, if you'd like.

List of conditions


ifGamemode	ifItemDamage (Needs Section)		ifItemEnchants	ifPlayerHasItem
ifTargetType	ifNotTargetType		ifTargetDistance	ifTargetHasItem
ifItemInHand	ifItemInOffHand
ifInRegion	ifNotInRegion	ifMemberOfRegion	ifOwnerOfRegion
ifCrawling (Needs Section)	ifFlying	ifGliding	ifSneaking	ifSwimming
ifPlayerHeadIs	ifPlayerChestIs	ifPlayerLegsAre	ifPlayerFeetAre
ifTargetHeadIs	ifTargetChestIs	ifTargetLegsAre	ifTargetFeetAre
ifHasPermission	ifHasPermissionRaw		ifNotHasPermission	ifNotHasPermissionRaw
ifTargetHasPermission	ifTargetHasPermissionRaw		ifTargetNotHasPermission	ifTargetNotHasPermissionRaw
ifWeather	ifWorldTime	ifWorld
ifPlayerEXP	ifPlayerLevel		ifTargetEXP	ifTargetLevel
ifPlayerHealth	ifPlayerFoodLevel		ifTargetHealth	ifTargetFoodLevel
ifPlayerX	ifPlayerY	ifPlayerZ	ifPlayerYaw	ifPlayerPitch
ifTargetX	ifTargetY	ifTargetZ	ifTargetYaw	ifTargetPitch
ifBlockX	ifBlockY	ifBlockZ
ifStatementCombine		invertIfResult
ifSlot	ifWearingFullSet	ifCropGrowth	ifBlockType	ifThroughBlockType

ifBlockType

Alias: ifBlockTypes
string or string list — if the block type is (one of)

ifCropGrowth

This check will always fail if the target block is not a crop decimal between 0 and 1 — is the target block's crop growth is this. For example:

ifCropGrowth: "> 0.5" % if the crop is more than 50% grown
ifCropGrowth: "<= 0.1" % if the crop is less than or equal to 10% growh
ifCropGrowth: "1" % if the crop is fully grown

ifThroughBlockType

Alias: ifThroughBlock
string or string list — if the block selected was selected through (one of) the following transparent blocks. For example, when right-clicking dirt at the bottom of water, ifBlockType will succeed if you list dirt, and ifThroughBlockType will succeed if you list water

ifHasPermission

string — if the player has the permission. Automatically prefixed with "customitems.action." For example, "useMyItem" will require the permission "customitems.action.useMyItem"

ifNotHasPermission

string — if the player doesn't have the permission. Automatically prefixed like ifHasPermission

ifHasPermissionRaw

string — if the player has the permission, not prefixed

ifNotHasPermissionRaw

*string — if the player doesn't have the permission, not prefixed

ifTargetHasPermission

string or string list — if the target entity has all of these permissions. Automatically prefixed with "customitems.action." For example, "useMyItem" will require the permission "customitems.action.useMyItem".

This will be ignored if there is no target, and will always fail if the target can't have permissions (for example, a zombie with no permissions)

ifTargetNotHasPermission

string or string list* — if the target entity doesn't have any of these permissions. Automatically prefixed like ifTargetHasPermission

This will be ignored if there is no target, and will always succeed if the target can't have permissions (for example, a zombie with no permissions)

ifTargetHasPermissionRaw

string or string list* — if the target entity has all of these permission, not prefixed

This will be ignored if there is no target, and will always fail if the target can't have permissions (for example, a zombie with no permissions)

ifTargetNotHasPermissionRaw

string or string list* — if the target entity doesn't have any of these permission, not prefixed

This will be ignored if there is no target, and will always succeed if the target can't have permissions (for example, a zombie with no permissions)

ifItemInHand

Alias: ifItemsInHand
string or string list — if the item in the player's hand is (one of)

ifItemInOffHand

Alias: ifItemsInOffHand
string or string list — if the item in the player's off hand is (one of)

ifSlot

Alias: ifSlotUsed
string or string list — if the equipment slot that was used is one of these. You can use the following slots: "HAND", "OFF_HAND", "HEAD", "CHEST", "LEGS", and "FEET". You can also use placeholders here!

ifSlot: # if this action was run by an item that is either...
  - "HEAD" # on the player's head, or...
  - "OFF_HAND" # in their off hand, or...
  - "{variable.mySlotToCheck}" # in the slot name stored in the "mySlotToCheck variable"

ifWearingFullSet

string or string list - if the player is wearing a full set of this armor category

ifPlayerHeadIs

string or string list — if the player is wearing this on their head — set this to "nothing" to require the player wears nothing in this slot

ifPlayerChestIs

string or string list — if the player is wearing this on their chest — set this to "nothing" to require the player wears nothing in this slot

ifPlayerLegsAre

string or string list — if the player is wearing this on their legs — set this to "nothing" to require the player wears nothing in this slot

ifPlayerFeetAre

string or string list — if the player is wearing this on their feet — set this to "nothing" to require the player wears nothing in this slot

ifItemEnchants

map of enchantments — if the item in the player's hand has the given enchantments. Formatted like this:

ifItemEnchants:
  # Only run if the item has the fortune enchantment at a level ABOVE 1
  "minecraft:FORTUNE": "> 1"

  # AND Only run if the item has a silk touch enchantment at a level LESS THAN OR EQUAL TO 2
  "minecraft:SILK_TOUCH": "<= 2"

  # AND Only run if the item has a sharpness enchantment at level 0 (doesn't have the enchantment)
  "minecraft:SHARPNESS": "= 0"

ifTargetDistance

string — if the player is this distance away from the target. You can use the same operators like in ifItemEnchants, like

ifTargetDistance: "< 5" # less than five blocks away

ifPlayerHealth

string — if the player has this amount of health, measured in HALF-HEARTS (20 is the normal max health). You can use the same operators like in ifItemEnchants, like

ifPlayerHealth: ">= 8" # at least 8 half-hearts (4 hearts)

ifPlayerFoodLevel

string — if the player has this food-level, measured in HALVES (20 is the normal max food level). You can use the same operators like in ** ifPlayerHealth**, like

ifPlayerFoodLevel: "< 20" # less than 20 half-hunger (anything less than the normal full hunger bar)

ifTargetHealth

string — if the target has this health, measured in HALF-HEARTS (20 is the normal max health). You can use the same operators like in ** ifPlayerHealth**

ifTargetFoodLevel

string — if the player has this food-level, measured in HALVES (20 is the normal max food level). You can use the same operators like in ifPlayerFoodLevel

ifPlayerEXP

string - if the player has this much TOTAL EXPERIENCE (doesn't reset when the player levels up). You can use the same operators like in ifPlayerHealth

ifTargetEXP

string - if the target has this much TOTAL EXPERIENCE (doesn't reset when the player levels up). You can use the same operators like in ** ifTargetHealth**

ifPlayerLevel

string - if the player has this many EXPERIENCE LEVELS. You can use the same operators like in ifPlayerHealth

ifTargetLevel

string - if the target has this many EXPERIENCE LEVELS. You can use the same operators like in ifTargetHealth

ifPlayerHasItem

Alias: ifPlayerHasItems
string or string list — if the player has (one of these) this item(s) in their inventory. You can also use operators here!

ifPlayerHasItem: "minecraft:DIAMOND" # if the player has at least 1 diamond

ifPlayerHasItem:
  "minecraft:DIAMOND": ">= 3" # if the player has at least 3 diamond
  "minecraft:GOLD_INGOT": "< 2" # if the player has LESS THAN 2 gold ingots
  "myCustomItem": 9, # interpreted as ">= 9". If the player has at least 9 of "myCustomItem"
  "anotherCustomItem": "between 3 and 4"  # if the player has between 3 and 4 of anotherCustomItem

ifTargetHasItem

Alias: ifTargetHasItems
string or string list — if the target has (one of these) this item(s) in their inventory. The formatting is exactly like ifPlayerHasItem, and you can use operators here, too!

ifTargetHeadIs

string or string list — if the target entity is wearing this on their head — set this to "nothing" to require the target entity wears nothing in this slot

ifTargetChestIs

string or string list — if the target entity is wearing this on their chest — set this to "nothing" to require the target entity wears nothing in this slot

ifTargetLegsAre

string or string list — if the target entity is wearing this on their legs — set this to "nothing" to require the target entity wears nothing in this slot

ifTargetFeetAre

string or string list — if the target entity is wearing this on their feet — set this to "nothing" to require the target entity wears nothing in this slot

ifTargetType

Alias: ifTargetTypes
string or string list — if the target's entity type is (one of)

ifNotTargetType

Alias: ifNotTargetTypes
string or string list — if the target's entity type is not (one of)

ifSneaking

true/false — if the player is sneaking

ifSwimming

true/false — if the player is swimming

ifGliding

true/false — if the player is gliding (with an elytra, for example)

ifFlying

true/false — if the player is flying (flying in creative or with a /fly command, for example)

ifGamemode

Alias: ifGamemodes
string or string list — if the player's Game Mode is (one of)

ifWeather

string or string list — if the the weather in the player's world is this (or one of these, in the case of a list). You can use "rain", "thunder", or "clear"

ifWeather: "clear" # if the weather in the player's world is clear

ifWeather:
  - "rain" # if the weather in the player's world is rain ...
  - "thunder" # ... or thunder

ifWorldTime

string — if the time in the player's world is this. You can use placeholders in this condition!

In Minecraft, time can be anywhere between 0 and 23999. You can check out this page on the Minecraft Wiki for more info about the day-night cycle and what each time means.

For example:

ifWorldTime: "<= 6000" # if it's before time 6000 (noon)
ifWorldTime: ">= 13000" # if it's after time 13000 (night)
ifWorldTime: "between 13188 and 22812" # if it's between 13188 and 22812 (when monsters naturally spawn in clear weather)

ifWorld

Alias: ifWorlds
string or string list — if the player's current world is (one of)

ifPlayerX

number or placeholder — if the player's current X position is this. Operators are allowed! For example,

ifPlayerX: "> 5000" # if the player's current X position is greater than 5,000
ifPlayerY: ">= {target.location.y}" # if the player's Y position is higher than the target's Y position 
ifPlayerZ: "< {variable.MY_VARIABLE}" # if the player's current Z position is less than the variable in MY_VARIABLE. you can learn more about variables here on the wiki!

ifPlayerY

number or placeholder — if the player's current Y position is this. You can use operators and placeholders like in ifPlayerX

ifPlayerZ

number or placeholder — if the player's current Z position is this. You can use operators and placeholders like in ifPlayerX

ifPlayerPitch

number or placeholder — if the player's current pitch is this. You can use operators and placeholders like in ifPlayerX

ifPlayerYaw

number or placeholder — if the player's current yaw is this. You can use operators and placeholders like in ifPlayerX

ifTargetX

number or placeholder — if the target's current X position is this. You can use operators and placeholders like in ifPlayerX

ifTargetY

number or placeholder — if the target's current Y position is this. You can use operators and placeholders like in ifPlayerX

ifTargetZ

number or placeholder — if the target's current Z position is this. You can use operators and placeholders like in ifPlayerX

ifTargetPitch

number or placeholder — if the target's current pitch is this. You can use operators and placeholders like in ifPlayerX

ifTargetYaw

number or placeholder — if the target's current yaw is this. You can use operators and placeholders like in ifPlayerX

ifBlockX

number or placeholder — if the block's X position is this. You can use operators and placeholders like in ifPlayerX

ifBlockY

number or placeholder — if the block's Y position is this. You can use operators and placeholders like in ifPlayerX

ifBlockZ

number or placeholder — if the block's Z position is this. You can use operators and placeholders like in ifPlayerX

ifInRegion

Alias: ifInRegions
string or string list — if the player is currently in (one of) the World Guard Regions. If the player interacted with a block, this will check at the block's location, and not the player's location

ifNotInRegion

Alias: ifNotInRegion
string or string list — if the player is not currently in (one of) the World Guard Regions If the player interacted with a block, this will check at the block's location, and not the player's location

ifMemberOfRegion

Alias: ifRegionMember
true/false — if the player is a member of all of the WorldGuard regions that they are currently in. Use true to check if the player IS a member, and false to check if the player is NOT a member. If the player interacted with a block, this will check at the block's location, and not the player's location

ifOwnerOfRegion

Coming Soon

Alias: ifRegionOwner
true/false — if the player is the owner of all of the WorldGuard regions that they are currently in. Use true to check if the player IS the owner, and false to check if the player is NOT the owner. If the player interacted with a block, this will check at the block's location, and not the player's location

Special Conditions

ifStatementCombine

SPECIAL PARAMETER
string — How the if statements should be combined. "AND" to make sure all conditions are satisfied, or "OR" to run as long as one or more of the conditions is satisfied, no matter whether or not the other conditions are satisfied.

You can also use "XOR" to run the action only if exactly one statement is true — if multiple are true, or none are true, the action will not run with "XOR".

Default is "AND"

invertIfResult

SPECIAL PARAMETER
boolean (true/false) — Inverts the result of your if statements. If your action would normally not run, and you set this to true, your action will run. If your action normally would run, and you set this to true, your action will not run.

Default is false

Operators in Conditions

You can use all of the following operators in conditions: =, >, >= (greater than or equal to), <, <= (less than or equal to), between X and Y (will satisfy the condition if the value is between X and Y)

For example:

ifPlayerLevel: "= 1"
ifPlayerX: "< 0"
ifPlayerY: "> 64"
ifPlayerZ: ">= 0"

ifPlayerYaw: "between 0 and 180"

Actions and Parameters

bolded parameters are required

Actions are what actually do things when players interact with custom items

For example, let's make it so that when a player right-clicks air with this item (the handler rightClickAir), they get teleported to the location x: 0, y: 0, z: 0 in "world". We'll do this using the teleportPlayer action

handlers:
  rightClickAir: # when a player right-clicks air with this item
    actions: # run these actions 
      - # make sure you have all of the indenting correct!
        action: teleportPlayer

        world: "world" # this is REQUIRED because it's bolded in the action reference
        x: 0 # this is REQUIRED because it's bolded in the action reference
        y: 0 # this is REQUIRED because it's bolded in the action reference
        z: 0 # this is REQUIRED because it's bolded in the action reference
        
        method: "set" # this is NOT required because it's NOT bolded in the action reference
        bringToTop: true # this is NOT required because it's NOT bolded in the action reference. However, we want to change the default behavior of this action (if you look at the action reference, by default bringToTop is false)
      -
        action: # you can put a second action here, if you like
      -
        action: # you can put a third action here, and so on...

List of actions

Actions	Player Actions	Target Actions	Special Actions
sendMessage	givePlayerItem	giveTargetItem	runActions
playerRunCommand	playerRemoveItem	targetRemoveItem	runDrupi
consoleRunCommand	damagePlayer	damageTarget	runSkript
destroyItemUsed	extinguishPlayer	extinguishTarget	print
damageItemUsed	teleportPlayer	teleportTarget
repairItemUsed	playerAddEffect	targetAddEffect
setItemDisplayName	playerRemoveEffects	targetRemoveEffect
setItemLore	playerClearEffects	targetClearEffects
placeBlock	addHealth	targetAddHealth
setBlockType	setHealth	targetSetHealth
setThroughBlockType	addFireTicks	targetAddFireTicks
setDrops		despawnTarget
cancel		killTarget
uncancel
addFood	Player Exp & Level Actions	Target Exp & Level Actions
setFood	playerSetLevel	targetSetLevel
addSaturation	playerAddLevels	targetAddLevels
setSaturation	playerRemoveLevels	targetRemoveLevels
playerPlaySound	playerSetEXP	targetSetEXP
playerSpawnParticle	playerAddEXP	targetAddEXP
	playerRemoveEXP	targetRemoveEXP	none
setTextureID

Here is an explinatio of all actions. Remember, bolded parameters are required

setTextureID

Useful for changing the texture of an item when something happens.

id - integer or string. You can use placeholders

#example
action: setTextureID
id: 7

sendMessage

Alias: sendMessages
Send message(s) to the player

message — string or string list
prefix — boolean (default true)

playerRunCommand

Alias: playerRunCommands
Force the player to run command(s)

command — string or string list

consoleRunCommand

Alias: consoleRunCommands
Force the console to run command(s)

command — string or string list

Prevent console output You can now prevent console output for the "consoleRunCommands" action by setting "silenceOutput" to true

action: consoleRunCommands
silenceOutput: true
commands:
  - "say Hello, world!"

Note: If you want to get something to not act like a placeholder, you need to escape it with backslashes. For example, {not a placeholder} will turn into {not a placeholder}. BE CAREFUL doing this in your item yml files! You may need to do \{not a placeholder\} if you're using double quotes like "\{this\}"

destroyItemUsed

Destroy the item in the player's hand

amount — integer (default 1, use -1 to remove all items of the same type)

damageItemUsed

Damage the item in the player's hand (one point of damage is applied to an item when breaking a block by default so this action will add additional points)

amount — integer (default 1)

repairItemUsed

Repair the item in the player's hand

amount - integer (default 1)

setItemDisplayName

Set the name of the item that the player used. You can use {placeholders} and &color codes.

name - string

setItemLore

Set the lore of the item that the player used. You can use {placeholders} and &color codes.

lore - list of strings

placeBlock

Place a block on the clicked block. Setting "force": true to make it so that the block will be placed regardless of whether or not the player has permission to build

type — string
force — true/false (default: false)

setBlockType

Set the clicked block to type. Set "force": true to make it so that the block will be set regardless of whether or not the player has permission to build

type — string
force — true/false (default: false)

You can also specify a radius in setBlockType, to set all blocks in that radius to type. Just set xRadius, yRadius, and/or zRadius:

ifBlockType: "minecraft:DIRT"
action: setBlockType
type: "minecraft:GRASS"

xRadius: 5
yRadius: 1
zRadius: 5

setThroughBlockType

Set the type of the block that was clicked through. For example, if you have

ifThroughBlockType:
  - "minecraft:WATER"
action: setThroughBlockType
type: "minecraft:ICE"

Then whenever a player right-clicks through water, the water will turn into ice. If the player is on the surface of the water, setBlockType would set the block type at the bottom of the water, whereas setThroughBlockType will set the block type on the surface of the water

type — string

setDrops

Set the items to drop.

item — (alas: items) string or string list, or a map of the item and the amount

For example, this will drop three diamonds, 4 CustomItems with the ID myCustomItem, and 1 apple:

action: setDrops
items:
  "minecraft:DIAMOND": 3
  "minecraft:APPLE": 1
  "myCustomItem": 4

And this will drop 1 diamond, 1 apple, and 1 CustomItem with the ID myCustomItem

action: setDrops
# Notice how this is now a "list" because each item has a "-" before it, and there's no number after the item
items:
  - "minecraft:DIAMOND"
  - "minecraft:APPLE"
  - "myCustomItem"

givePlayerItem

Give the player the specified item.

type — string
amount — integer (default 1)

playerRemoveItem

Remove the specified item from the player's inventory.

type — string
amount — integer (default all items)

giveTargetItem

Give the target the specified item.

type — string
amount — integer (default 1)

targetRemoveItem

Remove the specified item from the target's inventory.

type — string
amount — integer (default all items)

cancel

Cancel what just happened.

(no parameters)

uncancel

Uncancel what just happened.

(no parameter)

addFood

Adds food to the player

amount — integer

setFood

Sets the food of the player

amount — integer

addSaturation

Adds saturation to the player

amount — integer

setSaturation

Sets the saturation of the player

amount — integer

addHealth

Adds health to the player in half-hearts.

amount — integer (Make sure you use whole numbers, not decimals or it won't work)

Example:

action: addHealth
amount: 1 #this is half heart

setHealth

Sets the health of the player in half-hearts

amount — integer (Make sure you use whole numbers, not decimals or it won't work)

Example:

action: setHealth
amount: 1 #this is half heart

damagePlayer

Damages the player in half-hearts.

amount — integer (Make sure you use whole numbers, not decimals or it won't work)

Example:

action: damagePlayer
amount: 1 #this is half heart

addFireTicks

Adds to the number of ticks the player is on fire

ticks — integer

setFireTicks

Sets the number of ticks the player is on fire

ticks — integer

extinguishPlayer

Extinguishes the player

(no parameters)