001 /**
002 * PluginListener.java - Extend this and register it to listen to specific
003 * hooks.
004 *
005 * @author Maine
006 */
007 public class PluginListener {
008
009 /**
010 * Priority - Used for priority for plugin listeners
011 */
012 public enum Priority {
013
014 /**
015 * Highly critical for hooks that absolutely must occur before any
016 * others. Use carefully.
017 */
018 CRITICAL,
019 /**
020 * May block/interrupt/undo the action, but prefer MEDIUM
021 */
022 HIGH,
023 /**
024 * Preferred priority for blocking/interrupting/undoing the action
025 */
026 MEDIUM,
027 /**
028 * Must not block/interrupt/undo the action
029 */
030 LOW
031 }
032
033 /**
034 * Called when a player moves from one block to another
035 *
036 * @param player
037 * player moving
038 * @param from
039 * previous block location
040 * @param to
041 * current block location
042 */
043 public void onPlayerMove(Player player, Location from, Location to) {
044 }
045
046 /**
047 * Called when a player teleports from one location to another
048 *
049 * @param player
050 * player moving
051 * @param from
052 * previous block location
053 * @param to
054 * current block location
055 * @return false if you want the player to teleport.
056 */
057 public boolean onTeleport(Player player, Location from, Location to) {
058 return false;
059 }
060
061 /**
062 * Called during the early login process to check whether or not to kick the
063 * player
064 *
065 * @param user
066 * @return kick reason. null if you don't want to kick the player.
067 */
068 public String onLoginChecks(String user) {
069 return null;
070 }
071
072 /**
073 * Called during the later login process
074 *
075 * @param player
076 */
077 public void onLogin(Player player) {
078 }
079
080 /**
081 * Called on player disconnect
082 *
083 * @param player
084 */
085 public void onDisconnect(Player player) {
086 }
087
088 /**
089 * Called when a player talks. If you return true the message won't be sent
090 * out.
091 *
092 * @param player
093 * @param message
094 * @return false if you want the message to be sent.
095 */
096 public boolean onChat(Player player, String message) {
097 return false;
098 }
099
100 /**
101 * Called before the command is parsed. Return true if you don't want the
102 * command to be parsed.
103 *
104 * @param player
105 * @param split
106 * @return false if you want the command to be parsed.
107 */
108 public boolean onCommand(Player player, String[] split) {
109 return false;
110 }
111
112 /**
113 * Called before the console command is parsed. Return true if you don't
114 * want the server command to be parsed by the server.
115 *
116 * @param split
117 * @return false if you want the command to be parsed.
118 */
119 public boolean onConsoleCommand(String[] split) {
120 return false;
121 }
122
123 /**
124 * Called when a player is banned
125 *
126 * @param mod
127 * moderator that's banning
128 * @param player
129 * player being banned
130 * @param reason
131 * reason for ban
132 */
133 public void onBan(Player mod, Player player, String reason) {
134 }
135
136 /**
137 * Called when a player is IP banned
138 *
139 * @param mod
140 * moderator that's banning
141 * @param player
142 * player being banning
143 * @param reason
144 * for IP ban
145 */
146 public void onIpBan(Player mod, Player player, String reason) {
147 }
148
149 /**
150 * Called when a player is kicked
151 *
152 * @param mod
153 * moderator that's kicking
154 * @param player
155 * player being kicked
156 * @param reason
157 * reason for kick
158 */
159 public void onKick(Player mod, Player player, String reason) {
160 }
161
162 /**
163 * Called when someone presses right click aimed at a block.
164 * You can intercept this to add your own right click actions
165 * to different item types (see itemInHand)
166 *
167 * @param player
168 * @param blockPlaced
169 * @param blockClicked
170 * @param itemInHand
171 * @return false if you want the action to go through
172 *
173 * @deprecated use onBlockRightClick to get the information
174 * @see #onBlockRightClicked(Player, Block, Item)
175 * @see #onBlockPlace(Player, Block, Block, Item)
176 * @see #onItemUse(Player, Block, Block, Item)
177 */
178 @Deprecated
179 public boolean onBlockCreate(Player player, Block blockPlaced, Block blockClicked, int itemInHand) {
180 return false;
181 }
182
183 /**
184 * Called when a person left clicks a block.
185 *
186 * @param player
187 * @param block
188 * @return
189 */
190 public boolean onBlockDestroy(Player player, Block block) {
191 return false;
192 }
193
194 /**
195 * Called when a person actually breaks the block.
196 *
197 * @param player
198 * @param block
199 * @return
200 */
201 public boolean onBlockBreak(Player player, Block block) {
202 return false;
203 }
204
205 /**
206 * Called when a player swings their arm, aka left clicks (even if no block
207 * is in front of them)
208 *
209 * @param player
210 * player swinging
211 */
212 public void onArmSwing(Player player) {
213 }
214
215 /**
216 * Called when a player drops an item.
217 *
218 * @param player
219 * player who dropped the item
220 * @param item
221 * item that was dropped
222 * @return true if you don't want the dropped item to be spawned in the
223 * world
224 */
225 public boolean onItemDrop(Player player, Item item) {
226 return false;
227 }
228
229 /**
230 * Called when a player picks up an item.
231 *
232 * @param player
233 * player who picked up the item
234 * @param item
235 * item that was picked up
236 * @return true if you want to leave the item where it was
237 */
238 public boolean onItemPickUp(Player player, Item item) {
239 return false;
240 }
241
242 /**
243 * Called when either a lava block or a lighter tryes to light something on fire.
244 * block status depends on the light source:
245 * 1 = lava.
246 * 2 = lighter (flint + steel).
247 * 3 = spread (dynamic spreading of fire).
248 * @param block block that the fire wants to spawn in.
249 * @param player player
250 * @return true if you dont want the fire to ignite.
251 */
252 public boolean onIgnite(Block block, Player player) {
253 return false;
254 }
255
256 /**
257 * Called when a dynamite block or a creeper is triggerd.
258 * block status depends on explosive compound:
259 * 1 = dynamite.
260 * 2 = creeper.
261 * @param block
262 * dynamite block/creeper location block.
263 *
264 * @return true if you dont the block to explode.
265 */
266 public boolean onExplode(Block block) {
267 return false;
268 }
269
270 /**
271 * Called when fluid wants to flow to a certain block.
272 * (10 & 11 for lava and 8 & 9 for water)
273 *
274 * @param blockFrom
275 * the block where the fluid came from.
276 * (blocktype = fluid type)
277 * @param blockTo
278 * the block where fluid wants to flow to.
279 *
280 *
281 * @return true if you dont want the substance to flow.
282 */
283 public boolean onFlow(Block blockFrom, Block blockTo) {
284 return false;
285 }
286
287 /**
288 * @param mob Mob attempting to spawn.
289 * @return true if you dont want mob to spawn.
290 */
291 public boolean onMobSpawn(Mob mob) {
292 return false;
293 }
294
295 /**
296 * Called when a living object is attacked.
297 * tip:
298 * Use isMob() and isPlayer() and getPlayer().
299 *
300 * @param type
301 * type of damage dealt.
302 * @param attacker
303 * object that is attacking.
304 * @param defender
305 * object that is defending.
306 * @param amount
307 * amount of damage dealt.
308 *
309 * @return
310 */
311 public boolean onDamage(PluginLoader.DamageType type, BaseEntity attacker, BaseEntity defender, int amount) {
312 return false;
313 }
314
315 /**
316 * Called when a players health changes.
317 * @param player
318 * the player which health is changed.
319 * @param oldValue
320 * old lives value
321 * @param newValue
322 * new lives value
323 * @return
324 * return true to stop the change.
325 */
326 public boolean onHealthChange(Player player, int oldValue, int newValue) {
327 return false;
328 }
329
330 /**
331 * Called whenever a redstone source (wire, switch, torch) changes its
332 * current.
333 *
334 * Standard values for wires are 0 for no current, and 14 for a strong current.
335 * Default behaviour for redstone wire is to lower the current by one every
336 * block.
337 *
338 * For other blocks which provide a source of redstone current, the current
339 * value will be 1 or 0 for on and off respectively.
340 *
341 * @param block
342 * @param oldLevel the old current
343 * @param newLevel the new current
344 * @return the new current to use (newLevel to leave as-is)
345 */
346 public int onRedstoneChange(Block block, int oldLevel, int newLevel) {
347 return newLevel;
348 }
349
350 /**
351 * Called when the game is checking the physics for a certain block.
352 * This method is called frequently whenever a nearby block is changed,
353 * or if the block has just been placed.
354 * Currently the only supported blocks are sand, gravel and portals.
355 *
356 * @param block Block which requires special physics
357 * @param placed True if block was just placed
358 * @return true if you do want to stop the default physics for this block
359 */
360 public boolean onBlockPhysics(Block block, boolean placed) {
361 return false;
362 }
363
364 /**
365 * Called when you place a vehicle.
366 *
367 * @param vehicle the vehicle placed
368 */
369 public void onVehicleCreate(BaseVehicle vehicle) {
370
371 }
372
373 /**
374 * Called when vehicle receives damage
375 *
376 * @param vehicle
377 * @param attacker entity that dealt the damage
378 * @param damage
379 * @return false to set damage
380 */
381 public boolean onVehicleDamage(BaseVehicle vehicle, BaseEntity attacker, int damage) {
382 return false;
383 }
384
385 /**
386 * Called when a vehicle changes speed
387 *
388 * @param vehicle the vehicle
389 */
390 public void onVehicleUpdate(BaseVehicle vehicle) {
391
392 }
393
394 /**
395 * Called when a collision occurs with a vehicle and an entity.
396 *
397 * @param vehicle the vehicle
398 * @param collisioner
399 * @return false to ignore damage
400 */
401 public Boolean onVehicleCollision(BaseVehicle vehicle, BaseEntity collisioner) {
402 return false;
403 }
404
405 /**
406 * Called when a vehicle is destroyed
407 *
408 * @param vehicle the vehicle
409 */
410 public void onVehicleDestroyed(BaseVehicle vehicle) {
411
412 }
413
414 /**
415 * Called when a player enter or leaves a vehicle
416 *
417 * @param vehicle the vehicle
418 * @param player the player
419 */
420 public void onVehicleEnter(BaseVehicle vehicle, HumanEntity player) {
421
422 }
423 /**
424 * Called when a vehicle changes block
425 * @param vehicle the vehicle
426 * @param x coordinate x
427 * @param y coordinate y
428 * @param z coordinate z
429 */
430 public void onVehiclePositionChange(BaseVehicle vehicle, int x, int y, int z) {
431
432 }
433
434 /**
435 * Called when a player uses an item (rightclick with item in hand)
436 * @param player the player
437 * @param blockPlaced where a block would end up when the item was a bucket
438 * @param blockClicked
439 * @param item the item being used (in hand)
440 * @return true to prevent using the item.
441 */
442 public boolean onItemUse(Player player, Block blockPlaced, Block blockClicked, Item item) {
443 return false;
444 }
445
446 /**
447 * Called when someone places a block. Return true to prevent the placement.
448 *
449 * @param player
450 * @param blockPlaced
451 * @param blockClicked
452 * @param itemInHand
453 * @return true if you want to undo the block placement
454 */
455 public boolean onBlockPlace(Player player, Block blockPlaced, Block blockClicked, Item itemInHand) {
456 return false;
457 }
458
459 /**
460 * Called when someone presses right click aimed at a block.
461 * You can intercept this to add your own right click actions
462 * to different item types (see itemInHand)
463 *
464 * @param player
465 * @param blockClicked
466 * @param itemInHand
467 */
468 public void onBlockRightClicked(Player player, Block blockClicked, Item item) {
469
470 }
471
472 /**
473 * Called when water or lava tries to populate a block, you can prevent
474 * crushing of torches, railways, flowers etc. You can alternatively allow
475 * to let normally solid blocks be crushed.
476 *
477 * @param currentState the current tristate, once it's set to a non DEFAULT_ACTION it is final.
478 * @param liquidBlock the type of the attacking block
479 * @param targetBlock the block to be destroyed
480 * @return final after a non DEFAULT_ACTION
481 */
482 public PluginLoader.HookResult onLiquidDestroy( PluginLoader.HookResult currentState, int liquidBlockId, Block targetBlock ) {
483 return PluginLoader.HookResult.DEFAULT_ACTION;
484 }
485
486 /**
487 * Called when an entity (attacker) tries to hurt a player (defender).
488 * Returning 'true' prevents all damage, returning 'false' lets the game handle it.
489 * Remember that the damage will be lessened by the amount of {@link LivingEntity#getLastDamage()}
490 * the defender has.
491 *
492 * @param attacker the giver
493 * @param defender the taker
494 * @param amount of damage the entity tries to do
495 * @return
496 */
497 public boolean onAttack(LivingEntity attacker, LivingEntity defender, Integer amount) {
498 return false;
499 }
500
501 /**
502 * Called when a player attempts to open an inventory; whether it's a
503 * workbench, a chest or their own player inventory
504 *
505 * @param player user who attempted to open the inventory
506 * @param inventory the inventory that they are attempting to open
507 * @return
508 */
509 public boolean onOpenInventory(Player player, Inventory inventory) {
510 return false;
511 }
512
513 /**
514 * Called when a sign is shown to a player, most often when they come into
515 * range of a sign.
516 *
517 * @param player Player who this sign is being shown to
518 * @param sign Sign which is being shown to the player
519 */
520 public void onSignShow(Player player, Sign sign) {
521 }
522
523 /**
524 * Called when a sign is changed by a player (Usually, when they first place it)
525 *
526 * @param player Player who changed the sign
527 * @param sign Sign which had changed
528 * @return true if you wish to cancel this change
529 */
530 public boolean onSignChange(Player player, Sign sign) {
531 return false;
532 }
533
534 /**
535 * Called when a leaf block is about to decay.
536 *
537 * @param block The leaf block about to decay
538 * @return true if you wish to stop the block from decaying
539 */
540 public boolean onLeafDecay(Block block) {
541 return false;
542 }
543
544 /**
545 * Called when the player places an inventory item, or adds amount to an existing inventory slot.
546 *
547 * @param player Player who placed their inventory item
548 * @param inventory The inventory that had an item placed
549 * @param placedItem The item (and amount) that was placed.
550 * @param oldSlot The slot that the item was placed in.
551 * @return true if you want the placement to be undone; false otherwise
552 */
553 public boolean onInventoryPlaceItem(Player player, Inventory inventory, Item placedItem, Integer slot) {
554 return false;
555 }
556
557 /**
558 * Called when the player takes an inventory item, whether they selected half or the whole slot.
559 *
560 * @param player Player who took their inventory item
561 * @param inventory The inventory that had an item taken
562 * @param takenItem The item (and amount) that was taken
563 * @param oldSlot The slot that the item was taken from.
564 * @return true if you want the taking to be undone; false otherwise
565 */
566 public boolean onInventoryTakeItem(Player player, Inventory inventory, Item takenItem, Integer slot) {
567 return false;
568 }
569
570 /**
571 * Called when a slot's contents are swapped with the contents of the cursor.
572 *
573 * @param player Player who swapped their inventory item
574 * @param inventory The inventory that had an item swapped
575 * @param slot The slot that had items swapped
576 * @param oldItemInSlot The old item in the slot, which is now on the cursor
577 * @param newItemInSlot The new item in the slot, which was on the cursor
578 * @return true if you want the swap to be undone; false otherwise
579 */
580 public boolean onInventoryCursorSwap(Player player, Inventory inventory, Integer slot, Item oldItemInSlot, Item newItemInSlot) {
581 return false;
582 }
583 }