Skip to main content

Developer API


description: Get the API and some examples

Full js documentation: https://jd.plajer.xyz/minecraft/villagedefense

warning

Contents may be not up to date! Please use js docs instead. Here you can only get some simple examples.

Maven repository #

Maven repository usually contains latest releases, if not, please check in few days if release is there.

How to access repo:

  1. Add repository
<repositories>
<repository>
<id>plugilyprojects</id>
<url>https://maven.plugily.xyz</url>
</repository>
</repositories>

2. Add the dependency

<dependencies>
<dependency>
<groupId>plugily.projects</groupId>
<artifactId>villagedefense</artifactId>
<version>{version}</version>
<scope>provided</scope>
</dependency>
</dependencies>

Events#

VillageGameJoinAttemptEvent (Cancellable)#

The event is called when a player is trying to join an arena.

Example:

@EventHandler
public void onGameJoin(VillageGameJoinAttemptEvent event){
e.getPlayer().sendMessage("You have joined " + e.getArena().getID());
e.setCancelled(true);
e.getPlayer().sendMessage("Or maybe not? :D");
}

event#getPlayer() - returns player involved in this event

event#getArena() - returns existing arena where player is attempting to join

event#isCancelled() - returns true if event is cancelled

caution

A message from language file is sent to the player when the attempt is cancelled (see In-Game.Join-Cancelled-Via-API in language.yml)

VillageGameStartEvent#

The event is called when the arena starts.

Example:

@EventHandler
public void onGameStart(VillageGameStartEvent event){
for(Player p : e.getArena().getPlayers()){
p.sendMessage("Game has started!");
}
}

event#getArena() - returns event arena

VillageGameStartEvent#

The event is called when the arena starts.

Example:

@EventHandler
public void onGameStart(VillageGameStartEvent event){
for(Player p : e.getArena().getPlayers()){
p.sendMessage("Game has started!");
}
}

event#getArena() - returns event arena

VillageGameLeaveAttemptEvent#

The event is called when a player is trying to leave an arena.

Example:

@EventHandler
public void onGameQuit(VillageGameLeaveAttemptEvent event){
e.getPlayer().sendMessage("You have quitted" + e.getArena().getID());
}

event#getPlayer() - returns player involved in this event

event#getArena() - returns existing arena what player is attempting to leave

VillageGameStopEvent#

The event is called when a game is stopped.

Example:

@EventHandler
public void onGameStop(VillageGameStopEvent event){
for(Player p : e.getArena().getPlayers()){
p.sendMessage("You've lost the game! Maybe play again?");
}
}

event#getArena() - returns existing arena that is stopped

VillagePlayerChooseKitEvent (Cancellable)#

The event is called when the player chose kit in game.

Example:

@EventHandler
public void onKitChoose(VillagePlayerChooseKitEvent event){
Kit kit = e.getKit();
if(kit.getName().contains("knight")){
e.getPlayer().sendMessage("Knight kits aren't for you mate! Use archer kit instead!");
e.setCancelled(true);
}
}

event#getArena() - returns arena player is playing (player is always in arena when this event is called)

event#getPlayer() - returns event player

event#getKit() - returns selected kit

event#isCancelled() - returns true if event is cancelled

warning

Cancelling the event doesn't really influence the in-game kit chooser, #isCancelled()should be used for external add-ons!

VillageWaveEndEvent#

The event is called when the wave is finished (all zombies are killed).

Example:

