ctf

Class CTFBattleClass

java.lang.Object

ctf.CTFBattleClass

Direct Known Subclasses:

Archer, Tank

public abstract class CTFBattleClass
extends java.lang.Object

Generic class, implementations of which can be used as separate classes for CTF_V2 Minecraft Bukkit/Spigot plugin.
Needed imports are essential Bukkit imports and ctf.*.
When instantiating Bukkit Location, World argument should be getGameWorld().

IMPORTANT!!!
Scripting Guidelines:

• By contract, implementations of this class should not modify inventory of any other player except the assigned player. This player can be accessed with call getPlayer().
  
  
• By convention it is not permitted for a CTF Battle class implementation to teleport any entity outside the game world.
  
  
• It is not advised to write heavy code in abstract methods of this class, as that will impact overall server performance. In general each implementation should use maximum one lightweight timer registration.
  
  
• It is not efficient to make any initializations in constructor, so it is best to implement no constructor. All initializations should be done in onInitialization() method.
  
  
• To ensure that any abilities of this BattleClass implementation are actually recorded as damage dealt from this player, it is important to call setDamager(Player). Direct hits are registered automatically, so it is not recommended to set damager in CTFBattleClass#onEntityHit(Entity, double) to save performance.
  
  
• To set description of implementation simply create public static String field with variable name Description and assign String object that contains description.
  
  
• Modifying material of any block with Block.setMaterial(Material) or Block.setData(byte) is not recommended. Better solution is to call modifyBlock(Block, Material, byte, int).
  
  
• It is not recommended to register Bukkit events that are already handled in CTF Game Handler.
  
  
• Calling constructor of main plugin class will result in AssertionException or ExceptionInInitializerError.

CTF Game Handler handled events:
PlayerJoinEvent, PlayerQuitEvent, EntityDeathEvent, EntityDamageByEntityEvent, EntityExplodeEvent, InventoryClickEvent, PlayerInteractEntityEvent, PlayerInteractEvent, PlayerPickupItemEvent, PlayerDropItemEvent, EntityDamageEvent

FAQ:
Q: Why abstract methods are used and not annotation-driven event handler?
A: Because annotation-driven handling means use of native code to invoke registered methods, which is slower.
Also there can be multiple method registrations for one event, which will mean poorer performance.

Q: Is it possible to register Bukkit events in implementations?
A: Yes. It is but not advised unless current CTFBattleClass api doesnt provide enough handles. Call registerBukkitHandler() and register events as would be done in normal Bukkit plugin.

Q: How to setup new CTF Battle class?
A: Eclipse:

1) Create new project, add references Bukkit server jar and this plugin jar.
2) Create new class with the name of wanted battle class in 'default package' (no package) and extend it to this class ( MyBattleClass extends CTFBattleClass).
3) Eclipse will ask to add unimplemented methods or to make created class abstract, option to add unimplemented methods should be chosen.
4) Generated methods will appear in the class body, ready for modification.
5) [OPTIONAL] To add description to created battle class, add public static String field with name Description. String object with desired description should be assigned.

Method Summary

Methods

