CommandHelperStagedEvent API

Events allow you to trigger scripts not just on commands, but also on other actions, such as a player logging in, or a player breaking a block. See the documentation on events for more information

Event Name	Description	Prefilters	Event Data	Mutable Fields	Since
block_break	This event is called when a block is broken. Cancelling the event cancels the breakage.	player: String Match type: String Match data: String Match	player: The player's name block: An array with keys 'type' (int), 'data' (int), 'X' (int), 'Y' (int), 'Z' (int) and 'world' (string) for the physical location of the block location: the locationArray of this block drops : xp:	drops: : an array of arrays (with keys 'type' (string), 'qty' (int), 'data' (int), 'enchants' (array)) of items the block will drop xp: : the xp that this block will drop, if any	3.3.1
block_burn	This event is called when a block is burned. Cancelling the event cancels the burn.	type: String Match data: String Match	block: An array with keys 'type' (int), 'data' (int), 'X' (int), 'Y' (int), 'Z' (int) and 'world' (string) for the physical location of the block location: the locationArray of this block	block	3.3.1
block_dispense	This event is called when a dispenser dispense an item. Cancelling the event cancels dispensing.	type: String Match Type of dispenser item: Item Match Item which is dispensed	type: Type of dispenser item: Item which is dispensed velocity: Returns an associative array indicating the x/y/z components of item velocity. As a convenience, the magnitude is also included. location: Location of dispenser	item velocity	3.3.1
block_grow	This event is called when a block grows naturally. If the event is cancelled, the block will not grow.	oldtype: String Match The block type before the growth olddata: String Match The block data before the growth newtype: String Match The block type after the growth newdata: String Match The block data after the growth world: Macro	oldblock: The block before the growth (an array with keys 'type' and 'data') newblock: The block after the growth (an array with keys 'type' and 'data') location: the location of the block that will grow		3.3.1
block_ignite	This event is called when a block or entity is ignited.	player: String Match cause: Macro world: Macro	player: The player's name ignitingentity: entity ID, if entity is ignited ignitingblock: block ID, if block is ignited location: the locationArray of block or entity cause: the cause of ignition, one of: LAVA, FLINT_AND_STEEL, SPREAD, LIGHTNING, FIREBALL, ENDER_CRYSTAL, EXPLOSION		3.3.1
block_place	This event is called when a player places a block. Cancelling the event cancels placing the block.	player: String Match type: String Match data: String Match	player: The player's name type: numerical type id of the block being placed X: the X coordinate of the block Y: the Y coordinate of the block Z: the Z coordinate of the block world: the world of the block data: the data value for the block being placed against: the block being placed against oldblock: the blocktype and blockdata being replaced location: A locationArray for this block	type data	3.3.1
book_edited	This event is called when a player edit a book.	player: Macro The player which edited the book signing: Boolean Match Whether or not the book is being signed	player: The player which edited the book slot: The inventory slot number where the book is oldbook: The book before the editing (an array with keys title, author and pages) newbook: The book after the editing (an array with keys title, author and pages) signing: Whether or not the book is being signed	title author pages signing	3.3.1
creature_spawn	Fired when a living entity spawns on the server.	type: Macro reason: Macro One of BED, BREEDING, BUILD_IRONGOLEM, BUILD_SNOWMAN, BUILD_WITHER, CHUNK_GEN, CUSTOM, DEFAULT, EGG, JOCKEY, LIGHTNING, NATURAL, REINFORCEMENTS, SLIME_SPLIT, SPAWNER, SPAWNER_EGG, VILLAGE_DEFENSE, VILLAGE_INVASION, NETHER_PORTAL, or DISPENSE_EGG	type: the type of creature spawning id: the entityID of the creature reason: the reason this creature is spawning location: locationArray of the event	type: : Spawn a different entity instead. This will fire a new event with a reason of 'CUSTOM'.	3.3.1
entity_change_block	Fires when an entity change block in some way.	from: Math Match the block ID before the change to: Math Match the block ID after change location: Location Match the location of the block changed	entity: the entity ID of the entity which changed block from: the block ID before the change data: the data value for the block being changed to: the block ID after change location: the location of the block changed		3.3.1
entity_damage	Fires when any loaded entity takes damage.	id: Macro The entityID type: Macro The type of entity being damaged cause: Macro world: String Match	type: The type of entity the got damaged id: The entityID of the victim player: the player who got damaged (only present if type is PLAYER) world : location : cause: The type of damage amount : damager: If the source of damage is a player this will contain their name, otherwise it will be the entityID of the damager (only available when an entity causes damage) shooter: The name of the player who shot, otherwise the entityID (only available when damager is a projectile)	amount: : the amount of damage recieved (in half hearts)	3.3.1
entity_damage_player	This event is called when a player is damaged by another entity.	id: Macro The entityID damager: String Match	player: The player being damaged damager: The type of entity causing damage amount: amount of damage caused cause: the cause of damage data: the attacking player's name or the shooter if damager is a projectile id: EntityID of the damager location:	amount	3.3.1
entity_death	Fires when any living entity dies.	id: Macro The entityID type: Macro The type of entity dying.	type : id: The entityID drops: an array of item arrays of each stack xp : cause: the last entity_damage object for this entity location: where the entity was when it died	drops: : an array of item arrays of what will be dropped, replaces the normal drops, can be null xp: : the amount of xp to drop	3.3.1
entity_enter_portal	Fires when an entity touches a portal block.	type: Macro the type of entity block: Math Match the blockID of the portal	id: the entityID of the entity location: the location of the block touched type : block:		3.3.1
entity_explode	Fires when an explosion occurs. The entity itself may not exist if triggered by a plugin. Cancelling this event only protects blocks, entities are handled in damage events.	id: Macro The entityID. If null is used here, it will match events that lack a specific entity, such as using the explosion function. type: Macro The type of entity exploding. Can be null, as id.	id: entityID, or null if no entity type: entitytype, or null if no entity location: where the explosion occurs blocks : yield:	blocks: : An array of blocks destroyed by the explosion. yield: : Percent of the blocks destroyed that should drop items. A value greater than 100 will cause more drops than the original blocks.	3.3.1
exp_change	Fired when a player's experience changes naturally.	player: Macro	player : amount:	amount: : the amount of exp the player will recieve	3.3.1
gamemode_change	Fires when something causes a player's gamemode to change. Cancelling the event will cancel the change. The mode itself cannot be modified.	newmode: Macro gamemode being changed to player: Macro	player: player whose mode is changing newmode:		3.3.1
hanging_break	This event is called when a hanged entity is broken.	type: Macro The entity type of the hanging entity cause: Macro The cause of the removing world: Macro	id: The entityID of the hanging entity type: The entity type of the hanging entity, can be ITEM_FRAME, PAINTING or LEASH_HITCH cause: The cause of the removing, can be DEFAULT, ENTITY, EXPLOSION, OBSTRUCTION, or PHYSICS location: Where was the hanging entity before the removing remover: If the hanging entity has been removed by an other entity, this will contain its entityID, otherwise null player: If the hanging entity has been removed by a player, this will contain their name, otherwise null		3.3.1
inventory_click	Fired when a player clicks a slot in any inventory.	slottype: Macro The type of slot being clicked, can be ARMOR, CONTAINER, CRAFTING, FUEL, OUTSIDE, QUICKBAR, or RESULT clicktype: Macro One of LEFT, SHIFT_LEFT, RIGHT, SHIFT_RIGHT, WINDOW_BORDER_LEFT, WINDOW_BORDER_RIGHT, MIDDLE, NUMBER_KEY, DOUBLE_CLICK, DROP, CONTROL_DROP, CREATIVE, or UNKNOWN action: Macro One of NOTHING, PICKUP_ALL, PICKUP_SOME, PICKUP_HALF, PICKUP_ONE, PLACE_ALL, PLACE_SOME, PLACE_ONE, SWAP_WITH_CURSOR, DROP_ALL_CURSOR, DROP_ONE_CURSOR, DROP_ALL_SLOT, DROP_ONE_SLOT, MOVE_TO_OTHER_INVENTORY, HOTBAR_MOVE_AND_READD, HOTBAR_SWAP, CLONE_STACK, COLLECT_TO_CURSOR, or UNKNOWN slotitem: Item Match	player: The player who clicked viewers: everyone looking in this inventory leftclick: true/false if this was a left click keyboardclick: true/false if a key was pressed rightclick: true/false if this was a right click shiftclick: true/false if shift was being held creativeclick: true/false if this action could only be performed in creative mode slot: the number of the slot rawslot: the number of the slot in whole inventory window slottype : slotitem : inventorytype : inventorysize: number of slots in opened inventory cursoritem : inventory: all the items in the (top) inventory clicktype : action:	slotitem: : the item currently in the clicked slot cursoritem: : the item on the cursor	3.3.1
inventory_close	Fired when a player closes an inventory.		player: The player inventory: the inventory items in this inventory inventorytype: type of inventory		3.3.1
inventory_drag	Fired when a player clicks (by left or right mouse button) a slot in inventory and drag mouse across slots.	world: String Match World name type: Macro Can be SINGLE, or EVEN cursoritem: Item Match item in hand, before event starts	player: The player who clicked newcursoritem: item on cursor, after event oldcursoritem: item on cursor, before event slots: used slots rawslots: used slots, as the numbers of the slots in whole inventory window newitems: array of items which are dropped in selected slots inventorytype : inventorysize: number of slots in opened inventory	cursoritem: : the item on the cursor, after event	3.3.1
inventory_open	Fired when a player opens an inventory.		player: The player inventory: the inventory items in this inventory inventorytype: type of inventory		3.3.1
item_drop	This event is called when a player drops an item.	player: String Match item: Item Match	player: The player item: An item array representing the item being dropped.	item: : setting this to null removes the dropped item	3.3.1
item_enchant	Fired when a player enchants an item.		player: The player that enchanted the item item: The item to be enchanted inventorytype: type of inventory levels: The amount of levels the player used enchants: Array of added enchantments location: Location of the used enchantment table option: The enchantment option the player clicked	levels: : The amount of levels to use item: : The item to be enchanted enchants: : The enchants to add to the item	3.3.1
item_held	Fires when a player changes which quickbar slot they have selected.		player : to : from: the slot the player is switching from	to: : the slot that the player is switching to	3.3.1
item_pickup	This event is called when a player picks up an item.	player: String Match item: Item Match	player: The player item: An item array representing the item being picked up remaining: Other items left on the ground.	item: : setting this to null will remove the item from the world	3.3.1
item_pre_craft	Fires when a recipe is formed in a crafting matrix, but the result has not yet been clicked.		viewers: all humanentities viewing the screen this event takes place in matrix : result : isRepair: true if this event was triggered by a repair operation (different than normal crafting) recipe: information about the formed recipe, or null if there is not one		3.3.1
item_pre_enchant	Fired when a player places an item in an enchantment table		player: The player that placed the item item: The item to be enchanted inventorytype: Type of inventory enchantmentbonus: the amount of bookshelves influencing the enchantment table expcosts: The offered costs of the 3 options location: Location of the used enchantment table	item: : The item to be enchanted expcosts: : The costs of the 3 options on the enchantment table	3.3.1
item_spawn	Fires when an item entity comes into existance.	item: Item Match the item id and data value to check	location: where the item spawns id: the item's entityID item:	item: : the itemstack of the entity	3.3.1
player_chat	Fired when any player attempts to send a chat message.	player: Macro	message: The message to be sent recipients : format:	message recipients: : An array of players that will recieve the chat message. If a player doesn't exist or is offline, and is in the array, it is simply ignored, no exceptions will be thrown. format: : The "printf" format string, by default: "<%1$s> %2$s". The first parameter is the player's display name, and the second one is the message.	3.3.0
player_command	This event is fired off when a player runs any command at all. This actually fires before normal CommandHelper aliases, allowing you to insert control before defined aliases, even.	command: String Match The entire command the player ran prefix: String Match Just the first part of the command, i.e. '/cmd' in '/cmd blah blah' player: Macro The player using the command	command: The entire command prefix: Just the prefix of the command	command	3.3.1
player_consume	Fires as a player is finishing eating/drinking an item. Cancelling the event will cause any effects to not be applied and the item to not be taken from the player.	item: Item Match	player: the player consuming item: the item being consumed	item: : A different item to be consumed, changing this will cause the original item to remain in the inventory	3.3.1
player_death	Fired when a player dies.	player: Macro	player: The player that died drops: An array of the dropped items xp: The xp that will be dropped cause: The cause of death death_message: The death message keep_level : new_level: the player's level when they respawn killer: The name of the killer, if a player killed them, otherwise, null	xp drops: : An array of item objects, or null. The items to be dropped are replaced with the given items, not added to death_message: : the death message, or null to remove it entirely keep_level: : if true, the player will not lose their xp and levels new_level	3.3.0
player_enter_bed	Fires when a player tries to enter a bed.	location: The location of the bed	location: The location of the bed player: The player associated with this event		3.3.1
player_fish	Fires when a player casts or reels a fishing rod	state: Macro Can be one of CAUGHT_ENTITY, CAUGHT_FISH, FAILED_ATTEMPT, FISHING, or IN_GROUND player: Macro The player who is fishing world: String Match	player : world : state : chance : xp : hook: the fishhook entity caught: the id of the snared entity, can be a fish item	chance: : the chance of catching a fish from pulling the bobber at random xp: : the exp the player will get from catching a fish	3.3.1
player_interact	Fires when a player left or right clicks a block or the air	block: Item Match If the block the player interacts with is this button: String Match left or right. If they left or right clicked item: Item Match The item they are holding when they interacted player: String Match The player that triggered the event	action: One of either: left_click_block, right_click_block, left_click_air, or right_click_air block: The id of the block they clicked, or 0 if they clicked the air. If they clicked the air, neither facing or location will be present. player: The player associated with this event facing: The (lowercase) face of the block they clicked. (One of NORTH, EAST, SOUTH, WEST, UP, DOWN, NORTH_EAST, NORTH_WEST, SOUTH_EAST, SOUTH_WEST, WEST_NORTH_WEST, NORTH_NORTH_WEST, NORTH_NORTH_EAST, EAST_NORTH_EAST, EAST_SOUTH_EAST, SOUTH_SOUTH_EAST, SOUTH_SOUTH_WEST, WEST_SOUTH_WEST, or SELF) location: The (x, y, z, world) location of the block they clicked		3.3.0
player_interact_entity	Fires when a player right clicks an entity. Note, not all entities are clickable.	clicked: the type of entity being clicked	player: the player clicking clicked : id: the id of the entity data: if a player is clicked, this will contain their name		3.3.1
player_join	This event is called when a player logs in. Setting join_message to null causes it to not be displayed at all. Cancelling the event does not prevent them from logging in. Instead, you should just pkick() them.	player: String Match world: String Match join_message: Regex	player: The player's name world : join_message: The default join message first_login: True if this is the first time the player has logged in.	join_message	3.3.0
player_kick	Fired when a player is kicked from the game.	player: Macro reason: Macro	player: the kicked player message: the message shown to all online players reason: the message shown to the player getting kicked	message reason	3.3.1
player_leave_bed	Fires when a player leaves a bed.	location: The location of the bed	location: The location of the bed player: The player associated with this event		3.3.1
player_login	This event is called when a player is about to log in. This event cannot be cancelled. Instead, you can deny them by setting 'result' to KICK_BANNED, KICK_WHITELIST, KICK_OTHER, or KICK_FULL. The default for 'result' is ALLOWED. When setting 'result', you can specify the kick message by modifying 'kickmsg'.	player: String Match	player: The player's name kickmsg: The default kick message ip: the player's IP address result: the default response to their logging in	kickmsg result	3.3.1
player_move	This event is fired off AFTER a player has moved. This is a read only event because of this, however, the determination logic is run asynchronously from the main server thread, so general detection of a movement will not cause any lag, beyond lag caused by any other thread. Prefilters are extremely important to use however, because the prefilter code is also run asynchronously, however your code is not, and therefore, is slower. It is also advisable to use a threshold, so you are not firing an event every time a player moves. A threshold of 5 or 10 will likely be sufficient for all use cases, and should considerably reduce server thread resources. Though this event is read only, you can "cancel" the event by moving the player back to the from location, or otherwise "change" the location by using set_ploc(). Note that on a server with lots of players, this "stride" distance, that is, the distance a player will have moved before the event picks it up will be greater. The movement detection thread is slightly throttled.	player: Macro The player that moved. Switching worlds does not trigger this event. from: Location Match This should be a location array (x, y, z, world). to: Location Match The location the player is now in. This should be a location array as well. threshold: <custom> The minimum distance the player must have travelled before the event will be triggered. This is based on the 3D distance, and is measured in block units.	player : from: The location the player is coming from to: The location the player is now in		3.3.1
player_portal_travel	Fired when a player collides with portal.	player: Macro from: Location Match This should be a location array (x, y, z, world). to: Location Match The location the player is coming to. This should be a location array as well. type: the type of portal occuring, one of: COMMAND, END_PORTAL, ENDER_PEARL, NETHER_PORTAL, PLUGIN, UNKNOWN	player: The player that teleport from: The location the player is coming from to: The location the player is coming to. Returns null when using Nether portal and "allow-nether" in server.properties is set to false or when using Ender portal and "allow-end" in bukkit.yml is set to false. type: the type of portal occuring creationradius: Gets the maximum radius from the given location to create a portal. searchradius: Gets the search radius value for finding an available portal.	to creationradius searchradius	3.3.1
player_prelogin	This event is called when a player is about to be authed. This event only fires if your server is in online mode. This event cannot be cancelled. Instead, you can deny them by setting 'result' to KICK_BANNED, KICK_WHITELIST, KICK_OTHER, or KICK_FULL. The default for 'result' is ALLOWED. When setting 'result', you can specify the kick message by modifying 'kickmsg'.	player: String Match	player: The player's name kickmsg: The default kick message ip: the player's IP address result: the default response to their logging in	kickmsg result	3.3.1
player_quit	Fired when any player quits.	player: Macro	message: The message to be sent	message	3.3.1
player_spawn	Fires when a player respawns. Technically during this time, the player is not considered to be 'online'. This can cause problems if you try to run an external command with run() or something. CommandHelper takes into account the fact that the player is offline, and works around this, so all CH functions should respond correctly, as if the player was online, however other plugins or plain text commands that are run may not.	x: Expression y: Expression z: Expression world: String Match player: Macro	player: The player that is respawning location: The location they are going to respawn at bed_spawn: True if the respawn location is the player's bed	location	3.3.0
player_teleport		player: Macro The player that teleport. Switching worlds will trigger this event, but world_changed is called after, only if this isn't cancelled first. from: Location Match This should be a location array (x, y, z, world). to: Location Match The location the player is now in. This should be a location array as well.	player : from: The location the player is coming from to: The location the player is now in type: the type of teleport occuring, one of: COMMAND, END_PORTAL, ENDER_PEARL, NETHER_PORTAL, PLUGIN, UNKNOWN	to	3.3.1
player_toggle_flight	Called when a player toggles their flying state.	player: Macro The player who toggled their flying state flying: Boolean Match Whether or not the player is trying to start or stop flying world: Macro	player: The player who toggled their flying state flying: Whether or not the player is trying to start or stop flying location: Where the player is		3.3.1
player_toggle_sneak	Called when a player toggles their sneaking state.	player: Macro The player who toggled their sneaking state sneaking: Boolean Match Whether or not the player is now sneaking world: Macro	player: The player who toggled their sneaking state sneaking: Whether or not the player is now sneaking location: Where the player is		3.3.1
player_toggle_sprint	Called when a player toggles their sprinting state.	player: Macro The player who toggled their sprinting state sprinting: Boolean Match Whether or not the player is now sprinting world: Macro	player: The player who toggled their sprinting state sprinting: Whether or not the player is now sprinting location: Where the player is		3.3.1
plugin_message_received	Fires when a player's client sends a plugin message.	channel: String Match	player: the player channel: the channel used bytes: byte array of the data sent		3.3.1
pressure_plate_activated	Fires when a player steps on a pressure plate	location: Location Match The location of the pressure plate activated: Boolean Match If true, only will trigger when the plate is stepped on. Currently, this will only be true, since the event is only triggered on activations, not deactivations, but is reserved for future use.	location: The location of the pressure plate activated: If true, then the player has stepped on the plate, if false, they have gotten off of it. Currently, this will always be true, because the event is only triggered for activations, not deactivations, but is reserved for future use. player: The player associated with this event		3.3.1
projectile_hit	Fires when a projectile collides with something.	id: Macro The entityID type: Macro the entity type of the projectile	type : id: the entityID of the projectile location: where it makes contact shooter:	shooter: : the entityID of the mob/player that fired the projectile, or null if it is from a dispenser	3.3.1
projectile_launch	This event is called when a projectile is launched. Cancelling the event will only cancel the launching of the projectile. For instance when a player shoots an arrow with a bow, if the event is cancelled the bow will still take damage from use.	type: Macro The entity type of the projectile world: Macro shootertype: Macro The entity type of the shooter, or 'block', or 'null'	id: The entityID of the projectile type: The entity type of the projectile shooter: The entityID of the shooter (null if the projectile is launched by a dispenser) shootertype: The entity type of the shooter (null if the projectile is launched by a dispenser) player: the player which has launched the projectile (null if the shooter is not a player) location: from where the projectile is launched velocity: the velocity of the projectile	velocity	3.3.1
server_ping	Fired when a user who has saved this server looks at their serverlist.	players: Math Match maxplayers: Math Match	ip: The address the ping is coming from players: the number of players online maxplayers: the number of slots on the server motd:	motd: : The message a player is shown on the serverlist maxplayers	3.3.1
sign_changed	This event is called when a player changes a sign. Cancelling the event cancels any edits completely.	player: String Match 1: Macro 2: Macro 3: Macro 4: Macro	player: The player's name location: an array usable as a locationArray while also compatible with X,Y,Z,world indices text: An array with keys 0 thru 3 defining every line on the sign	1 2 3 4 text: : An array with keys 0 thru 3 defining every line on the sign	3.3.1
tab_complete_chat	Fires when a player asks for a list of completions to the current word in their chat message. Setting the completions to an empty array is this event's equivalent of cancel().	player: Macro	player: the player asking for completion message: the full message they have typed last: the partial word completion is asked for completions:	completions: : the list of completions to send, default is player names containing the last text	3.3.1
tab_complete_command	This will fire if a tab completer has not been set, or if the set tab completer doesn't return an array.		command : alias : completions : args : sender:	completions	3.3.1
target_player	This event is called when a player is targeted by another entity.	player: String Match mobtype: Macro	player: The player's name mobtype: The type of mob targeting the player (this will be all capitals!) id: The EntityID of the mob	player: : target a different player, or null to make the mob re-look for targets	3.3.1
vehicle_collide	Fires when a vehicle runs into something. If it ran into a block, event data will contain block info. If it ran into an entity, event data will contain info and options relevant to hitting an entity.	type: Macro The entitytype of the vehicle collisiontype: Macro One of BLOCK or ENTITY hittype: Macro Matches an entitytype in an enitity collision hittype: Item Match Matches a block in a block collision	type : id: The entityID of the vehicle entity: the entityID of the entity that was hit block: the location of the block that was hit collisiontype : collide : pickup:	collide: : whether the vehicle hits the entity or passes through it pickup: : whether or not the vehicle pick up the entity both fields can only be modified for entity collisions	3.3.1
vehicle_enter	Fires when an entity enters a vehicle.	vehicletype: Macro the entitytype of the vehicle passengertype: Macro the enitytype of the passenger	vehicletype : passengertype : vehicle: entityID passenger: entityID player: player name if passenger is a player, null otherwise		3.3.1
vehicle_leave	Fires when an entity leaves a vehicle.	vehicletype: Macro the entitytype of the vehicle passengertype: Macro the enitytype of the passenger	vehicletype : passengertype : vehicle: entityID passenger: entityID player: player name if passenger is a player, null otherwise		3.3.1
vehicle_move	Fires when an vehicle is moving.	vehicletype: Macro the entitytype of the vehicle passengertype: Macro the enitytype of the passenger	from: Get the previous position to: Get the next position vehicletype : passengertype : id: entityID passenger: entityID player: player name if passenger is a player, null otherwise		3.3.1
world_changed	This event is fired off when a player changes worlds. This event is not cancellable, so to prevent it, the player_teleport event must be checked.	player: Macro The player that switched worlds from: String Match The world the player is coming from to: String Match The world the player is now in	player : from: The world the player is coming from to: The world the player is now in		3.3.1

Errors in documentation

Please note that this documentation is generated automatically, if you notice an error in the documentation, please file a bug report for the plugin itself! For information on undocumented functions, see this page