@EventHandler
public void onWaveEnd(VillageWaveEndEvent event){
for(Player p : e.getArena().getPlayers()){
p.sendMessage("Wave has ended! You recived free diamond!");
p.getInventory().addItem(new ItemStack(Material.DIAMOND, 1);
}
}

event#getArena() - returns event arena

event#getWaveNumber() - returns number of current wave

VillageWaveStartEvent#

The event is called when the wave starts.

Example:

@EventHandler
public void onWaveStart(VillageWaveStartEvent event){
for(Player p : e.getArena().getPlayers()){
p.sendMessage("Wave has started! Good luck.");
}
}

event#getArena() - returns event arena

event#getWaveNumber() - returns number of current wave

VillageGameStateChangeEvent#

The event is called when arena game state changes.

Example:

@EventHandler
public void onGameStateChange(VillageGameStateChangeEvent event){
String state = e.getArenaState().getFormattedName();
for(Player p : e.getArena().getPlayers()){
p.sendMessage("Arena state changed to " + state);
}
}

event#getArena() - returns event arena

event#getArenaState() - returns current arena state

VillagePlayerStatisticChangeEvent#

The event is called when the player receives a new statistic.

Example:

@EventHandler
public void onStatChange(VillagePlayerStatisticChangeEvent event){
StatisticType stat = e.getStatisticType();
int statNumber = e.getNumber();
e.getPlayer().sendMessage("Your statistic " + stat.getName() + " has changed to " + statNumber);
}

event#getPlayer() - returns player involved in this event

event#getArena() - returns arena player is playing (player is always in arena when this event is called)

event#getStatisticType() - returns statistic of StatsStorage.StatisticType enum

event#getNumber() - returns current value of statistic

VillageEntityUpgradeEvent#

The event is called when player upgrades entity.

Example:

@EventHandler
public void onEntityUpgrade(VillagePlayerEntityUpgradeEvent event) {
event.getPlayer().sendMessage("You applied " + event.getAppliedUpgrade().getName() + " upgrade! You paid " + event.getAppliedUpgrade().getCost(e.getTier()) + " orbs!");
if(event.getEntity().getType() == EntityType.WOLF) {
event.getPlayer().sendMessage("You applied this upgrade to wolf!");
} else {
event.getPlayer().sendMessage("You applied this upgrade to iron golem!");
}
}

event#getEntity() - returns entity which was upgraded

event#getUpgrade() - returns upgrade that was applied

event#getPlayer() - returns player who upgraded entity

event#getArena() - returns arena where entity was upgraded

VillagePowerupPickEvent#

The event is called when the player picks up a power-up.

Example:

@EventHandler
public void onPowerupPick(VillagePlayerPowerupPickupEvent event) {
Powerup powerup = event.getPowerup();
event.getPlayer().sendMessage("You picked up " + powerup.getName() + " with identifier " + powerup.getId());
}

event#getPowerup() - returns powerup

event#getPlayer() - returns player involved in this event

event#getArena() - returns arena player is playing

Stats storage #

Retrieving online players stats#

You can easily get online players stats using Village Defense API - Stats Storage class.

Example:

public int getZombieKills(Player p){
return StatsStorage.getUserStats(p, StatsStorage.StatisticType.KILLS);
}

Very easy, right?

Requesting sorted statistics of all players#

To access sorted statistics Map with players you must call it from StatsStorage class.

Example:

public void printBestStats(StatsStorage.StatisticType statistic){
Map<UUID, Integer> statsMap = StatsStorage.getStats(statistic);
UUID[] uuidsArray = (UUID[]) StatsStorage.getStats(statistic).keySet().toArray();
for(int i = 0; i < 10; i++){
Bukkit.broadcastMessage("#" + i + " UUID: " + uuidsArray[i] + ", stats: " + statsMap.get(uuidsArray[i]));
}
}
warning

Be aware of IndexOutOfBoundsException as the list might be not enough big!

Available statistic types#

warning

Orbs statistic is temporary and shouldn't be used for out game usages!

Statistic name (enum)Statistic identifier (string) (for advanced things)Description
ORBS (non-persistent)orbsLocal orbs of player which is ingame
KILLSkillsTotal kills amount
DEATHSdeathsTotal deaths amount
GAMES_PLAYEDgamesplayedTotal games played
HIGHEST_WAVEhighestwaveHighest wave the player reached
LEVELlevelThe current level a player got
XPxpThe current xp a player got

Kit registry #

Registering new kit is quite simple. We need to implement all methods from abstract Kit class and edit it by yourself. After that just register it via KitRegistry.

Example:

//This kit will be premium
Kit supporter = new PremiumKit() {
//We need to implement methods from abstract Kit class
//Permissions needed to unlock it, if it is free just return true
@Override
public boolean isUnlockedByPlayer(Player p) {
return p.hasPermission("my.super.kit");
}
//Items given on game start
@Override
public void giveKitItems(Player player) {
player.getInventory().addItem(new ItemStack(Material.IRON_AXE, 1));
player.getInventory().addItem(new ItemStack(Material.GOLDEN_APPLE, 5));
}
//Material represented by this kit in the kit menu. Must be unique!
@Override
public Material getMaterial() {
return Material.GOLDEN_APPLE;
}
//Items given every next wave
@Override
public void reStock(Player player) {
player.getInventory().addItem(new ItemStack(Material.GOLDEN_APPLE, 1));
}
};
//Now just set kit name and description and register it via KitRegistry
supporter.setName("Supporter");
supporter.setDescription(new String[]{ChatColor.GREEN + "My super description"});
KitRegistry.registerKit(supporter);

Manipulating player join/leave attempts #

Join attempt #

To force player to join specified arena you can use our ArenaManager class.

public void sendPlayerToArena(String arena, Player player){
ArenaManager.joinAttempt(player, ArenaRegistry.getArena(arena));
}
// or
public void sendPlayerToArena(Arena arena, Player player){
ArenaManager.joinAttempt(player, arena);
}
caution

You should check is arena name exist otherwise it will throw NullPointerException

After that you can check for #isCancelled() if join attempt was cancelled or not.

Leave attempt #

You can also use ArenaManager class to force player to quit arena.

public void forcePlayerQuit(Player player){
Arena arena = ArenaRegistry.getArena(player);
ArenaManager.leaveAttempt(player, arena);
}
caution

You should check is arena isn't null otherwise it will throw NullPointerException

Last updated on by Tigerpanzer_02