From 77aa3763412ce2ee1da814bba7d8e26ea85240fb Mon Sep 17 00:00:00 2001
From: LMBishop <13875753+LMBishop@users.noreply.github.com>
Date: Wed, 3 Mar 2021 13:29:42 +0000
Subject: Add documentation
---
.../quests/player/QPlayerManager.java | 5 +-
.../questprogressfile/QuestProgressFile.java | 104 +++++++++++++++++----
2 files changed, 88 insertions(+), 21 deletions(-)
(limited to 'src/main/java/com')
diff --git a/src/main/java/com/leonardobishop/quests/player/QPlayerManager.java b/src/main/java/com/leonardobishop/quests/player/QPlayerManager.java
index ac7504fe..ba942978 100644
--- a/src/main/java/com/leonardobishop/quests/player/QPlayerManager.java
+++ b/src/main/java/com/leonardobishop/quests/player/QPlayerManager.java
@@ -45,7 +45,7 @@ public class QPlayerManager {
}
/**
- * Unloads and saves the player to disk.
+ * Unloads and saves the player to disk. Must be invoked from the main thread.
*
* @param uuid the uuid of the player
*/
@@ -76,7 +76,7 @@ public class QPlayerManager {
/**
* Load the player from disk if they exist, otherwise create a new {@link QuestProgressFile}.
- * Will have no effect if player is already loaded.
+ * This will have no effect if player is already loaded. Can be invoked asynchronously.
*
* @param uuid the uuid of the player
*/
@@ -91,6 +91,7 @@ public class QPlayerManager {
File file = new File(plugin.getDataFolder() + File.separator + "playerdata" + File.separator + uuid.toString() + ".yml");
if (file.exists()) {
YamlConfiguration data = YamlConfiguration.loadConfiguration(file);
+ plugin.getQuestsLogger().debug("Player " + uuid + " has a valid quest progress file.");
if (data.isConfigurationSection("quest-progress")) { //Same job as "isSet" + it checks if is CfgSection
for (String id : data.getConfigurationSection("quest-progress").getKeys(false)) {
boolean started = data.getBoolean("quest-progress." + id + ".started");
diff --git a/src/main/java/com/leonardobishop/quests/player/questprogressfile/QuestProgressFile.java b/src/main/java/com/leonardobishop/quests/player/questprogressfile/QuestProgressFile.java
index 16ccd020..b2596079 100644
--- a/src/main/java/com/leonardobishop/quests/player/questprogressfile/QuestProgressFile.java
+++ b/src/main/java/com/leonardobishop/quests/player/questprogressfile/QuestProgressFile.java
@@ -42,6 +42,16 @@ public class QuestProgressFile {
this.plugin = plugin;
}
+ /**
+ * Attempt to complete a quest for the player. This will also play all effects (such as titles, messages etc.)
+ * and also dispatches all rewards for the player.
+ *
+ * Warning: rewards will not be sent and the {@link PlayerFinishQuestEvent} will not be fired if the
+ * player is not online
+ *
+ * @param quest the quest to complete
+ * @return true (always)
+ */
public boolean completeQuest(Quest quest) {
QuestProgress questProgress = getQuestProgress(quest);
questProgress.setStarted(false);
@@ -82,7 +92,15 @@ public class QuestProgressFile {
return true;
}
+ /**
+ * Attempt to track a quest for the player. This will also play all effects (such as titles, messages etc.)
+ *
+ * Warning: will fail if the player is not online.
+ *
+ * @param quest the quest to track
+ */
public void trackQuest(Quest quest) {
+ //TODO change how this works
Player player = Bukkit.getPlayer(playerUUID);
if (quest == null) {
playerPreferences.setTrackedQuestId(null);
@@ -99,7 +117,7 @@ public class QuestProgressFile {
/**
* Check if the player can start a quest.
- *
+ *
* Warning: will fail if the player is not online.
*
* @param quest the quest to check
@@ -150,12 +168,12 @@ public class QuestProgressFile {
}
/**
- * Start a quest for the player.
- *
+ * Attempt to start a quest for the player. This will also play all effects (such as titles, messages etc.)
+ *
* Warning: will fail if the player is not online.
*
- * @param quest the quest to check
- * @return the quest start result
+ * @param quest the quest to start
+ * @return the quest start result -- {@code QuestStartResult.QUEST_SUCCESS} indicates success
*/
// TODO PlaceholderAPI support
public QuestStartResult startQuest(Quest quest) {
@@ -239,6 +257,12 @@ public class QuestProgressFile {
return code;
}
+ /**
+ * Attempt to cancel a quest for the player. This will also play all effects (such as titles, messages etc.)
+ *
+ * @param quest the quest to start
+ * @return true if the quest was cancelled, false otherwise
+ */
public boolean cancelQuest(Quest quest) {
QuestProgress questProgress = getQuestProgress(quest);
Player player = Bukkit.getPlayer(this.playerUUID);
@@ -269,6 +293,13 @@ public class QuestProgressFile {
this.questProgress.put(questProgress.getQuestId(), questProgress);
}
+ /**
+ * Gets all started quests.
+ * Note: if quest autostart is enabled then this may produce unexpected results as quests are
+ * not "started" by the player if autostart is true. Consider {@link #hasStartedQuest(Quest)} instead.
+ *
+ * @return
+ */
public List getStartedQuests() {
List startedQuests = new ArrayList<>();
for (QuestProgress questProgress : questProgress.values()) {
@@ -280,19 +311,7 @@ public class QuestProgressFile {
}
/**
- * @return {@code List} all quest
- * @deprecated use {@code getAllQuestsFromProgress(QuestsProgressFilter)} instead
- *
- * Returns all {@code Quest}s a player has encountered
- * (not to be confused with a collection of quest progress)
- */
- @Deprecated
- public List getQuestsProgress(String filter) {
- return getAllQuestsFromProgress(QuestsProgressFilter.fromLegacy(filter));
- }
-
- /**
- * Returns all {@code Quest}s a player has encountered
+ * Returns all {@link Quest} a player has encountered
* (not to be confused with a collection of quest progress)
*
* @return {@code List} all quests
@@ -353,10 +372,22 @@ public class QuestProgressFile {
return questProgress.values();
}
+ /**
+ * Checks whether or not the player has {@link QuestProgress} for a specified quest
+ *
+ * @param quest the quest to check for
+ * @return true if they have quest progress
+ */
public boolean hasQuestProgress(Quest quest) {
return questProgress.containsKey(quest.getId());
}
+ /**
+ * Gets whether or not the player has started a specific quest.
+ *
+ * @param quest the quest to test for
+ * @return true if the quest is started or quest autostart is enabled and the quest is ready to start, false otherwise
+ */
public boolean hasStartedQuest(Quest quest) {
if (Options.QUEST_AUTOSTART.getBooleanValue()) {
QuestStartResult response = canStartQuest(quest);
@@ -366,6 +397,12 @@ public class QuestProgressFile {
}
}
+ /**
+ * Gets the remaining cooldown before being able to start a specific quest.
+ *
+ * @param quest the quest to test for
+ * @return 0 if no cooldown remaining or the cooldown is disabled, otherwise the cooldown in milliseconds
+ */
public long getCooldownFor(Quest quest) {
QuestProgress questProgress = getQuestProgress(quest);
if (quest.isCooldownEnabled() && questProgress.isCompleted()) {
@@ -377,6 +414,12 @@ public class QuestProgressFile {
return 0;
}
+ /**
+ * Tests whether or not the player meets the requirements to start a specific quest.
+ *
+ * @param quest the quest to test for
+ * @return true if they can start the quest
+ */
public boolean hasMetRequirements(Quest quest) {
for (String id : quest.getRequirements()) {
Quest q = plugin.getQuestManager().getQuestById(id);
@@ -392,10 +435,21 @@ public class QuestProgressFile {
return true;
}
+ /**
+ * Get the {@link UUID} of the player this QuestProgressFile represents
+ *
+ * @return UUID
+ */
public UUID getPlayerUUID() {
return playerUUID;
}
+ /**
+ * Get the {@link QuestProgress} for a specified {@link Quest}, and generates a new one if it does not exist
+ *
+ * @param quest the quest to get progress for
+ * @return {@link QuestProgress} or null if the quest does not exist
+ */
public QuestProgress getQuestProgress(Quest quest) {
if (questProgress.containsKey(quest.getId())) {
return questProgress.get(quest.getId());
@@ -405,6 +459,13 @@ public class QuestProgressFile {
return null;
}
+ /**
+ * Generate a new blank {@link QuestProgress} for a specified {@code questid}.
+ * Has no effect if there is already an existing {@link QuestProgress} for {@code questid}.
+ *
+ * @param questid the quest to generate progress for
+ * @return true if successful
+ */
public boolean generateBlankQuestProgress(String questid) {
if (plugin.getQuestManager().getQuestById(questid) != null) {
Quest quest = plugin.getQuestManager().getQuestById(questid);
@@ -424,6 +485,11 @@ public class QuestProgressFile {
return playerPreferences;
}
+ /**
+ * Save the quest progress file to disk at /playerdata/[uuid]. Must be invoked from the main thread.
+ *
+ * @param async save the file asynchronously
+ */
public void saveToDisk(boolean async) {
plugin.getQuestsLogger().debug("Saving player " + playerUUID + " to disk. Main thread: " + async);
List questProgressValues = new ArrayList<>(questProgress.values());
@@ -477,7 +543,7 @@ public class QuestProgressFile {
}
/**
- * Removes any references to quests or tasks which are no longer defined in the config
+ * Removes any references to quests or tasks which are no longer defined in the config.
*/
public void clean() {
plugin.getQuestsLogger().debug("Cleaning file " + playerUUID + ".");
--
cgit v1.2.3-70-g09d2