Events

An event is something that happens at some instant of time. In MD, event routines are executed when a specific event occurs.

Listed here underneath each event are the names of the different "things" available to the routines in that event. In the various routine pages, when you see placeholders in the code like {entity}, the things named in each event are the things you can pick from to fill the placeholders.

Entities are anything in Minecraft that moves. This includes, players, pigs, arrows, primed-and-flashing-TNT-about-to-explode-in-your-face, etc.

Projectiles are arrows, eggs, snowballs, etc. They are also entities, and can be used anywhere an entity reference is needed.

Item Stacks are a stack of items. They have a type, a data integer, a durability, and an amount.

Integers are integer variables that relate directly to the event. The one marked (default) is the one that will be altered by change value routines.

All Entities and Projectiles can be used with the Type conditional to check what type they are.

Events

##Misc Events

Init

A compact event for Spawn and Reloading ModDamage. Optimal for starting or restarting a Repeat Event.
Entities: entity

Command

Repeat

##Player Events

Interact

Entities: player
Blocks interact_block
Conditionals: interact_left, interact_right, interact_air, interact_with_block

This happens when a player left or right clicks and doesn't happen to hit an entity. If the player does hit an entity, then left clicks become the Damage event, and right clicks become the InteractEntity event.

InteractEntity

Entities: player, target

This happens when a player right clicks an entity.

Join

Entities: player

This happens when a player joins the server.

LevelChange

Entities: player
Integers: oldlevel, newlevel

This happens when a player has enough experience to change from one level to the next.

PickupExp

Entities: player
Integers: experience (default)

This is fired whenever a player picks up experience orbs.

Quit

Entities: player

This happens when a player leaves the server. Be careful about relying on this for things like removing tags, because if the server crashes this won't be run.

Teleport

Entities: entity
Locations: from, to

This happens when an entity teleports directly from one location to another. There is also a special cause value that can be tested with a cause.is.{cause} conditional, where {cause} is one of these:

• COMMAND - Indicates the teleportation was caused by a player executing a command
• END_PORTAL - Indicates the teleportation was caused by a player entering an End portal
• ENDER_PEARL - Indicates the teleporation was caused by a player throwing an Ender Pearl
• NETHER_PORTAL - Indicates the teleportation was caused by a player entering a Nether portal
• PLUGIN - Indicates the teleportation was caused by a plugin
• UNKNOWN - Indicates the teleportation was caused by an event not covered by this enum

Note: cause will be 'null' if a non-player entity is used.

ToggleFlight

Entities: player

Happens when a player double jumps to enter or exit flying mode.

ToggleSneak

Entities: player

Happens when a player begins or finishes sneaking.

ToggleSprint

Entities: player

Happens when a player double-presses the Forward key to start sprinting, or lets go to stop sprinting.

Fish

##Item Events

DropItem

Entities: player
Item Stacks: item

This happens when a player drops an item from their inventory or from a chest or other storage unit. item refers to the item entity dropped.

PickupItem

Entities: player
Integers: remaining
Item Stacks: item

This happens when a player picks up a dropped item entity, and it is placed into the inventory. item refers to the item or block picked up, and remaining is the amount remaining on the ground, if any.

ItemHeld

Entities: player
Integers: prevslot, newslot

This happens when a player switches which item slot in their inventory is active. prevslot is the number of the previous slot they had active, newslot is the new, current one.

Enchant

Entities: player
Item Stacks: item
Integers: level

This happens when the player chooses an enchantment from the enchantment table. Changing level will affect the number of levels subtracted from the player.

PrepareEnchant

Entities: player
Item Stacks: item
Integers: bonus, level_1, level_2, level_3

This happens when a player places an item into the enchantment table. Bonus is the number of bookshelves nearby, and the levels are the numbers that will be displayed in each slot of the enchantment GUI. Please beware that this event is sent multiple times by Bukkit. It seems to be twice when the item is placed, and once when it is picked up, but be careful about relying on that behavior. Also note that MC will occasionally throw an exception if you set one of the levels above 50 and a player picks one of them.

##Block Events

BreakBlock

Entities: player
Blocks: block

Happens when a player breaks a block. Not triggered when anything else breaks a block, such as an explosion.

PlaceBlock

Entities: player
Blocks: block, againstBlock
Conditionals: canBuild

Happens when a player places a block. againstBlock is the block the player right-clicked to cause the event.

LeavesDecay

Blocks: block

Happens when a leaf decays due to no log nearby. Does not fire when a player breaks a leaf block.

BlockGrow

Blocks: block
Integers: newtypeid, newdata BlockTypes: newtype

