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_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
creature_spawn	Fired when a living entity spawns on the server.	type : reason: One of BREEDING, BUILD_IRONGOLEM, BUILD_SNOWMAN, BUILD_WITHER, CHUNK_GEN, CUSTOM, DEFAULT, EGG, JOCKEY, LIGHTNING, NATURAL, SLIME_SPLIT, SPAWNER, SPAWNER_EGG, VILLAGE_DEFENSE, VILLAGE_INVASION, or BED	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_damage	Fires when any loaded entity takes damage.	type: Macro The type of entity being damaged cause: Macro	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) 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.		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	amount	3.3.1
entity_death	Fires when any living entity dies.	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.	type: Macro The type of entity exploding. If null is used here, it will match events that lack a specific entity, such as using the explosion function	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
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 slotitem: Item Match	player: The player who clicked rightclick: true/false if this was a right click shiftclick: true/false if shift was being held 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:	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_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_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
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	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	player : 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 kick() them.	player: String Match join_message: Regex	player: The player's name 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: <custom> This should be a location array (x, y, z, world). The location is matched via block matching, so if the array's x parameter were 1, if the playermoved from 1.3, that parameter would match. to: <custom> 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_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: <custom> This should be a location array (x, y, z, world). The location is matched via block matching, so if the array's x parameter were 1, if the playermoved from 1.3, that parameter would match. to: <custom> 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
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: The location of the pressure plate activated: 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.	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
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
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		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