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!

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!

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

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!"

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!"

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

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

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

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

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

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

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

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

string — if the player has the permission, not prefixed

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

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)

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)

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)

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)

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

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

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"

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

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

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

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

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

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"

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

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)

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)

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**

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

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

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**

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

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

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

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!

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

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

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

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

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

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

true/false — if the player is sneaking

true/false — if the player is swimming

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

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

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

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

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)

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

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!

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 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"

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

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"

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

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

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

id - integer or string. You can use placeholders

#example
action: setTextureID
id: 7

Alias: sendMessages
Send message(s) to the player

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

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

command — string or string list

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\}"

Destroy the item in the player's hand

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

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)

Repair the item in the player's hand

amount - integer (default 1)

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

name - string

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

lore - list of strings

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)

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

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

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"

Give the player the specified item.

type — string
amount — integer (default 1)

Remove the specified item from the player's inventory.

type — string
amount — integer (default all items)

Give the target the specified item.

type — string
amount — integer (default 1)

Remove the specified item from the target's inventory.

type — string
amount — integer (default all items)

Cancel what just happened.

(no parameters)

Uncancel what just happened.

(no parameter)

Adds food to the player

amount — integer

Sets the food of the player

amount — integer

Adds saturation to the player

amount — integer

Sets the saturation of the player

amount — integer

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

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

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

Adds to the number of ticks the player is on fire

ticks — integer

Sets the number of ticks the player is on fire

ticks — integer

Extinguishes the player

(no parameters)

Give experience points to the player

amount - integer or string. You can use placeholders

Remove experience points from the player

amount - integer or string. You can use placeholders

Set the total number of experience points the player has

amount - integer or string. You can use placeholders

Give experience points to the target

amount - integer or string. You can use placeholders

Remove experience points from the target

amount - integer or string. You can use placeholders

Set the total number of experience points the target has

amount - integer or string. You can use placeholders

Give levels to the player

amount - integer or string. You can use placeholders

Remove levels from the player

amount - integer or string. You can use placeholders

Set the total number of levels the player has

amount - integer or string. You can use placeholders

Give levels to the target

amount - integer or string. You can use placeholders

Remove levels from the target

amount - integer or string. You can use placeholders

Set the total number of levels the target has

amount - integer or string. You can use placeholders

Teleport the player.

