From 891262ca003eb6653d810368e5d4154c5ad95558 Mon Sep 17 00:00:00 2001 From: montlikadani Date: Tue, 24 Nov 2020 20:43:58 +0100 Subject: [PATCH] Document some of api events --- .../com/gamingmesh/jobs/PlayerManager.java | 6 +- .../jobs/api/JobsAreaSelectionEvent.java | 13 ++ .../jobs/api/JobsChunkChangeEvent.java | 21 +++- .../gamingmesh/jobs/api/JobsExpGainEvent.java | 45 +++++++ .../gamingmesh/jobs/api/JobsJoinEvent.java | 10 ++ .../gamingmesh/jobs/api/JobsLeaveEvent.java | 10 ++ .../gamingmesh/jobs/api/JobsLevelUpEvent.java | 114 +++++++++++++----- .../gamingmesh/jobs/api/JobsPaymentEvent.java | 26 +++- .../jobs/api/JobsPrePaymentEvent.java | 55 +++++++++ .../jobs/api/JobsScheduleStartEvent.java | 8 ++ .../jobs/api/JobsScheduleStopEvent.java | 8 ++ .../jobs/stuff/FurnaceBrewingHandling.java | 2 +- 12 files changed, 281 insertions(+), 37 deletions(-) diff --git a/src/main/java/com/gamingmesh/jobs/PlayerManager.java b/src/main/java/com/gamingmesh/jobs/PlayerManager.java index 34d666ba..945c04da 100644 --- a/src/main/java/com/gamingmesh/jobs/PlayerManager.java +++ b/src/main/java/com/gamingmesh/jobs/PlayerManager.java @@ -688,7 +688,8 @@ public class PlayerManager { message = message.replace("%jobname%", job.getNameWithColor()); if (levelUpEvent.getOldTitle() != null) - message = message.replace("%titlename%", levelUpEvent.getOldTitleColor() + levelUpEvent.getOldTitleName()); + message = message.replace("%titlename%", levelUpEvent.getOldTitle() + .getChatColor().toString() + levelUpEvent.getOldTitle().getName()); message = message.replace("%playername%", player != null ? player.getDisplayName() : jPlayer.getName()); message = message.replace("%joblevel%", "" + prog.getLevel()); @@ -724,7 +725,8 @@ public class PlayerManager { message = Jobs.getLanguage().getMessage("message.skillup.nobroadcast"); message = message.replace("%playername%", player != null ? player.getDisplayName() : jPlayer.getName()); - message = message.replace("%titlename%", levelUpEvent.getNewTitleColor() + levelUpEvent.getNewTitleName()); + message = message.replace("%titlename%", levelUpEvent.getNewTitle() + .getChatColor().toString() + levelUpEvent.getNewTitle().getName()); message = message.replace("%jobname%", job.getNameWithColor()); for (String line : message.split("\n")) { diff --git a/src/main/java/com/gamingmesh/jobs/api/JobsAreaSelectionEvent.java b/src/main/java/com/gamingmesh/jobs/api/JobsAreaSelectionEvent.java index 5a24a937..272aac0b 100644 --- a/src/main/java/com/gamingmesh/jobs/api/JobsAreaSelectionEvent.java +++ b/src/main/java/com/gamingmesh/jobs/api/JobsAreaSelectionEvent.java @@ -4,6 +4,9 @@ import org.bukkit.entity.Player; import com.gamingmesh.jobs.container.CuboidArea; +/** + * Called when a player attempted to select an area. + */ public final class JobsAreaSelectionEvent extends BaseEvent { private CuboidArea area; private Player player; @@ -13,10 +16,20 @@ public final class JobsAreaSelectionEvent extends BaseEvent { this.area = area; } + /** + * The player who selected an area. + * + * @return {@link Player} + */ public Player getPlayer() { return player; } + /** + * Gets the selected area. + * + * @return {@link CuboidArea} + */ public CuboidArea getArea() { return area; } diff --git a/src/main/java/com/gamingmesh/jobs/api/JobsChunkChangeEvent.java b/src/main/java/com/gamingmesh/jobs/api/JobsChunkChangeEvent.java index 377d0a81..dbc7a2f3 100644 --- a/src/main/java/com/gamingmesh/jobs/api/JobsChunkChangeEvent.java +++ b/src/main/java/com/gamingmesh/jobs/api/JobsChunkChangeEvent.java @@ -3,7 +3,11 @@ package com.gamingmesh.jobs.api; import org.bukkit.Chunk; import org.bukkit.entity.Player; import org.bukkit.event.Cancellable; - +/** + * Fired when there is a new chunk explored by player moving. + *

+ * This is same behaviour when using {@link org.bukkit.event.player.PlayerMoveEvent} + */ public final class JobsChunkChangeEvent extends BaseEvent implements Cancellable { private Player player; private Chunk oldChunk; @@ -16,14 +20,29 @@ public final class JobsChunkChangeEvent extends BaseEvent implements Cancellable this.newChunk = newChunk; } + /** + * Gets the player who explored a chunk. + * + * @return {@link Player} + */ public Player getPlayer() { return player; } + /** + * Returns the old explored chunk. + * + * @return {@link Chunk} + */ public Chunk getOldChunk() { return oldChunk; } + /** + * Returns the new explored chunk. + * + * @return {@link Chunk} + */ public Chunk getNewChunk() { return newChunk; } diff --git a/src/main/java/com/gamingmesh/jobs/api/JobsExpGainEvent.java b/src/main/java/com/gamingmesh/jobs/api/JobsExpGainEvent.java index 42b62ca9..9e13fbf4 100644 --- a/src/main/java/com/gamingmesh/jobs/api/JobsExpGainEvent.java +++ b/src/main/java/com/gamingmesh/jobs/api/JobsExpGainEvent.java @@ -9,6 +9,9 @@ import org.bukkit.event.Cancellable; import com.gamingmesh.jobs.container.ActionInfo; import com.gamingmesh.jobs.container.Job; +/** + * Called when a player gains exp from jobs. + */ public final class JobsExpGainEvent extends BaseEvent implements Cancellable { private OfflinePlayer offlinePlayer; @@ -37,34 +40,76 @@ public final class JobsExpGainEvent extends BaseEvent implements Cancellable { this.info = info; } + /** + * Returns the player who got exp. + * + * @return {@link OfflinePlayer} + */ public OfflinePlayer getPlayer() { return offlinePlayer; } + /** + * Returns the job where the player is got the exp from. + * + * @return {@link Job} + */ public Job getJob() { return job; } + /** + * Returns the amount of gained exp for player. + * + * @return got exp amount + */ public double getExp() { return exp; } + /** + * Sets the exp to a new value. + * + * @param exp the new value + */ public void setExp(double exp) { this.exp = exp; } + /** + * Returns the block which the player broken and got income. + * + * @return {@link Block} + */ public Block getBlock() { return block; } + /** + * Returns the entity that the player killed or did something before. + *

+ * This method is used for Citizens NPCs and armor stand breaking. + * + * @return {@link Entity} + */ public Entity getEntity() { return entity; } + /** + * Returns the living entity that the player killed. + * + * @return {@link LivingEntity} + */ public LivingEntity getLivingEntity() { return living; } + /** + * Returns the action info, containing the action which the player performed. + * + * @return {@link ActionInfo} + */ public ActionInfo getActionInfo() { return info; } diff --git a/src/main/java/com/gamingmesh/jobs/api/JobsJoinEvent.java b/src/main/java/com/gamingmesh/jobs/api/JobsJoinEvent.java index 147fbe73..97e67b83 100644 --- a/src/main/java/com/gamingmesh/jobs/api/JobsJoinEvent.java +++ b/src/main/java/com/gamingmesh/jobs/api/JobsJoinEvent.java @@ -15,10 +15,20 @@ public final class JobsJoinEvent extends BaseEvent implements Cancellable { this.job = job; } + /** + * Returns the player who joined to a job. + * + * @return {@link JobsPlayer} + */ public JobsPlayer getPlayer() { return player; } + /** + * Returns the job where the player joined. + * + * @return {@link Job} + */ public Job getJob() { return job; } diff --git a/src/main/java/com/gamingmesh/jobs/api/JobsLeaveEvent.java b/src/main/java/com/gamingmesh/jobs/api/JobsLeaveEvent.java index 01427ee3..c5a0dcc7 100644 --- a/src/main/java/com/gamingmesh/jobs/api/JobsLeaveEvent.java +++ b/src/main/java/com/gamingmesh/jobs/api/JobsLeaveEvent.java @@ -15,10 +15,20 @@ public final class JobsLeaveEvent extends BaseEvent implements Cancellable { this.job = job; } + /** + * Returns the player who left a job. + * + * @return {@link JobsPlayer} + */ public JobsPlayer getPlayer() { return player; } + /** + * Returns the job where the player left. + * + * @return {@link Job} + */ public Job getJob() { return job; } diff --git a/src/main/java/com/gamingmesh/jobs/api/JobsLevelUpEvent.java b/src/main/java/com/gamingmesh/jobs/api/JobsLevelUpEvent.java index 7d622d04..411aa542 100644 --- a/src/main/java/com/gamingmesh/jobs/api/JobsLevelUpEvent.java +++ b/src/main/java/com/gamingmesh/jobs/api/JobsLevelUpEvent.java @@ -7,25 +7,25 @@ import com.gamingmesh.jobs.container.JobsPlayer; import com.gamingmesh.jobs.container.Title; public final class JobsLevelUpEvent extends BaseEvent implements Cancellable { + private JobsPlayer player; - private String JobName; - private Title OldTitle; - private Title NewTitle; - private int level; - private Sound soundLevelupSound = Sound.values()[0]; - private int soundLevelupVolume = 1; - private int soundLevelupPitch = 3; - private Sound soundTitleChangeSound = Sound.values()[0]; - private int soundTitleChangeVolume = 1; - private int soundTitleChangePitch = 3; + private String jobName; + private Title oldTitle; + private Title newTitle; + + private Sound soundLevelupSound; + private Sound soundTitleChangeSound; + + private int level, soundLevelupVolume = 1, soundLevelupPitch = 3, + soundTitleChangeVolume = 1, soundTitleChangePitch = 3; private boolean cancelled = false; public JobsLevelUpEvent(JobsPlayer jPlayer, String JobName, int level, Title OldTitle, Title NewTitle, String soundLevelupSound, Integer soundLevelupVolume, Integer soundLevelupPitch, String soundTitleChangeSound, Integer soundTitleChangeVolume, Integer soundTitleChangePitch) { this.player = jPlayer; - this.JobName = JobName; - this.OldTitle = OldTitle; - this.NewTitle = NewTitle; + this.jobName = JobName; + this.oldTitle = OldTitle; + this.newTitle = NewTitle; this.level = level; this.soundLevelupSound = getSound(soundLevelupSound); this.soundLevelupVolume = soundLevelupVolume; @@ -35,52 +35,99 @@ public final class JobsLevelUpEvent extends BaseEvent implements Cancellable { this.soundTitleChangePitch = soundTitleChangePitch; } - private static Sound getSound(String soundName) { - for (Sound one : Sound.values()) { - if (one.name().equalsIgnoreCase(soundName)) - return one; + private Sound getSound(String soundName) { + if (soundName != null) { + for (Sound one : Sound.values()) { + if (one.name().equalsIgnoreCase(soundName)) + return one; + } } - return null; + + return Sound.values()[0]; } + /** + * Returns the player who got level up in a job. + * + * @return {@link JobsPlayer} + */ public JobsPlayer getPlayer() { return player; } + /** + * Gets the job name where the player level up. + * + * @return the job name + */ public String getJobName() { - return JobName; + return jobName; } + /** + * Gets the old title of the player. + * + * @return {@link Title} + */ public Title getOldTitle() { - return OldTitle; + return oldTitle; } + /** + * @deprecated use {@link #getOldTitle()} + */ + @Deprecated(forRemoval = true) public String getOldTitleName() { - return OldTitle.getName(); + return oldTitle.getName(); } + /** + * @deprecated use {@link #getOldTitle()} + */ + @Deprecated(forRemoval = true) public String getOldTitleShort() { - return OldTitle.getShortName(); + return oldTitle.getShortName(); } + /** + * @deprecated use {@link #getOldTitle()} + */ + @Deprecated(forRemoval = true) public String getOldTitleColor() { - return OldTitle.getChatColor().toString(); + return oldTitle.getChatColor().toString(); } + /** + * Gets the new title of the player. + * + * @return {@link Title} + */ public Title getNewTitle() { - return NewTitle; + return newTitle; } + /** + * @deprecated use {@link #getNewTitle()} + */ + @Deprecated(forRemoval = true) public String getNewTitleName() { - return NewTitle.getName(); + return newTitle.getName(); } + /** + * @deprecated use {@link #getNewTitle()} + */ + @Deprecated(forRemoval = true) public String getNewTitleShort() { - return NewTitle.getShortName(); + return newTitle.getShortName(); } + /** + * @deprecated use {@link #getNewTitle()} + */ + @Deprecated(forRemoval = true) public String getNewTitleColor() { - return NewTitle.getChatColor().toString(); + return newTitle.getChatColor().toString(); } @Deprecated @@ -89,11 +136,11 @@ public final class JobsLevelUpEvent extends BaseEvent implements Cancellable { } public Sound getSound() { - return this.soundLevelupSound == null ? Sound.values()[0] : this.soundLevelupSound; + return soundLevelupSound; } public void setSound(Sound soundLevelupSound) { - this.soundLevelupSound = soundLevelupSound; + this.soundLevelupSound = soundLevelupSound == null ? Sound.values()[0] : soundLevelupSound; } public int getSoundVolume() { @@ -118,11 +165,11 @@ public final class JobsLevelUpEvent extends BaseEvent implements Cancellable { } public Sound getTitleChangeSound() { - return this.soundTitleChangeSound == null ? Sound.values()[0] : this.soundTitleChangeSound; + return soundTitleChangeSound; } public void setTitleChangeSound(Sound soundTitleChangeSound) { - this.soundTitleChangeSound = soundTitleChangeSound; + this.soundTitleChangeSound = soundTitleChangeSound == null ? Sound.values()[0] : soundTitleChangeSound; } public int getTitleChangeVolume() { @@ -141,6 +188,11 @@ public final class JobsLevelUpEvent extends BaseEvent implements Cancellable { this.soundTitleChangePitch = soundTitleChangePitch; } + /** + * Returns the player job progression level. + * + * @return player job progression level + */ public int getLevel() { return level; } diff --git a/src/main/java/com/gamingmesh/jobs/api/JobsPaymentEvent.java b/src/main/java/com/gamingmesh/jobs/api/JobsPaymentEvent.java index 8e83922b..a4c5a52b 100644 --- a/src/main/java/com/gamingmesh/jobs/api/JobsPaymentEvent.java +++ b/src/main/java/com/gamingmesh/jobs/api/JobsPaymentEvent.java @@ -30,6 +30,11 @@ public final class JobsPaymentEvent extends Event implements Cancellable { this.payments = payments; } + /** + * Returns the player who got payment. + * + * @return {@link OfflinePlayer} + */ public OfflinePlayer getPlayer() { return offlinePlayer; } @@ -68,15 +73,32 @@ public final class JobsPaymentEvent extends Event implements Cancellable { this.payments.put(CurrencyType.POINTS, points); } + /** + * Returns the payment amount of currency type. + * + * @param type {@link CurrencyType} + * @return the amount of payment in specific type + */ public Double get(CurrencyType type) { - Double amount = payments.get(type); - return amount == null ? 0 : amount; + return payments.getOrDefault(type, 0D); } + /** + * Sets the payment amount to a new one for the given currency type. + * + * @param type {@link CurrencyType} + * @param amount the new amount + * @return the given amount + */ public Double set(CurrencyType type, double amount) { return payments.put(type, amount); } + /** + * Returns all payment types map. + * + * @return {@link HashMap} + */ public HashMap getPayment() { return payments; } diff --git a/src/main/java/com/gamingmesh/jobs/api/JobsPrePaymentEvent.java b/src/main/java/com/gamingmesh/jobs/api/JobsPrePaymentEvent.java index 726c6c53..5a875f45 100644 --- a/src/main/java/com/gamingmesh/jobs/api/JobsPrePaymentEvent.java +++ b/src/main/java/com/gamingmesh/jobs/api/JobsPrePaymentEvent.java @@ -8,6 +8,9 @@ import org.bukkit.entity.Entity; import org.bukkit.entity.LivingEntity; import org.bukkit.event.Cancellable; +/** + * Event fired, before the payment calculation process should beginning. + */ public final class JobsPrePaymentEvent extends BaseEvent implements Cancellable { private OfflinePlayer offlinePlayer; private double money; @@ -39,42 +42,94 @@ public final class JobsPrePaymentEvent extends BaseEvent implements Cancellable this.info = info; } + /** + * Returns the player who performed something in a job. + * + * @return {@link OfflinePlayer} + */ public OfflinePlayer getPlayer() { return offlinePlayer; } + /** + * Returns the amount of expected income. + * + * @return expected income before calculations + */ public double getAmount() { return money; } + /** + * Returns the amount of expected points. + * + * @return expected points before calculations + */ public double getPoints() { return points; } + /** + * Returns the job where the payment will calculate. + * + * @return {@link Job} + */ public Job getJob() { return job; } + /** + * Sets a new money amount before calculations. + * + * @param money new amount + */ public void setAmount(double money) { this.money = money; } + /** + * Sets a new points amount before calculations. + * + * @param points + */ public void setPoints(double points) { this.points = points; } + /** + * Returns the block which the player performed to break. + * + * @return {@link Block} + */ public Block getBlock() { return block; } + /** + * Returns the entity that the player killed or did something before. + *

+ * This method is used for Citizens NPCs and armor stand breaking. + * + * @return {@link Entity} + */ public Entity getEntity() { return entity; } + /** + * Returns the living entity that the player killed. + * + * @return {@link LivingEntity} + */ public LivingEntity getLivingEntity() { return living; } + /** + * Returns the action info, containing the action which the player performed. + * + * @return {@link ActionInfo} + */ public ActionInfo getActionInfo() { return info; } diff --git a/src/main/java/com/gamingmesh/jobs/api/JobsScheduleStartEvent.java b/src/main/java/com/gamingmesh/jobs/api/JobsScheduleStartEvent.java index 616d3e6c..14f22a3f 100644 --- a/src/main/java/com/gamingmesh/jobs/api/JobsScheduleStartEvent.java +++ b/src/main/java/com/gamingmesh/jobs/api/JobsScheduleStartEvent.java @@ -3,6 +3,9 @@ package com.gamingmesh.jobs.api; import com.gamingmesh.jobs.container.Schedule; import org.bukkit.event.Cancellable; +/** + * Called when a schedule has been started. + */ public class JobsScheduleStartEvent extends BaseEvent implements Cancellable { private boolean cancelled = false; private Schedule schedule; @@ -11,6 +14,11 @@ public class JobsScheduleStartEvent extends BaseEvent implements Cancellable { this.schedule = schedule; } + /** + * Returns the schedule which started. + * + * @return {@link Schedule} + */ public Schedule getSchedule() { return schedule; } diff --git a/src/main/java/com/gamingmesh/jobs/api/JobsScheduleStopEvent.java b/src/main/java/com/gamingmesh/jobs/api/JobsScheduleStopEvent.java index e862fb33..2eef2682 100644 --- a/src/main/java/com/gamingmesh/jobs/api/JobsScheduleStopEvent.java +++ b/src/main/java/com/gamingmesh/jobs/api/JobsScheduleStopEvent.java @@ -3,6 +3,9 @@ package com.gamingmesh.jobs.api; import com.gamingmesh.jobs.container.Schedule; import org.bukkit.event.Cancellable; +/** + * Called when a schedule has been stopped. + */ public class JobsScheduleStopEvent extends BaseEvent implements Cancellable { private boolean cancelled = false; private Schedule schedule; @@ -11,6 +14,11 @@ public class JobsScheduleStopEvent extends BaseEvent implements Cancellable { this.schedule = schedule; } + /** + * Returns the schedule which stopped. + * + * @return {@link Schedule} + */ public Schedule getSchedule() { return schedule; } diff --git a/src/main/java/com/gamingmesh/jobs/stuff/FurnaceBrewingHandling.java b/src/main/java/com/gamingmesh/jobs/stuff/FurnaceBrewingHandling.java index 2e755a92..e7e779ac 100644 --- a/src/main/java/com/gamingmesh/jobs/stuff/FurnaceBrewingHandling.java +++ b/src/main/java/com/gamingmesh/jobs/stuff/FurnaceBrewingHandling.java @@ -25,7 +25,7 @@ import com.gamingmesh.jobs.listeners.JobsPaymentListener; * marked as "removeable". In the future this class will get removed * and not used anymore by anyone. Instead use {@link Jobs#getBlockOwnerShips()} */ -@Deprecated +@Deprecated(forRemoval = true) public class FurnaceBrewingHandling { static HashMap> furnaceMap = new HashMap<>();