Update documentation for release 3.15

19 files changed, 319 insertions, 1 deletions

diff --git a/bukkit/src/main/resources/resources/bukkit/quests/example1.yml b/bukkit/src/main/resources/resources/bukkit/quests/example1.yml
index ca57f714..f55ad0ff 100644
--- a/bukkit/src/main/resources/resources/bukkit/quests/example1.yml
+++ b/bukkit/src/main/resources/resources/bukkit/quests/example1.yml
@@ -45,6 +45,11 @@ placeholders:
   description: "&7Break &f30 blocks &7of any type."
   progress: " &8- &f{mining:progress}&7/30 broken"
 
+# Progress placeholders are used exclusively for the bossbar and actionbar.
+# Use the name of the task, or '*' for all tasks.
+progress-placeholders:
+  '*': "&f{mining:progress}&7/30 blocks broken"
+
 # Everything inside this section define quest-specific options
 options:
   # This is the category for the quest, it will appear under the "examples" category. Categories can be disabled.
diff --git a/bukkit/src/main/resources/resources/bukkit/quests/example2.yml b/bukkit/src/main/resources/resources/bukkit/quests/example2.yml
index 7ad82bea..567c1d8e 100644
--- a/bukkit/src/main/resources/resources/bukkit/quests/example2.yml
+++ b/bukkit/src/main/resources/resources/bukkit/quests/example2.yml
@@ -34,6 +34,9 @@ rewards:
 placeholders:
   description: "&7Break and place &f100 blocks &7of any type."
   progress: " &8- &f{mining:progress}&7/100 broken, &f{building:progress}&7/100 placed"
+progress-placeholders:
+  mining: "&f{mining:progress}&7/100 blocks broken"
+  building: "&f{building:progress}&7/100 blocks placed"
 options:
   category: "examples"
   # Unlike the previous quest, this quest has "example1" as a required quest. You cannot start this quest without "example1" quest complete.
diff --git a/bukkit/src/main/resources/resources/bukkit/quests/example3.yml b/bukkit/src/main/resources/resources/bukkit/quests/example3.yml
index dbd893e4..8b33b3af 100644
--- a/bukkit/src/main/resources/resources/bukkit/quests/example3.yml
+++ b/bukkit/src/main/resources/resources/bukkit/quests/example3.yml
@@ -37,6 +37,9 @@ rewards:
 placeholders:
   description: "&7Break &f81 gold ore &7and place &f9 gold blocks."
   progress: " &8- &f{mining:progress}&7/81 gold ore, &f{building:progress}&7/9 gold blocks"
+progress-placeholders:
+  mining: "&f{mining:progress}&7/81 gold ore broken"
+  building: "&f{building:progress}&7/9 gold blocks placed"
 options:
   category: "examples"
   requires:
diff --git a/bukkit/src/main/resources/resources/bukkit/quests/example4.yml b/bukkit/src/main/resources/resources/bukkit/quests/example4.yml
index 4e9c27a8..d4ab2301 100644
--- a/bukkit/src/main/resources/resources/bukkit/quests/example4.yml
+++ b/bukkit/src/main/resources/resources/bukkit/quests/example4.yml
@@ -35,6 +35,8 @@ rewards:
 placeholders:
   description: "&7Kill &f3 &7mobs."
   progress: " &8- &f{mobkilling:progress}&7/3 mobs"
+progress-placeholders:
+  mobkilling: "&f{mobkilling:progress}&7/3 mobs killed"
 # Here you can list messages which will be sent to the player (if they are online) upon completion.
 rewardstring:
   - " &8* &c$1000 &7was added to your in-game balance."
diff --git a/bukkit/src/main/resources/resources/bukkit/quests/example5.yml b/bukkit/src/main/resources/resources/bukkit/quests/example5.yml
index cb92f0f1..a75a00a2 100644
--- a/bukkit/src/main/resources/resources/bukkit/quests/example5.yml
+++ b/bukkit/src/main/resources/resources/bukkit/quests/example5.yml
@@ -24,6 +24,8 @@ rewards:
 placeholders:
   description: "&7Place &f10 &7blocks of any type."
   progress: " &8- &f{building:progress}&7/10 blocks"