world — string
locationX — decimal
locationY — decimal
locationZ — decimal
function — string ("set" or "add" to the player's location. Default is "set")
bringToSurface — boolean (default false)

Alias: playerAddEffects
Add potion effect(s) to the player.

effect — potion(s) see Referencing Potions

Example:

action: playerAddEffects
effects:
  -
    type: "NIGHT_VISION"
    time: 20 # 20 seconds
    strength: 1
    particles: false
  -
    type: # another potion effect, if you want...

Remove the potion effects from the player.

effect — string or string list

Remove all potion effects from the player (no parameters)

Play a sound effect to the player

sound - string or string list

Alias: playerSpawnParticles
Spawn particle effects at the player's location. This action has full {placeholder} support for every parameter!

If you're using Minecraft 1.9 or newer, You can find a list of valid particle names here. Note that if you're using Minecraft 1.8, particles are handled differently, so you must use this list instead

particles - either a single particle, or a list of particles. For each particle, you can use the following parameters:

FOR EACH PARTICLE:
name - string | the name of the particle

amount — number | default: 1 — how many particles to spawn

xSpread — decimal | default: 0 — how much the particles should spread in the x direction
yRadius — decimal | default: 0 — how much the particles should spread in the y direction
zRadius — decimal | default: 0 — how much the particles should spread in the z direction

xOffset — decimal | default: 0 — how much the particles should be offset from the player's location (in the x direction)
yOffset — decimal | default: 0 — how much the particles should be offset from the player's location (in the y direction)
zOffset — decimal | default: 0 — how much the particles should be offset from the player's location (in the z direction)

color — string | default: "777777" — for particles that support this parameter, what color the particle should be, in hex color code format — google "hex color picker". This is for particles that take Particle.DustOptions as a parameter. As of writing this (MC 1.16), only "REDSTONE" supports this.

size — number | default: 1 — for particles that support this parameter, what color the particle should be. If this is too high or too low, the particle simply won't show. This is for particles that take Particle.DustOptions as a parameter. As of writing this (MC 1.16), only "REDSTONE" supports this.

itemType — string | default: "wooden_planks" — for particles that support this parameter, what item the particle should be based off of. This is for particles that take ItemStack or MaterialData as a parameter. As of writing this (MC 1.16), supported particles are: "ITEM_CRACK", "LEGACY_BLOCK_CRACK", "LEGACY_BLOCK_DUST", "LEGACY_FALLING_DUST"

action: playerSpawnParticles
particles:
  -  # show a huge explosion at the player's location
    name: "EXPLOSION_HUGE"

  -  # show smoke, spread out around the player
    name: "SMOKE_NORMAL"

    # spawn 20 smoke particles in total...
    amount: 20

    # ... and spread them out 4 blocks in every direction
    xSpread: 4
    ySpread: 4
    zSpread: 4

  - # show blue dust at the bottom of the explosion
    name: "REDSTONE" # use REDSTONE, so we can change the color
    amount: 30 # spawn 30 redstone particles in total...

    # ... spread them out 10 blocks horizontally, but don't spread them in the y direction ...
    xSpread: 10 
    ySpread: 0
    zSpread: 10
    
    # ... make them bigger than normal redstone particles, and...
    size: 4

    # ... make them aqua blue
    color: "0077ff"

Adds health to the target in half-hearts.

amount — integer

Sets the health of the target in half-hearts.

amount — integer

Damages the target in half-hearts

amount — integer

Kills the target. (no parameters)

Despawns the target. (no parameters)

Adds to the number of ticks the target is on fire

ticks — integer

Sets the number of ticks the target is on fire

ticks — integer

Extinguishes the target. (no parameters)

Teleport the target

world — string
locationX — decimal
locationY — decimal
locationZ — decimal
function — string ("set" or "add" to the target's location. Default is "set")
bringToSurface — boolean (default false)

Alias: targetAddEffects
Add potion effects to the target

effect — potion(s) see Referencing Potions

Example:

action: targetAddEffects
effects:
  -
    type: "NIGHT_VISION"
    time: 20 # 20 seconds
    strength: 1
    particles: false
  -
    type: # another potion effect, if you want...

Alias: targetRemoveEffects
Remove the potion effects from the target

effect — string or string list

Remove all potion effects from the target. (no parameters)

Print something to the console. Useful for debugging your actions

message - string or string list

runs no action. (no parameter)

Special action that runs more actions. This is useful when used in combination with conditions.

actions — action list

Example:

action: runActions
actions:
  -
    action: sendMessage
    message: "Here's a diamond"
  -
    action: givePlayerItem
    type: "minecraft:DIAMOND"

Special action that calls a Drupi event with the specified ID.

actionID — string or string list — the id(s) of the actions to run in the drupi script. Listen for onCustomItemsHandle and check event.getActionID()

Special action that runs Skript code with the specified ID

actionID — string or string list — the id(s) of the actions to run in the Skript files

Valid for every action

The maximum distance (in blocks) that CustomItems will search for a target for any "target" actions. This can be set as high as 60. If you set this too high and use it too often, it may be hard on your server. If you don't need to use this, you shouldn't.

When a player right-clicks air, this will try to find a target within 20 blocks of them, and then give the target a diamond. If there's no target, nothing will happen.

handlers:
  rightClickAir:
    actions:
      -
        action: "giveTargetItem"
        type: "minecraft:DIAMOND"
        targetMaxDistance: 20

A list of permissions that should be overridden for this action. This is useful if you want to force the player to run a command that they normally don't have access to. This shouldn't interfere with any other plugins, but just be aware that this works by giving the player the permission, running the command, and then quickly removing the permission again.

action: playerRunCommand
command: "fireball"
overridePermissions:
  - essentials.fireball.fireball

Formatted like runActions, and run if the conditions (the "if..." conditions) aren't met

ifHasPermission: "myPermission"
action: giveItem
type: "DIAMOND"
elseActions:
  -
    action: sendMessage
    message: "You don't have the permission customitems.action.myPermission, so NO DIAMONDS FOR YOU"

decimal between 0 and 1 (default 1.0)
the probability that this action will run. For example, set this to 0.7 to have your action run 70% of the time, and not run the other 30% of the time. Set it to 0.025 to have your action run 2.5% of the time, and not the other 97.5% of the time.

probability and relativeProbability do very different things — read relativeProbability just below this for some more info!

number (default none)
the RELATIVE probability that this action will run, and it looks at the other actions in the action list. If you have a list of actions, and you give each of them "relativeProbability: 1", then each one of them will have the same chance of running, and exactly one will run. If you set this to "10" for one action and "1" for ten other actions, then the action with "10" will have a 50% chance of running while the other actions will each have a 5% (1 in 20) chance of running.

If you don't set this for an action in an action list, then that action will run. Here's an example:

actions:
  -
    action: sendMessage
    message: "You will always get this message, and you have a 10% chance of getting a diamond, and a 90% chance of getting iron"
    # There's no "relativeProbability", so this action will always run!
    # If you want, you can also set "relativeProbability: -1" to do this
    # more explicitly, and the action will always run.
  -
    action: givePlayerItem
    type: "minecraft:DIAMOND"
    # There's a 10 in 100 chance this will run
    relativeProbability: 10
  -
    action: givePlayerItem
    type: "minecraft:IRON_INGOT" 
    # There's a 90 in 100 chance this will run
    relativeProbability: 90

On the other hand, if you had used probability in this instance, a player would get diamond 10% of the time AND they would get iron 90% of the time. There's actually a 9% chance the player would get both iron and a diamond, and a 9% chance the player would get neither.

relativeProbability ensures that exactly one of the actions will run. So, there is a 10% chance the player would get a diamond OR a 90% chance the player would get iron. There's no chance they would get both or neither.

The relativeProbabilitys don't have to add up to exactly 100 — the plugin accounts for whatever you set them to. So, if you set one relativeProbability to 109 and another relativeProbability to 12, then one of the actions will run 109 in 109 + 12 = 121 times, and the other will run 12 in 121 times

formatted like runActions, and run if either the probability or relativeProbability isn't met

number (default 0)
the number of ticks the to wait before running the action (there are 20 ticks in one second). For example, set this to 10 to make the action wait half a second before running.

number (default 1)
number of times to do nothing before running this action. For example, set this to 2 to make the action run every other time, and set it to 10 to make the action run every 10th time.

formatted like "actions", and run if the run interval isn't met

number (default 0)
the number of ticks to wait before allowing the same player to run the action again. For example, set this to 10 to give the action a half a second cooldown. Set this to -1 to make it so the player can only run the action once per server restart.

Cooldowns are per-player-per-action. In other words, cooldowns prevent an action from running too quickly for a given player. Check out notCooldownActions just below to see how to format this

formatted like runActions, and run if the cooldown hasn't happened yet.

Here's an example using cooldown and notCooldownActions

handlers:
  rightClick:
    actions:
      -
        cooldown: 200 # 200 ticks = 10 seconds
        action: sendMessage
        message: "You've cooled down!"
        notCooldownActions:
          - 
            action: sendMessages
            messages:
              - "You need to wait {cooldown.remaining} ticks, or {{cooldown.remaining / 20} round 0} seconds, before doing this again!"
              - "You've waited a total of {cooldown.elapsed} of {cooldown.total} ticks"

If you want to apply the same cooldown to multiple actions, you should apply it to a "runActions" action

cooldown: 200
action: runActions
actions:
  -
    action: # your first action
  -
    action: # your second action
  -
    action: # your third action

• runInterval is evaluated AFTER probability and relativeProbability. Also, the current interval resets on server restarts (for now)

In messages and commands, the following things are placeholders that are automatically replaced.

{player} OR {player.name} is replaced with the player's name

{player.uuid} is replaced with the player's UUID

{player.health} is replaced with the player's health. On the normal health scale, this will be "20.0" at its max. With full health, "{player.health / 2} hearts" would turn into "10 hearts"

{player.exp} replaced with the total number of experience points the player has (This doesn't reset on level up or down)

{player.level} replaced with the total number of Levels the player has

{block.location.world}, {block.location.x}, {block.location.y}, {block.location.z} are respectively replaced with the world, x component, y component, and z component of the clicked block's location

{block.type} is replaced with the block's type, or the custom item ID if the block is a custom block

{player.location.world}, {player.location.x}, {player.location.y}, {player.location.z} are respectively replaced with the world, x component, y component, and z component of the player's location

{player.food} is replaced with the players food

{target.name} is replaced with the target's name

{target.uuid} is replaced with the target's UUID

{target.type} is replaced with the targets type

{target.location.world}, {target.location.x}, {target.location.y}, {target.location.z} are respectively replaced with the world, x component, y component, and z component of the target's location

{target.exp} is replaced with the total number of experience points the target has (This doesn't reset on level up or down)

{target.level} is replaced with the total number of Levels the target has

{random.number from X to Y} is replaced with a random integer number between X and Y. For example, {random.number from 0 to 64} will automatically be replaced with some random number between 0 and 64, inclusive. Keep in mind that this number will be randomly chosen every time.

{cooldown.remaining} is replaced with the TICKS remaining for the cooldown. Minecraft servers run at 20 ticks per second without lag, so you can change this into seconds by using {cooldown.remaining / 20}, and round it to have no decimal points by using {{cooldown.remaining / 20} round 0}

{cooldown.elapsed} is replaced with the total TICKS elapsed since the start of the cooldown.

{cooldown.total} is replaced with the total TICKS required for the action to cool down.

{variable.VARIABLE_NAME} is replaced with the value of whatever the VARIABLE_NAME variable is set to

{global.GLOBAL_NAME} is replaced with the value of whatever the GLOBAL_NAME global is set to

{time} - Unix timestamp in seconds

{cui.action.id} — for advanced users only — is replaced by a unique number identifier for the action.

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\\}"

This also works in the actions "teleportPlayer" and "teleportTarget":

action: teleportPlayer

# It's important to put the quotation marks
# around the placeholders
world: "{target.location.world}"
locationX: "{target.location.x}"
locationY: "{target.location.y}"
locationZ: "{target.location.z}"

You can also do math in all of the number placeholders like {player.location.x} and {target.location.x}! Just use one of + - * /, like this:

action: sendMessages
messages:
  - "Hey there, {player}!"
  - "Your y position is {player.location.y}!"
  - "If we add five to that, we get {player.location.y + 5}!"
  - "If we multiply it by two, we get {player.location.y * 2}"
  - "If we divide by three, we get {player.location.y / 3}!"

Additionally, you can round numbers using the round <decimal points> operator:

If the player's x location were 712.572, then {player.location.x round 0} would be 713, {player.location.x round 1} would be 712.6, and {player.location.x round 2} would be 712.57

You can also use placeholders from Placeholder API (PAPI) in CustomItems! To do so, just wrap the placeholder with percent signs (NOT curly braces). For example,

action: sendMessages
messages:
  - "Using a CustomItems placeholder, you're in the world {player.location.world}"
  - "Using a PAPI placeholder, you're in the world %player_world%" # notice how there's no curly braces around the PAPI placeholder

You can nest placeholders and do operations using multiple placeholders, too! However, you can only ever do an operation using two things at a time. curly braces are like parentheses in math — the things 'deeper' in curly braces get evaluated first:
{10 + {2 * 2}} = {10 + 4} = 14, but {{10 + 2} * 2} = {12 * 2} = 24

For example, if you wanted to compute x + y + z, you would need to do either {x + {y + z}} or {x + {y + z}}. If you instead try to do {x + y + z}, the placeholder won't work

Let's say that:
a * b = x
c * d = y
x + y = z

So, if we wanted to compute (a * b) + (c * d), we would need to use {{a * b} + {c * d}}, because on the first pass, the placeholder will be computed to {x + y}, and then, this will be evaluated to just z

However, If we didn't have the outside curly braces, and instead tried to do {a * b} + {c * d}, then this would just evaluate to x + y, and this would be the final message that we get!

Now, what if we want to compute (a * b) + (c * d) + e, rounded to 2 decimal points?

1. We could use {{a * b} + {c * d}} from above to get the (a * b) + (c * d) part.
2. Now, we want to also add e to this, so we can add another set of curly braces around it and add e: {e + {{a * b} + {c * d}}}. This gives us (a * b) + (c * d) + e
3. Lastly, we want to round this to 2 decimal points, so we could add another set of curly braces: {{e + {{a * b} + {c * d}}} round 2}. This gives us (a * b) + (c * d) + e, rounded to 2 decimal points!

Make sure you have all of the curly braces in the right places! If you had misplaced some curly braces and used {{{e + a} * {b + c}} * {d round 2}} instead, this would give you (e + a) * (b + c) * (d rounded to 2 decimal points), which is not what we wanted!

Here's a few more examples:

action: sendMessages
messages:
   - "10 + 10 = {10 + 10}" # will print "10 + 10 = 20"
   - "10 * 10 * 10" = {10 * {10 * 10}}" # will print "10 * 10 * 10 = 1000"
   - "{{10 / 9} round 1}" # will print "1.1" (1.11111, rounded to 1 decimal place)
   - "if we multiply your coordinates, we get {player.location.x * {player.location.y * player.location.z}}" # will print the product of the player's x, y, and z coordinates
   - "{{10 + 10} + {10 + 10}}" # will print "40"
   - "{{{location.x + {location.y + location.z}} / 10} round 2}" # will print whatever (x + y + z) / 10 is, with 2 decimal points

   - "20 * 20 = {{10 + 10} * {10 + 10}}" # will print "20 * 20 = 4000"
   - "20 * 20 =  {10 + 10} * {10 + 10} " # will print "20 * 20 = 20 * 20"
   - "20 * 20 =   10 + 10  * {10 + 10} " # will print "20 * 20 = 10 + 10 * 20"