Modifier and Type	Method and Description
int	createExplosion(org.bukkit.Location location, float power) Creates explosion in specified location and returns affected blocks in an array. No blocks are destroyed in the game world.
org.bukkit.entity.Item	dropItem(org.bukkit.Location location, org.bukkit.inventory.ItemStack itemstack, int removedelay) Drops an item in game world. Negative values of removedelay will not start remove trigger.
org.bukkit.entity.Item	dropItemNaturally(org.bukkit.Location location, org.bukkit.inventory.ItemStack itemstack, int removedelay) Drops item with random offset in game world. Negative values of removedelay will not start remove trigger.
abstract org.bukkit.inventory.ItemStack[]	getArmor() This method must return armor contents array. Contents of returned array will not be modified in any way. Null values represent no armor for the slot. [0] = Helmet [1] = Chestplate [2] = Leggings [3] = Boots
abstract org.bukkit.inventory.ItemStack[]	getEquipment() This method must return inventory contents array. Contents of returned array will not be modified in any way. Null values represent no item for the slot. Indexes of items in the returned array will correspond to placement of those items in the inventory.
org.bukkit.World	getGameWorld() Gets current gameworld.
org.bukkit.entity.Player	getLastDamager() Gets last player that damaged this player.
org.bukkit.entity.Player	getPlayer() Gets player that chose this class.
TickTimer[]	getRegisteredTimers() Gets immutable array of currently active timers this CTFBattleClass instance has registered.
void	modifyBlock(org.bukkit.block.Block block, org.bukkit.Material material, byte data, int repairdelay) Sets target block's material and byte data.
abstract void	onAirLeftClick() Called when this player left-clicks no block.
abstract void	onAirRightClick() Called when this player right-clicks no block.
abstract void	onBlockLeftClick(org.bukkit.block.Block block) Called when this player left-clicks a block.
abstract void	onBlockRightClick(org.bukkit.block.Block block) Called when this player right-clicks a block.
abstract void	onDefeat(org.bukkit.entity.Player successor) Called when this player is killed by another player.
abstract void	onDropItem(org.bukkit.entity.Item item) Called when this players drops an item (default: Q).
abstract void	onEntityHit(org.bukkit.entity.Entity victim, double damage, CancelState cancel) Called when this player hits another entity.
abstract void	onEntityRightClick(org.bukkit.entity.Entity victim) Called when another entity gets right-clicked by this player.
abstract void	onExplosionCreated(int id, org.bukkit.block.Block[] blocks) Called when explosion happens that was earlier created by this instance.
abstract void	onGetHit(org.bukkit.entity.Entity damager, double damage) Called when this player is hit by another entity.
abstract void	onInitialization() Called when this class is first instantiated. This method can be safely used to add special effects to this player, register essential timers.
abstract void	onPlayerKill(org.bukkit.entity.Player victim) Called when this player kills another player.
void	playEffect(org.bukkit.Location location, org.bukkit.Effect effect, int paramInt) Plays specified effect in game world.
void	playSound(org.bukkit.Location location, org.bukkit.Sound sound, float paramFloat1, float paramFloat2) Plays specified sound in game world.
void	registerBukkitHandler() Deprecated. Handling Bukkit events directly can break CTF Game Handler mechanics.
TickTimer	registerNewRepeatingTask(java.lang.Runnable runnable, int delay) Registers new timer to be run at specified rate.
void	resetBlock(org.bukkit.block.Block block) Resets specified block to it's initial state if it was modified with modifyBlock(Block, Material, byte, int) call.
void	setDamager(org.bukkit.entity.Player victim) Sets this player as last damager of specfied player.
org.bukkit.entity.Arrow	spawnArrow(org.bukkit.Location location, org.bukkit.util.Vector vector, float paramFloat1, float paramFloat2, int removedelay) Spawns an arrow in game world. Negative values of removedelay will not start remove trigger. Arrows have special support to be removed when in ground.
org.bukkit.entity.LivingEntity	spawnCreature(org.bukkit.Location location, org.bukkit.entity.CreatureType creaturetype, int removedelay) Spawns living entity in game world. Negative values of removedelay will not start remove trigger.
org.bukkit.entity.Entity	spawnEntity(org.bukkit.Location location, org.bukkit.entity.EntityType entitytype, int removedelay) Spawns an entity in game world. Negative values of removedelay will not start remove trigger.
void	strikeLightningEffect(org.bukkit.Location location) Plays lightning strike effect in game world.
void	unregisterBukkitHandler() Deprecated. registerBukkitHandler()

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

spawnEntity

public final org.bukkit.entity.Entity spawnEntity(org.bukkit.Location location,
                                   org.bukkit.entity.EntityType entitytype,
                                   int removedelay)
                                           throws InstanceDisposedException

Spawns an entity in game world.
Negative values of removedelay will not start remove trigger.

Parameters:

location - location of spawned entity

entitytype - type of entity to spawn

removedelay - delay in ticks after which spawned item will be removed

Returns:

Entity that was spawned.

Throws:

InstanceDisposedException

spawnCreature

public final org.bukkit.entity.LivingEntity spawnCreature(org.bukkit.Location location,
                                           org.bukkit.entity.CreatureType creaturetype,
                                           int removedelay)
                                                   throws InstanceDisposedException

Spawns living entity in game world.
Negative values of removedelay will not start remove trigger.

Parameters:

location - location of spawned entity

creaturetype - type of entity

removedelay - delay in ticks after which spawned item will be removed

Returns:

LivingEntity that was spawned.

Throws:

InstanceDisposedException

spawnArrow