+progress-placeholders:
+  building: "&f{building:progress}&7/10 blocks placed"
 options:
   category: "examples"
   requires:
diff --git a/bukkit/src/main/resources/resources/bukkit/quests/example6.yml b/bukkit/src/main/resources/resources/bukkit/quests/example6.yml
index 0913a7cb..f6b5191d 100644
--- a/bukkit/src/main/resources/resources/bukkit/quests/example6.yml
+++ b/bukkit/src/main/resources/resources/bukkit/quests/example6.yml
@@ -24,6 +24,8 @@ rewards:
 placeholders:
   description: "&7Place &f10 &7blocks of any type."
   progress: " &8- &f{building:progress}&7/10 blocks"
+progress-placeholders:
+  building: "&f{building:progress}&7/10 blocks placed"
 options:
   category: "permissionexample"
   # This quest has no specific permission, however its category does. The permission for the category is "quests.category.permissionexample"
diff --git a/bukkit/src/main/resources/resources/bukkit/quests/example7.yml b/bukkit/src/main/resources/resources/bukkit/quests/example7.yml
index 32bb7e04..37c5532f 100644
--- a/bukkit/src/main/resources/resources/bukkit/quests/example7.yml
+++ b/bukkit/src/main/resources/resources/bukkit/quests/example7.yml
@@ -26,6 +26,8 @@ rewards:
 placeholders:
   description: "&7Place &f10 &7blocks of any type in world &fworld."
   progress: " &8- &f{building:progress}&7/10 blocks"
+progress-placeholders:
+  building: "&f{building:progress}&7/10 blocks placed"
 options:
   category: "permissionexample"
   # This quest has no specific permission, however its category does. The permission for the category is "quests.category.permissionexample"
diff --git a/docs/configuration/basic-options.md b/docs/configuration/basic-options.md
index 6b461d4f..713674e6 100644
--- a/docs/configuration/basic-options.md
+++ b/docs/configuration/basic-options.md
@@ -74,6 +74,57 @@ options:
   titles-enabled: true
 ```
 
+## Bossbar
+
+*`options.bossbar`*
+
+This configures a temporary bossbar which will appear when a player
+makes progress on a task, or completes a task. The bar itself
+represents the percentage done for a task.
+
+The text displayed will be the [progress placeholder](/configuration/creating-a-quest#progress-placeholders)
+for the task. In the future, there will also be a method to
+automatically generate this text.
+
+```yaml
+options:
+  # ...
+  bossbar:
+    # Enable bossbar for task progress
+    progress: false
+    # Enable bossbar for task completions
+    complete: false
+    # Time in seconds to display bossbar
+    time: 5
+    # See https://hub.spigotmc.org/javadocs/spigot/org/bukkit/boss/BarColor.html
+    color:
+      '0.0': BLUE # for 0.0 and higher progress values (progress is always between 0.0 and 1.0)
+    # See https://hub.spigotmc.org/javadocs/spigot/org/bukkit/boss/BarStyle.html
+    style:
+      '0.0': SOLID # for 0.0 and higher progress values (progress is always between 0.0 and 1.0)
+```
+
+## Actionbar
+
+*`options.actionbar`*
+
+This configures a temporary action bar which will appear when a player
+makes progress on a task, or completes a task. 
+
+The text displayed will be the [progress placeholder](/configuration/creating-a-quest#progress-placeholders)
+for the task. In the future, there will also be a method to
+automatically generate this text.
+
+```yaml
+options:
+  # ...
+  actionbar:
+    # Enable actionbar for task progress
+    progress: false
+    # Enable actionbar for task completions
+    complete: false
+```
+
 ## Quest started limit
 
 *`options.quest-started-limit`*
@@ -228,6 +279,18 @@ list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html)
 list](https://helpch.at/docs/1.8.8/index.html?org/bukkit/Sound.html)
 (1.8).
 
+An alternative syntax is available for 
+[namespaced sound names](https://www.digminecraft.com/lists/sound_list_pc.php):
+
+``` yaml
+options:
+  # ...
+  sounds:
+    quest-start: "(minecraft:entity.player.levelup):2:3"
+    # ...
+```
+
+
 To not have a sound play, you can leave the string blank (i.e. `""`),
 for example:
 
@@ -247,6 +310,9 @@ player, not the actual volume played back on the client.
 **Example (1.9+):** `ENTITY_PLAYER_LEVELUP:2:3` -\> sound
 `ENTITY_PLAYER_LEVELUP` at pitch `2` with a volume of `3`.
 
+**Example (namespaced sound):** `(minecraft:entity.player.levelup):2:3` -\> sound
+`minecraft:entity.player.levelup` at pitch `2` with a volume of `3`.
+
 ## GUI hide locked
 
   
diff --git a/docs/configuration/creating-a-quest.md b/docs/configuration/creating-a-quest.md
index 4e7353a6..6b47e3e6 100644
--- a/docs/configuration/creating-a-quest.md
+++ b/docs/configuration/creating-a-quest.md
@@ -141,6 +141,20 @@ startcommands:
   - "broadcast {player} has started a quest"
 ```
 
