From 467715dcb3ee23e05e8fe445d9e2a2416a26a8e0 Mon Sep 17 00:00:00 2001 From: LMBishop <13875753+LMBishop@users.noreply.github.com> Date: Wed, 5 Jul 2023 20:54:36 +0100 Subject: Migrate docs to GitHub pages --- docs/API.md | 32 -- docs/Basic-options.md | 584 --------------------- docs/Colour-codes.md | 51 -- docs/Commands-and-permissions.md | 77 --- docs/Configuration-problems.md | 77 --- docs/Contributing-to-the-wiki.md | 52 -- docs/Creating-a-category.md | 54 -- docs/Creating-a-quest-or-category.md | 10 - docs/Creating-a-quest.md | 444 ---------------- docs/Custom-GUI-items.md | 61 --- docs/Data-migration-tool.md | 27 - docs/Defining-items.md | 327 ------------ docs/Download.md | 54 -- docs/GUI-configuration.md | 262 --------- docs/Gemfile.lock | 81 +++ docs/Getting-started.md | 22 - docs/Global-configurations.md | 91 ---- docs/New-task-type.md | 80 --- docs/PlaceholderAPI.md | 117 ----- docs/Quest-debugger.md | 46 -- docs/Quest-progress-in-scoreboard.md | 180 ------- docs/Storage-providers.md | 137 ----- docs/Task-types.md | 67 --- docs/Tips.md | 36 -- docs/_Sidebar.md | 38 +- docs/_config.yml | 32 +- docs/commands-and-permissions.md | 85 +++ docs/configuration/basic-options.md | 569 ++++++++++++++++++++ docs/configuration/colour-codes.md | 58 ++ docs/configuration/configuration-problems.md | 96 ++++ docs/configuration/creating-a-category.md | 68 +++ docs/configuration/creating-a-quest.md | 428 +++++++++++++++ docs/configuration/custom-gui-items.md | 68 +++ docs/configuration/defining-items.md | 317 +++++++++++ docs/configuration/global-configurations.md | 103 ++++ docs/configuration/gui-configuration.md | 269 ++++++++++ docs/configuration/index.md | 7 + docs/configuration/storage-providers.md | 137 +++++ docs/contributing-to-the-wiki.md | 58 ++ docs/developer/api.md | 35 ++ docs/developer/index.md | 7 + docs/developer/new-task-type.md | 85 +++ docs/download.md | 60 +++ docs/getting-started.md | 15 + docs/guides/index.md | 7 + docs/guides/quest-progress-in-scoreboard.md | 188 +++++++ docs/index.md | 16 +- docs/task-type/askyblock_level-(task-type).md | 15 +- docs/task-type/bentobox_level-(task-type).md | 15 +- docs/task-type/blockbreak-(task-type).md | 14 +- docs/task-type/blockplace-(task-type).md | 12 + docs/task-type/breeding-(task-type).md | 11 + docs/task-type/brewing-(task-type).md | 11 + docs/task-type/bucketempty-(task-type).md | 11 + docs/task-type/bucketfill-(task-type).md | 11 + docs/task-type/citizens_deliver-(task-type).md | 15 +- docs/task-type/citizens_interact-(task-type).md | 15 +- docs/task-type/command-(task-type).md | 11 + docs/task-type/consume-(task-type).md | 11 + docs/task-type/crafting-(task-type).md | 11 + docs/task-type/dealdamage-(task-type).md | 11 + docs/task-type/distancefrom-(task-type).md | 11 + docs/task-type/enchanting-(task-type).md | 11 + docs/task-type/essentials_balance-(task-type).md | 15 +- docs/task-type/essentials_moneyearn-(task-type).md | 15 +- docs/task-type/expearn-(task-type).md | 11 + docs/task-type/fabledskyblock_level-(task-type).md | 15 +- docs/task-type/farming-(task-type).md | 19 +- docs/task-type/fishing-(task-type).md | 14 +- docs/task-type/index.md | 7 + docs/task-type/inventory-(task-type).md | 12 + .../task-type/iridiumskyblock_value-(task-type).md | 15 +- docs/task-type/milking-(task-type).md | 11 + docs/task-type/mobkilling-(task-type).md | 12 + docs/task-type/mythicmobs_killing-(task-type).md | 15 +- docs/task-type/permission-(task-type).md | 13 + .../placeholderapi_evaluate-(task-type).md | 17 +- docs/task-type/playerkilling-(task-type).md | 12 + docs/task-type/playtime-(task-type).md | 14 + docs/task-type/position-(task-type).md | 11 + docs/task-type/shearing-(task-type).md | 12 + docs/task-type/shopguiplus_buy-(task-type).md | 16 +- docs/task-type/shopguiplus_sell-(task-type).md | 16 +- docs/task-type/smelting-(task-type).md | 12 + .../superiorskyblock_level-(task-type).md | 15 +- .../superiorskyblock_worth-(task-type).md | 17 +- docs/task-type/taming-(task-type).md | 11 + docs/task-type/uskyblock_level-(task-type).md | 15 +- docs/task-type/votingplugin_vote-(task-type).md | 15 +- docs/task-type/walking-(task-type).md | 11 + docs/tips.md | 43 ++ docs/tools/data-migration-tool.md | 35 ++ docs/tools/index.md | 7 + docs/tools/placeholderapi.md | 148 ++++++ docs/tools/quest-debugger.md | 54 ++ 95 files changed, 3615 insertions(+), 2951 deletions(-) delete mode 100644 docs/API.md delete mode 100644 docs/Basic-options.md delete mode 100644 docs/Colour-codes.md delete mode 100644 docs/Commands-and-permissions.md delete mode 100644 docs/Configuration-problems.md delete mode 100644 docs/Contributing-to-the-wiki.md delete mode 100644 docs/Creating-a-category.md delete mode 100644 docs/Creating-a-quest-or-category.md delete mode 100644 docs/Creating-a-quest.md delete mode 100644 docs/Custom-GUI-items.md delete mode 100644 docs/Data-migration-tool.md delete mode 100644 docs/Defining-items.md delete mode 100644 docs/Download.md delete mode 100644 docs/GUI-configuration.md create mode 100644 docs/Gemfile.lock delete mode 100644 docs/Getting-started.md delete mode 100644 docs/Global-configurations.md delete mode 100644 docs/New-task-type.md delete mode 100644 docs/PlaceholderAPI.md delete mode 100644 docs/Quest-debugger.md delete mode 100644 docs/Quest-progress-in-scoreboard.md delete mode 100644 docs/Storage-providers.md delete mode 100644 docs/Task-types.md delete mode 100644 docs/Tips.md create mode 100644 docs/commands-and-permissions.md create mode 100644 docs/configuration/basic-options.md create mode 100644 docs/configuration/colour-codes.md create mode 100644 docs/configuration/configuration-problems.md create mode 100644 docs/configuration/creating-a-category.md create mode 100644 docs/configuration/creating-a-quest.md create mode 100644 docs/configuration/custom-gui-items.md create mode 100644 docs/configuration/defining-items.md create mode 100644 docs/configuration/global-configurations.md create mode 100644 docs/configuration/gui-configuration.md create mode 100644 docs/configuration/index.md create mode 100644 docs/configuration/storage-providers.md create mode 100644 docs/contributing-to-the-wiki.md create mode 100644 docs/developer/api.md create mode 100644 docs/developer/index.md create mode 100644 docs/developer/new-task-type.md create mode 100644 docs/download.md create mode 100644 docs/getting-started.md create mode 100644 docs/guides/index.md create mode 100644 docs/guides/quest-progress-in-scoreboard.md create mode 100644 docs/task-type/index.md create mode 100644 docs/tips.md create mode 100644 docs/tools/data-migration-tool.md create mode 100644 docs/tools/index.md create mode 100644 docs/tools/placeholderapi.md create mode 100644 docs/tools/quest-debugger.md (limited to 'docs') diff --git a/docs/API.md b/docs/API.md deleted file mode 100644 index 03ea4d8a..00000000 --- a/docs/API.md +++ /dev/null @@ -1,32 +0,0 @@ -*** - -### ๐Ÿ”จ ***This page is under construction*** -*The information contained here may be inaccurate or incomplete. You can help by [contributing information to the wiki](https://github.com/LMBishop/Quests/wiki/Contributing-to-the-wiki).* - -*** - -Quests provides an API for other people to use. **This API is experimental and may be subject to change.** For usages, it is best to take a look into the plugin itself. - -## Bukkit -You can get an instance of Quests as you would with any other plugin: -```java -BukkitQuestsPlugin questsPlugin = (BukkitQuestsPlugin) Bukkit.getPluginManager().getPlugin("Quests"); -``` -From there, you can access the `QPlayerManager`, `QuestManager` etc. See the javadoc in [this file](https://github.com/LMBishop/Quests/blob/master/common/src/main/java/com/leonardobishop/quests/common/plugin/Quests.java), and in each class for more info on its purpose. - -### Events -Quests provides some Bukkit events, you can see them all [here](https://github.com/LMBishop/Quests/tree/master/bukkit/src/main/java/com/leonardobishop/quests/bukkit/api/event). - -### Registering task types -Task types **must** be registered during startup, after Quests has initialized its task type manager. You cannot register task types after this period as individual quests are registered to their task types for performance reasons. - -```java -@Override -public void onEnable() { - // ... - Quests questsPlugin = (Quests) Bukkit.getPluginManager().getPlugin("Quests"); - BukkitTaskTypeManager taskTypeManager = (BukkitTaskTypeManager) questsPlugin.getTaskTypeManager(); - - taskTypeManager.registerTaskType(new ...); -} -``` \ No newline at end of file diff --git a/docs/Basic-options.md b/docs/Basic-options.md deleted file mode 100644 index 29b255cf..00000000 --- a/docs/Basic-options.md +++ /dev/null @@ -1,584 +0,0 @@ -Quests allows you to configure **basic options** for the -plugin. These can all be located in the `config.yml`. - -## Table of contents - -- [Categories enabled](Basic_options#Categories_enabled "wikilink") -- [Trim gui size](Basic_options#Trim_gui_size "wikilink") -- [Titles enabled](Basic_options#Titles_enabled "wikilink") -- [Quest started limit](Basic_options#Quest_started_limit "wikilink") -- [Quset limit](Basic_options#Quest_limit "wikilink") -- [Allow quest cancel](Basic_options#Allow_quest_cancel "wikilink") -- [Allow quest track](Basic_options#Allow_quest_track "wikilink") -- [Task type exclusions](Basic_options#Task_type_exclusions "wikilink") -- [Guinames](Basic_options#Guinames "wikilink") -- [Sounds](Basic_options#Sounds "wikilink") -- [GUI hide locked](Basic_options#GUI_hide_locked "wikilink") -- [GUI confirm cancel](Basic_options#GUI_confirm_cancel "wikilink") -- [GUI hide quests if no - permission](Basic_options#GUI_hide_quests_if_no_permission "wikilink") -- [GUI hide categoires if no - permission](Basic_options#GUI_hide_categories_if_no_permission "wikilink") -- [GUI use - PlaceholderAPI](Basic_options#GUI_use_PlaceholderAPI "wikilink") -- [GUI truncate - requirements](Basic_options#GUI_truncate_requirements "wikilink") -- [GUI actions](Basic_options#GUI_actions "wikilink") -- [Quest autostart](Basic_options#Quest_autostart "wikilink") -- [Quest autotrack](Basic_options#Quest_autotrack "wikilink") -- [Verbose logging - level](Basic_options#Verbose_logging_level "wikilink") -- [Quests use - PlaceholderAPI](Basic_options#Quests_use_PlaceholderAPI "wikilink") -- [Verify quest exists on - load](Basic_options#Verify_quest_exists_on_load "wikilink") -- [Performance tweaking](Basic_options#Performance_tweaking "wikilink") -- [Tab completion](Basic_options#Tab_completion "wikilink") -- [Error checking](Basic_options#Error_checking "wikilink") -- [Placeholder cache - time](Basic_options#Placeholder_cache_time "wikilink") -- [Global task configuration - override](Basic_options#Global_task_configuration_override "wikilink") -- [Global quest display configuration - override](Basic_options#Global_quest_display_configuration_override "wikilink") -- [Storage](Basic_options#Storage "wikilink") - -## Categories enabled - - -*`options.categories-enabled`* - -Choose whether or not quests will be sorted into categories. If this is -disabled, quests will be put into one big GUI instead, with categories -only helping determine the order they are sorted. - -``` yaml -options: - ... - categories-enabled: true -``` - -## Trim gui size - - -*`options.trim-gui-size`* - -Choose whether or not the quests GUI will scale down (reduce the number -of rows) so that there are not any empty rows. - -``` yaml -options: - ... - trim-gui-size: true -``` - -## Titles enabled - - -*`options.titles-enabled`* - -Choose whether or not titles will appear when starting / finishing -quests. - -``` yaml -options: - ... - titles-enabled: true -``` - -## Quest started limit - - -*`options.quest-started-limit`* - -โ›”๏ธ **This option has been removed in version 3.8 and this wiki entry is -subject to removal.** *Please see [Basic options#Quest -limit](Basic_options#Quest_limit "wikilink") instead.* - -Choose the number of quests players can start at one time. This will -include quests which have [quest-specific -autostart](Creating_a_quest#Autostart "wikilink") enabled, however this -value will be ignored if [global -`quest-autostart`](Basic_options#Quest_autostart "wikilink") is enabled. - -``` yaml -options: - ... - quest-started-limit: 2 -``` - -## Quest limit - - -*`options.quest-limit`* - -Choose the number of quests players can start at one time. This will -include quests which have [quest-specific -autostart](Creating_a_quest#Autostart "wikilink") enabled, however this -value will be ignored if [global -`quest-autostart`](Basic_options#Quest_autostart "wikilink") is enabled. - -Each key is called a **limit group** (sometimes referred to as a quest -rank), and players can start the set number of quests depending on their -limit group. The group named `default` must be defined and is available -to everybody, however the rest can be granted through the permission -`quests.limit.`. - -``` yaml -options: - ... - quest-limit: - default: 2 - group1: 5 - group2: 10 - # ... -``` - -Group permissions are also documented in [Commands and permissions ยง -Permissions](Commands-and-permissions#permissions "wikilink"). - -## Allow quest cancel - - -*`options.allow-quest-cancel`* - -Choose whether or not players can cancel quests themselves via command -or by right-clicking in the GUI. If this is set to false, consider -removing the right-click cancel instruction from the [global quest -display -configuration](Global_configurations#Global_quest_display_configuration "wikilink"). - -``` yaml -options: - ... - allow-quest-cancel: true -``` - -## Allow quest track - - -*`options.allow-quest-track`* - -Choose whether or not players can track quests themselves via command or -by middle-clicking in the GUI. If this is set to false, consider -removing the middle-click track instruction from the [global quest -display -configuration](Global_configurations#Global_quest_display_configuration "wikilink"). - -``` yaml -options: - ... - allow-quest-track: true -``` - -## Task type exclusions - - -*`options.task-type-exclusions`* - -Prevent Quests from allowing specific task type registrations from those -bearing a specific name. This can be used if you have an incompatible -plugin which causes a dependent task type to activate, thus potentially -leading to errors. - -``` yaml -options: - ... - task-type-exclusions: [] -``` - -**Example** - -``` yaml -options: - ... - task-type-exclusions: - - "blockbreak" - - "blockbreakcertain" -``` - -## Guinames - - -*`options.guinames`* - -Change and define specific GUI names for localization. - -``` yaml -options: - ... - guinames: - quests-category: "Quests Categories" - quests-menu: "Quests" - quests-started-menu: "Started Quests" - daily-quests: "Daily Quests" - quest-cancel: "Cancel Quest" -``` - -## Sounds - - -*`options.sounds`* - -Choose which sounds play at certain events. - -``` yaml -options: - ... - sounds: - quest-start: "ENTITY_PLAYER_LEVELUP:2:3" - quest-cancel: "UI_TOAST_OUT:2:3" - quest-complete: "UI_TOAST_CHALLENGE_COMPLETE:1.25:3" - gui: - open: "ITEM_BOOK_PAGE_TURN:1:3" - interact: "ITEM_BOOK_PAGE_TURN1:3" -``` - -To define a sound, choose one from [this -list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html) -(1.9+) or [this -list](https://helpch.at/docs/1.8.8/index.html?org/bukkit/Sound.html) -(1.8). - -To not have a sound play, you can leave the string blank (i.e. `""`), -for example: - -``` yaml -options: - ... - sounds: - quest-start: "" -``` - -You can choose a specific pitch and volume by including them in the -following format `SOUND:PITCH:VOLUME`. Note that the pitch is any float -between 0.5 and 2 (inclusively), and the volume must be greater than 0. -The volume only changes how far out the sound can be heard by the -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`. - -## GUI hide locked - - -*`options.gui-hide-locked`* - -Choose whether quests which cannot be started is visible to the player -or not. - -``` yaml -options: - ... - gui-hide-locked: false -``` - -## GUI confirm cancel - - -*`options.gui-confirm-cancel`* - -Choose whether or not there is a confirmation screen when right clicking -to cancel a quest. Cancelling by command does not prompt a confirmation -screen. - -``` yaml -options: - ... - gui-confirm-cancel: true -``` - -## GUI hide quests if no permission - - -*`options.gui-hide-quests-nopermission`* - -Choose whether or not quests are hidden to the player if they do not -have permission for the quest. - -``` yaml -options: - ... - gui-hide-quests-nopermission: false -``` - -## GUI hide categories if no permission - - -*`options.gui-hide-categories-nopermission`* - -Choose whether or not categories are hidden to the player if they do not -have permission for the category. - -``` yaml -options: - ... - gui-hide-categories-nopermission: false -``` - -## GUI use PlaceholderAPI - - -*`options.gui-use-placeholderapi`* - -Choose whether or not the quest GUI is parsed with PlaceholderAPI. This -is disabled by default for performance reasons. - -``` yaml -options: - ... - gui-use-placeholderapi: false -``` - -## GUI truncate requirements - - -*`options.gui-truncate-requirements`* - -Choose whether or not the displayed quest requirements for specific -quests should be cut short. The plugin will show "Quest 1 +X more" as -the requirement, rather than listing each quest "Quest 1, Quest 2, Quest -3, ..." to stop lores overflowing off the screen. - -``` yaml -options: - ... - gui-truncate-requirements: true -``` - -## GUI actions - - -*`options.gui-actions`* - -Set the click actions for the UI. For a list of click types, check the -[ClickType javadoc -page](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/ClickType.html). - -``` yaml -options: - ... - gui-actions: - start-quest: "LEFT" - track-quest: "MIDDLE" - cancel-quest: "RIGHT" -``` - -## Quest autostart - - -*`options.quest-autostart`* - -Choose whether or not players need to start quests themselves. This will -ignore the configured [quest started -limit](#Quest_started_limit "wikilink"), and is different from the -[autostart](#Autostart "wikilink") option. - -``` yaml -options: - ... - quest-autostart: false -``` - -## Quest autotrack - - -*`options.quest-autotrack`* - -Choose whether or not players need to track quests themselves. This will -automatically track quests when they are started, and will attempt to -track the next available started quests when the player finishes a -quest. - -``` yaml -options: - ... - quest-autotrack: true -``` - -## Verbose logging level - - -*`options.verbose-logging-level`* - -Choose how much quests will log to the console. This will filter the -output based on the following options: 0 = errors only, 1 = warnings, 2 -= info, 3 = debug - -``` yaml -options: - ... - verbose-logging-level: 2 -``` - -## Quests use PlaceholderAPI - - -*`options.quests-use-placeholderapi`* - -Choose whether or not start strings, reward strings, reward commands and -start commands are parsed with PlaceholderAPI. This is disabled by -default for performance reasons. - -``` yaml -options: - ... - quests-use-placeholderapi: false -``` - -## Verify quest exists on load - - -*`options.verify-quest-exists-on-load`* - -Verify quests exist when a player's data is loaded - inconsistencies may -arise when players progress on specific quests and those quests are -later removed. Their progress is still retained in the quest progress -file, which may lead to issues such as players reaching a quest started -limit when the quests they had active no longer exist - having this -option enabled prevents non-existent quests from loading as quest -progress. - -``` yaml -options: - ... - verify-quest-exists-on-load: true -``` - -## Performance tweaking - - -*`options.performance-tweaking`* - -Set some specific options within the internals of Quests. - -The `queue executor interval` relates to how frequently players are -checked for completed quests. Not every player is checked at once for -performance purposes, and players are only submitted to the queue upon -completion of a task. The interval defines how frequently players are -polled from the queue. - -The `autosave interval` refers to how frequently all online players data -is saved. Data is saved at autosave intervals to prevent data loss -should the server crash. - -These options are measured in ticks, 1 second = 20 ticks. - -``` yaml -options: - ... - performance-tweaking: - quest-queue-executor-interval: 1 - quest-autosave-interval: 12000 -``` - -## Tab completion - - -*`options.tab-completion`* - -Choose whether or not commands can be tab completed. Quests will never -offer tab completions which players cannot run, regardless of this -setting. (In other words, players who are not admins will not see tab -completions for `/quests admin` if they do not have the admin -permission.) - -``` yaml -options: - ... - tab-completion: - enabled: true -``` - -## Error checking - - -*`options.error-checking`* - -Configure how Quests handles errors in your configuration. By default, -Quests will not allow quests to be loaded if they contain an -[error](Configuration_problems#Types_of_problem "wikilink"), since this -could lead to undefined behaviour. The option `override-errors` will -ignore this behaviour and forcibly allow the quest to be registered. - -``` yaml -options: - ... - error-checking: - override-errors: false -``` - -## Placeholder cache time - - -''`options.placeholder-cache-time`" - -Set how long Quests will retain parsed PlaceholderAPI strings in the -cache, in seconds. See [PlaceholderAPI ยง Caching -placeholders](PlaceholderAPI#Caching_placeholders "wikilink") for more -information. - -``` yaml -options: - ... - placeholder-cache-time: 10 -``` - -## Global task configuration override - - -*`options.global-task-configuration-override`* - -Choose whether or not options set in the [global task -configuration](Global_configurations#Global_task_configuration "wikilink") -will override per-quest specific options. - -``` yaml -options: - ... - global-task-configuration-override: false -``` - -## Global quest display configuration override - - -*`options.global-quest-display-configuration-override`* - -Choose whether or not the [global quest display -configuration](Global_configurations#Global_quest_display_configuration "wikilink") -will override per-quest specific options. - -``` yaml -options: - ... - global-quest-display-configuration-override: false -``` - -## Storage - - -*`options.storage`* - -Configure how Quests will store playerdata. See [storage -providers](Storage_providers "wikilink") for more info. - -``` yaml -options: - ... - storage: - provider: "yaml" - synchronisation: - delay-loading: 0 - database-settings: - network: - database: "minecraft" - username: "root" - password: "" - address: "localhost:3306" - connection-pool-settings: - maximum-pool-size: 8 - minimum-idle: 8 - maximum-lifetime: 1800000 - connection-timeout: 5000 - table-prefix: "quests_" -``` diff --git a/docs/Colour-codes.md b/docs/Colour-codes.md deleted file mode 100644 index aba83ee4..00000000 --- a/docs/Colour-codes.md +++ /dev/null @@ -1,51 +0,0 @@ -Jump to section: -* [Using Colour Codes](#using-colour-codes) -* [Using Hexadecimal Colour](#using-hexadecimal-colour) - -You can use colour codes anywhere the plugin accepts a message (plugin messages, display items, and in task configurations themselves). - -Your server version dictates which codes are allowed: -| | Before 1.16 | 1.16+ | -| ---- | ---- | ---- | -| Colour Codes | โœ”๏ธ | โœ”๏ธ | -| Hexadecimal | โŒ | โœ”๏ธ | - -## Colour codes -The plugin will automatically translate colour codes from '&' to 'ยง' for you. - -| Name | Chat Code | Hex Equivalent | -| ---- | ---- | ---- | -| Black | `&0` | #000000 | -| Dark Blue | `&1` | #0000AA | -| Dark Green | `&2` | #00AA00 | -| Dark Aqua | `&3` | #00AAAA | -| Dark Red | `&4` | #AA0000 | -| Dark Purple | `&5` | #AA00AA | -| Gold | `&6` | #FFAA00 | -| Gray | `&7` | #AAAAAA | -| Dark Gray | `&8` | #555555 | -| Blue | `&9` | #5555FF | -| Green | `&a` | #55FF55 | -| Aqua | `&b` | #55FFFF | -| Red | `&c` | #FF5555 | -| Light Purple | `&d` | #FF55FF | -| Yellow | `&e` | #FFFF55 | -| White | `&f` | #FFFFFF | -| Obfuscated | `&k` | - | -| Bold | `&l` | - | -| Strikethrough | `&m` | - | -| Underline | `&n` | - | -| Italic | `&o` | - | -| Reset | `&r` | - | - -## Hexadecimal colour -For compatible Minecraft versions, the plugin will also translate hex colour codes for you. - -You can include a hex colour code as you would with a normal colour code: `&#`. **Note: the `#` is important and must be there.** - -For example, the following messages are identical: -``` -&cThis is a red message. - -&#FF5555This is a red message. -``` diff --git a/docs/Commands-and-permissions.md b/docs/Commands-and-permissions.md deleted file mode 100644 index dcef33d3..00000000 --- a/docs/Commands-and-permissions.md +++ /dev/null @@ -1,77 +0,0 @@ -## Commands - -- **/quests \[or /q\]** - opens quest GUI -- **/quests help** - view help screen for quests commands -- **/quests started** - view a menu of started quests -- **/quests random \[category\]** - start a random quest \[in a random - category\] -- **/quests cancel \** - cancel quest by id -- **/quests q/quest \ \** - start quest - directly by ID. -- **/quests c/category \** - open category directly by ID. -- **/quests a/admin** - view help for admins - - **/quests a/admin opengui** - view help for opengui - - **/quests a/admin opengui q/quest \** - forcefully open - quests GUI for player (bypassing quests.command permission) - - **/quests a/admin opengui c/category \ \** - - forcefully open category by ID for player (bypassing - quests.command permission) - - **/quests a/admin opengui started \** - forcefully open - the started menu for player (bypassing quests.command permission) - - **/quests a/admin moddata** - view help for opengui - - **/quests a/admin moddata fullreset \** - fully clear a - players data file - - **/quests a/admin moddata reset \ \** - clear a - players data for a specifc quest - - **/quests a/admin moddata start \ \** - start a - quest for a player - - **/quests a/admin moddata complete \ \** - - complete a quest for a player - - **/quests a/admin moddata random \ \[category\]** - start - a random a quest for a player \[in a category\] - - *These commands modify quest progress for players. Use them - cautiously. Changes are irreversible.* - - **/quests a/admin items** - view registered quest items. - - **/quests a/admin items import \** - import a held quest - item. - - **/quests a/admin items give \ \ \[amount\]** - give - a player a quest item. - - **/quests a/admin debug** - view help for the [quest - debugger](quest_debugger "wikilink"). - - **/quests a/admin debug report** - generate a debug report. - - **/quests a/admin debug quest \ \** - enable - debug messages for a specific quest, or all of them. - - **/quests a/admin types \[type\]** - view activated task types, and - information on a specific one. - - **/quests a/admin info \[quest\]** - view loaded quests, and - information on a specific one. - - **/quests a/admin reload** - reload Quests. - - **/quests a/admin config** - see config problems. - - **/quests a/admin update** - check for updates. - - **/quests a/admin wiki** - get a link to the wiki. - - **/quests a/admin about** - view plugin information. - -## Permissions - -- `quests.command` - to view the quest menu (/quests) -- `quests.command.category` - to view a specific category (/q category) -- `quests.command.started` - to view quest started menu (/q started) -- `quests.command.quest` - to use /q quest -- `quests.command.start` - to start a quest by command (/q start) -- `quests.command.track` - to cancel a quest by command (q track) -- `quests.command.cancel` - to cancel a quest by command (/q cancel) -- `quests.command.random` - to starting a random quest (/q random) -- `quests.admin` - for admin commands - -The following are dependent on specific quests & categories: - -- `quests.category.` - permission to start quests within - `(category)`, if `permission-required` for the category is set to - `true` -- `quests.quest.` - permission to start quest `(quest id)`, if - `permission-required` for the quest is set to `true` - -The following are dependent on your configuration: - -- `quests.limit.` - permission to start a configured amount - of quests for members of this limit group diff --git a/docs/Configuration-problems.md b/docs/Configuration-problems.md deleted file mode 100644 index 258cbf86..00000000 --- a/docs/Configuration-problems.md +++ /dev/null @@ -1,77 +0,0 @@ -**Configuration problems** are designed to inform you when you have an **error** or **potential misconfiguration**. They may appear when reloading Quests, for example: - -![](https://i.imgur.com/5o7EyVm.png) - -These problems are designed to be as readable as possible, allowing self-diagnosis for your configuration. Warnings are also used to spot common misconfigurations, which may lead to quests not working as expected, thus being interpreted as a bug. - -## Types of problem -|Type|Description| -| :---: | --- | -|Error|Errors prevent the specific quest from loading. These can be overidden in the config at `options.error-checking.override-errors`. Examples include an incorrect quest ID or malformed YML file.| -|Warning|Warnings have no impact other than to inform you that a quest may not work as expected. Examples include an invalid material for a blockbuildcertain task, or a required quest which does not exist.| - -## Understanding the problems -Problems generally follow this format: -``` - ---- - | - : : -``` - -**Example 1** - -The following error will show if you try to create a `blockbreakcertain` task without specifying how many blocks or what block you need to break. -``` -example1.yml ---- - | - E: Required field 'amount' is missing for task type 'blockbreakcertain' :tasks.miningcertain.amount - | - E: Required field 'block' is missing for task type 'blockbreakcertain' :tasks.miningcertain.block -``` -In the above example, the problem is an Error (as denoted by E) and will prevent the quest (`example1`) from loading. At the end, it shows you exactly where the error comes from in the YML file, which looks like this: -```yaml -tasks: - miningcertain: - type: "blockbreakcertain" -``` -Where it says the location `:tasks.miningcertain.amount`, each dot deontes a level of indentation. So in this case, it is expecting values at `amount` and `block`, but they are not defined. Below is the fixed version. -```yaml -tasks: - miningcertain: - type: "blockbreakcertain" - amount: 10 - block: DIAMOND_ORE -``` -**Example 2** - -``` -example2.yml ---- - | - E: Expected an integer for 'amount', but got 'hey' instead :tasks.inventory.amount - | - W: Material 'thisisnotablock' does not exist :tasks.inventory.item - | - W: Quest requirement 'example' does not exist :options.requires -``` -```yaml -tasks: - inventory: - type: "inventory" - amount: hey - item: thisisnotablock -... -options: - requires: - - "example" - ... -``` -In this case, the task is broken since instead of numbers for the amount of items needed, the string "hey" is there instead, causing an error. The source of the error is indicated by the location at the end `tasks.inventory.amount`. - -Also, a warning is shown for the item "thisisnotablock" at `tasks.inventory.item` and for the requirement "example" at `options.requires`. These warnings are informing you that the task may not work as "thisisnotablock" is not a real item, and that the quest "example" which is required to have been completed in order to start this quest does not exist. - -Below is a fixed version: -```yaml -tasks: - inventory: - type: "inventory" - amount: 10 - item: DIAMOND -... -options: - # requirements section removed - ... -``` \ No newline at end of file diff --git a/docs/Contributing-to-the-wiki.md b/docs/Contributing-to-the-wiki.md deleted file mode 100644 index 16caa497..00000000 --- a/docs/Contributing-to-the-wiki.md +++ /dev/null @@ -1,52 +0,0 @@ -If you spot any errors in the wiki, or want to add more information of -you own, then we would be happy to review potential changes. Due to the -restrictions of the GitHub wiki pages, it is not possible to open pull -requests to the wiki repository, instead changes will have to be -submitted through the [on the issue -tracker](https://github.com/LMBishop/Quests/issues/new?assignees=&labels=docs%2Cstatus%3A+needs+investigating&template=documentation.yml). - -## Submitting edits - - -โœ๏ธ **The primary wiki format is Wikitext, edits using Markdown will not -be accepted.** - -If you want to add information or edit the wiki, it would be beneficial -if you submitted the source code of the page within backticks to make it -easy to change the wiki. - -You can view the raw source code of a wiki page by adding `.mediawiki` -to the url, for example: -[`https://github.com/LMBishop/Quests/wiki/Storage-providers.mediawiki`](https://github.com/LMBishop/Quests/wiki/Storage-providers.mediawiki). -**Note that some pages are edited using Markdown, if `.mediawiki` does -not resolve then use `.md` instead. These pages do not use Wikitext but -will soon be converted to it.** - -Please make your edits to the page there, and submit the **full page** -in the issue tracker. Due to constraints of the GitHub wiki, there is no -way to easily submit revisions for review. - -## Editing guidelines - -The Quests wiki loosely follows some conventions: - -- Article titles and headers should be written in lower case, with only - the first word being capitalised. The only exception to this is with - names (e.g. PlaceholderAPI, AnimatedScoreboard). -- Headings should not used to restate the page name. Pages usually open - with a short description at the top, they should never start with - another heading. -- British English should be used. -- Top-level headings should start at H2 (`## Heading` or - `== Heading ==`). H1 (`# Heading` or `= Heading =`) is never used as - this conflicts with the article title. The only exception to this is - on the home page, where the plugin name is displayed. -- Longer articles should have their contents listed at the top, with - wikilinks to each section of the page. -- Incomplete pages should have a warning at the top saying so. GitHub - wikis have no support for templates, or for transclusion, so you must - copy it manually from a different wiki page. - -These conventions may or may not be wholly followed throughout the wiki, -though it would be beneficial for new pages and new revisions to follow -this convention. diff --git a/docs/Creating-a-category.md b/docs/Creating-a-category.md deleted file mode 100644 index f41d919d..00000000 --- a/docs/Creating-a-category.md +++ /dev/null @@ -1,54 +0,0 @@ -# Creating a category - -Categories are stored in `categories.yml`. On older versions of Quests -they were stored in the main `config.yml`; quests will read categories -from `config.yml` if a `categories.yml` file is not present. - -## Category ID - -ID of category, this is the text you should enter when putting quests -inside a category. - -## Display - - -*`display`* - -The item that is shown in the GUI. - -### Name - - -*`display.name`* - -The name of the item. - -### Lore - - -*`display.lore`* - -The lore (description) of the item. - -### Type - - -*`display.type`* - -The type (material name/id) of item. - -## Permission required - - -*`permission-required`* - -Whether permission is needed to open this category, or start quests -within it. This permission will follow this format: -`quests.category.`\`. - -## Hidden - - -*`hidden`* - -Whether this category is shown in the main quests menu. diff --git a/docs/Creating-a-quest-or-category.md b/docs/Creating-a-quest-or-category.md deleted file mode 100644 index a109d3e3..00000000 --- a/docs/Creating-a-quest-or-category.md +++ /dev/null @@ -1,10 +0,0 @@ -*** - -### ๐Ÿ—‘๏ธ ***This page is subject to removal*** -*This page has been superseded, is unmaintained, or is not required. The information contained here may be inaccurate or incomplete.* - -*** - -**This page has been moved, please see the following pages instead:** -- [Creating a quest](Creating-a-quest) -- [Creating a category](Creating-a-category) \ No newline at end of file diff --git a/docs/Creating-a-quest.md b/docs/Creating-a-quest.md deleted file mode 100644 index fe85bdea..00000000 --- a/docs/Creating-a-quest.md +++ /dev/null @@ -1,444 +0,0 @@ -Each file inside the `quests` subfolder represents a -single quest. The **name** of the file represents the **quest id** and -must be alphanumeric (excluding the .yml extension). - -An example can be seen with the [default -configuration](https://github.com/LMBishop/Quests/blob/master/bukkit/src/main/resources/resources/bukkit/quests/example1.yml). - -## Table of contents - -- [Quest ID](Creating_a_quest#Quest_ID "wikilink") -- [Tasks](Creating_a_quest#Tasks "wikilink") -- [Display](Creating_a_quest#Display "wikilink") - - [Name](Creating_a_quest#Name "wikilink") - - [Normal lore](Creating_a_quest#Normal_lore "wikilink") - - [Started lore](Creating_a_quest#Started_lore "wikilink") - - [Type](Creating_a_quest#Type "wikilink") -- [Rewards](Creating_a_quest#Rewards "wikilink") -- [Start commands](Creating_a_quest#Start_commands "wikilink") -- [Start string](Creating_a_quest#Start_string "wikilink") -- [Reward string](Creating_a_quest#Reward_string "wikilink") -- [Placeholders](Creating_a_quest#Placeholders "wikilink") -- [Options](Creating_a_quest#Options "wikilink") - - [Category](Creating_a_quest#Category "wikilink") - - [Requirements](Creating_a_quest#Requirements "wikilink") - - [Permission - required](Creating_a_quest#Permission_required "wikilink") - - [Cancellable](Creating_a_quest#Cancellable "wikilink") - - [Counts towards - limit](Creating_a_quest#Counts_towards_limit "wikilink") - - [Repeatable](Creating_a_quest#Repeatable "wikilink") - - [Cooldown](Creating_a_quest#Cooldown "wikilink") - - [Time limit](Creating_a_quest#Time_limit "wikilink") - - [Sort order](Creating_a_quest#Sort_order "wikilink") - - [Autostart](Creating_a_quest#Autostart "wikilink") - - [Completed display](Creating_a_quest#completed_display "wikilink") - - [Cooldown display](Creating_a_quest#cooldown_display "wikilink") - - [Permission display](Creating_a_quest#permission_display "wikilink") - - [Locked display](Creating_a_quest#locked_display "wikilink") - -## Quest ID - -The quest ID is the name of the file (excluding .yml extension) and must -alphanumeric and unique. This ID is used as the reference in commands, -players' quest progress file and in placeholders. - -## Tasks - - -*`tasks`* - -Tasks are the objectives the player must do to complete the quest. -Simalar to quest IDs, there are task IDs. They can be identical to the -quest ID but must be unique to each other. - -For help on adding the tasks, refer to [task configuration -layout](Task_configuration_layout "wikilink") - -## Display - - -*`display`* - -This is the item which will be shown to the player in the quest GUI. - -### Name - - -*`display.name`* - -The name of the item. This is also the name used in chat messages. - -``` yaml -display: - name: "&cExample I (Single Task)" -``` - -### Normal lore - - -*`display.lore-normal`* - -The lore (description) of the item as seen if the quest is not started. - -``` yaml -display: - ... - lore-normal: - - "&cThis category is designed to show you the different" - - "&cattributes a quest can have." - - "" - - "&7This quest requires you to:" - - "&7 - Break &f30 blocks&7." - - "" - - "&7Rewards:" - - "&7 - &f10 &7diamonds." -``` - -### Started lore - - -*`display.lore-started`* - -The lore (description) of the item **appended to `lore-normal`** if the -quest is started. This is a good place to put progression details. To -get the progression of a player in a task, write `{TASKID:progress}` and -replace `TASKID` with the ID of the task you want to get the progress -for. Alternatively, you can write `{TASKID:complete}` to get if the task -is complete. - -``` yaml -display: - ... - lore-started: - - "" - - "&7Your current progression:" - - "&7 - &f{mining:progress}&7/30 blocks broken." -``` - -### Type - - -*`display.type`* - -The type (material name) of item. - -``` yaml -display: - ... - type: "WOODEN_PICKAXE" -``` - -## Rewards - - -*`rewards`* - -**Optional.** This is a list of commands which will be executed when the -player completes the quest. You can use `{player}` and the players name -will be substituted in place. - -``` yaml -rewards: - - "give {player} diamond 10" -``` - -## Start commands - - -*`startcommands`* - -**Optional.** This is a list of commands which will be executed when the -player starts the quest. You can use `{player}` and the player's name -will be substituted in place. - -``` yaml -startcommands: - - "broadcast {player} has started a quest" -``` - -## Start string - - -*`startstring`* - -**Optional.** This is a list of messages which will be sent to the -player when they start the quest. This is useful for telling the player -their objectives. - -``` yaml -startstring: - - " &8- &7You must break 30 blocks." -``` - -## Reward string - - -*`rewardstring`* - -**Optional.** This is a list of messages which will be sent to the -player when they complete the quest. This is useful for telling the -player their rewards. - -``` yaml -rewardstring: - - " &8- &7You have received 10 dimaonds." -``` - -## Placeholders - - -*`placeholders`* - -**Optional.** This is a set of placeholders which can be accessed using -PlaceholderAPI. To get the progression of a player in a task, write -`{TASKID:progress}` and replace `TASKID` with the ID of the task you -want to get the progress for. Alternatively, you can write -`{TASKID:complete}` to get if the task is complete. - -``` yaml -placeholders: - description: "&7Break &f30 blocks &7of any type." - progress: " &8- &f{mining:progress}&7/30 broken" -``` - -These placeholders will be called using PlaceholderAPI. See [quest -progress in scoreboard](Quest_progress_in_scoreboard "wikilink") for a -guide which utilises this feature. - -## Options - - -*`options`* - -This section defines quest-specific options. - -### Category - - -*`options.category`* - -**Optional.** The category the quest will be in. You should put the ID -of the category here. - -``` yaml -options: - ... - category: "example" -``` - -### Requirements - - -*`options.requires`* - -**Optional.** List of Quest IDs the player must complete before being -able to start this quest. - -``` yaml -options: - ... - requires: - - "quest-id" -``` - -### Permission required - - -*`options.permission-required`* - -**Optional.** Whether or not the quest should require a permission to -start. The permission will be `quests.quest.`. - -``` yaml -options: - ... - permission-required: false -``` - -### Cancellable - - -*`options.cancellable`* - -**Optional.** Whether or not this quest can be cancelled. If global or -local quest autostart is enabled, or is cancelling quests is disabled, -then this option is ignored. - -``` yaml -options: - ... - cancellable: false -``` - -### Counts towards limit - - -*`options.counts-towards-limit`* - -**Optional.** Whether or not this quest counts towards the players quest -started limit. If global quest autostart is enabled, this will have no -effect as quest limits are disabled. - -``` yaml -options: - ... - counts-towards-limit: false -``` - -### Repeatable - - -*`options.repeatable`* - -**Optional.** Whether or not the quest can be replayed. - -``` yaml -options: - ... - repeatable: false -``` - -### Cooldown - - -*`options.cooldown`* - -**Optional.** Whether ot not the quest is placed on cooldown or is -immediately replayable. - -``` yaml -options: - ... - cooldown: - enabled: true - time: 1440 # minutes -``` - -### Time limit - - -*`options.time-limit`* - -**Optional.** Whether or not this quest has a time limit to complete it. -If the time limit is reached, the quest will be cancelled and progress -reset. - -``` yaml -options: - ... - time-limit: - enabled: true - time: 1440 # minutes -``` - -### Sort order - - -*`options.sort-order`* - -**Optional.** How the plugin sorts the quests in the GUI, lower numbers -come first. - -``` yaml -options: - ... - sort-order: 1 -``` - -### Autostart - - -*`options.autostart`* - -**Optional.** Whether or not the quest should automatically be started. -This is similar to enabling quest autostart for the entire plugin, but -specific only to this quest, meaning it cannot be cancelled and counts -towards the players quest started limit. - -See [ยง counts towards -limit](Creating_a_quest#Counts_towards_limit "wikilink") if you do not -want autostart quests to count towards the quest started limit. - -``` yaml -options: - ... - autostart: true -``` - -### Completed display - - -*`options.completed-display`* - -**Optional.** The display item this quest should take if it is -completed. This accepts the standard ItemStack definition format -described in [Defining items](Defining_items "wikilink"). If this option -is not specified, the display item [defined in the main -config.yml](GUI-configuration#quest-completed-display "wikilink") will -be used. - -``` yaml -options: - ... - completed-display: - type: "STEAK" -``` - -### Cooldown display - - -*`options.cooldown-display`* - -**Optional.** The display item this quest should take if it is on -cooldown. This accepts the standard ItemStack definition format -described in [Defining items](Defining_items "wikilink"). If this option -is not specified, the display item [defined in the main -config.yml](GUI-configuration#quest-cooldown-display "wikilink") will be -used. - -``` yaml -options: - ... - cooldown-display: - type: "STEAK" -``` - -### Permission display - - -*`options.permission-display`* - -**Optional.** The display item this quest should take if the player does -not have permission to start it. This accepts the standard ItemStack -definition format described in [Defining -items](Defining_items "wikilink"). If this option is not specified, the -display item [defined in the main -config.yml](GUI-configuration#quest-permission-display "wikilink") will -be used. - -``` yaml -options: - ... - permission-display: - type: "STEAK" -``` - -### Locked display - - -*`options.locked-display`* - -**Optional.** The display item this quest should take if the player has -not unlocked it. This accepts the standard ItemStack definition format -described in [Defining items](Defining_items "wikilink"). If this option -is not specified, the display item [defined in the main -config.yml](GUI-configuration#quest-locked-display "wikilink") will be -used. - -``` yaml -options: - ... - locked-display: - type: "STEAK" -``` diff --git a/docs/Custom-GUI-items.md b/docs/Custom-GUI-items.md deleted file mode 100644 index 97cc27f1..00000000 --- a/docs/Custom-GUI-items.md +++ /dev/null @@ -1,61 +0,0 @@ -**Custom GUI items** are dummy items added to the category menu and the -quest menu. This can be used to help stylise your quests GUI. - -This can be done in the `config.yml`: - -``` yaml -custom-elements: - "categories": # apply to the categories menu (the main menu by default) - 0: # <--- slot 1, note the slots start from 0! so 0 = slot 1 in this case - display: - name: "&cExample Custom Item (slot 1)" - lore: - - "&7This is a custom item which can be added" - - "&7to your menus. This is purely cosmetic." - - "" - - "&7Two empty slots should follow." - type: "DIAMOND_BLOCK" - 1: # <--- start from slot 2 - spacer: true # empty slot in GUI - repeat: 2 # repeats for 2 slots - 3: # <--- start from slot 4 - display: - name: "&cExample Custom Item (slots 4 - 7)" - lore: - - "&7This is a custom item which can be added" - - "&7to your menus, but in slot 4 and repeated" - - "&73 times." - - "&7" - - "&7This will come after 2 empty slots." - - "&7" - - "&7This is purely cosmetic." - type: "NETHERRACK" - repeat: 3 # repeats for 3 more slots - commands: - - "this command will be executed if the player click on this item" -``` - -The optional `repeat` field will repeat the item for consecutive slots -after that. - -The optional `commands` list will execute commands if the player clicks -on the item. The `{player}` placeholder can be used to substitute the -player name. - -These custom elements take precedence over quest items, as quests and -categories will fill empty slots once all the custom items have been -set. - - - -To add a custom item within the quest menu itself, you must specify the -category, or if categories are disabled you can specify "quests" -instead: - -``` yaml -custom-elements: - "c:": # apply to menu - ... - "quests": # apply to whole quests menu if categories are disabled - ... -``` diff --git a/docs/Data-migration-tool.md b/docs/Data-migration-tool.md deleted file mode 100644 index 2022f285..00000000 --- a/docs/Data-migration-tool.md +++ /dev/null @@ -1,27 +0,0 @@ -The **data migration tool** is a tool that allows you to migrate your -data from one [storage provider](Storage_providers "wikilink") to -another. This can also be used as a backup tool. The tool can be -accessed using `/quests admin migratedata`, which will generate a file -[migrate_data.yml](https://github.com/LMBishop/Quests/blob/master/bukkit/src/main/resources/resources/bukkit/migrate_data.yml), -where you must configure both providers. - -The `from` section is the configuration for the storage provider you are -migrating from. The `to` section is the configuration for the storage -provider you are migrating to. Both sections are required. - -When you have entered the information for both systems, you must set the -`ready` flag to **true** at the end of the file. Then, to execute the -migration, run the following command: - - /quests admin migratedata execute - - -โš ๏ธ **It is advised that you do this process on a server with no players -online.** You should set a whitelist, or turn on maintenence mode, -before migrating data, and these commands should be done through your -server console. Trying this process with players online may result in -unexpected behaviour, or worse, potential data corruption! - -Once the migration has finished, you can safely delete migrate_data.yml. -You may also want to manually update your main configuration to point to -the new data provider. diff --git a/docs/Defining-items.md b/docs/Defining-items.md deleted file mode 100644 index e8312f6d..00000000 --- a/docs/Defining-items.md +++ /dev/null @@ -1,327 +0,0 @@ -An **ItemStack** is a **representation of an item** in an inventory. -Every configured ItemStack in Quests is parsed the exact same way. This -page gives guidance on how to define items with specific attributes. - -## Table of contents - -- [Configurable options](Defining_items#Configurable_options "wikilink") - - [Configuration - layout](Defining_items#Configuration_layout "wikilink") - - [Examples](Defining_items#Examples "wikilink") - - [Name](Defining_items#Name "wikilink") - - [Item](Defining_items#Item "wikilink") - - [Lore](Defining_items#Lore "wikilink") - - [Enchantments](Defining_items#Enchantments "wikilink") - - [Item flags](Defining_items#Item_flags "wikilink") - - [Unbreakable](Defining_items#Unbreakable "wikilink") - - [Attribute - modifiers](Defining_items#Attribute_modifiers "wikilink") - - [Custom model data](Defining_items#Custom_model_data "wikilink") - - [Owner](Defining_items#Owner "wikilink") -- [Quest items](Defining_items#Quest_items "wikilink") - - [Importing items](Defining_items#Importing_items "wikilink") - - [Manually defined - items](Defining_items#Manually_defined_items "wikilink") - - [Defined](Defining_items#Defined "wikilink") - - [MMOItems](Defining_items#MMOItems "wikilink") - - [Slimefun](Defining_items#Slimefun "wikilink") - - [ExecutableItems](Defining_items#ExecutableItems "wikilink") - - [Referencing a quest - item](Defining_items#Referencing_a_quest_item "wikilink") - -## Configurable options - -| Field | Optional | Minecraft Version | More Information | -|----------------------|------------------|-------------------|-------------------------------------------------------| -| `item` | โŒ | \- | [Jump](Defining_items#Item "wikilink") | -| `name` | โœ… \* | \- | [Jump](Defining_items#Name "wikilink") | -| `lore` | โœ… | \- | [Jump](Defining_items#Lore "wikilink") | -| `enchantments` | โœ… | \- | [Jump](Defining_items#Enchantments "wikilink") | -| `itemflags` | โœ… | 1.8+ | [Jump](Defining_items#Item_flags "wikilink") | -| `unbreakable` | โœ… | 1.13+ | [Jump](Defining_items#Unbreakable "wikilink") | -| `attributemodifiers` | โœ… | 1.13+ | [Jump](Defining_items#Attribute_modifiers "wikilink") | -| `custommodeldata` | โœ… | 1.14+ | [Jump](Defining_items#Custom_model_data "wikilink") | -| `owner-[...]` | โœ… | 1.8+ | [Jump](Defining_items#Owner_(skulls) "wikilink") | - -\*: The name must be defined for the display item of Quests. - -### Configuration layout - -``` yaml -item: - name: "&6&lSuper Cool Stick" - item: STICK - lore: - - "&7Really cool lore." - # field4: value4 - # etc. -``` - -### Examples - -#### Item - - -*`item` or `type`material* - -The item is the material the itemstack is made out of. Please see the -[latest -javadocs](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) -(1.13+) or the [1.12 -javadocs](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) -(1.8-1.12) for item names. For 1.8-1.12, data codes can be added on at -the end with a colon `:`. - -``` yaml -item: - item: "WHEAT" - ... -``` - -#### Name - - -*`name`* - -The name is displayed at the top of the item when hovered over, or just -above the hotbar when selected. - -``` yaml -item: - name: "&2&lSuper Cool Name" - ... -``` - -#### Lore - - -*`lore`* - -The lore is the description of the item seen when hovering over it. You -can remove this omit entirely if a lore is not desired. - -``` yaml -item: - lore: - - "Line 1" - - "Line 2" - ... -``` - -#### Enchantments - -The format of enchantments depends on your Minecraft version. - - -**Pre-1.13**: Use [spigot -names](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/enchantments/Enchantment.html) --\> format "{enchantment}:{level}" - -**1.13+**: Use Vanilla names -\> namespace for vanilla enchantments is -"minecraft" -\> format "{namespace}:{enchantment}:{level}" - -``` yaml -item: - enchantments: - - "minecraft:infinity:1" - ... -``` - -#### Item flags - -Item flags can be added to hide enchantment names, etc. A full list of -itemflags is available on the [Spigot -javadocs](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/inventory/ItemFlag.html). - -``` yaml -item: - itemflags: - - "HIDE_ATTRIBUTES" - ... -``` - -#### Unbreakable - -- *1.13+*' - -``` yaml -item: - unbreakable: true - ... -``` - -#### Attribute modifiers - -**1.13+** Adds specific attribute modifiers to the items. The UUID -should always be specified otherwise the server will randomly generate -one on each restart. Full list of attributes is available on the [Spigot -javadocs](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html), -along with full list of -[operations](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/AttributeModifier.Operation.html). - -``` yaml -item: - attributemodifiers: - - attribute: GENERIC_MOVEMENT_SPEED - modifier: - uuid: "49dc07dc-bfdb-4dc7-85d3-66ef52b51858" - name: "generic.movementSpeed" - operation: ADD_NUMBER - amount: 0.03 - equipmentslot: HAND - - attribute: GENERIC_MOVEMENT_SPEED - modifier: - uuid: "e22513cf-b15f-4443-9e2f-103c0ff9731b" - name: "generic.movementSpeed" - operation: ADD_NUMBER - amount: 0.01 - equipmentslot: OFF_HAND - ... -``` - -#### Custom model data - -**1.14+** - -``` yaml -item: - custommodeldata: 12345 - ... -``` - -#### Owner - -This only applies if you have a skull item stack (`PLAYER_HEAD` 1.13+, -`SKULL_ITEM` 1.8-1.12). There are three ways to define the player for -the skull: by **username**; **uuid**; or, **base64 encoded string**. - -The **preferred method** is to **explicitly specify a base64 encoded -string**. Using any of the other two methods require that the player has -joined the server before, and may possibly make a request to Mojang -(locking the server thread) depending on which server software you use. - -You can get the base64 encoded representation of a player skin here: -. It will look like the following (may be -referred to as 'texture data'): - - ewogICJ0aW1lc3RhbXAiIDogMTYyNTgzNjU0OTAxNCwKICAicHJvZmlsZUlkIiA6ICJlMmNlNzA0ZWVjNGE0YjE4YTNlYjA4MTRiMzdmYTFkNCIsCiAgInByb2ZpbGVOYW1lIiA6ICJmYXRwaWdzYXJlZmF0IiwKICAic2lnbmF0dXJlUmVxdWlyZWQiIDogdHJ1ZSwKICAidGV4dHVyZXMiIDogewogICAgIlNLSU4iIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlLzJiMTIzMWEyZjNkYTQ2OTQxZDY1OWI4NDNjZWZhNDljOGE1NTA0ZjE4MzNlOTA3YzY3YmJiMTQ2NTE0OTlhNyIKICAgIH0KICB9Cn0= - -You can specify each type by the following: - -``` yaml -item: - owner-base64: "base64 encoded string" - ... -``` - -``` yaml -item: - owner-username: "username" - ... -``` - -``` yaml -item: - owner-uuid: "uuid" - ... -``` - -## Quest items - -**Quest items** can help simplify your configuration by putting -individual itemstacks inside a named file (under directory items/), to -allow for easy referencing from a task configuration and reducing -configuration duplication across your quests. - -The types of quest items are as follows: - -- `raw` (items imported using /q a items import) -- `defined` (items manually written following the format above) -- `mmoitems` (items from MMOItems) -- `slimefun` (items from Slimefun) -- `executableitems` (items from ExecutableItems) - -### Importing items - -**Importing** an item means creating a new quest item **from the item -you are holding** in game. To do this, simply hold the desired item and -run `/q a items import `, where `` is the desired name of the -item. Your item will be saved to file items/\.yml, **with the type -'raw**'. - - - -### Manually defining items - -You can manually define an item by creating a new `yml` file within the -items/ directory. You must specify a `type` and the item itself under -`item`. - -#### Defined - -**Defined quest items** are regular ItemStacks and follow the format -defined under [ยง Configurable -options](Defined_items#Configurable_options "wikilink"). - - items/testitem.yml - -``` yaml -type: "defined" -item: - name: "Cool item" - type: DIAMOND_SWORD - lore: - - "Really cool lore" -``` - -#### MMOItems - -**MMOItems quest items** are ItemStacks which belong to the MMOItems -plugin. - - items/testitem.yml - -``` yaml -type: "mmoitems" -item: - type: "BOW" #mmoitems type - id: "HELL_BOW" #mmoitems id -``` - -#### Slimefun - -**Slimefun quest items** are ItemStacks which belong to the Slimefun -plugin. - - items/testitem.yml - -``` yaml -type: "slimefun" -item: - id: "slimefun_item_id" #slimefun id -``` - -#### ExecutableItems - -**ExecutableItems quest items** are ItemStacks which belong to the -ExecutableItems plugin. - - items/testitem.yml - -``` yaml -type: "executableitems" -item: - id: "executableitems_id" #executableitems id -``` - -### Referencing a quest item - -In most cases where an ItemStack is accepted in Quests, you can simply -provide the ID of the quest item under the key `quest-item`. - -``` yaml -# Within a task -type: "inventory" -item: - quest-item: "testitem" -``` diff --git a/docs/Download.md b/docs/Download.md deleted file mode 100644 index cbee853d..00000000 --- a/docs/Download.md +++ /dev/null @@ -1,54 +0,0 @@ -Release builds of Quests are officially distributed at the -sites on this page. Sources not listed here may contain modified, or -outdated versions. - -## Release builds - -- [SpigotMC - (preferred)](https://www.spigotmc.org/resources/quests-1-8-1-19-set-up-goals-for-players.23696/) -- [Modrinth](https://modrinth.com/mod/quests) -- [Polymart](https://polymart.org/resource/quests.938) -- [Songoda](https://songoda.com/marketplace/product/quests-quests.544) -- [GitHub](https://github.com/LMBishop/Quests/releases) -- [Hangar (testing)](https://hangar.benndorf.dev/LMBishop/Quests) - -Please note Hangar is still in active development and testing. It may be -removed at any time. - -### Distribution status - -Some platforms may not be up-to-date yet. - - - -## Development builds - -- [GitHub Actions](https://github.com/LMBishop/Quests/actions) - -Development builds are automatically built by GitHub. You may need a -GitHub account to see or download these artifacts. - -Instructions on building Quests is also provided here: - - -## License - -The full license text is available here: - - - Quests - - Copyright (C) 2022 Leonardo Bishop and contributors - - This program is free software: you can redistribute it and/or modify - it under the terms of the GNU General Public License as published by - the Free Software Foundation, either version 3 of the License, or - (at your option) any later version. - - This program is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - GNU General Public License for more details. - - You should have received a copy of the GNU General Public License - along with this program. If not, see [https://www.gnu.org/licenses]. diff --git a/docs/GUI-configuration.md b/docs/GUI-configuration.md deleted file mode 100644 index fb63d1f1..00000000 --- a/docs/GUI-configuration.md +++ /dev/null @@ -1,262 +0,0 @@ - -*See also [Custom GUI items](Custom_GUI_items "wikilink") and [Defining -items](Defining_items "wikilink").* - -The **GUI configuration** is defined in the `config.yml`. These define -the static UI elements such as the back button, quest locked display -etc. All options accept the standard ItemStack definition format -described in [Defining items](Defining_items "wikilink"). - -## Back button - - -*`gui.back-button`* - -The back button displayed within sub menus. - -``` yaml -gui: - ... - back-button: - name: "&cReturn" - lore: - - "&7Return to the categories menu." - type: "ARROW" -``` - -## Page previous - - -*`gui.page-prev`* - -The previous page button displayed on paiginated menus. - -``` yaml -gui: - ... - page-prev: - name: "&7Previous Page" - lore: - - "&7Switch the page to page &c{prevpage}." - type: "FEATHER" -``` - -The `{prevpage}` variable represents the page number for the previous -page. - -## Page next - - -*`gui.page-next`* - -The next page button displayed on paiginated menus. - -``` yaml -gui: - ... - page-next: - name: "&7Next Page" - lore: - - "&7Switch the page to page &c{nextpage}." - type: "FEATHER" -``` - -The `{nextpage}` variable represents the page number for the next page. - -## Page description - - -*`gui.page-next`* - -The current page item displayed on paginated menus. The amount of this -item will automatically update on the page number. - -``` yaml -gui: - ... - page-desc: - name: "&7Page &c{page}" - lore: - - "&7You are currently viewing page &c{page}." - type: "PAPER" -``` - -The `{page}` variable represents the page number for the current page. - -## Quest locked display - - -*`gui.quest-locked-display`* - -The item is used to represent locked quests. A quest is locked if its -[requirements](Creating_a_quest#Requirements "wikilink") are not met. - -``` yaml -gui: - ... - quest-locked-display: - name: "&c&lQuest Locked" - lore: - - "&7You have not completed the requirements" - - "&7for this quest (&c{quest}&7)." - - "" - - "&7Requires: &c{requirements}" - - "&7to be completed to unlock." - type: "RED_STAINED_GLASS_PANE" -``` - -The `{quest}` variable represents the quest [display -name](Creating_a_quest#name "wikilink"), with its formatting stripped. - -The `{questid}` variable represents the quest ID. - -The `{requirements}` variable represents the display names of the quests -needed to unlock this quest. By default, this name is truncated to show -only the first quest, with a number after (e.g. "Example II +4 more"). -This behaviour is defined at [Basic options ยง GUI-truncate -requirements](Basic-options#GUI-truncate-requirements "wikilink") - -## Quest permission display - - -*`gui.quest-permission-display`* - -The item is used to represent quests which the player does not have -permission to start. - -``` yaml -gui: - ... - quest-permission-display: - name: "&6&lNo Permission" - lore: - - "&7You do not have permission for this" - - "&7quest (&6{quest}&7)." - type: "BROWN_STAINED_GLASS_PANE" -``` - -The `{quest}` variable represents the quest [display -name](Creating_a_quest#name "wikilink"), with its formatting stripped. - -The `{questid}` variable represents the quest ID. - -## Quest cooldown display - - -*`gui.quest-cooldown-display`* - -The item is used to represent quests which are repeatable, the player -has completed, but are on cooldown. - -``` yaml -gui: - ... - quest-cooldown-display: - name: "&e&lQuest On Cooldown" - lore: - - "&7You have recently completed this quest" - - "&7(&e{quest}&7) and you must" - - "&7wait another &e{time} &7to unlock again." - type: "ORANGE_STAINED_GLASS_PANE" -``` - -The `{quest}` variable represents the quest [display -name](Creating_a_quest#name "wikilink"), with its formatting stripped. - -The `{questid}` variable represents the quest ID. - -The `{time}` variable represents the formatted time remaining until the -cooldown period is over. This can be configured in the messages section. - -## Quest completed display - - -*`gui.quest-completed-display`* - -The item is used to represent quests which are completed and not -repeatable. - -``` yaml -gui: - ... - quest-completed-display: - name: "&a&lQuest Complete" - lore: - - "&7You have completed this quest" - - "&7(&a{quest}&7) and cannot." - - "&7repeat it." - type: "GREEN_STAINED_GLASS_PANE" -``` - -The `{quest}` variable represents the quest [display -name](Creating_a_quest#name "wikilink"), with its formatting stripped. - -The `{questid}` variable represents the quest ID. - -## No started quests - - -*`gui.no-started-quests`* - -This is shown as the only item in the quest started menu if the player -has not started any quests. - -``` yaml -gui: - ... - no-started-quests: - name: "&c&lNo Started Quests" - lore: - - "&7Go start some!" - type: "FEATHER" -``` - -## Quest cancel yes - - -*`gui.quest-cancel-yes`* - -Confirmation item in the quest cancel menu. - -``` yaml -gui: - ... - quest-cancel-yes: - name: "&a&lConfirm Cancel" - lore: - - "&7Confirm you wish to cancel" - - "&7this quest and lose all" - - "&7progress." - type: "GREEN_STAINED_GLASS_PANE" -``` - -## Quest cancel no - - -*`gui.quest-cancel-no`* - -Cancellation item in the quest cancel menu. - -``` yaml -gui: - ... - quest-cancel-no: - name: "&c&lAbort Cancel" - lore: - - "&7Return to the quest menu." - type: "RED_STAINED_GLASS_PANE" -``` - -## Quest cancel background - - -*`gui.quest-cancel-background`* - -Background item in the quest cancel menu. - -``` yaml -gui: - ... - quest-cancel-background: - type: "GRAY_STAINED_GLASS_PANE" -``` diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 00000000..778d0bd7 --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,81 @@ +GEM + remote: https://rubygems.org/ + specs: + addressable (2.8.4) + public_suffix (>= 2.0.2, < 6.0) + colorator (1.1.0) + concurrent-ruby (1.2.2) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + eventmachine (1.2.7) + ffi (1.15.5) + forwardable-extended (2.6.0) + google-protobuf (3.23.3-x86_64-linux) + http_parser.rb (0.8.0) + i18n (1.14.1) + concurrent-ruby (~> 1.0) + jekyll (4.3.2) + addressable (~> 2.4) + colorator (~> 1.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (>= 0.3.6, < 0.5) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-default-layout (0.1.5) + jekyll (>= 3.0, < 5.0) + jekyll-sass-converter (3.0.0) + sass-embedded (~> 1.54) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + just-the-docs (0.5.4) + jekyll (>= 3.8.5) + jekyll-seo-tag (>= 2.0) + rake (>= 12.3.1) + kramdown (2.4.0) + rexml + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.8.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.4.0) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (5.0.1) + rake (13.0.6) + rb-fsevent (0.11.2) + rb-inotify (0.10.1) + ffi (~> 1.0) + rexml (3.2.5) + rouge (4.1.2) + safe_yaml (1.0.5) + sass-embedded (1.63.6-x86_64-linux-gnu) + google-protobuf (~> 3.23) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + unicode-display_width (2.4.2) + webrick (1.8.1) + +PLATFORMS + x86_64-linux + +DEPENDENCIES + jekyll (~> 4.3.2) + jekyll-default-layout + just-the-docs + +BUNDLED WITH + 2.4.13 diff --git a/docs/Getting-started.md b/docs/Getting-started.md deleted file mode 100644 index d5c3bece..00000000 --- a/docs/Getting-started.md +++ /dev/null @@ -1,22 +0,0 @@ -*** - -### ๐Ÿ”จ ***This page is under construction*** -*The information contained here may be inaccurate or incomplete. You can help by [contributing information to the wiki](https://github.com/LMBishop/Quests/wiki/Contributing-to-the-wiki).* - -Refer to the following pages instead: -* [Creating a quest or category](https://github.com/LMBishop/Quests/wiki/Creating-A-Quest-Or-Category) -* [Task configuration layout](https://github.com/LMBishop/Quests/wiki/Task-Configuration-Layout) -* [Global configurations](https://github.com/LMBishop/Quests/wiki/Global-Configurations) -* [Storage providers](https://github.com/LMBishop/Quests/wiki/Storage-Providers) -* [Configuration problems](https://github.com/LMBishop/Quests/wiki/Configuration-Problems) - -These are also listed on the sidebar. - -*** - -Welcome to Quests! This wiki should help you with creating your own custom quests on your server. - -### What is a quest? -A **quest** is simply a **group of tasks** which a player must complete in return for a reward. - -Each **task** may have a different **task type**, which range from breaking blocks to reaching a certain position in the world. Quests provides over 30 different types you can use, listed on [this page](https://github.com/LMBishop/Quests/wiki/Task-Types). diff --git a/docs/Global-configurations.md b/docs/Global-configurations.md deleted file mode 100644 index a575ebc8..00000000 --- a/docs/Global-configurations.md +++ /dev/null @@ -1,91 +0,0 @@ -**Global configurations** are intended to be used in place of -**quest-specific configurations**. This helps reduce repetition across -your configuration as you copy common elements from quest to quest, and -also allows you to quickly propagate edits across quests. - -## Global task configuration - -A global task configuration will add configuration values to all tasks -of a specified type. - -For example (in `config.yml`), - -``` yaml -... -global-task-configuration: - types: - inventory: - update-progress: true -... -``` - -This will add to *all* tasks configurations with `type: inventory` -across *all* quests the following: `update-progress: true`. *'Note that -any errors coming from here will appear as if they are coming from -individual quests.* - -Quest-level configurations will override anything set here. To change -this behaviour, modify the [global task configuration -override](Basic_options#Global_task_configuration_override "wikilink"). - -## Global quest display configuration - -A global quest display configuration adds text to the display items of -items in the GUI. - -By default, this is already configured: - -``` yaml -global-quest-display: - lore: - append-not-started: - - "" - - "&eLeft Click &7to start this quest." - append-started: - - "" - - "&aYou have started this quest." - - "&eMiddle Click &7to track this quest." - - "&eRight Click &7to cancel this quest." - append-tracked: - - "" - - "&aYou are &etracking &athis quest." - - "&eMiddle Click &7to stop tracking this quest." - - "&eRight Click &7to cancel this quest." -``` - - - -If you do not want this, simply remove the section. - -## Global macros - -Global macros are designed to help you reduce repetition across your -configuration files by centralizing values in your config.yml. Think of -them as your own variables/placeholders which you can use in your quest -files. - -To explain this feature, an example is more appropriate. - -In your config.yml, you can add a macro under the `global-macros` -section: - - global-macros: - ... - # : - top-bar: "&6---&7---&6---" - -To use these in your quests, simply reference it by using -`<$m name-of-macro $m>`. Macro names **cannot have spaces**. - -For example, to use the `top-bar` macro in `example-quest.yml`: - -``` yaml -tasks: - ... -display: - ... - lore-normal: - - "<$m top-bar $>" - - "..." - ... -``` diff --git a/docs/New-task-type.md b/docs/New-task-type.md deleted file mode 100644 index 4a3eb5dc..00000000 --- a/docs/New-task-type.md +++ /dev/null @@ -1,80 +0,0 @@ -*** - -### ๐Ÿ”จ ***This page is under construction*** -*The information contained here may be inaccurate or incomplete. You can help by [contributing information to the wiki](https://github.com/LMBishop/Quests/wiki/Contributing-to-the-wiki).* - -*** - -The following information is for developers who are interested in integrating Quests into their own plugin. - -Quests are a set of tasks which the player must complete in return for a reward. The **task** the player must complete depends on the **task type**, and how it is configured. When quests are loaded from the config, they are registered to each task type the quest contains. - -## Purpose of a task type -**The role of a task type is to handle the progress of tasks within quests which registered with your type.** - -How a task type handles the progress differs with each one. For example, a `blockbreak` task type may increase the progress whenever a block is broken, or a `position` task type may flag the quest as completed when a player is near a defined location. - -How a task type works generally follows this format: -1. Listen for related event -2. Iterate over every quest registered to the task type -3. Check if the player has started the quest -4. Iterate over each task of the quest -5. If the task is incomplete, increment the progress according to criteria -6. Mark the task as complete if over threshold - -Quests handles the completion of all tasks within a quest and dispatches rewards. **A task type simply handles the events which increment a single task.** - -โš  Task Types **MUST** be registered before the actual quests from the config are registered. They can be registered in between Quests inital activation and before the server is fully started. For example: you can register new Task Types inside of the `onEnable()` and add Quests to the `depend` or `softdepend` section of your `plugin.yml` to make sure that Quests is ready to accept your registration. - -Attempting to register a task type after the registration period has closed will throw a `IllegalStateException`. The registration period closes and quests are loaded after every plugin has finished loading (on the first server [tick](https://github.com/LMBishop/Quests/blob/master/src/main/java/com/leonardobishop/quests/Quests.java#L129)). - -## Writing task types -Your new Task Type must extend the [`TaskType`](https://github.com/LMBishop/Quests/blob/master/common/src/main/java/com/leonardobishop/quests/common/tasktype/TaskType.java) class. **`BukkitTaskType` implements `Listener` and automatically registers as an event listener if used with the `BukkitTaskTypeManager`.** Your subclass must pass the name of the Task Type into the constructor, and optionally the authors name and a brief description of the task. - -Example: -```java -public final class MiningTaskType extends BukkitTaskType { - - public MiningTaskType() { - super("blockbreak", "LMBishop", "Break a set amount of blocks."); - } - -} -``` -The name of the Task Type (`blockbreak` in this case) is what server owners put into their config. -### Bukkit listeners -You can use Bukkit event listeners like you normally would in your own plugin. The class is already registered as a listener by Quests. - -It is recommended that you set your event priority to `MONITOR` (only if you do not cancel the event) and setting `ignoreCancelled` to true in the `EventHandler` annotation. - -```java -@EventHandler(priority = EventPriority.MONITOR, ignoreCancelled = true) -``` -### Configuration -Quests will load the configuration of each task into a `HashMap` in the [`Task`](https://github.com/LMBishop/Quests/blob/master/common/src/main/java/com/leonardobishop/quests/common/quest/Task.java) class. Server owners define their task configuration in the quest config, for example: -```yaml -tasks: - mining: - type: "blockbreakcertain" - amount: 81 - block: GOLD_ORE -``` -Will lead to the following map: -```java -configValues = {type="blockbreakcertain";amount=81;block="GOLD_ORE"} -``` -These values can be accessed through `Task#getConfigValue(String)`. You can also specify a default value to be returned if a server owner has not defined a value with `Task#getConfigValue(String, String)`. - -### Implementing methods -The [`TaskType`](https://github.com/LMBishop/Quests/blob/master/common/src/main/java/com/leonardobishop/quests/common/tasktype/TaskType.java) class has some methods which can be optionally overridden. - -The `onReady()` method is called when the server has registered all quests to your task type. - -The `onStart()` method is called when a player starts a quest containing a task of your task type. - -The `onDisable()` method is called when the plugin is disabled, or is reloaded. If the plugin is reloaded, this will unregister all quests from your task type, then register the new quests again. - -The `validateConfig(String, HashMap)` method is called when each task is loaded. It is used to detect potential configuration issues and can be used to prevent the quest from loading if, for example, a required config option is missing. The first string is the task root (e.g `tasks.mining` in the first example) and the map is the config to check. The return type is a list of `ConfigProblem`, returning a list containing at least one `ConfigProblem` with an `ERROR` type will prevent the quest from loading. - -### Modifying progress -You can modify progress by obtaining an instance of a players `QuestProgressFile`, getting the specific `QuestProgress` and then getting the specific `TaskProgress`. You can see an example of this in the [`MiningTaskType`](https://github.com/LMBishop/Quests/blob/master/src/main/java/com/leonardobishop/quests/quest/tasktype/type/MiningTaskType.java) (which contains comments through the file). \ No newline at end of file diff --git a/docs/PlaceholderAPI.md b/docs/PlaceholderAPI.md deleted file mode 100644 index b726450c..00000000 --- a/docs/PlaceholderAPI.md +++ /dev/null @@ -1,117 +0,0 @@ -๐Ÿ“œ **No PAPI eCloud download is necessary - placeholders come with the plugin.** - -Jump to section: -* [Common placeholders (quest counters and lists)](#common-placeholders) -* [Advanced placeholders (quest details, per-category counters and lists)](#common-placeholders) -* [Caching placeholders](#caching-placeholders) - -## Common placeholders -### Quest counters -|Placeholder|Description| -|---|---| -|`%quests_all%`|Returns the **number** of quests on the server.| -|`%quests_completed%`|**\*** Returns the **number** of quests the player has completed.| -|`%quests_completedbefore%`|Returns the **number** of quests the player has completed **at least once**.| -|`%quests_started%`|Returns the **number** of quests which are active for the player.| -|`%quests_categories%`|Returns the **number** of categories on the server.| -### Quest lists -|Placeholder|Description| -|---|---| -|`%quests_all_list%`|Returns a **comma-seperated\*\* list** of quest **names** on the server.| -|`%quests_completed_list%`|\* Returns a **comma-seperated\*\* list** of quest **names** the player has completed.| -|`%quests_completedbefore_list%`|Returns a **comma-seperated\*\* list** of quest **names** the player has completed **at least once**.| -|`%quests_started_list%`|Returns a **comma-seperated\*\* list** of quest **names** which are active for the player.| -|`%quests_categories_list%`|Returns a **comma-seperated\*\* list** of category **names** on the server.| -### Quest ID lists -|Placeholder|Description| -|---|---| -|`%quests_all_listid%`|Returns a **comma-seperated\*\* list** of quest **IDs** on the server.| -|`%quests_completed_listid%`|\* Returns a **comma-seperated\*\* list** of quest **IDs** the player has completed.| -|`%quests_completedbefore_listid%`|Returns a **comma-seperated\*\* list** of quest **IDs** the player has completed **at least once**.| -|`%quests_started_listid%`|Returns a **comma-seperated\*\* list** of quest **IDs** which are active for the player.| -|`%quests_categories_listid%`|Returns a **comma-seperated\*\* list** of category **IDs** on the server.| - -**\*** *this does not include quests which have been repeated and not yet completed* - -**\*\*** *the delimiter can be changed by adding it in at the end: for example `%quests_completed_listid_ / %` will return a list of completed quests **seperated by the characters ` / ` (including the spaces around it)*** - -## Advanced placeholders -### Quest details -|Placeholder|Description| -|---|---| -|`%quests_quest:%`|Returns the **display name** of the quest **``**.| -|`%quests_quest:_started%`|Returns **true/false** on whether or not the quest **``** is started by the player.| -|`%quests_quest:_starteddate%`|Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the quest **``** was started by the player.| -|`%quests_quest:_completed%`|**\*** Returns **true/false** on whether or not the quest **``** is completed by the player.| -|`%quests_quest:_completedbefore%`|Returns **true/false** on whether or not the quest **``** is completed by the player **at least once**.| -|`%quests_quest:_completiondate%`|Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the quest **``** was completed by the player.| -|`%quests_quest:_cooldown%`|Returns a **time in seconds** of the cooldown for quest **``**.| -|`%quests_quest:_canaccept%`|Returns **true/false** on whether or not the quest **``** can be started by the player.| -|`%quests_quest:_meetsrequirements%`|Returns **true/false** on whether or not the player has completed the required quests for the quest **``**.| -|`%quests_quest:_task:_progress%`|Returns the **progress** of task **`task-id`** on the quest **``**.| -|`%quests_quest:_task:_completed%`|Returns **true/false** on whether or not the task **`task-id`** on the quest **``** is completed by the player.| -|`%quests_quest:_p:%`|Returns the **local quest placeholder ``** for the quest **``**.| - -|Placeholder|Description| -|---|---| -|`%quests_tracked%`|Returns the **display name** of the **players tracked quest** (or "No tracked quest").| -|`%quests_tracked_started%`|Returns **true/false** on whether or not the **players tracked quest** is started.| -|`%quests_tracked_starteddate%`|Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the **players tracked quest** was started by the player.| -|`%quests_tracked_completed%`|**\*** Returns **true/false** on whether or not the **players tracked quest** is completed.| -|`%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_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:_progress%`|Returns the **progress** of task **`task-id`** on the **players tracked quest**.| -|`%quests_tracked_task:_completed%`|Returns **true/false** on whether or not the task **`task-id`** on the **players tracked quest** is completed by the player.| -|`%quests_tracked_p:%`|Returns the **local quest placeholder ``** for the **players tracked quest**.| - -### Per-category quest counters -|Placeholder|Description| -|---|---| -|`%quests_category:%`|Returns the **id** of the category **``** (useful to check if it is a valid reference).| -|`%quests_category:_all%`|Returns the **number** of quests in the category **``**.| -|`%quests_category:_completed%`|**\*** Returns the **number** of quests in the category **``** the player has completed.| -|`%quests_category:_completedbefore%`|Returns the **number** of quests in the category **``** the player has completed **at least once**.| -|`%quests_category:_started%`|Returns the **number** of quests in the category **``** which are active for the player.| - -### Per-category quest lists -|Placeholder|Description| -|---|---| -|`%quests_category:_all_list%`|Returns a **comma-seperated\*\* list** of quest **names** on the server.| -|`%quests_category:_completed_list%`|\* Returns a **comma-seperated\*\* list** of quest **names** in the category **``** the player has completed.| -|`%quests_category:_completedbefore_list%`|Returns a **comma-seperated\*\* list** of quest **names** in the category **``** the player has completed **at least once**.| -|`%quests_category:_started_list%`|Returns a **comma-seperated\*\* list** of quest **names** in the category **``** which are active for the player.| - -### Per-category quest ID lists -|Placeholder|Description| -|---|---| -|`%quests_category:_all_listid%`|Returns a **comma-seperated\*\* list** of quest **IDs** on the server.| -|`%quests_category:_completed_listid%`|\* Returns a **comma-seperated\*\* list** of quest **IDs** in the category **``** the player has completed.| -|`%quests_category:_completedbefore_listid%`|Returns a **comma-seperated\*\* list** of quest **IDs** in the category **``** the player has completed **at least once**.| -|`%quests_category:_started_listid%`|Returns a **comma-seperated\*\* list** of quest **IDs** in the category **``** which are active for the player.| - -**\*** *this does not include quests which have been repeated and not yet completed* - -**\*\*** *the delimiter can be changed by adding it in at the end: for example `%quests_category:_completed_listid_ / %` will return a list of completed quests **seperated by the characters ` / ` (including the spaces around it)*** - -**\*\*\*** *the date format may be adjusted by including it at the end: for example `%quests_q:_completiondate_dd/MM HH:mm:ss%` will return a the date of compltion **formatted as `dd/MM HH:mm:ss`** - you may use any letter listed [here](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html)* - -## Caching placeholders -Placeholders may be cached for a short period (10 seconds by default) to help improve performance. To do this, **simply add `_cache` to the end of any placeholder**. Note: date formats are automatically cached as parsing them may be heavy. - -**Examples:** -``` -%quests_all_cache% -%quests_completedbefore_listid_cache% -%quests_quest:_task:_progress_cache% -``` - -The length of time Quests retains this cache can be configured in the configuration under `options.placeholder-cache-time`. By default, this cache is **10 seconds**. - -```yaml -options: - ... - placeholder-cache-time: 10 -``` \ No newline at end of file diff --git a/docs/Quest-debugger.md b/docs/Quest-debugger.md deleted file mode 100644 index 8533a2e2..00000000 --- a/docs/Quest-debugger.md +++ /dev/null @@ -1,46 +0,0 @@ -The **quests debugger** allows you to see why a quest may not be working -as intended. When turned on for a quest, it will print out what a task -type is doing and how it is evaluating it. This can be helpful to see -why a specific quest is not accepting a specific action. - -## Using the debugger - -The debugger can be enabled with **/q a debug quest \ -\**. Using \* in place of \ will enable it for all -quests. Enabling it for all will show debug logs for every player, -whereas self will show it for just yourself. - - - -## Example - -We may want to debug the following task: - -``` yaml -tasks: - mining: - type: "blockbreakcertain" - amount: 30 - blocks: - - DARK_OAK_LOG - - DARK_OAK_PLANKS - reverse-if-placed: false -``` - -When breaking PACKED_ICE, the debugger sends this output: - - -Here it is telling us that the task type is checking the broken block -against all the blocks in the `blocks` list, and not finding a match, -thus skipping this task. - -Now, when breaking DARK_OAK_PLANKS: - - - -The debugger tells us that it finds a match and increments the task -progress. - -This can be useful when trying to work out why a task may not be -working, such as in the case where you think you're breaking a block of -a specific type, but in reality it has a different type. diff --git a/docs/Quest-progress-in-scoreboard.md b/docs/Quest-progress-in-scoreboard.md deleted file mode 100644 index 5d05b8b4..00000000 --- a/docs/Quest-progress-in-scoreboard.md +++ /dev/null @@ -1,180 +0,0 @@ -This guide will show you how to show quest progress in a scoreboard. The -plugin -[](AnimatedScoreboard "wikilink") -will provide this scoreboard, however this will work for any plugin -accepting PlaceholderAPI. - -**This utilises three features from Quests:** - -- tracking quests -- PlaceholderAPI integration -- local quest placeholders - -The final result will look like this: - - - -## Adding local quest placeholders - -Local quest placeholders are used here to provide the progress of the -quest and to provide a breif description of the quest. We will use a -simple blockbreak quest as our base here, where we must break 30 blocks -to complete the quest. - - /Quests/quests/example1.yml - -``` yaml -... - -placeholders: - description: "&7Break &f30 blocks &7of any type." - progress: " &8- &f{mining:progress}&7/30 broken" - -... -``` - -These placeholders will be called using PlaceholderAPI using the -AnimatedScoreboard plugin. For example, using the placeholder -`%quests_q:example1_p:description%` with PlaceholderAPI will return -`&7Break &f30 blocks &7of any type.`. These are known as [local quest -placeholders](PlaceholderAPI#Quest_details "wikilink"). - -Our `description` placeholder provides a description of the quest. The -\`progress\` placeholder will show the players progression with the -quest. - -**You can create any placeholders here, and decide the names for -yourself.** These are designed for you to be able to access information -about a quest with PlaceholderAPI. Avoid using underscores and spaces, -this may cause issues when referencing them using placeholders. - -To see the full quest (with comments), click -[here](https://github.com/LMBishop/Quests/blob/master/src/main/resources/resources/bukkit/quests/example1.yml "wikilink"). - -## Configuring AnimatedScoreboard - -โš ๏ธ **This guide assumes you have a basic understanding of the plugin -[](AnimatedScoreboard "wikilink").** - -For our config with AnimatedScoreboard, we will create two seperate -scoreboards: one with tracked quest information and one informing the -user that they are not tracking a quest. - - /AnimatedScoreboard/scoreboards/questtrack.yml - -``` yaml -display: - title: - text: - - "&6&lAmazing Server" - line-1: - text: - - "&7" - score: 5 - line-2: - text: - - "&e&lTracked Quest:" - score: 4 - line-3: - text: - - "&e%quests_tracked%" - score: 3 - line-4: - text: - - "&7%quests_tracked_p:description%" - score: 2 - line-5: - text: - - "&7%quests_tracked_p:progress%" - score: 1 - line-6: - text: - - "&7" - score: 0 -``` - -The placeholder `%quests_tracked<...>%` will access the players tracked -quest. In order to track a quest you must middle-click in-game on the -quest within the GUI. By default, when you start a quest it is -automatically tracked. - -Simply put, we are accessing the placeholders called `description` and -`progress` which we made earlier in the player's tracked quest. - -Now, we are going to create a default scoreboard for when there is no -tracked quest. - - /AnimatedScoreboard/scoreboards/defaultscoreboard.yml - -``` yaml -display: - title: - text: - - "&6&lAmazing Server" - line-1: - text: - - "&7" - score: 3 - line-2: - text: - - "&e&lTracked Quest:" - score: 2 - line-3: - text: - - "&7You are not tracking a quest." - score: 1 - line-4: - text: - - "&7" - score: 0 -``` - -This is a simple static scoreboard. Finally, we must add a trigger to -switch between the two scoreboards. - -Triggers must first be enabled within AnimatedScoreboard: - - /AnimatedScoreboard/config.yml - -``` yaml -... -enable-triggers: true -... -``` - -Then, the server must be restarted. There should be a new folder called -`triggers`. - -Now, we must create two files `ontrack.yml` and `ontrackend.yml`. This -will switch between the two scoreboard whenever the player tracks / -stops tracking a quest. - - /AnimatedScoreboard/triggers/ontrack.yml - -``` yaml -event: com.leonardobishop.quests.bukkit.api.event.PlayerStartTrackQuestEvent -target-player: getPlayer -trigger-scoreboard: questtrack -``` - -This will switch to the \`questtrack\` scoreboard when a quest is -tracked. - - /AnimatedScoreboard/triggers/ontrackend.yml - -``` yaml -event: com.leonardobishop.quests.bukkit.api.event.PlayerStopTrackQuestEvent -target-player: getPlayer -trigger-scoreboard: defaultscoreboard -``` - -This will switch to the \`defaultscoreboard\` scoreboard when a quest is -no longer tracked. - -That's it! Restart the server and you should be able to see the progress -update in the scoreboard. Please note, you will have to include local -quest placeholders for every quest. - -## Further reading - -- [Creating a quest](Creating_a_quest "wikilink") diff --git a/docs/Storage-providers.md b/docs/Storage-providers.md deleted file mode 100644 index 41467dad..00000000 --- a/docs/Storage-providers.md +++ /dev/null @@ -1,137 +0,0 @@ -A **storage provider** is a source for player data -(sometimes referred to as quest progress files). Quests requires that -one storage system be configured to allow the plugin to initialise. If -there is no storage system configured, the plugin will default to -**yaml** storage. If there is an error for any reason during the -initialisation of a storage system, the plugin will be disabled. - -- YAML (`yaml`) -- MySQL (`mysql`) - -When changing storage systems, **the plugin must be restarted for the -changes to have effect**. - -## Table of contents - -- [Supported storage - systems](Storage_providers#Supported_storage_systems "wikilink") - - [Flatfile](Storage_providers#Flatfile "wikilink") - - [YAML](Storage_providers#YAML "wikilink") - - [Network](Storage_providers#Network "wikilink") - - [MySQL](Storage_providers#MySQL "wikilink") -- [Data - synchronisation](Storage_providers#Data_synchronisation "wikilink") - - [Delay loading](Storage_providers#Delay_loading "wikilink") - -## Supported storage systems - -### Flatfile - -#### YAML - -Storing player data in YAML files is the default storage method in -Quests, and is a type of 'flatfile' storage. - -``` yaml -options: - ... - storage: - provider: "yaml" -``` - -Player data can be found inside Quests/playerdata/ and can be modified -as long as the server is not running. It is not recommended to try and -alter these files while the server is online, as this could cause data -consistency issues. - -### Network - - -โš ๏ธ **Using Quests on a BungeeCord network may lead to a possible race -condition.** Allowing players to to connect directly to another server -running Quests may result in the new server loading old data. This -occurs as BungeeCord establishes a connection with the new server before -disconnecting the player from the old one, leading to the new server -loading player data before the old server has saved it. - - - - -Quests offers a workaround, which is to [delay the loading of player -data](Storage_providers#Delay_loading "wikilink"). You may want to -consider forcing players to switch servers through a hub server, or -decreasing the autosave period. In either case, the race condition still -exists; there is not an easy way to coordinate the loading/saving due to -how BungeeCord works. **You must understand this warning before using -Quests in this way.** - -#### MySQL - -Quests can connect to and store player data in a MySQL database. This is -particularly useful if you want to have multiple servers use the same -player data. - -``` yaml -options: - ... - storage: - provider: "mysql" -``` - -You must also configure the plugin to connect to the database. - -``` yaml - database-settings: - network: - database: "minecraft" - username: "root" - password: "" - address: "localhost:3306" -``` - -The database specified **must** exist before connecting Quests to it. -The address is given in the following format: ip:port (e.g -127.0.0.1:3306). - -There are also some other options you can configure, as Quests uses -HikariCP to manage its connections to the database. You can see -descriptions of each option on the [HikariCP -README](https://github.com/brettwooldridge/HikariCP). - -``` yaml - connection-pool-settings: - maximum-pool-size: 8 - minimum-idle: 8 - maximum-lifetime: 1800000 - connection-timeout: 5000 - table-prefix: "quests_" -``` - -## Data synchronisiation - -### Delay loading - -Quests offers a workaround to the [race -condition](Storage_providers#Network "wikilink"), which is to delay the -loading of player data in hopes that the server before has enough time -to save the data. - -You can enable this in your config here: - -``` yaml -options: - ... - storage: - provider: "mysql" - synchronisation: - delay-loading: 0 # (ticks - change to any value above 0) - ... -``` - -A value of 50 (2.5 seconds) should be enough for most servers, however -you may want to increase it if, for example, your database is not on the -same network as your Minecraft server. Again, this **does not solve the -race condition**, but it should help mitigate it. - -See the issue in the issue tracker: -[1](https://github.com/LMBishop/Quests/issues/180) diff --git a/docs/Task-types.md b/docs/Task-types.md deleted file mode 100644 index 089fb464..00000000 --- a/docs/Task-types.md +++ /dev/null @@ -1,67 +0,0 @@ -Jump to section: -* [Non-dependent task types](#non-dependent-task-types) -* [Dependent task types](#dependent-task-types) -* [External task types](#external-task-types) - -## Non-dependent task types -The following Task Types come with the plugin and are activated automatically -### Spigot -* **[blockplace](https://github.com/LMBishop/Quests/wiki/blockplace-(task-type))** - Place a set amount of blocks. -* **[blockbreak](https://github.com/LMBishop/Quests/wiki/blockbreak-(task-type))** - Break a set amount of blocks. -* **[breeding](https://github.com/LMBishop/Quests/wiki/breeding-(task-type))** - Breed a set amount of animals. -* **[brewing](https://github.com/LMBishop/Quests/wiki/brewing-(task-type))** - Brew a set amount of potions. -* **[bucketempty](https://github.com/LMBishop/Quests/wiki/bucketempty-(task-type))** - Empty a specific bucket. -* **[bucketfill](https://github.com/LMBishop/Quests/wiki/bucketfill-(task-type))** - Fill a specific bucket. -* **[command](https://github.com/LMBishop/Quests/wiki/command-(task-type))** - Execute a specific command. -* **[consume](https://github.com/LMBishop/Quests/wiki/consume-(task-type))** - Consume a specific item. -* **[crafting](https://github.com/LMBishop/Quests/wiki/crafting-(task-type))** - Craft a specific item. -* **[dealdamage](https://github.com/LMBishop/Quests/wiki/dealdamage-(task-type))** - Deal a certain amount of damage. -* **[distancefrom](https://github.com/LMBishop/Quests/wiki/distancefrom-(task-type))** - Be a set distance away from certain co-ordinates. -* **[enchanting](https://github.com/LMBishop/Quests/wiki/enchanting-(task-type))** - Enchant a certain amount of items. -* **[expearn](https://github.com/LMBishop/Quests/wiki/expearn-(task-type))** - Earn a set amount of exp after starting the quest. -* **[farming](https://github.com/LMBishop/Quests/wiki/farming-(task-type))** - Farm a set amount of any crop. -* **[fishing](https://github.com/LMBishop/Quests/wiki/fishing-(task-type))** - Catch a set amount of items from the sea. -* **[inventory](https://github.com/LMBishop/Quests/wiki/inventory-(task-type))** - Obtain a set of items. -* **[milking](https://github.com/LMBishop/Quests/wiki/milking-(task-type))** - Milk a set amount of cows. -* **[mobkilling](https://github.com/LMBishop/Quests/wiki/mobkilling-(task-type))** - Kill a set amount of entities. -* **[permission](https://github.com/LMBishop/Quests/wiki/permission-(task-type))** - Test if a player has a permission. -* **[playerkilling](https://github.com/LMBishop/Quests/wiki/playerkilling-(task-type))** - Kill a set amount of players. -* **[playtime](https://github.com/LMBishop/Quests/wiki/playtime-(task-type))** - Play for a certain amount of time. -* **[position](https://github.com/LMBishop/Quests/wiki/position-(task-type))** - Reach a set of co-ordinates. -* **[shearing](https://github.com/LMBishop/Quests/wiki/shearing-(task-type))** - Shear a set amount of sheep. -* **[taming](https://github.com/LMBishop/Quests/wiki/taming-(task-type))** - Tame a set amount of animals. -* **[walking](https://github.com/LMBishop/Quests/wiki/walking-(task-type))** - Walk a set distance. -* **[smelting](https://github.com/LMBishop/Quests/wiki/smelting-(task-type))** - Smelt a set amount of items. - -## Dependent task types -The following Task Types come with the plugin, but require another plugin installed to activate: -### ASkyBlock -* **[askyblock_level](https://github.com/LMBishop/Quests/wiki/askyblock_level-(task-type))** - Reach a certain island level using ASkyBlock. -### Citizens -* **[citizens_deliver](https://github.com/LMBishop/Quests/wiki/citizens_deliver-(task-type))** - Deliver a set of items to a NPC. -* **[citizens_interact](https://github.com/LMBishop/Quests/wiki/citizens_interact-(task-type))** - Interact with an NPC to complete the task. -### uSkyBlock -* **[uskyblock_level](https://github.com/LMBishop/Quests/wiki/uskyblock_level-(task-type))** - Reach a certain island level using uSkyBlock. -### MythicMobs -* **[mythicmobs_killing](https://github.com/LMBishop/Quests/wiki/mythicmobs_killing-(task-type))** - Kill a set amount of a MythicMobs entity. -### BentoBox -* **[bentobox_level](https://github.com/LMBishop/Quests/wiki/bentobox_level-(task-type))** - Reach a certain island level in the level addon for BentoBox. -### IridiumSkyblock -* **[iridiumskyblock_value](https://github.com/LMBishop/Quests/wiki/iridiumskyblock_value-(task-type))** - Reach a certain island value for IridiumSkyblock. -### PlaceholderAPI -* **[placeholderapi_evaluate](https://github.com/LMBishop/Quests/wiki/placeholderapi_evaluate-(task-type))** - Parse any placeholder and evaluate its result. -### Essentials -* **[essentials_balance](https://github.com/LMBishop/Quests/wiki/essentials_balance-(task-type))** - Reach a certain balance. -* **[essentials_moneyearn](https://github.com/LMBishop/Quests/wiki/essentials_moneyearn-(task-type))** - Earn a certain amount of money. -### ShopGUI+ -* **[shopguiplus_buy](https://github.com/LMBishop/Quests/wiki/shopguiplus_buy-(task-type))** - Buy something from a ShopGUI+ shop. -* **[shopguiplus_sell](https://github.com/LMBishop/Quests/wiki/shopguiplus_sell-(task-type))** - Sell something to a ShopGUI+ shop. -### FabledSkyblock -* **[fabledskyblock_level](https://github.com/LMBishop/Quests/wiki/fabledskyblock_level-(task-type))**- Reach a certain island level for FabledSkyblock. -### SuperiorSkyblock2 -* **[superiorskyblock_level](superiorskyblock_level-(task-type))** - Reach a certain island level for SuperiorSkyblock. -* **[superiorskyblock_worth](superiorskyblock_worth-(task-type))** - Reach a certain island worth for SuperiorSkyblock. -### VotingPlugin -* **[votingplugin_vote](votingplugin_vote-(task-type))** - Vote a certain amount of times. -## External task types -Quests makes it easy for other developers to create their own task types. You can find help at [this page](https://github.com/LMBishop/Quests/wiki/New-Task-Type). \ No newline at end of file diff --git a/docs/Tips.md b/docs/Tips.md deleted file mode 100644 index b7e1ea42..00000000 --- a/docs/Tips.md +++ /dev/null @@ -1,36 +0,0 @@ -Creating and editing quests can seem daunting at first, but the plugin -is designed to be as easy as possible to use. - -Here's some tips which may help you with your quest creation. - -- **The wiki is your Bible.** This wiki details out how to create each - type of quest and the many different types of quests you can create. - There is a lot of information in this wiki (and it also took ages to - write)! -- **Use a dedicated editor, such as VSCode.** This will make life much - easier if you open the quests directory in VSCode, as you have access - to all the files at once within one editor and you can easily copy / - paste / replace across many files. -- **Plan out your quests.** It might be a wise idea to plan how you want - to create your quests, what categories they will be in and what the - requirements will be like. -- **Back up the /quests/ and /playerdata/ folder.** Things may go wrong - sometimes. You may lose data. On top of whatever backup system you - have, you should back up your quests folder and the playerdata folder, - \*especially\* on a live server. If you use a database, ensure that is - backed up too! -- **Name your quests in a way which makes sense.** Prefix each quest - file with the name of the category for organisation. Name your tasks - in a way which makes sense. -- **Organise your quests into folders.** The /quests/ directory is read - recursively, which means you can sort your quests into folders. (It is - advised you organise them by category, though you should be warned - that file names must still be unique, no matter what directory it is - under.) -- **Follow the advice of the error checker.** You will be informed of - any issues in your config when you reload Quests, along with the exact - location of the problem. Use this information! -- **Be patient.** Creating quests may be a bit boring, there might be a - lot of copying and pasting, but once you get into the rhythm it can - take you less than a few hours to get the plugin fully configured to - how you want it to be. diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md index 8b576e3c..fc25c8c6 100644 --- a/docs/_Sidebar.md +++ b/docs/_Sidebar.md @@ -4,24 +4,24 @@ ## [Home / FAQs](https://github.com/LMBishop/Quests/wiki) -[Getting started](Getting-started) +[Getting started](getting-started) [Downloading](download) -[Tips](Tips) +[Tips](tips) -[Commands and permissions](Commands-and-permissions) +[Commands and permissions](commands-and-permissions) ### **Configuration** -* [Basic options](Basic-options) -* [Creating a quest](Creating-a-quest) -* [Creating a category](Creating-a-category) +* [Basic options](configuration/basic-options.md) +* [Creating a quest](configuration/creating-a-quest.md) +* [Creating a category](configuration/creating-a-category.md) * [Global configurations](Global-Configurations) -* [GUI configuration](GUI-configuration) -* [Custom GUI items](Custom-GUI-items) -* [Configuration problems](Configuration-problems) -* [Storage providers](Storage-providers) -* [Defining items](Defining-items) -* [Colour (color) codes](Colour-codes) +* [GUI configuration](configuration/gui-configuration.md) +* [Custom GUI items](configuration/custom-gui-items.md) +* [Configuration problems](configuration/configuration-problems.md) +* [Storage providers](configuration/storage-providers.md) +* [Defining items](configuration/defining-items.md) +* [Colour (color) codes](configuration/colour-codes.md) * [Default configuration](Default-configuration) ### **Task Types** @@ -72,16 +72,16 @@ ### **API** -* [API](API) -* [New task type](New-task-type) +* [API](developer/api.md) +* [New task type](developer/new-task-type.md) ### **Guides** -* [Quest progress in scoreboard](Quest-progress-in-scoreboard) +* [Quest progress in scoreboard](guides/quest-progress-in-scoreboard.md) ### **Other** -* [PlaceholderAPI](PlaceholderAPI) -* [Quest debugger](Quest-debugger) -* [Data migration tool](Data-migration-tool) -* [Contributing to the wiki](Contributing-to-the-wiki) \ No newline at end of file +* [PlaceholderAPI](tools/placeholderapi.md) +* [Quest debugger](tools/quest-debugger.md) +* [Data migration tool](tools/data-migration-tool.md) +* [Contributing to the wiki](contributing-to-the-wiki) \ No newline at end of file diff --git a/docs/_config.yml b/docs/_config.yml index 7569680c..f41d5a4e 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -1,7 +1,35 @@ -title: Quests documentation +title: Quests description: Documentation for the Quests plugin - theme: just-the-docs +url: https://lmbishop.github.io + +callouts_level: quiet +callouts: + highlight: + color: yellow + how-to-read: + title: How to read this page + color: grey-dk + important: + title: Important + color: blue + new: + title: New + color: green + note: + title: Note + color: purple + caution: + title: Caution + color: yellow + warning: + title: Warning + color: red + +nav_external_links: + - title: Quests on GitHub + url: https://github.com/LMBishop/Quests + plugins: - jekyll-default-layout \ No newline at end of file diff --git a/docs/commands-and-permissions.md b/docs/commands-and-permissions.md new file mode 100644 index 00000000..8e10b845 --- /dev/null +++ b/docs/commands-and-permissions.md @@ -0,0 +1,85 @@ +--- +title: Commands and permissions +nav_order: 4 +--- +# Commands and permissions +This page lists all commands and permissions for Quests. Commands can +also be viewed in-game by simply running `/quests`. + +## Commands + +- **/quests \[or /q\]** - opens quest GUI +- **/quests help** - view help screen for quests commands +- **/quests started** - view a menu of started quests +- **/quests random \[category\]** - start a random quest \[in a random + category\] +- **/quests cancel \** - cancel quest by id +- **/quests q/quest \ \** - start quest + directly by ID. +- **/quests c/category \** - open category directly by ID. +- **/quests a/admin** - view help for admins + - **/quests a/admin opengui** - view help for opengui + - **/quests a/admin opengui q/quest \** - forcefully open + quests GUI for player (bypassing quests.command permission) + - **/quests a/admin opengui c/category \ \** - + forcefully open category by ID for player (bypassing + quests.command permission) + - **/quests a/admin opengui started \** - forcefully open + the started menu for player (bypassing quests.command permission) + - **/quests a/admin moddata** - view help for opengui + - **/quests a/admin moddata fullreset \** - fully clear a + players data file + - **/quests a/admin moddata reset \ \** - clear a + players data for a specifc quest + - **/quests a/admin moddata start \ \** - start a + quest for a player + - **/quests a/admin moddata complete \ \** - + complete a quest for a player + - **/quests a/admin moddata random \ \[category\]** - start + a random a quest for a player \[in a category\] + - *These commands modify quest progress for players. Use them + cautiously. Changes are irreversible.* + - **/quests a/admin items** - view registered quest items. + - **/quests a/admin items import \** - import a held quest + item. + - **/quests a/admin items give \ \ \[amount\]** - give + a player a quest item. + - **/quests a/admin debug** - view help for the [quest + debugger](quest_debugger "wikilink"). + - **/quests a/admin debug report** - generate a debug report. + - **/quests a/admin debug quest \ \** - enable + debug messages for a specific quest, or all of them. + - **/quests a/admin types \[type\]** - view activated task types, and + information on a specific one. + - **/quests a/admin info \[quest\]** - view loaded quests, and + information on a specific one. + - **/quests a/admin reload** - reload Quests. + - **/quests a/admin config** - see config problems. + - **/quests a/admin update** - check for updates. + - **/quests a/admin wiki** - get a link to the wiki. + - **/quests a/admin about** - view plugin information. + +## Permissions + +- `quests.command` - to view the quest menu (/quests) +- `quests.command.category` - to view a specific category (/q category) +- `quests.command.started` - to view quest started menu (/q started) +- `quests.command.quest` - to use /q quest +- `quests.command.start` - to start a quest by command (/q start) +- `quests.command.track` - to cancel a quest by command (q track) +- `quests.command.cancel` - to cancel a quest by command (/q cancel) +- `quests.command.random` - to starting a random quest (/q random) +- `quests.admin` - for admin commands + +The following are dependent on specific quests & categories: + +- `quests.category.` - permission to start quests within + `(category)`, if `permission-required` for the category is set to + `true` +- `quests.quest.` - permission to start quest `(quest id)`, if + `permission-required` for the quest is set to `true` + +The following are dependent on your configuration: + +- `quests.limit.` - permission to start a configured amount + of quests for members of this limit group diff --git a/docs/configuration/basic-options.md b/docs/configuration/basic-options.md new file mode 100644 index 00000000..24927b12 --- /dev/null +++ b/docs/configuration/basic-options.md @@ -0,0 +1,569 @@ +--- +title: Basic options +parent: Configuration +nav_order: 1 +--- +# Basic options +{: .no_toc } + +Quests allows you to configure **basic options** for the +plugin. These can all be located in the `config.yml`. + +{: .how-to-read } +> Each option is laid out with its path underneath the title. +> A dot in the path means an extra level of indentation, for example +> `options.categories-enabled` represents: +> +> ```yaml +> options: +> categories-enabled: [value] +> ``` +> +> You should have a working knowledge of how to format YAML files +> before configuring this plugin. + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +## Categories enabled + + +*`options.categories-enabled`* + +Choose whether or not quests will be sorted into categories. If this is +disabled, quests will be put into one big GUI instead, with categories +only helping determine the order they are sorted. + +``` yaml +options: + ... + categories-enabled: true +``` + +## Trim gui size + + +*`options.trim-gui-size`* + +Choose whether or not the quests GUI will scale down (reduce the number +of rows) so that there are not any empty rows. + +``` yaml +options: + ... + trim-gui-size: true +``` + +## Titles enabled + + +*`options.titles-enabled`* + +Choose whether or not titles will appear when starting / finishing +quests. + +``` yaml +options: + ... + titles-enabled: true +``` + +## Quest started limit + +*`options.quest-started-limit`* + +{: .warning } +**This option has been removed in version 3.8 and this wiki entry is +subject to removal.** Please see [quest limit](#quest-limit "wikilink") +instead. + +Choose the number of quests players can start at one time. This will +include quests which have [quest-specific +autostart](Creating_a_quest#Autostart "wikilink") enabled, however this +value will be ignored if [global +`quest-autostart`](Basic_options#Quest_autostart "wikilink") is enabled. + +``` yaml +options: + ... + quest-started-limit: 2 +``` + +## Quest limit + + +*`options.quest-limit`* + +Choose the number of quests players can start at one time. This will +include quests which have [quest-specific +autostart](Creating_a_quest#Autostart "wikilink") enabled, however this +value will be ignored if [global +`quest-autostart`](Basic_options#Quest_autostart "wikilink") is enabled. + +Each key is called a **limit group** (sometimes referred to as a quest +rank), and players can start the set number of quests depending on their +limit group. The group named `default` must be defined and is available +to everybody, however the rest can be granted through the permission +`quests.limit.`. + +``` yaml +options: + ... + quest-limit: + default: 2 + group1: 5 + group2: 10 + # ... +``` + +Group permissions are also documented in [Commands and permissions ยง +Permissions](commands-and-permissions#permissions "wikilink"). + +## Allow quest cancel + + +*`options.allow-quest-cancel`* + +Choose whether or not players can cancel quests themselves via command +or by right-clicking in the GUI. If this is set to false, consider +removing the right-click cancel instruction from the [global quest +display +configuration](Global_configurations#Global_quest_display_configuration "wikilink"). + +``` yaml +options: + ... + allow-quest-cancel: true +``` + +## Allow quest track + + +*`options.allow-quest-track`* + +Choose whether or not players can track quests themselves via command or +by middle-clicking in the GUI. If this is set to false, consider +removing the middle-click track instruction from the [global quest +display +configuration](Global_configurations#Global_quest_display_configuration "wikilink"). + +``` yaml +options: + ... + allow-quest-track: true +``` + +## Task type exclusions + + +*`options.task-type-exclusions`* + +Prevent Quests from allowing specific task type registrations from those +bearing a specific name. This can be used if you have an incompatible +plugin which causes a dependent task type to activate, thus potentially +leading to errors. + +``` yaml +options: + ... + task-type-exclusions: [] +``` + +**Example** + +``` yaml +options: + ... + task-type-exclusions: + - "blockbreak" + - "blockbreakcertain" +``` + +## Guinames + + +*`options.guinames`* + +Change and define specific GUI names for localization. + +``` yaml +options: + ... + guinames: + quests-category: "Quests Categories" + quests-menu: "Quests" + quests-started-menu: "Started Quests" + daily-quests: "Daily Quests" + quest-cancel: "Cancel Quest" +``` + +## Sounds + + +*`options.sounds`* + +Choose which sounds play at certain events. + +``` yaml +options: + ... + sounds: + quest-start: "ENTITY_PLAYER_LEVELUP:2:3" + quest-cancel: "UI_TOAST_OUT:2:3" + quest-complete: "UI_TOAST_CHALLENGE_COMPLETE:1.25:3" + gui: + open: "ITEM_BOOK_PAGE_TURN:1:3" + interact: "ITEM_BOOK_PAGE_TURN1:3" +``` + +To define a sound, choose one from [this +list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html) +(1.9+) or [this +list](https://helpch.at/docs/1.8.8/index.html?org/bukkit/Sound.html) +(1.8). + +To not have a sound play, you can leave the string blank (i.e. `""`), +for example: + +``` yaml +options: + ... + sounds: + quest-start: "" +``` + +You can choose a specific pitch and volume by including them in the +following format `SOUND:PITCH:VOLUME`. Note that the pitch is any float +between 0.5 and 2 (inclusively), and the volume must be greater than 0. +The volume only changes how far out the sound can be heard by the +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`. + +## GUI hide locked + + +*`options.gui-hide-locked`* + +Choose whether quests which cannot be started is visible to the player +or not. + +``` yaml +options: + ... + gui-hide-locked: false +``` + +## GUI confirm cancel + + +*`options.gui-confirm-cancel`* + +Choose whether or not there is a confirmation screen when right clicking +to cancel a quest. Cancelling by command does not prompt a confirmation +screen. + +``` yaml +options: + ... + gui-confirm-cancel: true +``` + +## GUI hide quests if no permission + + +*`options.gui-hide-quests-nopermission`* + +Choose whether or not quests are hidden to the player if they do not +have permission for the quest. + +``` yaml +options: + ... + gui-hide-quests-nopermission: false +``` + +## GUI hide categories if no permission + + +*`options.gui-hide-categories-nopermission`* + +Choose whether or not categories are hidden to the player if they do not +have permission for the category. + +``` yaml +options: + ... + gui-hide-categories-nopermission: false +``` + +## GUI use PlaceholderAPI + + +*`options.gui-use-placeholderapi`* + +Choose whether or not the quest GUI is parsed with PlaceholderAPI. This +is disabled by default for performance reasons. + +``` yaml +options: + ... + gui-use-placeholderapi: false +``` + +## GUI truncate requirements + + +*`options.gui-truncate-requirements`* + +Choose whether or not the displayed quest requirements for specific +quests should be cut short. The plugin will show "Quest 1 +X more" as +the requirement, rather than listing each quest "Quest 1, Quest 2, Quest +3, ..." to stop lores overflowing off the screen. + +``` yaml +options: + ... + gui-truncate-requirements: true +``` + +## GUI actions + + +*`options.gui-actions`* + +Set the click actions for the UI. For a list of click types, check the +[ClickType javadoc +page](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/ClickType.html). + +``` yaml +options: + ... + gui-actions: + start-quest: "LEFT" + track-quest: "MIDDLE" + cancel-quest: "RIGHT" +``` + +## Quest autostart + + +*`options.quest-autostart`* + +Choose whether or not players need to start quests themselves. This will +ignore the configured [quest started +limit](#Quest_started_limit "wikilink"), and is different from the +[autostart](#Autostart "wikilink") option. + +``` yaml +options: + ... + quest-autostart: false +``` + +## Quest autotrack + + +*`options.quest-autotrack`* + +Choose whether or not players need to track quests themselves. This will +automatically track quests when they are started, and will attempt to +track the next available started quests when the player finishes a +quest. + +``` yaml +options: + ... + quest-autotrack: true +``` + +## Verbose logging level + + +*`options.verbose-logging-level`* + +Choose how much quests will log to the console. This will filter the +output based on the following options: 0 = errors only, 1 = warnings, 2 += info, 3 = debug + +``` yaml +options: + ... + verbose-logging-level: 2 +``` + +## Quests use PlaceholderAPI + + +*`options.quests-use-placeholderapi`* + +Choose whether or not start strings, reward strings, reward commands and +start commands are parsed with PlaceholderAPI. This is disabled by +default for performance reasons. + +``` yaml +options: + ... + quests-use-placeholderapi: false +``` + +## Verify quest exists on load + + +*`options.verify-quest-exists-on-load`* + +Verify quests exist when a player's data is loaded - inconsistencies may +arise when players progress on specific quests and those quests are +later removed. Their progress is still retained in the quest progress +file, which may lead to issues such as players reaching a quest started +limit when the quests they had active no longer exist - having this +option enabled prevents non-existent quests from loading as quest +progress. + +``` yaml +options: + ... + verify-quest-exists-on-load: true +``` + +## Performance tweaking + + +*`options.performance-tweaking`* + +Set some specific options within the internals of Quests. + +The `queue executor interval` relates to how frequently players are +checked for completed quests. Not every player is checked at once for +performance purposes, and players are only submitted to the queue upon +completion of a task. The interval defines how frequently players are +polled from the queue. + +The `autosave interval` refers to how frequently all online players data +is saved. Data is saved at autosave intervals to prevent data loss +should the server crash. + +These options are measured in ticks, 1 second = 20 ticks. + +``` yaml +options: + ... + performance-tweaking: + quest-queue-executor-interval: 1 + quest-autosave-interval: 12000 +``` + +## Tab completion + + +*`options.tab-completion`* + +Choose whether or not commands can be tab completed. Quests will never +offer tab completions which players cannot run, regardless of this +setting. (In other words, players who are not admins will not see tab +completions for `/quests admin` if they do not have the admin +permission.) + +``` yaml +options: + ... + tab-completion: + enabled: true +``` + +## Error checking + + +*`options.error-checking`* + +Configure how Quests handles errors in your configuration. By default, +Quests will not allow quests to be loaded if they contain an +[error](Configuration_problems#Types_of_problem "wikilink"), since this +could lead to undefined behaviour. The option `override-errors` will +ignore this behaviour and forcibly allow the quest to be registered. + +``` yaml +options: + ... + error-checking: + override-errors: false +``` + +## Placeholder cache time + + +''`options.placeholder-cache-time`" + +Set how long Quests will retain parsed PlaceholderAPI strings in the +cache, in seconds. See [PlaceholderAPI ยง Caching +placeholders](PlaceholderAPI#Caching_placeholders "wikilink") for more +information. + +``` yaml +options: + ... + placeholder-cache-time: 10 +``` + +## Global task configuration override + + +*`options.global-task-configuration-override`* + +Choose whether or not options set in the [global task +configuration](Global_configurations#Global_task_configuration "wikilink") +will override per-quest specific options. + +``` yaml +options: + ... + global-task-configuration-override: false +``` + +## Global quest display configuration override + + +*`options.global-quest-display-configuration-override`* + +Choose whether or not the [global quest display +configuration](Global_configurations#Global_quest_display_configuration "wikilink") +will override per-quest specific options. + +``` yaml +options: + ... + global-quest-display-configuration-override: false +``` + +## Storage + + +*`options.storage`* + +Configure how Quests will store playerdata. See [storage +providers](Storage_providers "wikilink") for more info. + +``` yaml +options: + ... + storage: + provider: "yaml" + synchronisation: + delay-loading: 0 + database-settings: + network: + database: "minecraft" + username: "root" + password: "" + address: "localhost:3306" + connection-pool-settings: + maximum-pool-size: 8 + minimum-idle: 8 + maximum-lifetime: 1800000 + connection-timeout: 5000 + table-prefix: "quests_" +``` diff --git a/docs/configuration/colour-codes.md b/docs/configuration/colour-codes.md new file mode 100644 index 00000000..6c7339c0 --- /dev/null +++ b/docs/configuration/colour-codes.md @@ -0,0 +1,58 @@ +--- +title: Colour codes +parent: Configuration +nav_order: 8 +--- +# Colour (color) codes + +You can use colour codes anywhere the plugin accepts a message (plugin messages, display items, and in task configurations themselves). + +The following table shows the colour capabilities of specific server versions: + +| | Before 1.16 | 1.16+ | +| ---- | ---- | ---- | +| Colour Codes | โœ”๏ธ | โœ”๏ธ | +| Hexadecimal | โŒ | โœ”๏ธ | + +## Colour codes +The plugin will automatically translate colour codes from '&' to 'ยง' for you. + +| Name | Chat Code | Hex Equivalent | +| ---- | ---- | ---- | +| Black | `&0` | #000000 | +| Dark Blue | `&1` | #0000AA | +| Dark Green | `&2` | #00AA00 | +| Dark Aqua | `&3` | #00AAAA | +| Dark Red | `&4` | #AA0000 | +| Dark Purple | `&5` | #AA00AA | +| Gold | `&6` | #FFAA00 | +| Gray | `&7` | #AAAAAA | +| Dark Gray | `&8` | #555555 | +| Blue | `&9` | #5555FF | +| Green | `&a` | #55FF55 | +| Aqua | `&b` | #55FFFF | +| Red | `&c` | #FF5555 | +| Light Purple | `&d` | #FF55FF | +| Yellow | `&e` | #FFFF55 | +| White | `&f` | #FFFFFF | +| Obfuscated | `&k` | - | +| Bold | `&l` | - | +| Strikethrough | `&m` | - | +| Underline | `&n` | - | +| Italic | `&o` | - | +| Reset | `&r` | - | + +## Hexadecimal colour +For compatible Minecraft versions, the plugin will also translate hex colour codes for you. + +You can include a hex colour code as you would with a normal colour code: `&#`. + +{: .important } +The `#` symbol indicates a hexadecimal colour code. These must be exactly six characters long. + +For example, the following messages are identical: +``` +&cThis is a red message. + +&#FF5555This is a red message. +``` diff --git a/docs/configuration/configuration-problems.md b/docs/configuration/configuration-problems.md new file mode 100644 index 00000000..a55bbfde --- /dev/null +++ b/docs/configuration/configuration-problems.md @@ -0,0 +1,96 @@ +--- +title: Configuration problems +parent: Configuration +nav_order: 9 +--- + +# Configuration problems + +If you have a configuration error, Quests will log details both to the console and in-game (if you use `/q a reload`). + +![](https://i.imgur.com/5o7EyVm.png) + +These problems are designed to be as readable as possible, allowing self-diagnosis for your configuration. Warnings are also used to spot common misconfigurations, which may lead to quests not working as expected, thus being interpreted as a bug. + +Most problems have extended descriptions if you mouse-over them in-game. + +## Types of problem + +| Type | Description | +|:-------:|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Error | Errors prevent the specific quest from loading. These can be overidden in the config at `options.error-checking.override-errors`. Examples include an incorrect quest ID or malformed YAML file. | +| Warning | Warnings have no impact other than to inform you that a quest may not work as expected. Examples include an invalid material for a blockbuildcertain task, or a required quest which does not exist. | + +## Understanding a problem +Problems generally follow this format: +``` + ---- + | - : : +``` + +**Example 1** + +Take the following configuration. + +```yaml +tasks: + damage: + type: "dealdamage" +``` +The following error will show if you try to create a `dealdamage` task without specifying how much damage needs to be dealt. +``` +example1.yml ---- + | - E: Required field 'amount' is missing for task type 'dealdamage' :tasks.damage.amount +``` +In the above example, the problem is an error (as denoted by E) and will prevent the quest (`example1`) from loading. +The descriptor at the end shows you exactly where the error comes from in the YML file, which looks like this: + +The source of the error is given by `:tasks.damage.amount`, where each dot denotes a level of indentation. In this case, it is expecting a value at `amount`, but it is not defined. + +Below is the fixed version. + +```yaml +tasks: + damage: + type: "dealdamage" + amount: 10 +``` + +**Example 2** + +``` +example2.yml ---- + | - E: Expected an integer for 'amount', but got 'ten' instead :tasks.inventory.amount + | - W: Material 'notablock' does not exist :tasks.inventory.item + | - W: Quest requirement 'example' does not exist :options.requires +``` +```yaml +tasks: + inventory: + type: "inventory" + amount: ten + item: notablock +... +options: + requires: + - "example" + ... +``` +In this case, the task is broken since instead of numbers for the amount of items needed (`amount`), the string "ten" is there instead, causing an error. The source of the error is indicated by the location at the end `tasks.inventory.amount`. + +Also, a warning is shown for the item "thisisnotablock" at `tasks.inventory.item` and for the requirement "example" at `options.requires`. These warnings are informing you that the task may not work as expected, as "thisisnotablock" is not a real item, and that the quest "example" which is required to have been completed in order to start this quest does not exist. + +Unlike errors, warnings do not prevent quests from being loaded. + +Below is a fixed version: +```yaml +tasks: + inventory: + type: "inventory" + amount: 10 + item: DIAMOND +... +options: + # requirements section removed + ... +``` \ No newline at end of file diff --git a/docs/configuration/creating-a-category.md b/docs/configuration/creating-a-category.md new file mode 100644 index 00000000..e777b260 --- /dev/null +++ b/docs/configuration/creating-a-category.md @@ -0,0 +1,68 @@ +--- +title: Creating a category +parent: Configuration +nav_order: 3 +--- + +# Creating a category +{: .no_toc } + +Categories are stored in `categories.yml`. On older versions of Quests +they were stored in the main `config.yml`; quests will read categories +from `config.yml` if a `categories.yml` file is not present. + + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +## Category ID + +ID of category, this is the text you should enter when putting quests +inside a category. + +## Display + + +*`display`* + +The item that is shown in the GUI. + +### Name + + +*`display.name`* + +The name of the item. + +### Lore + + +*`display.lore`* + +The lore (description) of the item. + +### Type + + +*`display.type`* + +The type (material name/id) of item. + +## Permission required + + +*`permission-required`* + +Whether permission is needed to open this category, or start quests +within it. This permission will follow this format: +`quests.category.`\`. + +## Hidden + + +*`hidden`* + +Whether this category is shown in the main quests menu. diff --git a/docs/configuration/creating-a-quest.md b/docs/configuration/creating-a-quest.md new file mode 100644 index 00000000..6e3b7283 --- /dev/null +++ b/docs/configuration/creating-a-quest.md @@ -0,0 +1,428 @@ +--- +title: Creating a quest +parent: Configuration +nav_order: 2 +--- + +# Creating a quest +{: .no_toc } + +Each file inside the `quests` subfolder represents a +single quest. The **name** of the file represents the **quest id** and +must be alphanumeric (excluding the .yml extension). + +{: .note } +An example can be seen in the [default +configuration](https://github.com/LMBishop/Quests/blob/master/bukkit/src/main/resources/resources/bukkit/quests/example1.yml). + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +## Quest ID + +The quest ID is the name of the file (excluding .yml extension) and must +alphanumeric and unique. This ID is used as the reference in commands, +players' quest progress file and in placeholders. + +## Tasks + + +*`tasks`* + +Tasks are the objectives the player must do to complete the quest. +Simalar to quest IDs, there are task IDs. They can be identical to the +quest ID but must be unique to each other. + +For help on adding the tasks, refer to [task configuration +layout](Task_configuration_layout "wikilink") + +## Display + + +*`display`* + +This is the item which will be shown to the player in the quest GUI. + +### Name + + +*`display.name`* + +The name of the item. This is also the name used in chat messages. + +``` yaml +display: + name: "&cExample I (Single Task)" +``` + +### Normal lore + + +*`display.lore-normal`* + +The lore (description) of the item as seen if the quest is not started. + +``` yaml +display: + ... + lore-normal: + - "&cThis category is designed to show you the different" + - "&cattributes a quest can have." + - "" + - "&7This quest requires you to:" + - "&7 - Break &f30 blocks&7." + - "" + - "&7Rewards:" + - "&7 - &f10 &7diamonds." +``` + +### Started lore + + +*`display.lore-started`* + +The lore (description) of the item **appended to `lore-normal`** if the +quest is started. This is a good place to put progression details. To +get the progression of a player in a task, write `{TASKID:progress}` and +replace `TASKID` with the ID of the task you want to get the progress +for. Alternatively, you can write `{TASKID:complete}` to get if the task +is complete. + +``` yaml +display: + ... + lore-started: + - "" + - "&7Your current progression:" + - "&7 - &f{mining:progress}&7/30 blocks broken." +``` + +### Type + + +*`display.type`* + +The type (material name) of item. + +``` yaml +display: + ... + type: "WOODEN_PICKAXE" +``` + +## Rewards + + +*`rewards`* + +**Optional.** This is a list of commands which will be executed when the +player completes the quest. You can use `{player}` and the players name +will be substituted in place. + +``` yaml +rewards: + - "give {player} diamond 10" +``` + +## Start commands + + +*`startcommands`* + +**Optional.** This is a list of commands which will be executed when the +player starts the quest. You can use `{player}` and the player's name +will be substituted in place. + +``` yaml +startcommands: + - "broadcast {player} has started a quest" +``` + +## Start string + + +*`startstring`* + +**Optional.** This is a list of messages which will be sent to the +player when they start the quest. This is useful for telling the player +their objectives. + +``` yaml +startstring: + - " &8- &7You must break 30 blocks." +``` + +## Reward string + + +*`rewardstring`* + +**Optional.** This is a list of messages which will be sent to the +player when they complete the quest. This is useful for telling the +player their rewards. + +``` yaml +rewardstring: + - " &8- &7You have received 10 dimaonds." +``` + +## Placeholders + + +*`placeholders`* + +**Optional.** This is a set of placeholders which can be accessed using +PlaceholderAPI. To get the progression of a player in a task, write +`{TASKID:progress}` and replace `TASKID` with the ID of the task you +want to get the progress for. Alternatively, you can write +`{TASKID:complete}` to get if the task is complete. + +``` yaml +placeholders: + description: "&7Break &f30 blocks &7of any type." + progress: " &8- &f{mining:progress}&7/30 broken" +``` + +These placeholders will be called using PlaceholderAPI. See [quest +progress in scoreboard](Quest_progress_in_scoreboard "wikilink") for a +guide which utilises this feature. + +## Options + + +*`options`* + +This section defines quest-specific options. + +### Category + + +*`options.category`* + +**Optional.** The category the quest will be in. You should put the ID +of the category here. + +``` yaml +options: + ... + category: "example" +``` + +### Requirements + + +*`options.requires`* + +**Optional.** List of Quest IDs the player must complete before being +able to start this quest. + +``` yaml +options: + ... + requires: + - "quest-id" +``` + +### Permission required + + +*`options.permission-required`* + +**Optional.** Whether or not the quest should require a permission to +start. The permission will be `quests.quest.`. + +``` yaml +options: + ... + permission-required: false +``` + +### Cancellable + + +*`options.cancellable`* + +**Optional.** Whether or not this quest can be cancelled. If global or +local quest autostart is enabled, or is cancelling quests is disabled, +then this option is ignored. + +``` yaml +options: + ... + cancellable: false +``` + +### Counts towards limit + + +*`options.counts-towards-limit`* + +**Optional.** Whether or not this quest counts towards the players quest +started limit. If global quest autostart is enabled, this will have no +effect as quest limits are disabled. + +``` yaml +options: + ... + counts-towards-limit: false +``` + +### Repeatable + + +*`options.repeatable`* + +**Optional.** Whether or not the quest can be replayed. + +``` yaml +options: + ... + repeatable: false +``` + +### Cooldown + + +*`options.cooldown`* + +**Optional.** Whether ot not the quest is placed on cooldown or is +immediately replayable. + +``` yaml +options: + ... + cooldown: + enabled: true + time: 1440 # minutes +``` + +### Time limit + + +*`options.time-limit`* + +**Optional.** Whether or not this quest has a time limit to complete it. +If the time limit is reached, the quest will be cancelled and progress +reset. + +``` yaml +options: + ... + time-limit: + enabled: true + time: 1440 # minutes +``` + +### Sort order + + +*`options.sort-order`* + +**Optional.** How the plugin sorts the quests in the GUI, lower numbers +come first. + +``` yaml +options: + ... + sort-order: 1 +``` + +### Autostart + + +*`options.autostart`* + +**Optional.** Whether or not the quest should automatically be started. +This is similar to enabling quest autostart for the entire plugin, but +specific only to this quest, meaning it cannot be cancelled and counts +towards the players quest started limit. + +See [ยง counts towards +limit](Creating_a_quest#Counts_towards_limit "wikilink") if you do not +want autostart quests to count towards the quest started limit. + +``` yaml +options: + ... + autostart: true +``` + +### Completed display + + +*`options.completed-display`* + +**Optional.** The display item this quest should take if it is +completed. This accepts the standard ItemStack definition format +described in [Defining items](Defining_items "wikilink"). If this option +is not specified, the display item [defined in the main +config.yml](gui-configuration#quest-completed-display "wikilink") will +be used. + +``` yaml +options: + ... + completed-display: + type: "STEAK" +``` + +### Cooldown display + + +*`options.cooldown-display`* + +**Optional.** The display item this quest should take if it is on +cooldown. This accepts the standard ItemStack definition format +described in [Defining items](Defining_items "wikilink"). If this option +is not specified, the display item [defined in the main +config.yml](gui-configuration#quest-cooldown-display "wikilink") will be +used. + +``` yaml +options: + ... + cooldown-display: + type: "STEAK" +``` + +### Permission display + + +*`options.permission-display`* + +**Optional.** The display item this quest should take if the player does +not have permission to start it. This accepts the standard ItemStack +definition format described in [Defining +items](Defining_items "wikilink"). If this option is not specified, the +display item [defined in the main +config.yml](gui-configuration#quest-permission-display "wikilink") will +be used. + +``` yaml +options: + ... + permission-display: + type: "STEAK" +``` + +### Locked display + + +*`options.locked-display`* + +**Optional.** The display item this quest should take if the player has +not unlocked it. This accepts the standard ItemStack definition format +described in [Defining items](Defining_items "wikilink"). If this option +is not specified, the display item [defined in the main +config.yml](gui-configuration#quest-locked-display "wikilink") will be +used. + +``` yaml +options: + ... + locked-display: + type: "STEAK" +``` diff --git a/docs/configuration/custom-gui-items.md b/docs/configuration/custom-gui-items.md new file mode 100644 index 00000000..3ce97b15 --- /dev/null +++ b/docs/configuration/custom-gui-items.md @@ -0,0 +1,68 @@ +--- +title: Custom GUI items +parent: Configuration +nav_order: 7 +--- +# Custom GUI items + +**Custom GUI items** are dummy items added to the category menu and the +quest menu. This can be used to help stylise your quests GUI. + +This can be done in the `config.yml`: + +``` yaml +custom-elements: + "categories": # apply to the categories menu (the main menu by default) + 0: # <--- slot 1, note the slots start from 0! so 0 = slot 1 in this case + display: + name: "&cExample Custom Item (slot 1)" + lore: + - "&7This is a custom item which can be added" + - "&7to your menus. This is purely cosmetic." + - "" + - "&7Two empty slots should follow." + type: "DIAMOND_BLOCK" + 1: # <--- start from slot 2 + spacer: true # empty slot in GUI + repeat: 2 # repeats for 2 slots + 3: # <--- start from slot 4 + display: + name: "&cExample Custom Item (slots 4 - 7)" + lore: + - "&7This is a custom item which can be added" + - "&7to your menus, but in slot 4 and repeated" + - "&73 times." + - "&7" + - "&7This will come after 2 empty slots." + - "&7" + - "&7This is purely cosmetic." + type: "NETHERRACK" + repeat: 3 # repeats for 3 more slots + commands: + - "this command will be executed if the player click on this item" +``` + +The optional `repeat` field will repeat the item for consecutive slots +after that. + +The optional `commands` list will execute commands if the player clicks +on the item. The `{player}` placeholder can be used to substitute the +player name. + +These custom elements take precedence over quest items, as quests and +categories will fill empty slots once all the custom items have been +set. + +![Example of how custom GUI items are laid out](https://i.imgur.com/5odcqM9.png) + +To add a custom item within the quest menu itself, you must specify the +category, or if categories are disabled you can specify "quests" +instead: + +``` yaml +custom-elements: + "c:": # apply to menu + ... + "quests": # apply to whole quests menu if categories are disabled + ... +``` diff --git a/docs/configuration/defining-items.md b/docs/configuration/defining-items.md new file mode 100644 index 00000000..fddec792 --- /dev/null +++ b/docs/configuration/defining-items.md @@ -0,0 +1,317 @@ +--- +title: Defining items +parent: Configuration +nav_order: 5 +--- + +# Defining items +{: .no_toc } + +An **ItemStack** is a **representation of an item** in an inventory. +Every configured ItemStack in Quests is parsed the exact same way. This +page gives guidance on how to define items with specific attributes. + +{: .note } +The information on this page describes how to define items across every +configuration file. + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +## Layout + +``` yaml +item: + name: "&6&lSuper Cool Stick" + item: STICK + lore: + - "&7Really cool lore." + # field4: value4 + # etc. +``` + +## Options + +| Field | Optional | Minecraft Version | More Information | +|----------------------|-----------------|-------------------|-----------------------------------------| +| `item` | โŒ | \- | [Jump](#item "wikilink") | +| `name` | โœ… \* | \- | [Jump](#name "wikilink") | +| `lore` | โœ… | \- | [Jump](#lore "wikilink") | +| `enchantments` | โœ… | \- | [Jump](#enchantments "wikilink") | +| `itemflags` | โœ… | 1.8+ | [Jump](#item-flags "wikilink") | +| `unbreakable` | โœ… | 1.13+ | [Jump](#unbreakable "wikilink") | +| `attributemodifiers` | โœ… | 1.13+ | [Jump](#attribute-modifiers "wikilink") | +| `custommodeldata` | โœ… | 1.14+ | [Jump](#custom-model-data "wikilink") | +| `owner-[...]` | โœ… | 1.8+ | [Jump](#owner "wikilink") | + +\*: The name must be defined for the display item of Quests. + +### Item + + +*`item` or `type` or `material`* + +The item is the material the itemstack is made out of. Please see the +[latest +javadocs](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) +(1.13+) or the [1.12 +javadocs](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) +(1.8-1.12) for item names. For 1.8-1.12, data codes can be added on at +the end with a colon `:`. + +``` yaml +item: + item: "WHEAT" + ... +``` + +### Name + + +*`name`* + +The name is displayed at the top of the item when hovered over, or just +above the hotbar when selected. + +``` yaml +item: + name: "&2&lSuper Cool Name" + ... +``` + +### Lore + + +*`lore`* + +The lore is the description of the item seen when hovering over it. You +can remove this omit entirely if a lore is not desired. + +``` yaml +item: + lore: + - "Line 1" + - "Line 2" + ... +``` + +### Enchantments + +The format of enchantments depends on your Minecraft version. + + +**Pre-1.13**: Use [spigot +names](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/enchantments/Enchantment.html) +-\> format "{enchantment}:{level}" + +**1.13+**: Use Vanilla names -\> namespace for vanilla enchantments is +"minecraft" -\> format "{namespace}:{enchantment}:{level}" + +``` yaml +item: + enchantments: + - "minecraft:infinity:1" + ... +``` + +### Item flags + +Item flags can be added to hide enchantment names, etc. A full list of +itemflags is available on the [Spigot +javadocs](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/inventory/ItemFlag.html). + +``` yaml +item: + itemflags: + - "HIDE_ATTRIBUTES" + ... +``` + +### Unbreakable + +- *1.13+*' + +``` yaml +item: + unbreakable: true + ... +``` + +### Attribute modifiers + +**1.13+** Adds specific attribute modifiers to the items. The UUID +should always be specified otherwise the server will randomly generate +one on each restart. Full list of attributes is available on the [Spigot +javadocs](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html), +along with full list of +[operations](https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/AttributeModifier.Operation.html). + +``` yaml +item: + attributemodifiers: + - attribute: GENERIC_MOVEMENT_SPEED + modifier: + uuid: "49dc07dc-bfdb-4dc7-85d3-66ef52b51858" + name: "generic.movementSpeed" + operation: ADD_NUMBER + amount: 0.03 + equipmentslot: HAND + - attribute: GENERIC_MOVEMENT_SPEED + modifier: + uuid: "e22513cf-b15f-4443-9e2f-103c0ff9731b" + name: "generic.movementSpeed" + operation: ADD_NUMBER + amount: 0.01 + equipmentslot: OFF_HAND + ... +``` + +### Custom model data + +**1.14+** + +``` yaml +item: + custommodeldata: 12345 + ... +``` + +### Owner + +This only applies if you have a skull item stack (`PLAYER_HEAD` 1.13+, +`SKULL_ITEM` 1.8-1.12). There are three ways to define the player for +the skull: by **username**; **uuid**; or, **base64 encoded string**. + +The **preferred method** is to **explicitly specify a base64 encoded +string**. Using any of the other two methods require that the player has +joined the server before, and may possibly make a request to Mojang +(locking the server thread) depending on which server software you use. + +You can get the base64 encoded representation of a player skin here: +. It will look like the following (may be +referred to as 'texture data'): + + ewogICJ0aW1lc3RhbXAiIDogMTYyNTgzNjU0OTAxNCwKICAicHJvZmlsZUlkIiA6ICJlMmNlNzA0ZWVjNGE0YjE4YTNlYjA4MTRiMzdmYTFkNCIsCiAgInByb2ZpbGVOYW1lIiA6ICJmYXRwaWdzYXJlZmF0IiwKICAic2lnbmF0dXJlUmVxdWlyZWQiIDogdHJ1ZSwKICAidGV4dHVyZXMiIDogewogICAgIlNLSU4iIDogewogICAgICAidXJsIiA6ICJodHRwOi8vdGV4dHVyZXMubWluZWNyYWZ0Lm5ldC90ZXh0dXJlLzJiMTIzMWEyZjNkYTQ2OTQxZDY1OWI4NDNjZWZhNDljOGE1NTA0ZjE4MzNlOTA3YzY3YmJiMTQ2NTE0OTlhNyIKICAgIH0KICB9Cn0= + +You can specify each type by the following: + +``` yaml +item: + owner-base64: "base64 encoded string" + ... +``` + +``` yaml +item: + owner-username: "username" + ... +``` + +``` yaml +item: + owner-uuid: "uuid" + ... +``` + +## Quest items + +**Quest items** can help simplify your configuration by putting +individual itemstacks inside a named file (under directory items/), to +allow for easy referencing from a task configuration and reducing +configuration duplication across your quests. + +The types of quest items are as follows: + +- `raw` (items imported using /q a items import) +- `defined` (items manually written following the format above) +- `mmoitems` (items from MMOItems) +- `slimefun` (items from Slimefun) +- `executableitems` (items from ExecutableItems) + +### Importing items + +**Importing** an item means creating a new quest item **from the item +you are holding** in game. To do this, simply hold the desired item and +run `/q a items import `, where `` is the desired name of the +item. Your item will be saved to file items/\.yml, **with the type +'raw**'. + + + +### Defining items + +You can manually define an item by creating a new `yml` file within the +items/ directory. You must specify a `type` and the item itself under +`item`. + +#### Defined + +**Defined quest items** are regular ItemStacks and follow the format +defined under [ยง Configurable +options](Defined_items#Configurable_options "wikilink"). + + items/testitem.yml + +``` yaml +type: "defined" +item: + name: "Cool item" + type: DIAMOND_SWORD + lore: + - "Really cool lore" +``` + +#### MMOItems + +**MMOItems quest items** are ItemStacks which belong to the MMOItems +plugin. + + items/testitem.yml + +``` yaml +type: "mmoitems" +item: + type: "BOW" #mmoitems type + id: "HELL_BOW" #mmoitems id +``` + +#### Slimefun + +**Slimefun quest items** are ItemStacks which belong to the Slimefun +plugin. + + items/testitem.yml + +``` yaml +type: "slimefun" +item: + id: "slimefun_item_id" #slimefun id +``` + +#### ExecutableItems + +**ExecutableItems quest items** are ItemStacks which belong to the +ExecutableItems plugin. + + items/testitem.yml + +``` yaml +type: "executableitems" +item: + id: "executableitems_id" #executableitems id +``` + +### Referencing a quest item + +In most cases where an ItemStack is accepted in Quests, you can simply +provide the ID of the quest item under the key `quest-item`. + +``` yaml +# Within a task +type: "inventory" +item: + quest-item: "testitem" +``` diff --git a/docs/configuration/global-configurations.md b/docs/configuration/global-configurations.md new file mode 100644 index 00000000..6be6b744 --- /dev/null +++ b/docs/configuration/global-configurations.md @@ -0,0 +1,103 @@ +--- +title: Global configurations +parent: Configuration +nav_order: 4 +--- + +# Global configurations + +**Global configurations** are intended to be used in place of +**quest-specific configurations**. This helps reduce repetition across +your configuration as you copy common elements from quest to quest, and +also allows you to quickly propagate edits across quests. + +## Global task configuration + +A global task configuration will add configuration values to all tasks +of a specified type. + +For example (in `config.yml`), + +``` yaml +... +global-task-configuration: + types: + inventory: + update-progress: true +... +``` + +This will add to *all* tasks configurations with `type: inventory` +across *all* quests the following: `update-progress: true`. + +{: .note } +Any errors which arise from global task configurations will appear as +if they are coming from individual quests. + +Quest-level configurations will override anything set here. To change +this behaviour, modify the [global task configuration +override](Basic_options#Global_task_configuration_override "wikilink"). + +## Global quest display configuration + +A global quest display configuration adds text to the display items of +items in the GUI. + +By default, this is already configured: + +``` yaml +global-quest-display: + lore: + append-not-started: + - "" + - "&eLeft Click &7to start this quest." + append-started: + - "" + - "&aYou have started this quest." + - "&eMiddle Click &7to track this quest." + - "&eRight Click &7to cancel this quest." + append-tracked: + - "" + - "&aYou are &etracking &athis quest." + - "&eMiddle Click &7to stop tracking this quest." + - "&eRight Click &7to cancel this quest." +``` + + + +If you do not want this, simply remove the section. + +## Global macros + +Global macros help you reduce repetition across your configuration +files by centralizing values in your config.yml. Think of them as your +own variables/placeholders which you can use in your quest files. + +You can define macros in your `config.yml`, under the `global-macros` +section: + + global-macros: + ... + # : + top-bar: "&6---&7---&6---" + +To use these in your quests, reference it by using +`<$m name-of-macro $m>`. Macro names **cannot have spaces**. + +For example, to use the `top-bar` macro in `example-quest.yml`: + +``` yaml +tasks: + ... +display: + ... + lore-normal: + - "<$m top-bar $>" + - "..." + ... +``` + +{: .caution } +Macros are replaced by a pre-processor before a configuration is +parsed. This means they have the ability to cause syntax errors in +ways you do not expect if you are not careful. \ No newline at end of file diff --git a/docs/configuration/gui-configuration.md b/docs/configuration/gui-configuration.md new file mode 100644 index 00000000..6a40629a --- /dev/null +++ b/docs/configuration/gui-configuration.md @@ -0,0 +1,269 @@ +--- +title: GUI configuration +parent: Configuration +nav_order: 6 +--- + +# GUI configuration + +*See also [Custom GUI items](Custom_GUI_items "wikilink") and [Defining +items](Defining_items "wikilink").* + +The **GUI configuration** is defined in the `config.yml`. These define +the static UI elements such as the back button, quest locked display +etc. All options accept the standard ItemStack definition format +described in [Defining items](Defining_items "wikilink"). + +## Back button + + +*`gui.back-button`* + +The back button displayed within sub menus. + +``` yaml +gui: + ... + back-button: + name: "&cReturn" + lore: + - "&7Return to the categories menu." + type: "ARROW" +``` + +## Page previous + + +*`gui.page-prev`* + +The previous page button displayed on paiginated menus. + +``` yaml +gui: + ... + page-prev: + name: "&7Previous Page" + lore: + - "&7Switch the page to page &c{prevpage}." + type: "FEATHER" +``` + +The `{prevpage}` variable represents the page number for the previous +page. + +## Page next + + +*`gui.page-next`* + +The next page button displayed on paiginated menus. + +``` yaml +gui: + ... + page-next: + name: "&7Next Page" + lore: + - "&7Switch the page to page &c{nextpage}." + type: "FEATHER" +``` + +The `{nextpage}` variable represents the page number for the next page. + +## Page description + + +*`gui.page-next`* + +The current page item displayed on paginated menus. The amount of this +item will automatically update on the page number. + +``` yaml +gui: + ... + page-desc: + name: "&7Page &c{page}" + lore: + - "&7You are currently viewing page &c{page}." + type: "PAPER" +``` + +The `{page}` variable represents the page number for the current page. + +## Quest locked display + + +*`gui.quest-locked-display`* + +The item is used to represent locked quests. A quest is locked if its +[requirements](Creating_a_quest#Requirements "wikilink") are not met. + +``` yaml +gui: + ... + quest-locked-display: + name: "&c&lQuest Locked" + lore: + - "&7You have not completed the requirements" + - "&7for this quest (&c{quest}&7)." + - "" + - "&7Requires: &c{requirements}" + - "&7to be completed to unlock." + type: "RED_STAINED_GLASS_PANE" +``` + +The `{quest}` variable represents the quest [display +name](Creating_a_quest#name "wikilink"), with its formatting stripped. + +The `{questid}` variable represents the quest ID. + +The `{requirements}` variable represents the display names of the quests +needed to unlock this quest. By default, this name is truncated to show +only the first quest, with a number after (e.g. "Example II +4 more"). +This behaviour is defined at [Basic options ยง GUI-truncate +requirements](basic-options.md#GUI-truncate-requirements "wikilink") + +## Quest permission display + + +*`gui.quest-permission-display`* + +The item is used to represent quests which the player does not have +permission to start. + +``` yaml +gui: + ... + quest-permission-display: + name: "&6&lNo Permission" + lore: + - "&7You do not have permission for this" + - "&7quest (&6{quest}&7)." + type: "BROWN_STAINED_GLASS_PANE" +``` + +The `{quest}` variable represents the quest [display +name](Creating_a_quest#name "wikilink"), with its formatting stripped. + +The `{questid}` variable represents the quest ID. + +## Quest cooldown display + + +*`gui.quest-cooldown-display`* + +The item is used to represent quests which are repeatable, the player +has completed, but are on cooldown. + +``` yaml +gui: + ... + quest-cooldown-display: + name: "&e&lQuest On Cooldown" + lore: + - "&7You have recently completed this quest" + - "&7(&e{quest}&7) and you must" + - "&7wait another &e{time} &7to unlock again." + type: "ORANGE_STAINED_GLASS_PANE" +``` + +The `{quest}` variable represents the quest [display +name](Creating_a_quest#name "wikilink"), with its formatting stripped. + +The `{questid}` variable represents the quest ID. + +The `{time}` variable represents the formatted time remaining until the +cooldown period is over. This can be configured in the messages section. + +## Quest completed display + + +*`gui.quest-completed-display`* + +The item is used to represent quests which are completed and not +repeatable. + +``` yaml +gui: + ... + quest-completed-display: + name: "&a&lQuest Complete" + lore: + - "&7You have completed this quest" + - "&7(&a{quest}&7) and cannot." + - "&7repeat it." + type: "GREEN_STAINED_GLASS_PANE" +``` + +The `{quest}` variable represents the quest [display +name](Creating_a_quest#name "wikilink"), with its formatting stripped. + +The `{questid}` variable represents the quest ID. + +## No started quests + + +*`gui.no-started-quests`* + +This is shown as the only item in the quest started menu if the player +has not started any quests. + +``` yaml +gui: + ... + no-started-quests: + name: "&c&lNo Started Quests" + lore: + - "&7Go start some!" + type: "FEATHER" +``` + +## Quest cancel yes + + +*`gui.quest-cancel-yes`* + +Confirmation item in the quest cancel menu. + +``` yaml +gui: + ... + quest-cancel-yes: + name: "&a&lConfirm Cancel" + lore: + - "&7Confirm you wish to cancel" + - "&7this quest and lose all" + - "&7progress." + type: "GREEN_STAINED_GLASS_PANE" +``` + +## Quest cancel no + + +*`gui.quest-cancel-no`* + +Cancellation item in the quest cancel menu. + +``` yaml +gui: + ... + quest-cancel-no: + name: "&c&lAbort Cancel" + lore: + - "&7Return to the quest menu." + type: "RED_STAINED_GLASS_PANE" +``` + +## Quest cancel background + + +*`gui.quest-cancel-background`* + +Background item in the quest cancel menu. + +``` yaml +gui: + ... + quest-cancel-background: + type: "GRAY_STAINED_GLASS_PANE" +``` diff --git a/docs/configuration/index.md b/docs/configuration/index.md new file mode 100644 index 00000000..32f9e38e --- /dev/null +++ b/docs/configuration/index.md @@ -0,0 +1,7 @@ +--- +title: Configuration +nav_order: 5 +has_children: true +--- + +# Configuration \ No newline at end of file diff --git a/docs/configuration/storage-providers.md b/docs/configuration/storage-providers.md new file mode 100644 index 00000000..f8d68886 --- /dev/null +++ b/docs/configuration/storage-providers.md @@ -0,0 +1,137 @@ +--- +title: Storage providers +parent: Configuration +nav_order: 10 +--- + +# Storage providers +{: .no_toc } + +A **storage provider** is a source for player data +(sometimes referred to as quest progress files). Quests requires that +one storage system be configured to allow the plugin to initialise. If +there is no storage system configured, the plugin will default to +**yaml** storage. If there is an error for any reason during the +initialisation of a storage system, the plugin will be disabled. + +- YAML (`yaml`) +- MySQL (`mysql`) + +When changing storage systems, **the plugin must be restarted for the +changes to have effect**. + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + +## Supported storage systems + +### Flatfile + +#### YAML + +Storing player data in YAML files is the default storage method in +Quests, and is a type of 'flatfile' storage. + +``` yaml +options: + ... + storage: + provider: "yaml" +``` + +Player data can be found inside Quests/playerdata/ and can be modified +as long as the server is not running. It is not recommended to try and +alter these files while the server is online, as this could cause data +consistency issues. + +### Network + +{: .warning } +> ๏ธ**Using Quests on a BungeeCord network may lead to a possible race +> condition.** Allowing players to to connect directly to another server +> running Quests may result in the new server loading old data. This +> happens because BungeeCord establishes a connection with the new server +> before disconnecting the player from the old one, leading to the new +> server loading player data before the old server has saved it. +> +> Quests offers a workaround, which is to [delay the loading of player +> data](#delay-loading "wikilink"). You may also want to +> consider forcing players to switch servers through a hub server, or +> decreasing the autosave period. In either case, the race condition still +> exists; there is not an easy way to coordinate the loading/saving due to +> how BungeeCord works. **You must understand this warning before using +> Quests in this way.** + +#### MySQL + +Quests can connect to and store player data in a MySQL database. This is +particularly useful if you want to have multiple servers use the same +player data. + +``` yaml +options: + ... + storage: + provider: "mysql" +``` + +You must also configure the plugin to connect to the database. + +``` yaml + database-settings: + network: + database: "minecraft" + username: "root" + password: "" + address: "localhost:3306" +``` + +The database specified **must** exist before connecting Quests to it. +The address is given in the following format: ip:port (e.g +127.0.0.1:3306). + +There are also some other options you can configure, as Quests uses +HikariCP to manage its connections to the database. You can see +descriptions of each option on the [HikariCP +README](https://github.com/brettwooldridge/HikariCP). + +``` yaml + connection-pool-settings: + maximum-pool-size: 8 + minimum-idle: 8 + maximum-lifetime: 1800000 + connection-timeout: 5000 + table-prefix: "quests_" +``` + +## Data synchronisiation + +### Delay loading + +Quests offers a workaround to the [race +condition](Storage_providers#Network "wikilink"), which is to delay the +loading of player data in hopes that the server before has enough time +to save the data. + +You can enable this in your config here: + +``` yaml +options: + ... + storage: + provider: "mysql" + synchronisation: + delay-loading: 0 # (ticks - change to any value above 0) + ... +``` + +A value of 50 (2.5 seconds) should be enough for most servers, however +you may want to increase it if, for example, your database is not on the +same network as your Minecraft server. Again, this **does not solve the +race condition**, but it should help mitigate it. + +See the issue in the issue tracker: +[Issue 180](https://github.com/LMBishop/Quests/issues/180) diff --git a/docs/contributing-to-the-wiki.md b/docs/contributing-to-the-wiki.md new file mode 100644 index 00000000..7a7a3c52 --- /dev/null +++ b/docs/contributing-to-the-wiki.md @@ -0,0 +1,58 @@ +--- +title: Contributing to the wiki +nav_order: 10 +--- + +# Contributing to the wiki + +{: .caution } +This information is out of date since the wiki migration. + +If you spot any errors in the wiki, or want to add more information of +you own, then we would be happy to review potential changes. Due to the +restrictions of the GitHub wiki pages, it is not possible to open pull +requests to the wiki repository, instead changes will have to be +submitted through the [on the issue +tracker](https://github.com/LMBishop/Quests/issues/new?assignees=&labels=docs%2Cstatus%3A+needs+investigating&template=documentation.yml). + +## Submitting edits + +If you want to add information or edit the wiki, it would be beneficial +if you submitted the source code of the page within backticks to make it +easy to change the wiki. + +You can view the raw source code of a wiki page by adding `.mediawiki` +to the url, for example: +[`https://github.com/LMBishop/Quests/wiki/Storage-providers.mediawiki`](https://github.com/LMBishop/Quests/wiki/Storage-providers.mediawiki). +**Note that some pages are edited using Markdown, if `.mediawiki` does +not resolve then use `.md` instead. These pages do not use Wikitext but +will soon be converted to it.** + +Please make your edits to the page there, and submit the **full page** +in the issue tracker. Due to constraints of the GitHub wiki, there is no +way to easily submit revisions for review. + +## Editing guidelines + +The Quests wiki loosely follows some conventions: + +- Article titles and headers should be written in lower case, with only + the first word being capitalised. The only exception to this is with + names (e.g. PlaceholderAPI, AnimatedScoreboard). +- Headings should not used to restate the page name. Pages usually open + with a short description at the top, they should never start with + another heading. +- British English should be used. +- Top-level headings should start at H2 (`## Heading` or + `== Heading ==`). H1 (`# Heading` or `= Heading =`) is never used as + this conflicts with the article title. The only exception to this is + on the home page, where the plugin name is displayed. +- Longer articles should have their contents listed at the top, with + wikilinks to each section of the page. +- Incomplete pages should have a warning at the top saying so. GitHub + wikis have no support for templates, or for transclusion, so you must + copy it manually from a different wiki page. + +These conventions may or may not be wholly followed throughout the wiki, +though it would be beneficial for new pages and new revisions to follow +this convention. diff --git a/docs/developer/api.md b/docs/developer/api.md new file mode 100644 index 00000000..5bc91ff2 --- /dev/null +++ b/docs/developer/api.md @@ -0,0 +1,35 @@ +--- +title: API +parent: Developer +--- + +# API + +{: .highlight } +**This page is under construction.** The information contained here may be inaccurate or incomplete. You can help by [contributing information to the wiki](https://github.com/LMBishop/Quests/wiki/Contributing-to-the-wiki). + +Quests provides an API for other people to use. **This API is experimental and may be subject to change.** For usages, it is best to take a look into the plugin itself. + +## Bukkit +You can get an instance of Quests as you would with any other plugin: +```java +BukkitQuestsPlugin questsPlugin = (BukkitQuestsPlugin) Bukkit.getPluginManager().getPlugin("Quests"); +``` +From there, you can access the `QPlayerManager`, `QuestManager` etc. See the javadoc in [this file](https://github.com/LMBishop/Quests/blob/master/common/src/main/java/com/leonardobishop/quests/common/plugin/Quests.java), and in each class for more info on its purpose. + +### Events +Quests provides some Bukkit events, you can see them all [here](https://github.com/LMBishop/Quests/tree/master/bukkit/src/main/java/com/leonardobishop/quests/bukkit/api/event). + +### Registering task types +Task types **must** be registered during startup, after Quests has initialized its task type manager. You cannot register task types after this period as individual quests are registered to their task types for performance reasons. + +```java +@Override +public void onEnable() { + // ... + Quests questsPlugin = (Quests) Bukkit.getPluginManager().getPlugin("Quests"); + BukkitTaskTypeManager taskTypeManager = (BukkitTaskTypeManager) questsPlugin.getTaskTypeManager(); + + taskTypeManager.registerTaskType(new ...); +} +``` \ No newline at end of file diff --git a/docs/developer/index.md b/docs/developer/index.md new file mode 100644 index 00000000..cc6268b6 --- /dev/null +++ b/docs/developer/index.md @@ -0,0 +1,7 @@ +--- +title: Developer +has_children: true +nav_order: 9 +--- + +# Developer \ No newline at end of file diff --git a/docs/developer/new-task-type.md b/docs/developer/new-task-type.md new file mode 100644 index 00000000..cedc3711 --- /dev/null +++ b/docs/developer/new-task-type.md @@ -0,0 +1,85 @@ +--- +title: New task type +parent: Developer +--- + +# New task type + +{: .highlight } +**This page is under construction.** The information contained here may be inaccurate or incomplete. You can help by [contributing information to the wiki](https://github.com/LMBishop/Quests/wiki/Contributing-to-the-wiki). + + +The following information is for developers who are interested in integrating Quests into their own plugin. + +Quests are a set of tasks which the player must complete in return for a reward. The **task** the player must complete depends on the **task type**, and how it is configured. When quests are loaded from the config, they are registered to each task type the quest contains. + +## Purpose of a task type +**The role of a task type is to handle the progress of tasks within quests which registered with your type.** + +How a task type handles the progress differs with each one. For example, a `blockbreak` task type may increase the progress whenever a block is broken, or a `position` task type may flag the quest as completed when a player is near a defined location. + +How a task type works generally follows this format: +1. Listen for related event +2. Iterate over every quest registered to the task type +3. Check if the player has started the quest +4. Iterate over each task of the quest +5. If the task is incomplete, increment the progress according to criteria +6. Mark the task as complete if over threshold + +Quests handles the completion of all tasks within a quest and dispatches rewards. **A task type simply handles the events which increment a single task.** + +{: .caution } +> Task Types **MUST** be registered before the actual quests from the config are registered. They can be registered in between Quests inital activation and before the server is fully started. For example: you can register new Task Types inside of the `onEnable()` and add Quests to the `depend` or `softdepend` section of your `plugin.yml` to make sure that Quests is ready to accept your registration. +> +> Attempting to register a task type after the registration period has closed will throw a `IllegalStateException`. The registration period closes and quests are loaded after every plugin has finished loading (on the first server [tick](https://github.com/LMBishop/Quests/blob/master/src/main/java/com/leonardobishop/quests/Quests.java#L129)). + +## Writing task types +Your new Task Type must extend the [`TaskType`](https://github.com/LMBishop/Quests/blob/master/common/src/main/java/com/leonardobishop/quests/common/tasktype/TaskType.java) class. **`BukkitTaskType` implements `Listener` and automatically registers as an event listener if used with the `BukkitTaskTypeManager`.** Your subclass must pass the name of the Task Type into the constructor, and optionally the authors name and a brief description of the task. + +Example: +```java +public final class MiningTaskType extends BukkitTaskType { + + public MiningTaskType() { + super("blockbreak", "LMBishop", "Break a set amount of blocks."); + } + +} +``` +The name of the Task Type (`blockbreak` in this case) is what server owners put into their config. +### Bukkit listeners +You can use Bukkit event listeners like you normally would in your own plugin. The class is already registered as a listener by Quests. + +It is recommended that you set your event priority to `MONITOR` (only if you do not cancel the event) and setting `ignoreCancelled` to true in the `EventHandler` annotation. + +```java +@EventHandler(priority = EventPriority.MONITOR, ignoreCancelled = true) +``` +### Configuration +Quests will load the configuration of each task into a `HashMap` in the [`Task`](https://github.com/LMBishop/Quests/blob/master/common/src/main/java/com/leonardobishop/quests/common/quest/Task.java) class. Server owners define their task configuration in the quest config, for example: +```yaml +tasks: + mining: + type: "blockbreakcertain" + amount: 81 + block: GOLD_ORE +``` +Will lead to the following map: +```java +configValues = {type="blockbreakcertain";amount=81;block="GOLD_ORE"} +``` +These values can be accessed through `Task#getConfigValue(String)`. You can also specify a default value to be returned if a server owner has not defined a value with `Task#getConfigValue(String, String)`. + +### Implementing methods +The [`TaskType`](https://github.com/LMBishop/Quests/blob/master/common/src/main/java/com/leonardobishop/quests/common/tasktype/TaskType.java) class has some methods which can be optionally overridden. + +The `onReady()` method is called when the server has registered all quests to your task type. + +The `onStart()` method is called when a player starts a quest containing a task of your task type. + +The `onDisable()` method is called when the plugin is disabled, or is reloaded. If the plugin is reloaded, this will unregister all quests from your task type, then register the new quests again. + +The `validateConfig(String, HashMap)` method is called when each task is loaded. It is used to detect potential configuration issues and can be used to prevent the quest from loading if, for example, a required config option is missing. The first string is the task root (e.g `tasks.mining` in the first example) and the map is the config to check. The return type is a list of `ConfigProblem`, returning a list containing at least one `ConfigProblem` with an `ERROR` type will prevent the quest from loading. + +### Modifying progress +You can modify progress by obtaining an instance of a players `QuestProgressFile`, getting the specific `QuestProgress` and then getting the specific `TaskProgress`. You can see an example of this in the [`MiningTaskType`](https://github.com/LMBishop/Quests/blob/master/src/main/java/com/leonardobishop/quests/quest/tasktype/type/MiningTaskType.java) (which contains comments through the file). \ No newline at end of file diff --git a/docs/download.md b/docs/download.md new file mode 100644 index 00000000..799cf804 --- /dev/null +++ b/docs/download.md @@ -0,0 +1,60 @@ +--- +title: Download +nav_order: 3 +--- +# Download + +Release builds of Quests are officially distributed at the +sites on this page. Sources not listed here may contain modified, or +outdated versions. + +## Release builds + +- [SpigotMC + (preferred)](https://www.spigotmc.org/resources/quests-1-8-1-19-set-up-goals-for-players.23696/) +- [Modrinth](https://modrinth.com/mod/quests) +- [Polymart](https://polymart.org/resource/quests.938) +- [Songoda](https://songoda.com/marketplace/product/quests-quests.544) +- [GitHub](https://github.com/LMBishop/Quests/releases) +- [Hangar (testing)](https://hangar.benndorf.dev/LMBishop/Quests) + +Please note Hangar is still in active development and testing. It may be +removed at any time. + +### Distribution status + +Some platforms may not be up-to-date yet. + + + +## Development builds + +- [GitHub Actions](https://github.com/LMBishop/Quests/actions) + +Development builds are automatically built by GitHub. You may need a +GitHub account to see or download these artifacts. + +Instructions on building Quests is also provided here: + + +## License + +The full license text is available here: + + + Quests + + Copyright (C) 2022 Leonardo Bishop and contributors + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see [https://www.gnu.org/licenses]. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..c25ba9cc --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,15 @@ +--- +title: Getting started +nav_order: 2 +--- +# Getting started + +{: .highlight } +**This page is under construction.** The information contained here may be inaccurate or incomplete. You can help by [contributing information to the wiki](https://github.com/LMBishop/Quests/wiki/Contributing-to-the-wiki). + +Welcome to Quests! This wiki should help you with creating your own custom quests on your server. + +### What is a quest? +A **quest** is simply a **group of tasks** which a player must complete in return for a reward. + +Each **task** may have a different **task type**, which range from breaking blocks to reaching a certain position in the world. Quests provides over 30 different types you can use, listed on [this page](https://github.com/LMBishop/Quests/wiki/Task-Types). diff --git a/docs/guides/index.md b/docs/guides/index.md new file mode 100644 index 00000000..e9349e10 --- /dev/null +++ b/docs/guides/index.md @@ -0,0 +1,7 @@ +--- +title: Guides +has_children: true +nav_order: 8 +--- + +# Guides \ No newline at end of file diff --git a/docs/guides/quest-progress-in-scoreboard.md b/docs/guides/quest-progress-in-scoreboard.md new file mode 100644 index 00000000..aa429dac --- /dev/null +++ b/docs/guides/quest-progress-in-scoreboard.md @@ -0,0 +1,188 @@ +--- +title: Quest progress in scoreboard +parent: Guides +--- + +# Quest progress in scoreboard + +This guide will show you how to show quest progress in a scoreboard. The +plugin +[](AnimatedScoreboard "wikilink") +will provide this scoreboard, however this will work for any plugin +accepting PlaceholderAPI. + +**This utilises three features from Quests:** + +- tracking quests +- PlaceholderAPI integration +- local quest placeholders + +The final result will look like this: + + + +## Adding local quest placeholders + +Local quest placeholders are used here to provide the progress of the +quest and to provide a breif description of the quest. We will use a +simple blockbreak quest as our base here, where we must break 30 blocks +to complete the quest. + + /Quests/quests/example1.yml + +``` yaml +... + +placeholders: + description: "&7Break &f30 blocks &7of any type." + progress: " &8- &f{mining:progress}&7/30 broken" + +... +``` + +These placeholders will be called using PlaceholderAPI using the +AnimatedScoreboard plugin. For example, using the placeholder +`%quests_q:example1_p:description%` with PlaceholderAPI will return +`&7Break &f30 blocks &7of any type.`. These are known as [local quest +placeholders](../tools/placeholderapi.md#Quest_details "wikilink"). + +Our `description` placeholder provides a description of the quest. The +\`progress\` placeholder will show the players progression with the +quest. + +**You can create any placeholders here, and decide the names for +yourself.** These are designed for you to be able to access information +about a quest with PlaceholderAPI. Avoid using underscores and spaces, +this may cause issues when referencing them using placeholders. + +To see the full quest (with comments), click +[here](https://github.com/LMBishop/Quests/blob/master/src/main/resources/resources/bukkit/quests/example1.yml "wikilink"). + +## Configuring AnimatedScoreboard + +{: .note } +This guide assumes you have a basic understanding of the plugin +[](AnimatedScoreboard "wikilink"). + +For our config with AnimatedScoreboard, we will create two seperate +scoreboards: one with tracked quest information and one informing the +user that they are not tracking a quest. + + /AnimatedScoreboard/scoreboards/questtrack.yml + +``` yaml +display: + title: + text: + - "&6&lAmazing Server" + line-1: + text: + - "&7" + score: 5 + line-2: + text: + - "&e&lTracked Quest:" + score: 4 + line-3: + text: + - "&e%quests_tracked%" + score: 3 + line-4: + text: + - "&7%quests_tracked_p:description%" + score: 2 + line-5: + text: + - "&7%quests_tracked_p:progress%" + score: 1 + line-6: + text: + - "&7" + score: 0 +``` + +The placeholder `%quests_tracked<...>%` will access the players tracked +quest. In order to track a quest you must middle-click in-game on the +quest within the GUI. By default, when you start a quest it is +automatically tracked. + +Simply put, we are accessing the placeholders called `description` and +`progress` which we made earlier in the player's tracked quest. + +Now, we are going to create a default scoreboard for when there is no +tracked quest. + + /AnimatedScoreboard/scoreboards/defaultscoreboard.yml + +``` yaml +display: + title: + text: + - "&6&lAmazing Server" + line-1: + text: + - "&7" + score: 3 + line-2: + text: + - "&e&lTracked Quest:" + score: 2 + line-3: + text: + - "&7You are not tracking a quest." + score: 1 + line-4: + text: + - "&7" + score: 0 +``` + +This is a simple static scoreboard. Finally, we must add a trigger to +switch between the two scoreboards. + +Triggers must first be enabled within AnimatedScoreboard: + + /AnimatedScoreboard/config.yml + +``` yaml +... +enable-triggers: true +... +``` + +Then, the server must be restarted. There should be a new folder called +`triggers`. + +Now, we must create two files `ontrack.yml` and `ontrackend.yml`. This +will switch between the two scoreboard whenever the player tracks / +stops tracking a quest. + + /AnimatedScoreboard/triggers/ontrack.yml + +``` yaml +event: com.leonardobishop.quests.bukkit.api.event.PlayerStartTrackQuestEvent +target-player: getPlayer +trigger-scoreboard: questtrack +``` + +This will switch to the \`questtrack\` scoreboard when a quest is +tracked. + + /AnimatedScoreboard/triggers/ontrackend.yml + +``` yaml +event: com.leonardobishop.quests.bukkit.api.event.PlayerStopTrackQuestEvent +target-player: getPlayer +trigger-scoreboard: defaultscoreboard +``` + +This will switch to the \`defaultscoreboard\` scoreboard when a quest is +no longer tracked. + +That's it! Restart the server and you should be able to see the progress +update in the scoreboard. Please note, you will have to include local +quest placeholders for every quest. + +## Further reading + +- [Creating a quest](Creating_a_quest "wikilink") diff --git a/docs/index.md b/docs/index.md index 1e63fec2..84855e52 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,15 +1,25 @@ +--- +title: Home +nav_order: 1 +--- +
+
+
+ +# Quests documentation + Welcome to the Quests Wiki! Please use the sidebar for navigation around the wiki. **๐ŸŒŸ New & Highlighted Articles** -- [Tips](Tips "wikilink") +- [Tips](tips "wikilink") - [Basic options](Basic_options "wikilink") - [Creating a quest](Creating_a_quest "wikilink") - [Creating a category](Creating_a_category "wikilink") - [Custom GUI items](Custom_GUI_items "wikilink") - [Task types](Task_types "wikilink") -- [PlaceholderAPI](PlaceholderAPI "wikilink") +- [PlaceholderAPI](tools/placeholderapi.md "wikilink") Spot a mistake or ambiguous information? Please consider [contributing to the wiki](contributing_to_the_wiki "wikilink"). @@ -91,7 +101,7 @@ Q. Does this plugin support PlaceholderAPI? -Yes, see [PlaceholderAPI](PlaceholderAPI "wikilink"). +Yes, see [PlaceholderAPI](tools/placeholderapi.md "wikilink"). diff --git a/docs/task-type/askyblock_level-(task-type).md b/docs/task-type/askyblock_level-(task-type).md index 11a46bf0..823a79a6 100644 --- a/docs/task-type/askyblock_level-(task-type).md +++ b/docs/task-type/askyblock_level-(task-type).md @@ -1,5 +1,16 @@ - -*Requires the ASkyBlock plugin to activate.* +--- +title: askyblock_level +parent: Task types +nav_order: 27 +--- + +# askyblock_level (task type) + +Since v1.7.1 +{: .label .label-green } + +Plugin 'ASkyBlock' required +{: .label } Reach a certain ASkyBlock level. diff --git a/docs/task-type/bentobox_level-(task-type).md b/docs/task-type/bentobox_level-(task-type).md index 1abc4302..933ee21d 100644 --- a/docs/task-type/bentobox_level-(task-type).md +++ b/docs/task-type/bentobox_level-(task-type).md @@ -1,5 +1,16 @@ - -*Requires the BentoBox plugin to activate.* +--- +title: bentobox_level +parent: Task types +nav_order: 28 +--- + +# bentobox_level (task type) + +Since v2.12 +{: .label .label-green } + +Plugin 'BentoBox' required +{: .label } Reach a certain BentoBox level. diff --git a/docs/task-type/blockbreak-(task-type).md b/docs/task-type/blockbreak-(task-type).md index a719bcb1..66595b5a 100644 --- a/docs/task-type/blockbreak-(task-type).md +++ b/docs/task-type/blockbreak-(task-type).md @@ -1,5 +1,17 @@ -Breaka set amount of blocks. +--- +title: blockbreak +parent: Task types +nav_order: 1 +--- +# blockbreak (task type) + +Since v1.0 +{: .label .label-green } + +Break a set amount of blocks. + +{: .note } Since Quests v3.13, `blockbreakcertain` and `blockbreak` have been merged into one. Both names can be used to refer to this task. diff --git a/docs/task-type/blockplace-(task-type).md b/docs/task-type/blockplace-(task-type).md index d5892423..e39538c8 100644 --- a/docs/task-type/blockplace-(task-type).md +++ b/docs/task-type/blockplace-(task-type).md @@ -1,5 +1,17 @@ +--- +title: blockplace +parent: Task types +nav_order: 2 +--- + +# blockplace (task type) + +Since v1.0 +{: .label .label-green} + Place a set amount of blocks. +{: .note } Since Quests v3.13, `blockplacecertain` and `blockplace` have been merged into one. Both names can be used to refer to this task. diff --git a/docs/task-type/breeding-(task-type).md b/docs/task-type/breeding-(task-type).md index 58797cb4..66459f7d 100644 --- a/docs/task-type/breeding-(task-type).md +++ b/docs/task-type/breeding-(task-type).md @@ -1,3 +1,14 @@ +--- +title: breeding +parent: Task types +nav_order: 3 +--- + +# breeding (task type) + +Since v2.2 +{: .label .label-green } + Breed a certain amount of animals. ## Options diff --git a/docs/task-type/brewing-(task-type).md b/docs/task-type/brewing-(task-type).md index d7fc9f28..312e3dfb 100644 --- a/docs/task-type/brewing-(task-type).md +++ b/docs/task-type/brewing-(task-type).md @@ -1,3 +1,14 @@ +--- +title: brewing +parent: Task types +nav_order: 4 +--- + +# brewing (task type) + +Since v2.0.13 +{: .label .label-green } + Brew a set amount of potions. ## Options diff --git a/docs/task-type/bucketempty-(task-type).md b/docs/task-type/bucketempty-(task-type).md index cbce8af8..49806d17 100644 --- a/docs/task-type/bucketempty-(task-type).md +++ b/docs/task-type/bucketempty-(task-type).md @@ -1,3 +1,14 @@ +--- +title: bucketempty +parent: Task types +nav_order: 5 +--- + +# bucketempty (task type) + +Since v3.9 +{: .label .label-green } + Empty a bucket. ## Options diff --git a/docs/task-type/bucketfill-(task-type).md b/docs/task-type/bucketfill-(task-type).md index d9969808..3648d06e 100644 --- a/docs/task-type/bucketfill-(task-type).md +++ b/docs/task-type/bucketfill-(task-type).md @@ -1,3 +1,14 @@ +--- +title: bucketfill +parent: Task types +nav_order: 6 +--- + +# bucketfill (task type) + +Since v3.9 +{: .label .label-green } + Fill a bucket up. ## Options diff --git a/docs/task-type/citizens_deliver-(task-type).md b/docs/task-type/citizens_deliver-(task-type).md index 3be9cdaa..14f56f20 100644 --- a/docs/task-type/citizens_deliver-(task-type).md +++ b/docs/task-type/citizens_deliver-(task-type).md @@ -1,5 +1,16 @@ - -*This requires the Citizens plugin to activate.* +--- +title: citizens_deliver +parent: Task types +nav_order: 29 +--- + +# citizens_deliver (task type) + +Since v2.0.15 +{: .label .label-green } + +Plugin 'Citizens' required +{: .label } Deliver a set of items to a Citizens NPC. diff --git a/docs/task-type/citizens_interact-(task-type).md b/docs/task-type/citizens_interact-(task-type).md index eb744f27..f25e9844 100644 --- a/docs/task-type/citizens_interact-(task-type).md +++ b/docs/task-type/citizens_interact-(task-type).md @@ -1,5 +1,16 @@ - -*This requires the Citizens plugin to activate.* +--- +title: citizens_interact +parent: Task types +nav_order: 30 +--- + +# citizens_interact (task type) + +Since v2.0.15 +{: .label .label-green } + +Plugin 'Citizens' required +{: .label } Interact with a Citizens NPC. diff --git a/docs/task-type/command-(task-type).md b/docs/task-type/command-(task-type).md index a5a42960..4e2d426f 100644 --- a/docs/task-type/command-(task-type).md +++ b/docs/task-type/command-(task-type).md @@ -1,3 +1,14 @@ +--- +title: command +parent: Task types +nav_order: 7 +--- + +# command (task type) + +Since v2.12 +{: .label .label-green } + Execute a specific command. This task may not work for commands not properly registered with the diff --git a/docs/task-type/consume-(task-type).md b/docs/task-type/consume-(task-type).md index b0d3acd4..4b748c89 100644 --- a/docs/task-type/consume-(task-type).md +++ b/docs/task-type/consume-(task-type).md @@ -1,3 +1,14 @@ +--- +title: consume +parent: Task types +nav_order: 8 +--- + +# consume (task type) + +Since v3.9 +{: .label .label-green } + Consume a specific item. ## Options diff --git a/docs/task-type/crafting-(task-type).md b/docs/task-type/crafting-(task-type).md index de9147b0..1622c502 100644 --- a/docs/task-type/crafting-(task-type).md +++ b/docs/task-type/crafting-(task-type).md @@ -1,3 +1,14 @@ +--- +title: crafting +parent: Task types +nav_order: 9 +--- + +# crafting (task type) + +Since v3.0 +{: .label .label-green } + Craft a set of items. ## Options diff --git a/docs/task-type/dealdamage-(task-type).md b/docs/task-type/dealdamage-(task-type).md index 2683e647..426f76e2 100644 --- a/docs/task-type/dealdamage-(task-type).md +++ b/docs/task-type/dealdamage-(task-type).md @@ -1,3 +1,14 @@ +--- +title: dealdamage +parent: Task types +nav_order: 10 +--- + +# dealdamage (task type) + +Since v2.2 +{: .label .label-green } + Deal a certain amount of damage. ## Options diff --git a/docs/task-type/distancefrom-(task-type).md b/docs/task-type/distancefrom-(task-type).md index 3fa7fdae..5c0e8305 100644 --- a/docs/task-type/distancefrom-(task-type).md +++ b/docs/task-type/distancefrom-(task-type).md @@ -1,3 +1,14 @@ +--- +title: distancefrom +parent: Task types +nav_order: 11 +--- + +# distancefrom (task type) + +Since v2.12 +{: .label .label-green } + Travel away from a set of co-ordinates. ## Options diff --git a/docs/task-type/enchanting-(task-type).md b/docs/task-type/enchanting-(task-type).md index c22907b7..1e2b6c80 100644 --- a/docs/task-type/enchanting-(task-type).md +++ b/docs/task-type/enchanting-(task-type).md @@ -1,3 +1,14 @@ +--- +title: enchanting +parent: Task types +nav_order: 12 +--- + +# enchanting (task type) + +Since v2.2 +{: .label .label-green } + Enchant an item. ## Options diff --git a/docs/task-type/essentials_balance-(task-type).md b/docs/task-type/essentials_balance-(task-type).md index ab600bc1..6d246376 100644 --- a/docs/task-type/essentials_balance-(task-type).md +++ b/docs/task-type/essentials_balance-(task-type).md @@ -1,5 +1,16 @@ - -*Requires the Essentials plugin to activate.* +--- +title: essentials_balance +parent: Task types +nav_order: 31 +--- + +# essentials_balance (task type) + +Since v2.12 +{: .label .label-green } + +Plugin 'Essentials' required +{: .label } Reach a certain balance. diff --git a/docs/task-type/essentials_moneyearn-(task-type).md b/docs/task-type/essentials_moneyearn-(task-type).md index bf5c8efd..eba692fa 100644 --- a/docs/task-type/essentials_moneyearn-(task-type).md +++ b/docs/task-type/essentials_moneyearn-(task-type).md @@ -1,5 +1,16 @@ - -*Requires the Essentials plugin to activate.* +--- +title: essentials_moneyearn +parent: Task types +nav_order: 32 +--- + +# essentials_moneyearn (task type) + +Since v2.12 +{: .label .label-green } + +Plugin 'Essentials' required +{: .label } Earn a certain amount of money after starting quest. diff --git a/docs/task-type/expearn-(task-type).md b/docs/task-type/expearn-(task-type).md index f4de7c5b..86cbf5ca 100644 --- a/docs/task-type/expearn-(task-type).md +++ b/docs/task-type/expearn-(task-type).md @@ -1,3 +1,14 @@ +--- +title: expearn +parent: Task types +nav_order: 13 +--- + +# expearn (task type) + +Since v2.2 +{: .label .label-green } + Earn a set amount of exp after starting the quest. ## Options diff --git a/docs/task-type/fabledskyblock_level-(task-type).md b/docs/task-type/fabledskyblock_level-(task-type).md index ec689b56..eecf2dc0 100644 --- a/docs/task-type/fabledskyblock_level-(task-type).md +++ b/docs/task-type/fabledskyblock_level-(task-type).md @@ -1,5 +1,16 @@ - -*Requires the FabledSkyblock plugin to activate.* +--- +title: fabledskyblock_level +parent: Task types +nav_order: 33 +--- + +# fabledskyblock_level (task type) + +Since v3.5 +{: .label .label-green } + +Plugin 'FabledSkyblock' required +{: .label } Reach a certain FabledSkyblock level. diff --git a/docs/task-type/farming-(task-type).md b/docs/task-type/farming-(task-type).md index de5c5d6a..57406c00 100644 --- a/docs/task-type/farming-(task-type).md +++ b/docs/task-type/farming-(task-type).md @@ -1,9 +1,22 @@ - -*Requires Minecraft 1.13+. For previous versions, use -[blockbreak](blockbreak_(task_type) "wikilink").* +--- +title: farming +parent: Task types +nav_order: 14 +--- + +# farming (task type) + +Since v3.5 +{: .label .label-green } + +Minecraft 1.13+ required +{: .label .label-purple } + +*For previous versions, use [blockbreak](blockbreak_(task_type) "wikilink").* Farm a set amount of crops. +{: .note } Since Quests v3.13, `farmingcertain` and `farming` have been merged into one. Both names can be used to refer to this task. diff --git a/docs/task-type/fishing-(task-type).md b/docs/task-type/fishing-(task-type).md index fa63358f..0143bbe4 100644 --- a/docs/task-type/fishing-(task-type).md +++ b/docs/task-type/fishing-(task-type).md @@ -1,7 +1,19 @@ +--- +title: fishing +parent: Task types +nav_order: 15 +--- + +# fishing (task type) + +Since v2.0 +{: .label .label-green } + Fish a set amount of items. +{: .note } Since Quests v3.13, `fishingcertain` and `fishing` have been merged into -one. +one. Both names can be used to refer to this task. ## Options diff --git a/docs/task-type/index.md b/docs/task-type/index.md new file mode 100644 index 00000000..4b0e657f --- /dev/null +++ b/docs/task-type/index.md @@ -0,0 +1,7 @@ +--- +title: Task types +has_children: true +nav_order: 6 +--- + +# Task types \ No newline at end of file diff --git a/docs/task-type/inventory-(task-type).md b/docs/task-type/inventory-(task-type).md index e5e22b15..67354434 100644 --- a/docs/task-type/inventory-(task-type).md +++ b/docs/task-type/inventory-(task-type).md @@ -1,3 +1,15 @@ +--- +title: inventory +parent: Task types +nav_order: 16 +--- + +# inventory (task type) + +Since v1.4 +{: .label .label-green } + + Obtain a set of items. ## Options diff --git a/docs/task-type/iridiumskyblock_value-(task-type).md b/docs/task-type/iridiumskyblock_value-(task-type).md index c465c049..40ca8a8c 100644 --- a/docs/task-type/iridiumskyblock_value-(task-type).md +++ b/docs/task-type/iridiumskyblock_value-(task-type).md @@ -1,5 +1,16 @@ - -*Requires the IridiumSkyblock plugin to activate.* +--- +title: iridiumskyblock_value +parent: Task types +nav_order: 34 +--- + +# iridiumskyblock_value (task type) + +Since v3.5 +{: .label .label-green } + +Plugin 'IridiumSkyblock' required - version 2.x only +{: .label } Reach a certain IridiumSkyblock value. diff --git a/docs/task-type/milking-(task-type).md b/docs/task-type/milking-(task-type).md index dcf296b2..75c2ed86 100644 --- a/docs/task-type/milking-(task-type).md +++ b/docs/task-type/milking-(task-type).md @@ -1,3 +1,14 @@ +--- +title: milking +parent: Task types +nav_order: 17 +--- + +# milking (task type) + +Since v2.0 +{: .label .label-green } + Milk a set amount of cows. ## Options diff --git a/docs/task-type/mobkilling-(task-type).md b/docs/task-type/mobkilling-(task-type).md index 6b7565d7..8ad286a3 100644 --- a/docs/task-type/mobkilling-(task-type).md +++ b/docs/task-type/mobkilling-(task-type).md @@ -1,5 +1,17 @@ +--- +title: mobkilling +parent: Task types +nav_order: 18 +--- + +# mobkilling (task type) + +Since v2.0 +{: .label .label-green } + Kill a set amount of mobs. +{: .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-type/mythicmobs_killing-(task-type).md b/docs/task-type/mythicmobs_killing-(task-type).md index 14f1a0ee..4862f66d 100644 --- a/docs/task-type/mythicmobs_killing-(task-type).md +++ b/docs/task-type/mythicmobs_killing-(task-type).md @@ -1,5 +1,16 @@ - -*Requires the MythicMobs plugin to activate.* +--- +title: mythicmobs_killing +parent: Task types +nav_order: 35 +--- + +# mythicmobs_killing (task type) + +Since v2.3 +{: .label .label-green } + +Plugin 'MythicMobs' required +{: .label } Kill a certain MythicMobs mob. diff --git a/docs/task-type/permission-(task-type).md b/docs/task-type/permission-(task-type).md index 631a462e..aa55c00a 100644 --- a/docs/task-type/permission-(task-type).md +++ b/docs/task-type/permission-(task-type).md @@ -1,5 +1,18 @@ +--- +title: permission +parent: Task types +nav_order: 19 +--- + +# permission (task type) + +Since v2.9.5 +{: .label .label-green } + Test if a player has a permission. +This task works by regularly polling a player at a certain interval. + ## Options | Key | Description | Type | Required | Default | Notes | diff --git a/docs/task-type/placeholderapi_evaluate-(task-type).md b/docs/task-type/placeholderapi_evaluate-(task-type).md index ae678193..87079d7f 100644 --- a/docs/task-type/placeholderapi_evaluate-(task-type).md +++ b/docs/task-type/placeholderapi_evaluate-(task-type).md @@ -1,7 +1,18 @@ - -*Requires the PlaceholderAPI plugin to activate.* +--- +title: placeholderapi_evaluate +parent: Task types +nav_order: 36 +--- -Reach a certain PlaceholderAPI level. +# placeholderapi_evaluate (task type) + +Since v2.9.5 +{: .label .label-green } + +Plugin 'PlaceholderAPI' required +{: .label } + +Evaluate a certain PlaceholderAPI placeholder and compare it against a given condition. ## Options diff --git a/docs/task-type/playerkilling-(task-type).md b/docs/task-type/playerkilling-(task-type).md index 62cc2343..4aee13bf 100644 --- a/docs/task-type/playerkilling-(task-type).md +++ b/docs/task-type/playerkilling-(task-type).md @@ -1,3 +1,15 @@ +--- +title: playerkilling +parent: Task types +nav_order: 20 +--- + +# playerkilling (task type) + +Since v2.0 +{: .label .label-green } + + Kill a set amount of players. ## Options diff --git a/docs/task-type/playtime-(task-type).md b/docs/task-type/playtime-(task-type).md index f3b827df..649b0db4 100644 --- a/docs/task-type/playtime-(task-type).md +++ b/docs/task-type/playtime-(task-type).md @@ -1,5 +1,19 @@ +--- +title: playtime +parent: Task types +nav_order: 21 +--- + +# playtime (task type) + +Since v1.8 +{: .label .label-green } + Play for a certain amount of time after starting the quest. +{: .note } +Before Quests v2.0, this task was known as `TIMEPLAYED`. + ## Options | Key | Description | Type | Required | Default | Notes | diff --git a/docs/task-type/position-(task-type).md b/docs/task-type/position-(task-type).md index dfa85e9a..bf990ca8 100644 --- a/docs/task-type/position-(task-type).md +++ b/docs/task-type/position-(task-type).md @@ -1,3 +1,14 @@ +--- +title: position +parent: Task types +nav_order: 22 +--- + +# position (task type) + +Since v2.0.3 +{: .label .label-green } + Reach a set of co-ordinates. ## Options diff --git a/docs/task-type/shearing-(task-type).md b/docs/task-type/shearing-(task-type).md index 4d65861d..5c81e1e7 100644 --- a/docs/task-type/shearing-(task-type).md +++ b/docs/task-type/shearing-(task-type).md @@ -1,3 +1,15 @@ +--- +title: shearing +parent: Task types +nav_order: 23 +--- + +# shearing (task type) + +Since v2.0 +{: .label .label-green } + + Shear a set amount of sheep. ## Options diff --git a/docs/task-type/shopguiplus_buy-(task-type).md b/docs/task-type/shopguiplus_buy-(task-type).md index 888a1384..85c03ae9 100644 --- a/docs/task-type/shopguiplus_buy-(task-type).md +++ b/docs/task-type/shopguiplus_buy-(task-type).md @@ -1,8 +1,20 @@ - -*Requires the ShopGUI+ plugin to activate.* +--- +title: shopguiplus_buy +parent: Task types +nav_order: 37 +--- + +# shopguiplus_buy (task type) + +Since v2.15 +{: .label .label-green } + +Plugin 'ShopGUI+' required +{: .label } Buy a certain number of items from a ShopGUI+ shop. +{: .note } Since Quests v3.13, `shopguiplus_buycertain` and `shopguiplus_buy` have been merged into one. Both names can be used to refer to this task. diff --git a/docs/task-type/shopguiplus_sell-(task-type).md b/docs/task-type/shopguiplus_sell-(task-type).md index 144e2a42..a1c94a10 100644 --- a/docs/task-type/shopguiplus_sell-(task-type).md +++ b/docs/task-type/shopguiplus_sell-(task-type).md @@ -1,8 +1,20 @@ - -*Requires the ShopGUI+ plugin to activate.* +--- +title: shopguiplus_sell +parent: Task types +nav_order: 38 +--- + +# shopguiplus_sell (task type) + +Since v2.15 +{: .label .label-green } + +Plugin 'ShopGUI+' required +{: .label } Sell a certain number of items to a ShopGUI+ shop. +{: .note } Since Quests v3.13, `shopguiplus_sellcertain` and `shopguiplus_sell` have been merged into one. Both names can be used to refer to this task. diff --git a/docs/task-type/smelting-(task-type).md b/docs/task-type/smelting-(task-type).md index edfd41d9..6a6f3f49 100644 --- a/docs/task-type/smelting-(task-type).md +++ b/docs/task-type/smelting-(task-type).md @@ -1,5 +1,17 @@ +--- +title: smelting +parent: Task types +nav_order: 24 +--- + +# smelting (task type) + +Since v3.12 +{: .label .label-green } + Cook a set amount of an item. +{: .note } Since Quests v3.13, `smeltingcertain` and `smelting` have been merged into one. Both names can be used to refer to this task. diff --git a/docs/task-type/superiorskyblock_level-(task-type).md b/docs/task-type/superiorskyblock_level-(task-type).md index 6289fc83..c23996b6 100644 --- a/docs/task-type/superiorskyblock_level-(task-type).md +++ b/docs/task-type/superiorskyblock_level-(task-type).md @@ -1,5 +1,16 @@ - -*Requires the SuperiorSkyblock plugin to activate.* +--- +title: superiorskyblock_level +parent: Task types +nav_order: 39 +--- + +# superiorskyblock_level (task type) + +Since v3.7 +{: .label .label-green } + +Plugin 'SuperiorSkyblock' required +{: .label } Reach a certain SuperiorSkyblock level. diff --git a/docs/task-type/superiorskyblock_worth-(task-type).md b/docs/task-type/superiorskyblock_worth-(task-type).md index 51572258..a47d50fe 100644 --- a/docs/task-type/superiorskyblock_worth-(task-type).md +++ b/docs/task-type/superiorskyblock_worth-(task-type).md @@ -1,5 +1,16 @@ - -*Requires the SuperiorSkyblock plugin to activate.* +--- +title: superiorskyblock_worth +parent: Task types +nav_order: 40 +--- + +# superiorskyblock_worth (task type) + +Since v3.7 +{: .label .label-green } + +Plugin 'SuperiorSkyblock' required +{: .label } Reach a certain SuperiorSkyblock worth. @@ -7,7 +18,7 @@ Reach a certain SuperiorSkyblock worth. | Key | Description | Type | Required | Default | Notes | |---------|---------------------|---------|----------|---------|-------| -| `worth` | The worth to worth. | Integer | Yes | \- | \- | +| `worth` | The worth to reach. | Integer | Yes | \- | \- | ## Examples diff --git a/docs/task-type/taming-(task-type).md b/docs/task-type/taming-(task-type).md index 775ff567..1847bda4 100644 --- a/docs/task-type/taming-(task-type).md +++ b/docs/task-type/taming-(task-type).md @@ -1,3 +1,14 @@ +--- +title: taming +parent: Task types +nav_order: 25 +--- + +# taming (task type) + +Since v3.13 +{: .label .label-green } + Tame a set amount of animals. ## Options diff --git a/docs/task-type/uskyblock_level-(task-type).md b/docs/task-type/uskyblock_level-(task-type).md index 2ae22ca4..729ca5c6 100644 --- a/docs/task-type/uskyblock_level-(task-type).md +++ b/docs/task-type/uskyblock_level-(task-type).md @@ -1,5 +1,16 @@ - -*Requires the uSkyBlock plugin to activate.* +--- +title: uskyblock_level +parent: Task types +nav_order: 41 +--- + +# uskyblock_level (task type) + +Since v1.7.1 +{: .label .label-green } + +Plugin 'uSkyBlock' required +{: .label } Reach a certain uSkyBlock level. diff --git a/docs/task-type/votingplugin_vote-(task-type).md b/docs/task-type/votingplugin_vote-(task-type).md index fec37347..6a17abac 100644 --- a/docs/task-type/votingplugin_vote-(task-type).md +++ b/docs/task-type/votingplugin_vote-(task-type).md @@ -1,5 +1,16 @@ - -*Requires the VotingPlugin plugin to activate.* +--- +title: votingplugin_vote +parent: Task types +nav_order: 42 +--- + +# votingplugin_vote (task type) + +Since v3.7 +{: .label .label-green } + +Plugin 'VotingPlugin' required +{: .label } Vote a number of times using VotingPlugin. diff --git a/docs/task-type/walking-(task-type).md b/docs/task-type/walking-(task-type).md index c2bc492e..4c38fc27 100644 --- a/docs/task-type/walking-(task-type).md +++ b/docs/task-type/walking-(task-type).md @@ -1,3 +1,14 @@ +--- +title: walking +parent: Task types +nav_order: 26 +--- + +# walking (task type) + +Since v2.0 +{: .label .label-green } + Walk a set distance. ## Options diff --git a/docs/tips.md b/docs/tips.md new file mode 100644 index 00000000..871a9968 --- /dev/null +++ b/docs/tips.md @@ -0,0 +1,43 @@ +--- +title: Tips +nav_order: 11 +--- + +# Tips + +Creating and editing quests can seem daunting at first, but the plugin +is designed to be as easy as possible to use. + +Here's some tips which may help you with your quest creation. + +- **The wiki is your Bible.** This wiki details out how to create each + type of quest and the many different types of quests you can create. + There is a lot of information in this wiki (and it also took ages to + write)! +- **Use a dedicated editor, such as VSCode.** This will make life much + easier if you open the quests directory in VSCode, as you have access + to all the files at once within one editor and you can easily copy / + paste / replace across many files. +- **Plan out your quests.** It might be a wise idea to plan how you want + to create your quests, what categories they will be in and what the + requirements will be like. +- **Back up the /quests/ and /playerdata/ folder.** Things may go wrong + sometimes. You may lose data. On top of whatever backup system you + have, you should back up your quests folder and the playerdata folder, + \*especially\* on a live server. If you use a database, ensure that is + backed up too! +- **Name your quests in a way which makes sense.** Prefix each quest + file with the name of the category for organisation. Name your tasks + in a way which makes sense. +- **Organise your quests into folders.** The /quests/ directory is read + recursively, which means you can sort your quests into folders. (It is + advised you organise them by category, though you should be warned + that file names must still be unique, no matter what directory it is + under.) +- **Follow the advice of the error checker.** You will be informed of + any issues in your config when you reload Quests, along with the exact + location of the problem. Use this information! +- **Be patient.** Creating quests may be a bit boring, there might be a + lot of copying and pasting, but once you get into the rhythm it can + take you less than a few hours to get the plugin fully configured to + how you want it to be. diff --git a/docs/tools/data-migration-tool.md b/docs/tools/data-migration-tool.md new file mode 100644 index 00000000..891862c7 --- /dev/null +++ b/docs/tools/data-migration-tool.md @@ -0,0 +1,35 @@ +--- +title: Data migration tool +parent: Tools +--- + +# Data migration tool + +The **data migration tool** is a tool that allows you to migrate your +data from one [storage provider](Storage_providers "wikilink") to +another. This can also be used as a backup tool. The tool can be +accessed using `/quests admin migratedata`, which will generate a file +[migrate_data.yml](https://github.com/LMBishop/Quests/blob/master/bukkit/src/main/resources/resources/bukkit/migrate_data.yml), +where you must configure both providers. + +The `from` section is the configuration for the storage provider you are +migrating from. The `to` section is the configuration for the storage +provider you are migrating to. Both sections are required. + +When you have entered the information for both systems, you must set the +`ready` flag to **true** at the end of the file. Then, to execute the +migration, run the following command: + + /quests admin migratedata execute + + +{: .warning } +**It is advised that you do this process on a server with no players +online.** You should set a whitelist, or turn on maintenence mode, +before migrating data, and these commands should be done through your +server console. Trying this process with players online may result in +unexpected behaviour, or worse, potential data corruption! + +Once the migration has finished, you can safely delete migrate_data.yml. +You may also want to manually update your main configuration to point to +the new data provider. diff --git a/docs/tools/index.md b/docs/tools/index.md new file mode 100644 index 00000000..83c7f894 --- /dev/null +++ b/docs/tools/index.md @@ -0,0 +1,7 @@ +--- +title: Tools +has_children: true +nav_order: 7 +--- + +# Tools \ No newline at end of file diff --git a/docs/tools/placeholderapi.md b/docs/tools/placeholderapi.md new file mode 100644 index 00000000..cc932600 --- /dev/null +++ b/docs/tools/placeholderapi.md @@ -0,0 +1,148 @@ +--- +title: PlaceholderAPI +parent: Tools +--- + +# PlaceholderAPI +{: .no_toc } + +This plugin integrates with PlaceholderAPI and exposes certain values via +placeholders. This can be used with other plugins. + +{: .important } +> **No PAPI eCloud download is necessary - placeholders come with the plugin.** +The eCloud extension called 'Quests' is not for this plugin, do not download it! +> +> {: .warning } +> > Once again, **do not download the eCloud extension**. There will be errors +> > if you do so. + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + + +## Common placeholders + +### Quest counters + +| Placeholder | Description | +|----------------------------|------------------------------------------------------------------------------| +| `%quests_all%` | Returns the **number** of quests on the server. | +| `%quests_completed%` | **\*** Returns the **number** of quests the player has completed. | +| `%quests_completedbefore%` | Returns the **number** of quests the player has completed **at least once**. | +| `%quests_started%` | Returns the **number** of quests which are active for the player. | +| `%quests_categories%` | Returns the **number** of categories on the server. | + +### Quest lists + +| Placeholder | Description | +|---------------------------------|-------------------------------------------------------------------------------------------------------| +| `%quests_all_list%` | Returns a **comma-seperated\*\* list** of quest **names** on the server. | +| `%quests_completed_list%` | \* Returns a **comma-seperated\*\* list** of quest **names** the player has completed. | +| `%quests_completedbefore_list%` | Returns a **comma-seperated\*\* list** of quest **names** the player has completed **at least once**. | +| `%quests_started_list%` | Returns a **comma-seperated\*\* list** of quest **names** which are active for the player. | +| `%quests_categories_list%` | Returns a **comma-seperated\*\* list** of category **names** on the server. | + +### Quest ID lists + +| Placeholder | Description | +|-----------------------------------|-----------------------------------------------------------------------------------------------------| +| `%quests_all_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** on the server. | +| `%quests_completed_listid%` | \* Returns a **comma-seperated\*\* list** of quest **IDs** the player has completed. | +| `%quests_completedbefore_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** the player has completed **at least once**. | +| `%quests_started_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** which are active for the player. | +| `%quests_categories_listid%` | Returns a **comma-seperated\*\* list** of category **IDs** on the server. | + +**\*** *this does not include quests which have been repeated and not yet completed* + +**\*\*** *the delimiter can be changed by adding it in at the end: for example `%quests_completed_listid_ / %` will return a list of completed quests **seperated by the characters ` / ` (including the spaces around it)*** + +## Advanced placeholders + +### Quest details + +| Placeholder | Description | +|------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| +| `%quests_quest:%` | Returns the **display name** of the quest **``**. | +| `%quests_quest:_started%` | Returns **true/false** on whether or not the quest **``** is started by the player. | +| `%quests_quest:_starteddate%` | Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the quest **``** was started by the player. | +| `%quests_quest:_completed%` | **\*** Returns **true/false** on whether or not the quest **``** is completed by the player. | +| `%quests_quest:_completedbefore%` | Returns **true/false** on whether or not the quest **``** is completed by the player **at least once**. | +| `%quests_quest:_completiondate%` | Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the quest **``** was completed by the player. | +| `%quests_quest:_cooldown%` | Returns a **time in seconds** of the cooldown for quest **``**. | +| `%quests_quest:_canaccept%` | Returns **true/false** on whether or not the quest **``** can be started by the player. | +| `%quests_quest:_meetsrequirements%` | Returns **true/false** on whether or not the player has completed the required quests for the quest **``**. | +| `%quests_quest:_task:_progress%` | Returns the **progress** of task **`task-id`** on the quest **``**. | +| `%quests_quest:_task:_completed%` | Returns **true/false** on whether or not the task **`task-id`** on the quest **``** is completed by the player. | +| `%quests_quest:_p:%` | Returns the **local quest placeholder ``** for the quest **``**. | + +| Placeholder | Description | +|---------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------| +| `%quests_tracked%` | Returns the **display name** of the **players tracked quest** (or "No tracked quest"). | +| `%quests_tracked_started%` | Returns **true/false** on whether or not the **players tracked quest** is started. | +| `%quests_tracked_starteddate%` | Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the **players tracked quest** was started by the player. | +| `%quests_tracked_completed%` | **\*** Returns **true/false** on whether or not the **players tracked quest** is completed. | +| `%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_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:_progress%` | Returns the **progress** of task **`task-id`** on the **players tracked quest**. | +| `%quests_tracked_task:_completed%` | Returns **true/false** on whether or not the task **`task-id`** on the **players tracked quest** is completed by the player. | +| `%quests_tracked_p:%` | Returns the **local quest placeholder ``** for the **players tracked quest**. | + +### Per-category quest counters + +| Placeholder | Description | +|---------------------------------------------------|------------------------------------------------------------------------------------------------------------------| +| `%quests_category:%` | Returns the **id** of the category **``** (useful to check if it is a valid reference). | +| `%quests_category:_all%` | Returns the **number** of quests in the category **``**. | +| `%quests_category:_completed%` | **\*** Returns the **number** of quests in the category **``** the player has completed. | +| `%quests_category:_completedbefore%` | Returns the **number** of quests in the category **``** the player has completed **at least once**. | +| `%quests_category:_started%` | Returns the **number** of quests in the category **``** which are active for the player. | + +### Per-category quest lists + +|Placeholder|Description| +|---|---| +|`%quests_category:_all_list%`|Returns a **comma-seperated\*\* list** of quest **names** on the server.| +|`%quests_category:_completed_list%`|\* Returns a **comma-seperated\*\* list** of quest **names** in the category **``** the player has completed.| +|`%quests_category:_completedbefore_list%`|Returns a **comma-seperated\*\* list** of quest **names** in the category **``** the player has completed **at least once**.| +|`%quests_category:_started_list%`|Returns a **comma-seperated\*\* list** of quest **names** in the category **``** which are active for the player.| + +### Per-category quest ID lists + +| Placeholder | Description | +|----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| `%quests_category:_all_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** on the server. | +| `%quests_category:_completed_listid%` | \* Returns a **comma-seperated\*\* list** of quest **IDs** in the category **``** the player has completed. | +| `%quests_category:_completedbefore_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** in the category **``** the player has completed **at least once**. | +| `%quests_category:_started_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** in the category **``** which are active for the player. | + +**\*** *this does not include quests which have been repeated and not yet completed* + +**\*\*** *the delimiter can be changed by adding it in at the end: for example `%quests_category:_completed_listid_ / %` will return a list of completed quests **seperated by the characters ` / ` (including the spaces around it)*** + +**\*\*\*** *the date format may be adjusted by including it at the end: for example `%quests_q:_completiondate_dd/MM HH:mm:ss%` will return a the date of compltion **formatted as `dd/MM HH:mm:ss`** - you may use any letter listed [here](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html)* + +## Caching placeholders + +Placeholders may be cached for a short period (10 seconds by default) to help improve performance. To do this, **simply add `_cache` to the end of any placeholder**. Note: date formats are automatically cached as parsing them may be heavy. + +**Examples:** +``` +%quests_all_cache% +%quests_completedbefore_listid_cache% +%quests_quest:_task:_progress_cache% +``` + +The length of time Quests retains this cache can be configured in the configuration under `options.placeholder-cache-time`. By default, this cache is **10 seconds**. + +```yaml +options: + ... + placeholder-cache-time: 10 +``` \ No newline at end of file diff --git a/docs/tools/quest-debugger.md b/docs/tools/quest-debugger.md new file mode 100644 index 00000000..1ffcaabd --- /dev/null +++ b/docs/tools/quest-debugger.md @@ -0,0 +1,54 @@ +--- +title: Quest debugger +parent: Tools +--- + +# Quest debugger + +The **quests debugger** allows you to see why a quest may not be working +as intended. When turned on for a quest, it will print out what a task +type is doing and how it is evaluating it. This can be helpful to see +why a specific quest is not accepting a specific action. + +## Using the debugger + +The debugger can be enabled with **/q a debug quest \ +\**. Using \* in place of \ will enable it for all +quests. Enabling it for all will show debug logs for every player, +whereas self will show it for just yourself. + + + +## Example + +We may want to debug the following task: + +``` yaml +tasks: + mining: + type: "blockbreakcertain" + amount: 30 + blocks: + - DARK_OAK_LOG + - DARK_OAK_PLANKS + reverse-if-placed: false +``` + +When breaking `PACKED_ICE`, the debugger sends this output: + + + +Here it is telling us that the task type is checking the broken block +against all the blocks in the `blocks` list, and not finding a match, +thus skipping this task. + +Now, when breaking `DARK_OAK_PLANKS`: + + + +The debugger tells us that it finds a match and increments the task +progress. + +This can be useful when trying to work out why a task may not be +working, such as in the case where you think you're breaking a block of +a specific type, but in reality it has a different type. -- cgit v1.2.3-70-g09d2