Variables

Global Variables

These variables can be used in any event.

%player% (player name)
%random_min_max% (will select a random number between "min" and "max". For example: %random_1_10% will choose a random number between 1 and 10)
%playerarmor_<type>% (material of the armor the player is wearing. Replace <type> with: helmet, chestplate, leggings or boots)
%playerarmor_name_<type>% (name of the armor the player is wearing)
%block_at_<x>_<y>_<z>_<world>% (material of the block at certain location)
%block_data_at_<x>_<y>_<z>_<world>% (it will return a numerical value on 1.8-1.12 and a text with several block properties on 1.13+. For example, a stairs block has a facing property, or a wheat block has an age property)
%playerblock_below_<distance>% (material of the block below the player with a certain distance. Example: %playerblock_below_1% will return the block just below the player)
%playerblock_above_<distance>% (material of the block above the player with a certain distance. Example: %playerblock_above_5% will return the block 5 blocks above the player)
%playerblock_inside% (material of the block the player is inside, like water or some special blocks, like when standing on a head/slab)
%player_is_outside% (will check if the player is outside or has no blocks above. It will return 'true' or 'false')
%random_player% (selects a random player connected to the server. It will return 'none' if no player is found)
%random_player_<world>% (selects a random player from a specific world. It will return 'none' if no player is found)
%randomword_<word1>-<word2>-<wordN>% (will select a random word of the provided list. Each word should be separated by a '-')
%is_nearby_<x>_<y>_<z>_<world>_<radius>% (will check if a player is nearby certain coordinates. It will return 'true' or 'false')
%world_time_<world>% (time of the world in ticks)
%world_is_raining% (will check if it is raining in the world the player is in. It will return 'true' or 'false')
%is_number_<variable>% (allows to check whether a certain variable is a number or not. It will return 'true' or 'false'. For example in a player_command event: %is_number_{arg_1}%)
%empty% (special variable that will return an empty text. You can use this variable on conditions where other variables return an empty value as well)

You can also use PlaceholderAPI variables for the conditions and actions of all events: https://github.com/PlaceholderAPI/PlaceholderAPI/wiki/Placeholders

Item Variables

These variables can be used in multiple item-related events.

%item% (type of the item. All types on this link: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html)
%item_durability% (datavalue of the item)
%item_amount% (amount of the item)
%item_name% (custom name of the item without color codes)
%item_color_format_name% (custom name of the item including color codes)
%item_lore% (description of the item)
%item_color_format_lore% (description of the item including color codes)
%item_lore_line_X% (the X line of the description of the item)
%item_color_format_lore_line_X% (the X line of the description of the item including color codes)
%item_custom_model_data% (the custom model data value of the item)
%item_meta% (text that provides more extensive information of the item, for example, potion effects)

For the Player Swap Hand event you can also get all the previous variables from the offhand item using %offhand:<variable>%. For example:

%offhand:item%
%offhand:item_lore%

Block Variables

These variables can be used in multiple block-related events.

%block% (type of the block. All types on this link: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html)
%block_x% (x coordinate of the block)
%block_y% (y coordinate of the block)
%block_z% (z coordinate of the block)
%block_world% (world of the block)
%block_head_texture% (texture id of a head block, it will return and empty text if not valid)
%block_data% (it will return a numerical value on 1.8-1.12 and a text with several block properties on 1.13+. For example, a stairs block has a facing property, or a wheat block has an age property)
%block_below_<distance>% (type of the block below the original event block, with a certain distance. Example: %block_below_1% will return the block just below the original event block)
%block_above_<distance>% (type of the block above the original event block, with a certain distance. Example: %block_above_1% will return the block just above the original event block)

Entity Variables

These variables can be used in multiple entity-related events.

%entity% (type of the entity. All types on this link: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html)
%entity_name% (name of the entity without color codes)
%entity_color_format_name% (name of the entity including color codes)
%entity_x% (x coordinate of the entity)
%entity_y% (y coordinate of the entity)
%entity_z% (z coordinate of the entity)
%entity_world% (world of the entity)
%entity_uuid% (uuid of the entity)

