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.

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.

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.

You can't use cancel_event action on this event. 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.

PLAYER DEATH

Event called when a player dies.

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

Variables:

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)

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)

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

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 SWAP HAND

Event called when a player swap items between main hand and off hand using the hotkey.

example:
  type: player_swap_hand
  actions:
    default:
    - "cancel_event: true"

Variables:

  • ConditionalEvents item variables (for items in main hand and off hand)

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:

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:

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

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

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?