Happens when Melon Stem, Melon, Pumpkin Stem, Pumpkin, Cactus, Wheat, Reeds, Potatoes, and Carrots grow from one stage into the next, or spawn the corresponding block next to the stem.

##Entity Events

Combust

Entities: player, combustor
Integers: block_type, block_data

This happens when an entity is lit on fire. If an entity, such as a WeatherStorm, Blaze, or player holding a FIRE_ASPECT enchanted item, is responsible, combustor will refer to them. Otherwise, block_type and block_data will refer to the type of block that caused the fire.

Damage

Entities: attacker, target
Projectiles: projectile
Damage Type: damage
Integers: damage (default)

This is the event ModDamage was originally created for. It happens any time an entity takes damage, whether from an arrow, mob attacking, fire, cactus, starving, etc.

Death

Entities: attacker, target
Projectiles: projectile
Damage Type: damage
Integers: damage, experience (default)

This happens when a living entity is killed. All the things are from the Damage event that caused the death, except the experience Integer.
An optional - 'clear.drops' routine may be used to cancel default mob drops in this event.

Explode

Entities: entity
Integers: yield

This happens when an entity explodes, such as creepers or TNT. (TNT is a block until it is primed, at which point it becomes an entity). yield refers to how big the explosion is, where 10 yield is the same as 1 block. Creepers will have a yield of 30, for instance.

Heal

Entities: entity
Integers: heal_amount (default)

Whenever an entity gains health, this is fired.

ProjectileHit

Entities: shooter
Projectiles: projectile
Blocks projectile_block, hitblock

This is fired when a projectile hits a block, not when it hits an entity.
projectile_block is the non-solid block the projectile is in before impact.
hitblock is the solid block the arrow is sticking out of when it impacts.
hitblock.is.none for all projectiles except arrow. [Bukkit Restriction]

###ProjectileLaunch
Entities: shooter, projectile

Happens whenever any projectile is thrown or shot out of an entity. Snowballs, fireballs, and arrows all throw this event, along with any other shoot/throwable item.

###ShootBow
Entities: shooter, projectile

Happens when a skeleton or player releases an arrow from a bow.

Spawn

Entities: entity
Integers: health (default)

This is fired whenever an entity spawns. Setting the health to 0 will cause the spawn to be canceled by Bukkit. There is also a special reason value that can be tested with a spawn_reason.is.{reason} conditional, where {reason} is one of these:

• BREEDING - When an animal breeds to create a child.
• BUILD_IRONGOLEM - When an iron golem is spawned by being built.
• BUILD_SNOWMAN - When a snowman is spawned by being built.
• CHUNK_GEN - When a creature spawns due to chunk generation.
• CUSTOM - When a creature is spawned by plugins. Expect this with Routine: Spawn Entity.
• DEFAULT - When an entity is missing a SpawnReason.
• TARGET_ATTACKED_OWNER - The target attacked the owner of the entity.
• EGG - When a creature spawns from an egg. Not a Spawn Egg.
• JOCKEY - When an entity spawns as a jockey of another entity (mostly spider jockeys).
• LIGHTNING - When a creature spawns because of a lightning strike.
• NATURAL - When something spawns from natural means.
• NONE - When there is no reason. Always the case with PLAYER spawns.
• SLIME_SPLIT - When a slime splits.
• SPAWNER - When a creature spawns from a spawner.
• SPAWNER_EGG - When a creature spawns from a Spawner Egg.
• VILLAGE_DEFENSE - When an iron golem is spawned to defend a village.
• VILLAGE_INVASION - When a zombie is spawned to invade a village.

Tame

Entities: target, tamer

Whenever an entity is tamed, currently Wolves and Ocelots.

Target

Entities: entity, target

This happens when an entity changes what it is targeting. There is also a special reason value that can be tested with a reason.is.{reason} conditional, where {reason} is one of these:

• TARGET_DIED - The entity's target has died.
• CLOSEST_PLAYER - The entity doesn't have a target, so it attacks the nearest player.
• TARGET_ATTACKED_ENTITY - The target attacked the entity.
• PIG_ZOMBIE_TARGET - The target attacked a fellow pig zombie, so the whole group will target him with this reason.
• FORGOT_TARGET - The target is forgotten for whatever reason. Occurs with spiders when there is a high brightness, and when the target is out of range.
• TARGET_ATTACKED_OWNER - The target attacked the owner of the entity.
• OWNER_ATTACKED_TARGET - The owner of the entity attacked the target.
• RANDOM_TARGET -The entity has no target, so it randomly chose one.
• DEFEND_VILLAGE - When an entity selects a target while defending a village.
• CUSTOM - For custom calls to the event.