Victim Variables

These variables can be used in multiple victim-related events.

%victim% (type of the victim entity. All types on this link: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html)
%victim_name% (name of the victim entity without color codes)
%victim_color_format_name% (name of the victim including color codes)
%victim_block_x% (x coordinate of the victim entity)
%victim_block_y% (y coordinate of the victim entity)
%victim_block_z% (z coordinate of the victim entity)
%victim_block_world% (world of the victim entity)
%victim_uuid% (uuid of the victim entity)
%victim_health% (health of the victim entity)

"Target" Variable

In somes cases like the player_attack ,player_kill or entity_interact events you will want to obtain a variable from the target player instead. For this to work you just need to add "target:" before the real variable.

For example, if you want to obtain the target's player name, instead of using %player% you need to use %target:player%.
If you need need to obtain the rank of the targeted player, instead of using %vault_rank% use %target:vault_rank%

Here is a full example:

example:
    type: player_attack
    conditions:
    - '%victim% equals PLAYER'
    - '%item% equals DIAMOND_SWORD'
    - '%item_name% equals Poison Sword'
    actions:
      default:
      - 'message: &aApplying poison to: &e%target:player%'
      - 'to_target: give_potion_effect: POISON;120;1'
      - 'to_target: message: &cYou were poisoned by &e%player%&c!'

"To" Variable

When using "To" Actions, you can obtain variables directly from the selected player instead. For this to work you just need to add "to:" before the real variable.

For example, if you want to obtain the selected player name, instead of using %player% (which is the original player who executed the event), you need to use %to:player%.

Here some examples:

example:
  type: call
  actions:
    default:
    - "console_message: &7Sending a welcome message to all players"
    - "to_all: message: &eHello &c%to:player%, &ewelcome to the server!"

example2:
  type: player_command
  conditions:
  - "%main_command% == /hello"
  actions:
    default:
    - "cancel_event: true"
    - "to_range: 10;false: message: &6%player% says: &7Hello %to:player%!"

Variables inside variables

On some specific cases you will need to obtain a result using multiple variables, placing a variable inside another. As an example, using the Math expansion from PlaceholderAPI you can create a formula using multiple ConditionalEvents variables.

For example, if you want to obtain the time of the world the player's in, you need to use the %world_time_<world>% variable (From ConditionalEvents) and inside <world> the variable %player_world% (From PlaceholderAPI). This can be done using brackets "{ }":

%world_time_{player_world}%

Here is a full example:

# Checks the time of the world you are in.
# Remember to download the Player expansion using
# /papi ecloud download Player
example:
    type: player_command
    conditions:
    - "%command% == /world-time"
    actions:
      default:
      - "cancel_event: true"
      - "message: Time in your current world: %world_time_{player_world}%"

Another example:

# Gets the IP of another player by command.
# Remember to download the OtherPlayer expansion using
# /papi ecloud download OtherPlayer
example2:
    type: player_command
    conditions:
    - "%command% == /ip or %command% startsWith /ip "
    - "%player_has_permission_conditionalevents.admin% == no execute error1"
    - "%args_length% < 1 execute error2"
    actions:
      default:
      - "cancel_event: true"
      - "message: &7IP of &a%arg_1% &7is: %otherplayer_ip_{arg_1}%"
      error1:
      - "cancel_event: true"
      - "message: &cYou don't have permissions."
      error2:
      - "cancel_event: true"
      - "message: &cYou must use /ip <player>"

You can add as many variables inside variables you need. For this to work enable variable_replacement option in the config.

An example that returns the block beneath the player using the PlaceholderAPI Math/Player expansions:

%block_at_{player_x}_{math_0:0_{player_y}-1}_{player_z}_{player_world}%

PreviousPlugin Actions NextCustom Events

Last updated 28 days ago