Update documentation for release 3.15

LMBishop · Feb 17, 2024 · 3c354a0 · 3c354a0
1 parent 832e99c
commit 3c354a0
Show file tree

Hide file tree

Showing 19 changed files with 319 additions and 1 deletion.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.