Player Events

PLAYER JOIN

Event called when a player joins the server.

example:
  type: player_join
  actions:
    default:
    - 'message: &eWelcome %player% to the server.'

This event has no variables, but you can still use ConditionalEvents variables or PlaceholderAPI variables.

This event can't be cancelled with cancel_event action.

PLAYER LEAVE

Event called when a player leaves the server.

example:
  type: player_leave
  actions:
    default:
    - 'to_all: message: &e%player% left the server.'

This event has no variables, but you can still use ConditionalEvents variables or PlaceholderAPI variables.

This event can't be cancelled with cancel_event action.

PLAYER PRE JOIN

Event called when a player tries to join the server.

example:
  type: player_pre_join
  conditions:
  - "%name% == Ajneb"
  - "%ip% != 192.168.0.1"
  actions:
    default:
    - "console_message: &8[&c&lALERT&8] &7A user with IP &e%ip% &7tried to join the server using and administrator account."
    - "prevent_join: &c&lERROR!\n&7You can't access this account with that IP."

Variables:

• %name% (Name of the player trying to join the server)

• %ip% (IP of the player)

• %uuid% (UUID of the player)

This is not a player event, which means you can't use player variables or player actions. Don't be confused, it is called a "player pre join", but it is a special event which doesn't contain player data.

This event can't be cancelled with cancel_event action. If you want to block the player from joining, use the prevent_join action instead.

PLAYER RESPAWN

Event called when a player respawns.

example:
  type: player_respawn
  conditions:
  - '%player_world% == pvp1'
  actions:
    default:
    - "teleport: lobby;0;60;0;90;0"
    - "message: &cYou died. Teleporting you back to the PvP Lobby..."

Variables:

• %x% (Coordinate X of the respawn point)

• %y% (Coordinate Y of the respawn point)

• %z% (Coordinate Z of the respawn point)

• %respawn_world% (World of the respawn point)

• %reason% (Reason of respawn. All reasons here: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/event/player/PlayerRespawnEvent.RespawnReason.html). Works only on 1.19.4+.

This event can't be cancelled with cancel_event action.

PLAYER DEATH

Event called when a player dies.

example:
  type: player_death
  actions:
    default:
    - 'message: &7You died because of: &c%cause%'

Variables:

• %cause% (Cause of death. All causes here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/entity/EntityDamageEvent.DamageCause.html)

• %killer_type% (If the player dies because of an entity, which type of entity. All types on this link: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html)

• %killer_name% (If the player dies because of an entity, the name of this entity without color codes)

• %killer_color_format_name% (The name of the killer including color codes)

This event can't be cancelled with cancel_event action.

PLAYER COMMAND

Event called when a player executes a command.

example:
  type: player_command
  conditions:
  - '%main_command% equalsIgnoreCase //calc or %main_command% equalsIgnoreCase //solve'
  actions:
    default:
    - 'cancel_event: true'
    - 'kick: &cWhat are you trying to do?'

Variables:

• %command% (The full command the player used)

• %main_command% (The main command without arguments)

• %arg_X% (The argument in the X position of the command. If the command is /announce hello world the %arg_1% variable would be "hello" and the %arg_2% would be "world")

• %args_length% (The amount of arguments of the command)

