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

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 DEATH

Event called when a player dies.

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

Variables:

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)

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

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 Z of the new location)

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

  • %to_x% (Coordinate X 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:

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

Variables:

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:

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:

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:

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:

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:

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

PreviousEvent TypesNextBlock Events

Last updated

Was this helpful?