# 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)_&#x20;
* **%playerarmor\_\<type>%** _(material of the armor the player is wearing. Replace \<type> with: helmet, chestplate, leggings or boots)_&#x20;
* **%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/sla&#x62;_)_
* **%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](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_](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,_ only works on 1.16-1.21.&#x33;_)_
* **%item\_meta%** _(text that provides more extensive information of the item, for example, potion effects)_

For the [**Player Swap Hand**](../event-types/player-events#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_](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)_&#x20;
* **%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_](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_](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`](../event-types/player-events#player-attack) ,[`player_kill`](../event-types/player-events#player-kill) or [`entity_interact`](../event-types/other-events#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.&#x20;

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

```yaml
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**](actions/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:

```yaml
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:

```yaml
# 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:

```yaml
# 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>"
```

{% hint style="info" %}
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}%
```
{% endhint %}