+## Cancel commands
+
+
+*`cancelcommands`*
+
+**Optional.** This is a list of commands which will be executed when the
+player cancels the quest. You can use `{player}` and the player's name
+will be substituted in place.
+
+``` yaml
+cancelcommands:
+  - "broadcast {player} has cancelled a quest"
+```
+
 ## Start string
 
   
@@ -190,6 +204,37 @@ These placeholders will be called using PlaceholderAPI. See [quest
 progress in scoreboard](../guides/quest-progress-in-scoreboard) for a
 guide which utilises this feature.
 
+## Progress placeholders
+
+*`progress-placeholders`*
+
+**Optional.** This is a list of placeholders which represent the progress
+of each task. These are used by the [bossbar](/configuration/basic-options#bossbar)
+and [actionbar](/configuration/basic-options#actionbar) configuration options.
+
+You can define a placeholder for each task, or for all of them as a catch-all.
+
+```yaml
+progress-placeholders:
+  <task-name>: "Progress for <task-name>"
+  '*': "Progress for tasks not defined above"
+```
+
+For example, in an actual quest:
+
+```yaml
+tasks:
+  mining:
+    type: "blockbreak"
+    amount: 100
+  building:
+    type: "blockplace"
+    amount: 100
+# ... 
+progress-placeholders:
+  mining: "&f{mining:progress}/100 &7blocks broken"
+  building: "&f{building:progress}/100 &7blocks placed"
+```
 ## Options
 
   
diff --git a/docs/configuration/defining-items.md b/docs/configuration/defining-items.md
index a32bb689..86218378 100644
--- a/docs/configuration/defining-items.md
+++ b/docs/configuration/defining-items.md
@@ -305,6 +305,19 @@ item:
   id: "executableitems_id"  #executableitems id
 ```
 
+#### ItemsAdder
+
+**ItemsAdder quest items** are ItemStacks which belong to the
+ItemsAdder plugin.
+
+    items/testitem.yml
+
+``` yaml
+type: "itemsadder"
+item:
+  id: "itemsadder"  #itemsdadder id
+```
+
 ### Referencing a quest item
 
 In most cases where an ItemStack is accepted in Quests, you can simply
diff --git a/docs/configuration/gui-configuration.md b/docs/configuration/gui-configuration.md
index 5b5b5ed0..da3efc13 100644
--- a/docs/configuration/gui-configuration.md
+++ b/docs/configuration/gui-configuration.md
@@ -25,6 +25,8 @@ The back button displayed within sub menus.
 gui:
   # ...
   back-button:
+    enabled: true
+    slot: 45 
     name: "&cReturn"
     lore:
     - "&7Return to the categories menu."
@@ -42,6 +44,8 @@ The previous page button displayed on paiginated menus.
 gui:
   # ...
   page-prev:
+    enabled: true
+    slot: 48 
     name: "&7Previous Page"
     lore:
     - "&7Switch the page to page &c{prevpage}."
@@ -62,6 +66,8 @@ The next page button displayed on paiginated menus.
 gui:
   # ...
   page-next:
+    enabled: true
+    slot: 50 
     name: "&7Next Page"
     lore:
     - "&7Switch the page to page &c{nextpage}."
@@ -82,6 +88,8 @@ item will automatically update on the page number.
 gui:
   # ...
   page-desc:
+    enabled: true
+    slot: 49
     name: "&7Page &c{page}"
     lore:
     - "&7You are currently viewing page &c{page}."
diff --git a/docs/task-types/blockbreak-(task-type).md b/docs/task-types/blockbreak-(task-type).md
index 2ec16687..d4dd1ab6 100644
--- a/docs/task-types/blockbreak-(task-type).md
+++ b/docs/task-types/blockbreak-(task-type).md
@@ -9,7 +9,10 @@ grand_parent: Task types
 Since v1.0
 {: .label .label-green }
 
-Break a set amount of blocks.
+Break a set amount of blocks. For items which can be broken by
+breaking a block underneath it (such as torches or signs), consider
+using the [blockitemdropping task type](blockitemdropping-(task-type))
+instead.
 
 {: .note }
 Since Quests v3.13, `blockbreakcertain` and `blockbreak` have been
diff --git a/docs/task-types/blockitemdropping-(task-type).md b/docs/task-types/blockitemdropping-(task-type).md
new file mode 100644
index 00000000..c4deba4a
--- /dev/null
+++ b/docs/task-types/blockitemdropping-(task-type).md
@@ -0,0 +1,42 @@
+---
+title: blockitemdropping
+parent: Built-in task types
+grand_parent: Task types
+---
+
+# blockitemdropping (task type)
+
+Since v3.15
+{: .label .label-green }
+
+Drop a certain amount of items from a block. In most cases, the
+player must be in survival mode for this to be triggered.
+
+This is triggered by [`BlockDropItemEvent`](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/event/block/BlockDropItemEvent.html):
+
+> Called if a block broken by a player drops an item. 
+> This event will also be called if the player breaks 
+> a multi block structure, for example a torch on top 
+> of a stone.
+
+## Options
+
+| Key           | Description                                            | Type                           | Required | Default | Notes                                                                                                                                                                                                                                                                           |
+|---------------|--------------------------------------------------------|--------------------------------|----------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `amount`      | The number of items.                                   | Integer                        | Yes      | \-      | \-                                                                                                                                                                                                                                                                              |
+| `item`        | The specific item to be dropped.                       | Material, or ItemStack         | Yes      | \-      | Accepts standard [item definition](../configuration/defining-items). Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) (1.13+) or [this list](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) (1.8-1.12) for material names.    |
+| `block`       | The specific blocks to break.                          | Material, or list of materials | No       | \-      | Not specifying this field will allow all blocks to count towards the task. Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) (1.13+) or [this list](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) (1.8-1.12) for block names. |
+| `data`        | The data code for the item.                            | Integer                        | No       | 0       | This field is not used in Minecraft versions 1.13+, nor is it compatible with ItemStack definitions.                                                                                                                                                                            |
+| `worlds`      | Worlds which should count towards the progress.        | List of world names            | No       | \-      | \-                                                                                                                                                                                                                                                                              |
+| `exact-match` | Whether the item should exactly match what is defined. | Boolean                        | No       | true    | \-                                                                                                                                                                                                                                                                              |
+
+## Examples
+
+Break 8 torches:
+
+``` yaml
+torch:
+  type: "blockitemdropping"
+  item: TORCH                           # name of item (can be id or minecraft name)
+  amount: 8                             # amount of item dropped
+```
diff --git a/docs/task-types/breeding-(task-type).md b/docs/task-types/breeding-(task-type).md
index 1d527402..19039744 100644
--- a/docs/task-types/breeding-(task-type).md
+++ b/docs/task-types/breeding-(task-type).md
@@ -11,6 +11,9 @@ Since v2.2
 
 Breed a certain amount of animals.
 
+This task type has specific logic implemented for compatibility with
+[WildStacker](https://bg-software.com/wildstacker/).
+
 ## Options
 
 | Key            | Description                                     | Type                             | Required | Default | Notes                                                                                                                                                                                              |
diff --git a/docs/task-types/ecomobs_killing-(task-type).md b/docs/task-types/ecomobs_killing-(task-type).md
new file mode 100644
index 00000000..04ea7224
--- /dev/null
+++ b/docs/task-types/ecomobs_killing-(task-type).md
@@ -0,0 +1,36 @@
+---
+title: ecomobs_killing
+parent: External task types
+grand_parent: Task types
+---
+
+# ecomobs_killing (task type)
+
+Since v3.15
+{: .label .label-green }
+
+Plugin 'EcoMobs' required
+{: .label }
+
+Kill a certain number of EcoMobs mob.
+
+## Options
+
+| Key          | Description                                     | Type                       | Required | Default | Notes |
+|--------------|-------------------------------------------------|----------------------------|----------|---------|-------|
+| `amount`     | The number of bosses to kill.                   | Integer                    | Yes      | \-      | \-    |
+| `id` / `ids` | The EcoMobs boss ID(s).                         | String, or list of strings | Yes      | \-      | \-    |
+| `worlds`     | Worlds which should count towards the progress. | List of world names        | No       | \-      | \-    |
+
+## Examples
+
+Kill 1 EcoMobs mobs with the ID "skeletalknight":
+
+``` yaml
+ecobosses:
+  type: "ecomobs_killing"
+  amount: 1                             # amount of mobs to be killed
+  id: "skeletalknight"                  # internal name of mob (name in config - NOT display name)
+  worlds:                               # (OPTIONAL) restrict to certain worlds
+   - "world"
+```
diff --git a/docs/task-types/mobkilling-(task-type).md b/docs/task-types/mobkilling-(task-type).md
index ecc45030..1a8d107d 100644
--- a/docs/task-types/mobkilling-(task-type).md
+++ b/docs/task-types/mobkilling-(task-type).md
@@ -11,6 +11,9 @@ Since v2.0
 
 Kill a set amount of mobs.
 
+This task type has specific logic implemented for compatibility with
+[WildStacker](https://bg-software.com/wildstacker/).
+
 {: .note }
 Since Quests v3.13, `mobkillingcertain` and `mobkilling` have been
 merged into one. Both names can be used to refer to this task.
diff --git a/docs/task-types/projectilelaunching-(task-type).md b/docs/task-types/projectilelaunching-(task-type).md
new file mode 100644
index 00000000..b8dcc238
--- /dev/null
+++ b/docs/task-types/projectilelaunching-(task-type).md
@@ -0,0 +1,45 @@
+---
+title: projectilelaunching
+parent: Built-in task types
+grand_parent: Task types
+---
+
+# projectilelaunching (task type)
+
+Since v3.15
+{: .label .label-green }
+
+Launch a certain number of projectiles. This happens when 
+a player fires a bow, throws a snowball, etc.
+
+## Options
+
+| Key                          | Description                                     | Type                             | Required | Default | Notes                                                                                                                                                                                                 |
+|------------------------------|-------------------------------------------------|----------------------------------|----------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `amount`                     | The number of projectiles to launch.            | Integer                          | Yes      | \-      | \-                                                                                                                                                                                                    |
+| `projectile` / `projectiles` | The specific projectile(s) to launch.           | Entity type, or list of entities | No       | \-      | Not specifying this field will allow all entity types to count towards the task. Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/entity/EntityType.html) for entity types. |
+| `worlds`                     | Worlds which should count towards the progress. | List of world names              | No       | \-      | \-                                                                                                                                                                                                    |
+
+## Examples
+
+Shoot 5 arrows:
+
+``` yaml
+projectilelaunching:
+  type: "projectilelaunching"
+  amount: 5                             # amount of projectiles launched
+  projectile: 'ARROW'                   # the projectile to launch
+  worlds:                               # (OPTIONAL) restrict to certain worlds
+   - "world"
+```
+
+Throw 5 snowballs:
+
+``` yaml
+projectilelaunching:
+  type: "projectilelaunching"
+  amount: 5                             # amount of projectiles launched
+  projectile: 'SNOWBALL'                # the projectile to launch
+  worlds:                               # (OPTIONAL) restrict to certain worlds
+   - "world"
+```
diff --git a/docs/task-types/pyrofishingpro_fishing-(task-type).md b/docs/task-types/pyrofishingpro_fishing-(task-type).md
new file mode 100644
index 00000000..4ba4a978
--- /dev/null
+++ b/docs/task-types/pyrofishingpro_fishing-(task-type).md
@@ -0,0 +1,33 @@
+---
+title: pyrofishingpro_fishing
+parent: External task types
+grand_parent: Task types
+---
+
+# pyrofishingpro_fishing (task type)
+
+Since v3.15
+{: .label .label-green }
+
+Plugin 'PyroFishingPro' required
+{: .label }
+
+Catch a set amount of a Pyro fish from the sea.
+
+## Options
+
+| Key           | Description                         | Type    | Required | Default | Notes                                                             |
+|---------------|-------------------------------------|---------|----------|---------|-------------------------------------------------------------------|
+| `amount`      | The number of Pyro fish to catch.   | Integer | Yes      | \-      | \-                                                                |
+| `fish-number` | The specific fish number to catch.  | Integer | No       | \-      | If this value is not specified, then any fish will count.         |
+| `tier`        | The specific tier of fish to catch. | Integer | No       | \-      | If this value is not specified, then any tier of fish will count. |
+
+## Examples
+
+Catch 10 Pyro fish:
+
+```yaml
+pyrofishing:
+  type: "pyrofishingpro_fishing"
+  amount: 10                             # number needed
+```
diff --git a/docs/tools/placeholderapi.md b/docs/tools/placeholderapi.md
index cc932600..c75a9522 100644
--- a/docs/tools/placeholderapi.md
+++ b/docs/tools/placeholderapi.md
@@ -73,6 +73,7 @@ The eCloud extension called 'Quests' is not for this plugin, do not download it!
 | `%quests_quest:<quest-id>_completedbefore%`          | Returns **true/false** on whether or not the quest **`<quest-id>`** is completed by the player **at least once**.            |
 | `%quests_quest:<quest-id>_completiondate%`           | Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the quest **`<quest-id>`** was completed by the player. |
 | `%quests_quest:<quest-id>_cooldown%`                 | Returns a **time in seconds** of the cooldown for quest **`<quest-id>`**.                                                    |
+| `%quests_quest:<quest-id>_timeleft%`                 | Returns the amount of time remaining to complete the quest **`<quest-id>`**.                                                 | 
 | `%quests_quest:<quest-id>_canaccept%`                | Returns **true/false** on whether or not the quest **`<quest-id>`** can be started by the player.                            |
 | `%quests_quest:<quest-id>_meetsrequirements%`        | Returns **true/false** on whether or not the player has completed the required quests for the quest **`<quest-id>`**.        |
 | `%quests_quest:<quest-id>_task:<task-id>_progress%`  | Returns the **progress** of task **`task-id`** on the quest **`<quest-id>`**.                                                |
@@ -88,6 +89,7 @@ The eCloud extension called 'Quests' is not for this plugin, do not download it!
 | `%quests_tracked_completedbefore%`          | Returns **true/false** on whether or not the **players tracked quest** is completed **at least once**.                          |
 | `%quests_tracked_completiondate%`           | Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the **players tracked quest** was completed by the player. |
 | `%quests_tracked_cooldown%`                 | Returns a **time in seconds** of the cooldown for the **players tracked quest**.                                                |
+| `%quests_tracked_timeleft%`                 | Returns the amount of time remaining to complete the **players tracked quest**.                                                 | 
 | `%quests_tracked_canaccept%`                | Returns **true/false** on whether or not the **players tracked quest** can be started by the player.                            |
 | `%quests_tracked_meetsrequirements%`        | Returns **true/false** on whether or not the player has completed the required quests for the **players tracked quest**.        |
 | `%quests_tracked_task:<task-id>_progress%`  | Returns the **progress** of task **`task-id`** on the **players tracked quest**.                                                |