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-CR Minecraft Bukkit/Spigot plugin.
Needed imports are essential Bukkit imports and ctf.* with ctf.eventmanipulation.*.
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 onEntityHit(Entity, DamageState, CancelState, DamageType) 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. If that must be done see registerBukkitHandler().
  
  
• Do not call ANY damage functions from ANY Entity in ANY Damage events! This includes onGetHit(Entity, double, DamageType) and onEntityHit(Entity, DamageState, CancelState, DamageType) calls!!! Failing to do so will result in method looping and eventually OutOfMemotyError.
  
  
• It is discouraged to use any World.createExplosion([args]) as those methods do not raise EntityExplodeEvent and will result in permanent map damage until complete reload. Instead use createBlockExplosion(Location, float).
  
  
• If player right-clicks while holding Material.COOKED_BEEF, he/she will be healed by 5 hearts.
  
  
• Calling constructor of main plugin class will result in AssertionException or ExceptionInInitializerError.

CTF Game Handler handled events:
PlayerJoinEvent, PlayerQuitEvent, EntityDeathEvent, InventoryClickEvent, EntityDamageByEntityEvent, EntityExplodeEvent, PlayerInteractEntityEvent, PlayerInteractEvent, PlayerDropItemEvent, EntityChangeBlockEvent, PlayerPickupItemEvent, EntityDamageEvent, PlayerTeleportEvent, ProjectileHitEvent, ProjectileLaunchEvent, BlockBreakEvent, BlockPlaceEvent.


Included libraries for particle effects and NBT data modification are in lib package.

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.


API Setup Guide
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 any package (except 'ctf', 'defaultclassesand' and 'lib') then 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) File 'crcfg.yml' must be created in the project (outside src folder). It must contain 'CRclass' field and it's path must lead to main implementation class.
Example:
CRclass: com.rito.MyBattleClass
CRname: My Battle Class
CRdesc: [Rito's first, battle class, implementation]

Author:

Rito

Method Summary

Methods

Modifier and Type	Method and Description
org.bukkit.block.Block[]	createBlockExplosion(org.bukkit.Location loc, 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[]	getInGamePlayers() Gets all players that are in game.
org.bukkit.entity.Player	getLastDamager() Gets last player that damaged this player.
org.bukkit.entity.Player	getPlayer() Gets player that chose this class.
Team	getPlayerTeam(org.bukkit.entity.Player player) Used to determine player team.
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.inventory.ItemStack itemstack) Called when this players drops an item (default: Q). Note that no item is actually dropped.
abstract void	onEntityHit(org.bukkit.entity.Entity victim, DamageState damage, CancelState cancel, DamageType damagetype) 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	onGetHit(org.bukkit.entity.Entity damager, double damage, DamageType damagetype) 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.
abstract void	onProjectileLaunch(org.bukkit.entity.Projectile p, CancelState cancel)
void	registerBukkitHandler() Deprecated. Handling Bukkit events directly can break CTF Game Handler mechanics.
TickTimer	registerNewDelayedTask(java.lang.Runnable runnable, int delay) Registers new timer to be run once after specified delay.
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 speed, float spread, 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	unregisterBukkitHandler() Deprecated. registerBukkitHandler()

Methods inherited from class java.lang.Object

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

Method Detail

getInGamePlayers

public final org.bukkit.entity.Player[] getInGamePlayers()

Gets all players that are in game. It is recommended to use this method rather than Bukkit.getOnlinePlayers().
Note that each call of this method will construct new array object!

getPlayerTeam

public final Team getPlayerTeam(org.bukkit.entity.Player player)

Used to determine player team. Only intended to be used in custom handled events to determine correct damage application.

Parameters:

player - player to get team

Returns:

Team object that represents player's team. Note that Team objects should compared with == operator!

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 entity 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 entity 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 speed,
                                 float spread,
                                 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. If an arrow launched by this method hits an enemy team player, then onEntityHit(Entity, DamageState, CancelState, DamageType) is invoked.

Parameters:

location - location of spawned arrow

vector - direction of spawned arrow

speed - speed of the arrow, recommend 0.6

spread - spread of the arrow, recommend 12

removedelay - delay in ticks after which spawned arrow 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

createBlockExplosion

public final org.bukkit.block.Block[] createBlockExplosion(org.bukkit.Location loc,
                                            float power)
                                                    throws InstanceDisposedException

Creates explosion in specified location and returns affected blocks in an array.
No blocks are destroyed in the game world. No players will be damaged by this explosion. Implementation must obtain damaged players and check their teams to not to damage team mates with call getPlayerTeam(Player).
Note that CTFBattleClass#onBlockExplosionCreated(int, Block[], CancelState) will only be called when explosion is created using this method.

Parameters:

location - location of explosion

power - strength of explosion

Returns:

ID number of explosion created. CTFBattleClass#onBlockExplosionCreated(int, Block[], CancelState) provided ID will be the same as returned by this method if explosion registered was caused by call of this method.

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

registerNewDelayedTask

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

Registers new timer to be run once after specified delay.

Parameters:

runnable - task to be run

delay - delay after which task will be run

Returns:

TickTimer object to control this delayed task.

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.

Do not modify any event data of CTF Event Handler handled events! Handled events should only be read. Other events can be modified if and only if getPlayer() is involved in the action! It is recommended to use EventPriority.MONITOR in read-only events (those that are handled by CTF Game Handler).

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.
The player actually does not die (to avoid 'Respawn' button lag issue), so all effects will be kept. This method can be used to do clean-up of unwanted effects.

Parameters:

successor - player that killed this player

onEntityHit

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

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,
            DamageType damagetype)

Called when this player is hit by another entity.

Parameters:

damager - another entity that hit this player

damage - final 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.inventory.ItemStack itemstack)

Called when this players drops an item (default: Q).
Note that no item is actually dropped.

Parameters:

itemstack - itemstack of an item that would be dropped

onProjectileLaunch

public abstract void onProjectileLaunch(org.bukkit.entity.Projectile p,
                      CancelState cancel)

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.