• %args_substring_<arg1>-<arg2>% (This variable will create a text using a first argument and a last argument. For example, if the command is /announce I am currently doing a Youtube livestreaming, you could use the %args_substring_1-6% variable to take arg1, arg2,...,arg6 and get the text that the player is announcing. If you don't care about the arguments length, instead of 6 use a large number like 100)

PLAYER CHAT

Event called when a player writes something in chat.

example:
  type: player_chat
  conditions:
  - '%message% contains hacker'
  actions:
    default:
    - 'cancel_event: true'
    - 'message: &cIf you found a hacker please report them on our Discord.'

Variables:

• %message% (The chat message)

PLAYER LEVELUP

Event called when a player changes its level.

example:
  type: player_levelup
  actions:
    default:
    - 'message: &aLevel &6&l%old_level% &7-> &6%new_level%'

Variables:

• %old_level% (The previous level of the player)

• %new_level% (The new level of the player)

This event can't be cancelled with cancel_event action.

PLAYER WORLD CHANGE

Event called when a player is moving to another world.

example:
  type: player_world_change
  actions:
    default:
    - 'message: &7Moving to &e%world_to% &7world'

Variables:

• %world_from% (The previous world)

• %world_to% (The world where the player is moving to)

• %online_players_from% (Amount of online players in the previous world)

• %online_players_to% (Amount of online players in the world where the player is moving to)

This event can't be cancelled with cancel_event action.

PLAYER ATTACK

Event called when a player damages an entity.

example:
  type: player_attack
  conditions:
  - '%victim% == PLAYER'
  - '%item% == DIAMOND_SWORD'
  - '%item_name% == Super Sword'
  - '%random_1_10% >= 8'
  actions:
    default:
    - 'message: &aYour diamond sword poison effect was activated! &6%target:player_name% &ais now poisoned!'
    - 'to_target: give_potion_effect: POISON;120;1'
    - 'to_target: message: &cYou were poisoned by &e%player%&c!'

Variables:

• %damage% (Damage made by the player)

• %original_damage% (Original damage made by the player)

• %attack_type% (Type of the damage. For projectiles it could be: ARROW, TRIDENT, SNOWBALL. If the damage is not made by a projectile, it will result in PLAYER)

• %is_critical% (Whether the damage was a critical damage or not. Requires Paper 1.17+)

• ConditionalEvents item variables (for item in hand)

• ConditionalEvents victim variables

On this event you can use target player variables and to_target actions.

PLAYER KILL

Event called when a player kills an entity.

example:
  type: player_kill
  conditions:
  - '%victim% == COW'
  actions:
    default:
    - 'message: &aAre you happy killing this cow?'

Variables:

• ConditionalEvents item variables (for item in hand)

• ConditionalEvents victim variables

This event can't be cancelled with cancel_event action.

On this event you can use target player variables and to_target actions.

PLAYER DAMAGE

Event called when a player is taking damage.

example:
  type: player_damage
  conditions:
  - '%cause% == DROWNING'
  actions:
    default:
    - 'cancel_event: true'

Variables:

• %cause% (Cause of the event. How did the player got damaged. All causes here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/entity/EntityDamageEvent.DamageCause.html)

• %damage% (Damage taken by the player)

• %original_damage% (Original damage taken by the player)

• %damager_type% (If the player takes damage from an entity, which type of entity. All types on this link: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html)

• %damager_name% (If the player takes damage from an entity, the name of this entity without color codes)

• %damager_color_format_name% (The name of the damager including color codes)

PLAYER ARMOR

Event called when a player equips or unequips armor.

example:
  type: player_armor
  conditions:
  - '%armor_type% == HELMET'
  - '%equip_type% == EQUIP'
  - '%item_name% == Super Diamond Helmet'
  - '%player_has_permission_items.super_diamond_helmet% == false'
  actions:
    default:
    - 'cancel_event: true'
    - "message: &cYou don't have permissions to equip that item!"

Variables:

• %armor_type% (Type of the armor. Could be: HELMET, CHESTPLATE, LEGGINGS or BOOTS)

• %equip_type% (Could be: EQUIP or UNEQUIP)

• ConditionalEvents item variables

If you are using EssentialsX: EssentialsX changes the way interactions behave in player armor, so if you want to use the player_armor event, set allow-direct-hat: false on EssentialsX config.

PLAYER TELEPORT

Event called when a player teleports somehow.

example:
  type: player_teleport
  conditions:
  - "%cause% == NETHER_PORTAL"
  actions:
    default:
    - 'cancel_event: true'
    - "message: &cYou can't use nether portals!"

Variables:

• %cause% (Cause of the event. Why is the player teleporting. All causes here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/player/PlayerTeleportEvent.TeleportCause.html)

• %from_x% (Coordinate X of the previous location)

• %from_y% (Coordinate Y of the previous location)

• %from_z% (Coordinate Z of the previous location)

• %from_world% (World of the previous location)

• %from_yaw% (Yaw of the previous location)

• %from_pitch% (Pitch of the previous location)

• %to_x% (Coordinate X of the new location)

• %to_y% (Coordinate Y of the new location)

• %to_z% (Coordinate Z of the new location)

• %to_world% (World of the new location)

• %to_yaw% (Yaw of the new location)

• %to_pitch% (Pitch of the new location)

PLAYER BED ENTER

Event called when a player enters a bed.

example:
  type: player_bed_enter
  conditions:
  - "%result% == OK"
  - "%player_world% == spawn"
  actions:
    default:
    - "cancel_event: true"
    - "message: &cYou can't sleep on this world."

Variables:

• %result% (Result of the event. Can the player really use the bed? All results here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/player/PlayerBedEnterEvent.BedEnterResult.html)

Only works on 1.13+!

PLAYER OFFHAND

Event called when players interact with their offhand.

• Swap items between main hand and offhand using the hotkey.

• Use the inventory to move items to the offhand.

• Use the inventory to recover items from the offhand.

example:
  type: player_offhand
  conditions:
  - "%item% endsWith _SWORD"
  actions:
    default:
    - "message: &cYou can't place swords in your offhand!"
    - "cancel_event: true"

Variables:

• %movement_type% (Could be: SWAP, PLACE, RECOVER, NOTHING)

• ConditionalEvents item variables (for the item the player is trying to put in the offhand)

• ConditionalEvents item variables (for the item the player is trying to recover from the offhand: %offhand:<variable>%)

PLAYER FISH

Event called when a player is fishing.

Example 1

example:
  type: player_fish
  conditions:
  - "%state% == CAUGHT_ENTITY"
  - "%caught_type% == COW or %caught_type% == PIG"
  actions:
    default:
    - "cancel_event: true"
    - "message: &cYou can't use a fishing rod on animals!"

Example 2

Variables:

• %state% (Current state of fishing. All states here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/player/PlayerFishEvent.State.html)

• %caught_type% (Entity caught. All entity types here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html)

• %caught_x% (Coordinate X of the caught location)

• %caught_y% (Coordinate Y of the caught location)

• %caught_z% (Coordinate Z of the caught location)

• ConditionalEvents item variables (For caught item if present. %state% must be CAUGHT_FISH and %caught_type% must be ITEM or DROPPED_ITEM)

On this event you can use target player variables and to_target actions (Only if %state% is CAUGHT_ENTITY and %caught_type% is a Living Entity)

PLAYER OPEN INVENTORY

Event called when a player opens an inventory.

example:
  type: player_open_inventory
  conditions:
  - "%inventory_type% == MERCHANT"
  actions:
    default:
    - "message: &cVillager trading is disabled."
    - "cancel_event: true"

Variables:

• %inventory_type% (Type of the opened inventory. All types here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/InventoryType.html)

• %inventory_title% (Title of the opened inventory without color codes)

PLAYER CLOSE INVENTORY

Event called when a players closes an inventory.

example:
  type: player_close_inventory
  conditions:
  - "%inventory_type% == MERCHANT"
  actions:
    default:
    - "message: &cClosing villager trading..."

Variables:

• %inventory_type% (Type of the closed inventory. All types here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/InventoryType.html)

• %inventory_title% (Title of the closed inventory without color codes)

This event can't be cancelled with cancel_event action.

PLAYER CLICK INVENTORY

Event called when a player clicks on an inventory.

example:
  type: player_click_inventory
  conditions:
  - "%inventory_title% == Custom Craftings"
  - "%slot% == 14"
  - "%item% == CHEST"
  - "%click_type% == LEFT"
  actions:
    default:
    - "message: &aLeft clicking on a Chest on slot 14 on inventory 'Custom Craftings'"

Variables:

• %inventory_type% (Type of the clicked inventory. All types here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/InventoryType.html)

• %inventory_title% (Title of the clicked inventory without color codes)

• %inventory_title_color_format% (Title of the clicked inventory with color codes)

• %click_type% (Click type. How is the player clicking on the inventory. All types here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/ClickType.html)

• %action_type% (Action type. What is the player doing in the inventory. All types here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/InventoryAction.html)

• %slot_type% (Type of the clicked slot. All types here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/InventoryType.SlotType.html)

• %slot% (Position of the inventory clicked)

• ConditionalEvents item variables (for clicked item)

• ConditionalEvents item variables (for item in cursor: %cursor:<variable>%)

PLAYER STATISTIC

Event called when a player statistic is incremented, like certain blocks breaked, jumps, items pickup...

example:
  type: player_statistic
  one_time: true
  conditions:
  - "%statistic_name% == MINE_BLOCK"
  - "%block% == EMERALD_ORE"
  - "%new_value% == 5"
  actions:
    default:
    - "centered_message: &a&lAchievement Unlocked!"
    - "centered_message:  "
    - "centered_message:  &eMine 5 Emerald Blocks."
    - "centered_message:  "
    - "centered_message:  &aRewards:"
    - "centered_message:  &7- $500"
    - "console_command: eco give %player% 500"

Variables:

• %statistic_name% (Name of the incremented statistic. All names here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Statistic.html)

• %new_value% (New value of this statistic)

• %previous_value% (Previous value of this statistic)

• %entity% (Associated entity type for this statistic, if present. All types here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html)

• %block% (Associated block type for this statistic, if present. All types here: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html)

PLAYER SNEAK

Event called when a player toggles their sneaking state.

example:
  type: player_sneak
  conditions:
  - "%is_sneaking% == true execute actions1"
  actions:
    actions1:
    - "message: &eSneaking"
    default:
    - "message: &eCancelling sneak"

Variables:

• %is_sneaking% (Whether the player is sneaking or not. Will return "true" or "false")

This event can't be cancelled with cancel_event action.

PLAYER RUN

Event called when a player toggles their running state (starts or stops running).

example:
  type: player_run
  conditions:
  - "%is_running% == true execute actions1"
  actions:
    actions1:
    - "message: &eRunning"
    default:
    - "message: &eStopped running"

Variables:

• %is_running% (Whether the player is running or not. Will return "true" or "false")

This event can't be cancelled with cancel_event action.

PLAYER REGAIN HEALTH

Event called when a player regains/regenerates health.

example:
  type: player_regain_health
  conditions:
  - "%reason% == SATIATED"
  actions:
    default:
    - 'cancel_event: true'

Variables:

• %reason% (Reason of the event. Why is the player regenerating health. All reasons here: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/entity/EntityRegainHealthEvent.RegainReason.html)

• %amount% (Amount of health regained)

PLAYER CHANGE FOOD

Event called when the food level of a player changes.

example:
  type: player_change_food
  conditions:
  - "%player_world% == minigames"
  actions:
    default:
    - "cancel_event: true"

Variables:

• %old_food_level% (The previous food level of the player)

• %new_food_level% (The new food level of the player)

Only works on 1.16+!

PLAYER TAB COMPLETE

Event called when a player is writing a command and about to display possible arguments. Mainly used with the tab_complete action.

custom_help_command_tab:
    type: player_tab_complete
    conditions:
    - '%main_command% == /help'
    - '%args_length% == 1 execute show_arguments_1'
    - '%args_length% == 2 and %arg_1% == worlds execute show_worlds_arguments'
    actions:
      show_arguments_1:
      - 'tab_complete: clear'
      - 'tab_complete: set;commands,economy,worlds'
      show_worlds_arguments:
      - 'tab_complete: set;overworld,nether,plots'

Variables:

• %main_command% (The command involved in this event)

• %args_length% (The current argument position of the command the player is trying to autocomplete)

• %arg_X% ( The argument in the X position of the command. If the command is /help worlds plots the %arg_1% variable would be "worlds" and the %arg_2% would be "plots")

This event will be detected ONLY if the command is already registered as a command, either by another plugin, or by ConditionalEvents. Remember that you can register commands on the register_commands option in the config.

Only works on 1.9+!