public final org.bukkit.entity.Arrow spawnArrow(org.bukkit.Location location,
                                 org.bukkit.util.Vector vector,
                                 float paramFloat1,
                                 float paramFloat2,
                                 int removedelay)
                                         throws InstanceDisposedException

Spawns an arrow in game world.
Negative values of removedelay will not start remove trigger.
Arrows have special support to be removed when in ground.

Parameters:

location - location of spawned arrow

vector - direction of spawned arrow

paramFloat1 - undocumented

paramFloat2 - undocumented

removedelay - delay in ticks after which spawned item will be removed

Returns:

Arrow that was spawned

Throws:

InstanceDisposedException

dropItem

public final org.bukkit.entity.Item dropItem(org.bukkit.Location location,
                              org.bukkit.inventory.ItemStack itemstack,
                              int removedelay)
                                      throws InstanceDisposedException

Drops an item in game world.
Negative values of removedelay will not start remove trigger.

Parameters:

location - location of the drop

itemstack - itemstack of the drop

removedelay - delay in ticks after which spawned item will be removed

Returns:

Item that was dropped.

Throws:

InstanceDisposedException

dropItemNaturally

public final org.bukkit.entity.Item dropItemNaturally(org.bukkit.Location location,
                                       org.bukkit.inventory.ItemStack itemstack,
                                       int removedelay)
                                               throws InstanceDisposedException

Drops item with random offset in game world.
Negative values of removedelay will not start remove trigger.

Parameters:

location - location of the drop

itemstack - itemstack of the drop

removedelay - delay in ticks after which spawned item will be removed

Returns:

Item that was dropped.

Throws:

InstanceDisposedException

playEffect

public final void playEffect(org.bukkit.Location location,
              org.bukkit.Effect effect,
              int paramInt)
                      throws InstanceDisposedException

Plays specified effect in game world.

Parameters:

location - location of the effect

effect - effect type

paramInt - undocumented

Throws:

InstanceDisposedException

playSound

public final void playSound(org.bukkit.Location location,
             org.bukkit.Sound sound,
             float paramFloat1,
             float paramFloat2)
                     throws InstanceDisposedException

Plays specified sound in game world.

Parameters:

location - location of sound effect

sound - sound type

paramFloat1 - undocumented

paramFloat2 - undocumented

Throws:

InstanceDisposedException

strikeLightningEffect

public final void strikeLightningEffect(org.bukkit.Location location)
                                 throws InstanceDisposedException

Plays lightning strike effect in game world.

Parameters:

location - location of lightning strike effect

Throws:

InstanceDisposedException

createExplosion

public final int createExplosion(org.bukkit.Location location,
                  float power)
                          throws InstanceDisposedException

Creates explosion in specified location and returns affected blocks in an array.
No blocks are destroyed in the game world.

Parameters:

location - location of explosion

power - strength of explosion

Returns:

ID number of explosion created.

Throws:

InstanceDisposedException

registerNewRepeatingTask

public final TickTimer registerNewRepeatingTask(java.lang.Runnable runnable,
                                 int delay)
                                         throws InstanceDisposedException

Registers new timer to be run at specified rate.

Parameters:

runnable - repeating task to be run

delay - delay between task invocations, must be more than 0

Returns:

TickTimer object to control this timer.

Throws:

InstanceDisposedException

getRegisteredTimers

public final TickTimer[] getRegisteredTimers()
                                      throws InstanceDisposedException

Gets immutable array of currently active timers this CTFBattleClass instance has registered.

Throws:

InstanceDisposedException

registerBukkitHandler

@Deprecated
public final void registerBukkitHandler()
                                 throws java.lang.UnsupportedOperationException

Deprecated. Handling Bukkit events directly can break CTF Game Handler mechanics.

Registers this CTF Battle Class instance to receive Bukkit events directly. Note that this will not prevent events from being processed by CTF Game Handler, and altering event data may destabilize the game.
Only non-handled events should be registered and processed, unless Game Handler processing mechanism for handled event is well known. Such event should not be modified to let Game Handler process it.

Throws:

java.lang.UnsupportedOperationException - if this CTF Battle class implementation does not implement Bukkit Listener.

unregisterBukkitHandler

@Deprecated
public final void unregisterBukkitHandler()
                                   throws java.lang.UnsupportedOperationException

Deprecated. registerBukkitHandler()

Removes this CTF Battle class instance from Bukkit event handler registry.

Throws:

java.lang.UnsupportedOperationException - if this CTF Battle class implementation does not implement Bukkit Listener.

modifyBlock

public final void modifyBlock(org.bukkit.block.Block block,
               org.bukkit.Material material,
               byte data,
               int repairdelay)
                       throws InstanceDisposedException

Sets target block's material and byte data. Specified block will be repaired after repairdelay ticks elapse. To cancel repair specify negative repairdelay. To revert block to it's initial state call resetBlock(Block).

Parameters:

block - target block

material - new material

data - new data

repairdelay - delay after which target block will be repaired

Throws:

InstanceDisposedException

See Also:

resetBlock(Block)

resetBlock

public final void resetBlock(org.bukkit.block.Block block)
                      throws InstanceDisposedException

Resets specified block to it's initial state if it was modified with modifyBlock(Block, Material, byte, int) call. Otherwise this call will have no effect on target block.

Parameters:

block - block to reset

Throws:

InstanceDisposedException

getGameWorld

public final org.bukkit.World getGameWorld()

Gets current gameworld. This method exists to provided entity teleportation manipulation. Entities should be spawned by calling final entity spawning methods of this class. However if performance is preferred then spawning entities through World is acceptable.

setDamager

public final void setDamager(org.bukkit.entity.Player victim)

Sets this player as last damager of specfied player.

Parameters:

victim - player to set damager

getLastDamager

public final org.bukkit.entity.Player getLastDamager()
                                              throws InstanceDisposedException

Gets last player that damaged this player.

Throws:

InstanceDisposedException

getPlayer

public final org.bukkit.entity.Player getPlayer()
                                         throws InstanceDisposedException

Gets player that chose this class.

Throws:

InstanceDisposedException

getArmor

public abstract org.bukkit.inventory.ItemStack[] getArmor()

This method must return armor contents array.
Contents of returned array will not be modified in any way.
Null values represent no armor for the slot.
[0] = Helmet
[1] = Chestplate
[2] = Leggings
[3] = Boots

getEquipment

public abstract org.bukkit.inventory.ItemStack[] getEquipment()

This method must return inventory contents array.
Contents of returned array will not be modified in any way.
Null values represent no item for the slot.
Indexes of items in the returned array will correspond to placement of those items in the inventory.

onPlayerKill

public abstract void onPlayerKill(org.bukkit.entity.Player victim)

Called when this player kills another player. Note that there is possibility that victim may be null.

Parameters:

victim - killed player

onDefeat

public abstract void onDefeat(org.bukkit.entity.Player successor)

Called when this player is killed by another player. Note that there is possibility that successor will be null.

Parameters:

successor - player that killed this player

onEntityHit

public abstract void onEntityHit(org.bukkit.entity.Entity victim,
               double damage,
               CancelState cancel)

Called when this player hits another entity.

Parameters:

victim - entity that was hit

damage - damage done to entity

cancel - CancelState object that monitors whether event is canceled

onGetHit

public abstract void onGetHit(org.bukkit.entity.Entity damager,
            double damage)

Called when this player is hit by another entity.

Parameters:

damager - another entity that hit this player

damage - damage that was done

onEntityRightClick

public abstract void onEntityRightClick(org.bukkit.entity.Entity victim)

Called when another entity gets right-clicked by this player.

Parameters:

victim - entity that was right-clicked

onBlockRightClick

public abstract void onBlockRightClick(org.bukkit.block.Block block)

Called when this player right-clicks a block.

Parameters:

block - block that was right-clicked

onBlockLeftClick

public abstract void onBlockLeftClick(org.bukkit.block.Block block)

Called when this player left-clicks a block.

Parameters:

block - block that was left-clicked

onAirRightClick

public abstract void onAirRightClick()

Called when this player right-clicks no block.

onAirLeftClick

public abstract void onAirLeftClick()

Called when this player left-clicks no block.

onDropItem

public abstract void onDropItem(org.bukkit.entity.Item item)

Called when this players drops an item (default: Q).

Parameters:

item - item that would be dropped.

onExplosionCreated

public abstract void onExplosionCreated(int id,
                      org.bukkit.block.Block[] blocks)

Called when explosion happens that was earlier created by this instance.

Parameters:

id - ID number of explosion

onInitialization

public abstract void onInitialization()

Called when this class is first instantiated.
This method can be safely used to add special effects to this player, register essential timers.