diff options
Diffstat (limited to 'docs')
132 files changed, 8532 insertions, 0 deletions
diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 00000000..03ea4d8a --- /dev/null +++ b/docs/API.md @@ -0,0 +1,32 @@ +*** + +### 🔨 ***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 new file mode 100644 index 00000000..ae803b5a --- /dev/null +++ b/docs/Basic-options.md @@ -0,0 +1,584 @@ +\_\_NOTOC\_\_ 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.<limit group>`. + +``` 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 new file mode 100644 index 00000000..aba83ee4 --- /dev/null +++ b/docs/Colour-codes.md @@ -0,0 +1,51 @@ +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: `&#<hex 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 new file mode 100644 index 00000000..dcef33d3 --- /dev/null +++ b/docs/Commands-and-permissions.md @@ -0,0 +1,77 @@ +## 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 \<questid/\*\>** - cancel quest by id +- **/quests q/quest \<questid\> \<start\|track\|cancel\>** - start quest + directly by ID. +- **/quests c/category \<categoryid\>** - 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 \<player\>** - forcefully open + quests GUI for player (bypassing quests.command permission) + - **/quests a/admin opengui c/category \<player\> \<categoryid\>** - + forcefully open category by ID for player (bypassing + quests.command permission) + - **/quests a/admin opengui started \<player\>** - forcefully open + the started menu for player (bypassing quests.command permission) + - **/quests a/admin moddata** - view help for opengui + - **/quests a/admin moddata fullreset \<player\>** - fully clear a + players data file + - **/quests a/admin moddata reset \<player\> \<questid\>** - clear a + players data for a specifc quest + - **/quests a/admin moddata start \<player\> \<questid\>** - start a + quest for a player + - **/quests a/admin moddata complete \<player\> \<questid\>** - + complete a quest for a player + - **/quests a/admin moddata random \<player\> \[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 \<id\>** - import a held quest + item. + - **/quests a/admin items give \<player\> \<id\> \[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 \<quest/\*\> \<all/self\>** - 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.<category>` - permission to start quests within + `(category)`, if `permission-required` for the category is set to + `true` +- `quests.quest.<quest id>` - 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.<limit group>` - permission to start a configured amount + of quests for members of this limit group diff --git a/docs/Common-Configuration-Issues.md b/docs/Common-Configuration-Issues.md new file mode 100644 index 00000000..515c4c5c --- /dev/null +++ b/docs/Common-Configuration-Issues.md @@ -0,0 +1,13 @@ +*** + +### 🗑️ ***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.* + +*** + +# Common Configuration Issues + +### My items are showing up as stone blocks! +Make sure you are using the correct item namesfor your version. **Quests is pre-configured with the names for 1.13+ items - you MUST change them for 1.8!**. + +//todo finish me
\ No newline at end of file diff --git a/docs/Configuration-problems.md b/docs/Configuration-problems.md new file mode 100644 index 00000000..258cbf86 --- /dev/null +++ b/docs/Configuration-problems.md @@ -0,0 +1,77 @@ +**Configuration problems** are designed to inform you when you have an **error** or **potential misconfiguration**. They may appear when reloading Quests, for example: + + + +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: +``` +<name of file> ---- + | - <type of problem>: <description of problem> :<location of problem> +``` + +**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 new file mode 100644 index 00000000..16caa497 --- /dev/null +++ b/docs/Contributing-to-the-wiki.md @@ -0,0 +1,52 @@ +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 new file mode 100644 index 00000000..f41d919d --- /dev/null +++ b/docs/Creating-a-category.md @@ -0,0 +1,54 @@ +# 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.<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 new file mode 100644 index 00000000..a109d3e3 --- /dev/null +++ b/docs/Creating-a-quest-or-category.md @@ -0,0 +1,10 @@ +*** + +### 🗑️ ***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 new file mode 100644 index 00000000..17a93215 --- /dev/null +++ b/docs/Creating-a-quest.md @@ -0,0 +1,444 @@ +\_\_NOTOC\_\_ 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.<id>`. + +``` 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 new file mode 100644 index 00000000..97cc27f1 --- /dev/null +++ b/docs/Custom-GUI-items.md @@ -0,0 +1,61 @@ +**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. + +<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:<category-name>": # apply to <category-name> 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 new file mode 100644 index 00000000..2022f285 --- /dev/null +++ b/docs/Data-migration-tool.md @@ -0,0 +1,27 @@ +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/Default-configuration.md b/docs/Default-configuration.md new file mode 100644 index 00000000..bb04edc8 --- /dev/null +++ b/docs/Default-configuration.md @@ -0,0 +1 @@ +Click [here](https://github.com/LMBishop/Quests/tree/master/bukkit/src/main/resources/resources/bukkit)
\ No newline at end of file diff --git a/docs/Defining-items.md b/docs/Defining-items.md new file mode 100644 index 00000000..cad57de9 --- /dev/null +++ b/docs/Defining-items.md @@ -0,0 +1,329 @@ +\_\_NOTOC\_\_ + +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` | ✅ <sup>\*</sup> | \- | [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") | + +<sup>\*: The name must be defined for the display item of Quests.</sup> + +### Configuration layout + +``` yaml +item: + name: "&6&lSuper Cool Stick" + item: STICK + lore: + - "&7Really cool lore." + # field4: value4 + # etc. +``` + +### Examples + +#### Item + + +*`item` or `type`material</code>* + +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 `:<code>`. + +``` 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: +<https://mineskin.org/>. 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 <id>`, where `<id>` is the desired name of the +item. Your item will be saved to file items/\<id\>.yml, **with the type +'raw**'. + +<https://i.imgur.com/6lsld61.png> <https://i.imgur.com/Pg2eO9a.png> + +### 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 new file mode 100644 index 00000000..460b8846 --- /dev/null +++ b/docs/Download.md @@ -0,0 +1,54 @@ +\_\_NOTOC\_\_ 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) +- <s>[Hangar (testing)](https://hangar.benndorf.dev/LMBishop/Quests)</s> + +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. + +<img src="https://mcbadges.leonardobishop.com/quests.svg"/> + +## 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: +<https://github.com/LMBishop/Quests/blob/master/CONTRIBUTING.md> + +## License + +The full license text is available here: +<https://github.com/LMBishop/Quests/blob/master/LICENSE.txt> + + 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 new file mode 100644 index 00000000..fb63d1f1 --- /dev/null +++ b/docs/GUI-configuration.md @@ -0,0 +1,262 @@ + +*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/Getting-started.md b/docs/Getting-started.md new file mode 100644 index 00000000..d5c3bece --- /dev/null +++ b/docs/Getting-started.md @@ -0,0 +1,22 @@ +*** + +### 🔨 ***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 new file mode 100644 index 00000000..a575ebc8 --- /dev/null +++ b/docs/Global-configurations.md @@ -0,0 +1,91 @@ +**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." +``` + +<https://i.imgur.com/l0FI5Ma.png> + +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: + ... + # <name of macro>: <string value of macro> + 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/Home.md b/docs/Home.md new file mode 100644 index 00000000..c11fac2b --- /dev/null +++ b/docs/Home.md @@ -0,0 +1,134 @@ +\_\_NOTOC\_\_ + +# Quests + +Welcome to the Quests Wiki! Please use the sidebar for navigation around +the wiki. + +**🌟 New & Highlighted Articles** + +- [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") + +Spot a mistake or ambiguous information? Please consider [contributing +to the wiki](contributing_to_the_wiki "wikilink"). + +## FAQs + +Q. What task types are there? + +<!-- --> + + +Many different [task types](task_types "wikilink") are provided. Follow +the links there to see how to format them. + +<!-- --> + +Q. Can I use this plugin on a BungeeCord network/use MySQL? + +<!-- --> + + +Yes, refer to [storage providers](storage_providers "wikilink"). + +<!-- --> + +Q. Players are able to place blocks then break them to advance tasks! How do I stop this? + +<!-- --> + + +Take a look at the [Task configuration layout § +blockbreakcertain](Task_configuration_layout#blockbreakcertain "wikilink"). +You can enable CoreProtect functionality to detect if a player has +placed a block, or enable the `reverse-if-broken` flag which will +subtract from task progress if a block is placed. + +<!-- --> + +Q. How do I limit a quest to a certain world? + +<!-- --> + + +Most task types support world restrictions. Take a look at the task +configuration in [task configuration +layout](task_configuration_layout "wikilink") to see if your task does. + +<!-- --> + +Q. How do I organise quests in the GUI? + +<!-- --> + + +Quests can have a `sort-order`, which organises them within the GUI. You +can see it at [creating a quest](creating_a_quest "wikilink"). + +<!-- --> + + +If you want to add custom elements to a quest GUI, you can refer to +[custom GUI items](custom_GUI_items "wikilink"). + +<!-- --> + +Q. How to I only let specific players do specific quests? + +<!-- --> + + +Specific quests can have permissions enabled for them. Take a look at +[creating a quest](creating_a_quest "wikilink") for more information. +Alternatively, entire categories can have permissions enabled. + +<!-- --> + +Q. Does this plugin support PlaceholderAPI? + +<!-- --> + + +Yes, see [PlaceholderAPI](PlaceholderAPI "wikilink"). + +<!-- --> + +Q. How do I get quest progress on a scoreboard? + +<!-- --> + + +I have written a guide for this: [Quest progress in +scoreboard](Quest_progress_in_scoreboard "wikilink") + +<!-- --> + +Q. I found a bug or have a feature request! Where do I report it? + +<!-- --> + + +Great! Go to the [issue +tracker](https://github.com/LMBishop/Quests/issues) to report bugs or +create feature requests. Please avoid using Spigot's discussion pages or +Discord for requests as I will most likely forget about it! + +<!-- --> + +Q. I have a sizeable portion of money and I feel the need to donate it to you, where do I go? + +<!-- --> + + +Consider giving your money to [Mind](https://www.mind.org.uk/donate); +[Help for Heroes](https://www.helpforheroes.org.uk/donate-online/); +[Cancer Research UK](https://www.cancerresearchuk.org/); or, any other +good cause in your country/local area. Or, if you are programmatically +gifted, donating some of [your +time](https://github.com/LMBishop/Quests/pulls) instead. diff --git a/docs/New-task-type.md b/docs/New-task-type.md new file mode 100644 index 00000000..4a3eb5dc --- /dev/null +++ b/docs/New-task-type.md @@ -0,0 +1,80 @@ +*** + +### 🔨 ***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<String, Object>)` 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 new file mode 100644 index 00000000..b726450c --- /dev/null +++ b/docs/PlaceholderAPI.md @@ -0,0 +1,117 @@ +📜 **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:<quest-id>%`|Returns the **display name** of the quest **`<quest-id>`**.| +|`%quests_quest:<quest-id>_started%`|Returns **true/false** on whether or not the quest **`<quest-id>`** is started by the player.| +|`%quests_quest:<quest-id>_starteddate%`|Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the quest **`<quest-id>`** was started by the player.| +|`%quests_quest:<quest-id>_completed%`|**\*** Returns **true/false** on whether or not the quest **`<quest-id>`** is completed by the player.| +|`%quests_quest:<quest-id>_completedbefore%`|Returns **true/false** on whether or not the quest **`<quest-id>`** is completed by the player **at least once**.| +|`%quests_quest:<quest-id>_completiondate%`|Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the quest **`<quest-id>`** was completed by the player.| +|`%quests_quest:<quest-id>_cooldown%`|Returns a **time in seconds** of the cooldown for quest **`<quest-id>`**.| +|`%quests_quest:<quest-id>_canaccept%`|Returns **true/false** on whether or not the quest **`<quest-id>`** can be started by the player.| +|`%quests_quest:<quest-id>_meetsrequirements%`|Returns **true/false** on whether or not the player has completed the required quests for the quest **`<quest-id>`**.| +|`%quests_quest:<quest-id>_task:<task-id>_progress%`|Returns the **progress** of task **`task-id`** on the quest **`<quest-id>`**.| +|`%quests_quest:<quest-id>_task:<task-id>_completed%`|Returns **true/false** on whether or not the task **`task-id`** on the quest **`<quest-id>`** is completed by the player.| +|`%quests_quest:<quest-id>_p:<placeholder>%`|Returns the **local quest placeholder `<placeholder>`** for the quest **`<quest-id>`**.| + +|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:<task-id>_progress%`|Returns the **progress** of task **`task-id`** on the **players tracked quest**.| +|`%quests_tracked_task:<task-id>_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:<placeholder>%`|Returns the **local quest placeholder `<placeholder>`** for the **players tracked quest**.| + +### Per-category quest counters +|Placeholder|Description| +|---|---| +|`%quests_category:<category-id>%`|Returns the **id** of the category **`<category-id>`** (useful to check if it is a valid reference).| +|`%quests_category:<category-id>_all%`|Returns the **number** of quests in the category **`<category-id>`**.| +|`%quests_category:<category-id>_completed%`|**\*** Returns the **number** of quests in the category **`<category-id>`** the player has completed.| +|`%quests_category:<category-id>_completedbefore%`|Returns the **number** of quests in the category **`<category-id>`** the player has completed **at least once**.| +|`%quests_category:<category-id>_started%`|Returns the **number** of quests in the category **`<category-id>`** which are active for the player.| + +### Per-category quest lists +|Placeholder|Description| +|---|---| +|`%quests_category:<category-id>_all_list%`|Returns a **comma-seperated\*\* list** of quest **names** on the server.| +|`%quests_category:<category-id>_completed_list%`|\* Returns a **comma-seperated\*\* list** of quest **names** in the category **`<category-id>`** the player has completed.| +|`%quests_category:<category-id>_completedbefore_list%`|Returns a **comma-seperated\*\* list** of quest **names** in the category **`<category-id>`** the player has completed **at least once**.| +|`%quests_category:<category-id>_started_list%`|Returns a **comma-seperated\*\* list** of quest **names** in the category **`<category-id>`** which are active for the player.| + +### Per-category quest ID lists +|Placeholder|Description| +|---|---| +|`%quests_category:<category-id>_all_listid%`|Returns a **comma-seperated\*\* list** of quest **IDs** on the server.| +|`%quests_category:<category-id>_completed_listid%`|\* Returns a **comma-seperated\*\* list** of quest **IDs** in the category **`<category-id>`** the player has completed.| +|`%quests_category:<category-id>_completedbefore_listid%`|Returns a **comma-seperated\*\* list** of quest **IDs** in the category **`<category-id>`** the player has completed **at least once**.| +|`%quests_category:<category-id>_started_listid%`|Returns a **comma-seperated\*\* list** of quest **IDs** in the category **`<category-id>`** 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:<category-id>_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:<quest-name>_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:<quest-id>_task:<task-id>_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 new file mode 100644 index 00000000..8533a2e2 --- /dev/null +++ b/docs/Quest-debugger.md @@ -0,0 +1,46 @@ +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 \<quest/\*\> +\<all/self\>**. Using \* in place of \<quest\> 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. + +<https://i.imgur.com/Sb5DrpJ.png> + +## 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: +<https://i.imgur.com/2GKba8i.png> + +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: + +<https://i.imgur.com/2nI8uCH.png> + +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 new file mode 100644 index 00000000..5d05b8b4 --- /dev/null +++ b/docs/Quest-progress-in-scoreboard.md @@ -0,0 +1,180 @@ +This guide will show you how to show quest progress in a scoreboard. The +plugin +[<https://www.spigotmc.org/resources/animatedscoreboard.20848/>](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: + +<https://i.imgur.com/NkcZTB2.png> <https://i.imgur.com/EIWAwb2.png> + +## 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 +[<https://www.spigotmc.org/resources/animatedscoreboard.20848/>](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 new file mode 100644 index 00000000..d366ae85 --- /dev/null +++ b/docs/Storage-providers.md @@ -0,0 +1,137 @@ +\_\_NOTOC\_\_ 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-configuration-layout.md b/docs/Task-configuration-layout.md new file mode 100644 index 00000000..dc934a0c --- /dev/null +++ b/docs/Task-configuration-layout.md @@ -0,0 +1,6 @@ +--- +### 🔃 This information has moved + +Each task type now has its own individual page. Please see the sidebar or [this page](https://github.com/LMBishop/Quests/wiki/Task-types) to get to them. + +---
\ No newline at end of file diff --git a/docs/Task-types.md b/docs/Task-types.md new file mode 100644 index 00000000..089fb464 --- /dev/null +++ b/docs/Task-types.md @@ -0,0 +1,67 @@ +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 new file mode 100644 index 00000000..b7e1ea42 --- /dev/null +++ b/docs/Tips.md @@ -0,0 +1,36 @@ +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/_Footer.md b/docs/_Footer.md new file mode 100644 index 00000000..cfdd9fd8 --- /dev/null +++ b/docs/_Footer.md @@ -0,0 +1,3 @@ +*This wiki serves as a manual for Quests, however there is no guarantee that the information is up-to-date or complete. As per the license, this software provides absolutely no warranty, nor are the maintainers liable for any damages. Please see the license text for more information.* + +[🏠 Home page](https://github.com/LMBishop/Quests/wiki/) ~ [💻 Source code](https://github.com/LMBishop/Quests/) ~ [🤝 Contributing to the wiki](https://github.com/LMBishop/Quests/wiki/Contributing-to-the-wiki) ~ [📜 Full license text](https://github.com/LMBishop/Quests/blob/master/LICENSE.txt)
\ No newline at end of file diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md new file mode 100644 index 00000000..8b576e3c --- /dev/null +++ b/docs/_Sidebar.md @@ -0,0 +1,87 @@ +<p align="center"> +<img src="https://leonardobishop.com/~/artwork/questcompass2-256.png" width="100" height="100"><br> +</p> + +## [Home / FAQs](https://github.com/LMBishop/Quests/wiki) + +[Getting started](Getting-started) + +[Downloading](download) + +[Tips](Tips) + +[Commands and permissions](Commands-and-permissions) +### **Configuration** +* [Basic options](Basic-options) +* [Creating a quest](Creating-a-quest) +* [Creating a category](Creating-a-category) +* [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) +* [Default configuration](Default-configuration) + +### **Task Types** + +* [Task types](Task-types) + * [blockplace](blockplace-(task-type)) + * [blockbreak](blockbreak-(task-type)) + * [breeding](breeding-(task-type)) + * [brewing](brewing-(task-type)) + * [bucketempty](bucketempty-(task-type)) + * [bucketfill](bucketfill-(task-type)) + * [command](command-(task-type)) + * [consume](consume-(task-type)) + * [crafting](crafting-(task-type)) + * [dealdamage](dealdamage-(task-type)) + * [distancefrom](distancefrom-(task-type)) + * [enchanting](enchanting-(task-type)) + * [expearn](expearn-(task-type)) + * [farming](farming-(task-type)) + * [fishing](fishing-(task-type)) + * [inventory](inventory-(task-type)) + * [milking](milking-(task-type)) + * [mobkilling](mobkilling-(task-type)) + * [permission](permission-(task-type)) + * [playerkilling](playerkilling-(task-type)) + * [playtime](playtime-(task-type)) + * [position](position-(task-type)) + * [shearing](shearing-(task-type)) + * [taming](taming-(task-type)) + * [walking](walking-(task-type)) + * [smelting](smelting-(task-type)) + * [askyblock_level](askyblock_level-(task-type)) + * [bentobox_level](bentobox_level-(task-type)) + * [citizens_deliver](citizens_deliver-(task-type)) + * [citizens_interact](citizens_interact-(task-type)) + * [essentials_balance](essentials_balance-(task-type)) + * [essentials_moneyearn](essentials_moneyearn-(task-type)) + * [fabledskyblock_level](fabledskyblock_level-(task-type)) + * [iridiumskyblock_value](iridiumskyblock_value-(task-type)) + * [mythicmobs_killing](mythicmobs_killing-(task-type)) + * [placeholderapi_evaluate](placeholderapi_evaluate-(task-type)) + * [shopguiplus_buy](shopguiplus_buy-(task-type)) + * [shopguiplus_sell](shopguiplus_sell-(task-type)) + * [superiorskyblock_level](superiorskyblock_level-(task-type)) + * [superiorskyblock_worth](superiorskyblock_worth-(task-type)) + * [votingplugin_vote](votingplugin_vote-(task-type)) + * [uskyblock_level](uskyblock_level-(task-type)) + +### **API** + +* [API](API) +* [New task type](New-task-type) + +### **Guides** + +* [Quest progress in scoreboard](Quest-progress-in-scoreboard) + +### **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 diff --git a/docs/_Templates.md b/docs/_Templates.md new file mode 100644 index 00000000..710f65e5 --- /dev/null +++ b/docs/_Templates.md @@ -0,0 +1,29 @@ +\_\_NOTOC\_\_ This page contains wikicode templates for use through the +wiki. GitHub does not support page transclusion so instead they should +be simply copied from here. + +## Dev build + + +**⚙️ This section describes a feature currently only available in a +[development build](https://github.com/LMBishop/Quests/actions) of +quests.** + +## Under construction + +------------------------------------------------------------------------ + +### 🔨 **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).* + +------------------------------------------------------------------------ + +## Removed option + + +⛔️ **This option has been removed in version and this wiki entry is +subject to removal.** *Please see [{{{other}}}]({{{other}}} "wikilink") +instead.* diff --git a/docs/_old_mediawiki/Basic-options.mediawiki b/docs/_old_mediawiki/Basic-options.mediawiki new file mode 100644 index 00000000..193ac237 --- /dev/null +++ b/docs/_old_mediawiki/Basic-options.mediawiki @@ -0,0 +1,365 @@ +__NOTOC__ +Quests allows you to configure '''basic options''' for the plugin. These can all be located in the <code>config.yml</code>. + +== Table of contents == +* [[Basic options#Categories enabled|Categories enabled]] +* [[Basic options#Trim gui size|Trim gui size]] +* [[Basic options#Titles enabled|Titles enabled]] +* [[Basic options#Quest started limit|Quest started limit]] +* [[Basic options#Quest limit|Quset limit]] +* [[Basic options#Allow quest cancel|Allow quest cancel]] +* [[Basic options#Allow quest track|Allow quest track]] +* [[Basic options#Task type exclusions|Task type exclusions]] +* [[Basic options#Guinames|Guinames]] +* [[Basic options#Sounds|Sounds]] +* [[Basic options#GUI hide locked|GUI hide locked]] +* [[Basic options#GUI confirm cancel|GUI confirm cancel]] +* [[Basic options#GUI hide quests if no permission|GUI hide quests if no permission]] +* [[Basic options#GUI hide categories if no permission|GUI hide categoires if no permission]] +* [[Basic options#GUI use PlaceholderAPI|GUI use PlaceholderAPI]] +* [[Basic options#GUI truncate requirements|GUI truncate requirements]] +* [[Basic options#GUI actions|GUI actions]] +* [[Basic options#Quest autostart|Quest autostart]] +* [[Basic options#Quest autotrack|Quest autotrack]] +* [[Basic options#Verbose logging level|Verbose logging level]] +* [[Basic options#Quests use PlaceholderAPI|Quests use PlaceholderAPI]] +* [[Basic options#Verify quest exists on load|Verify quest exists on load]] +* [[Basic options#Performance tweaking|Performance tweaking]] +* [[Basic options#Tab completion|Tab completion]] +* [[Basic options#Error checking|Error checking]] +* [[Basic options#Placeholder cache time|Placeholder cache time]] +* [[Basic options#Global task configuration override|Global task configuration override]] +* [[Basic options#Global quest display configuration override|Global quest display configuration override]] +* [[Basic options#Storage|Storage]] + +== Categories enabled == +:''<code>options.categories-enabled</code>'' +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 == +:''<code>options.trim-gui-size</code>'' +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 == +:''<code>options.titles-enabled</code>'' +Choose whether or not titles will appear when starting / finishing quests. +```yaml +options: + ... + titles-enabled: true +``` + +== Quest started limit == +:''<code>options.quest-started-limit</code>'' +: ⛔️ '''This option has been removed in version 3.8 and this wiki entry is subject to removal.''' ''Please see [[Basic options#Quest limit]] instead.'' + +Choose the number of quests players can start at one time. This will include quests which have [[Creating a quest#Autostart|quest-specific autostart]] enabled, however this value will be ignored if [[Basic options#Quest autostart|global <code>quest-autostart</code>]] is enabled. +```yaml +options: + ... + quest-started-limit: 2 +``` + +== Quest limit == +:''<code>options.quest-limit</code>'' +Choose the number of quests players can start at one time. This will include quests which have [[Creating a quest#Autostart|quest-specific autostart]] enabled, however this value will be ignored if [[Basic options#Quest autostart|global <code>quest-autostart</code>]] 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 <code>default</code> must be defined and is available to everybody, however the rest can be granted through the permission <code>quests.limit.<nowiki><limit group></nowiki></code>. +```yaml +options: + ... + quest-limit: + default: 2 + group1: 5 + group2: 10 + # ... +``` +Group permissions are also documented in [[Commands-and-permissions#permissions|Commands and permissions § Permissions]]. +== Allow quest cancel == +:''<code>options.allow-quest-cancel</code>'' +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 configurations#Global quest display configuration|global quest display configuration]]. +```yaml +options: + ... + allow-quest-cancel: true +``` + +== Allow quest track == +:''<code>options.allow-quest-track</code>'' +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 configurations#Global quest display configuration|global quest display configuration]]. +```yaml +options: + ... + allow-quest-track: true +``` + +== Task type exclusions == +:''<code>options.task-type-exclusions</code>'' +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 == +:''<code>options.guinames</code>'' +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 == +:''<code>options.sounds</code>'' +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 [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html this list] (1.9+) or [https://helpch.at/docs/1.8.8/index.html?org/bukkit/Sound.html this list] (1.8). + +To not have a sound play, you can leave the string blank (i.e. <code>""</code>), for example: +```yaml +options: + ... + sounds: + quest-start: "" +``` +You can choose a specific pitch and volume by including them in the following format <code>SOUND:PITCH:VOLUME</code>. 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+):''' +<code>ENTITY_PLAYER_LEVELUP:2:3</code> -> sound <code>ENTITY_PLAYER_LEVELUP</code> at pitch <code>2</code> with a volume of <code>3</code>. + +== GUI hide locked == +:''<code>options.gui-hide-locked</code>'' +Choose whether quests which cannot be started is visible to the player or not. +```yaml +options: + ... + gui-hide-locked: false +``` + +== GUI confirm cancel == +:''<code>options.gui-confirm-cancel</code>'' +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 == +:''<code>options.gui-hide-quests-nopermission</code>'' +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 == +:''<code>options.gui-hide-categories-nopermission</code>'' +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 == +:''<code>options.gui-use-placeholderapi</code>'' +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 == +:''<code>options.gui-truncate-requirements</code>'' +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 == +:''<code>options.gui-actions</code>'' +Set the click actions for the UI. For a list of click types, check the [https://hub.spigotmc.org/javadocs/spigot/org/bukkit/event/inventory/ClickType.html ClickType javadoc page]. +```yaml +options: + ... + gui-actions: + start-quest: "LEFT" + track-quest: "MIDDLE" + cancel-quest: "RIGHT" +``` + +== Quest autostart == +:''<code>options.quest-autostart</code>'' +Choose whether or not players need to start quests themselves. This will ignore the configured [[#Quest started limit|quest started limit]], and is different from the [[#Autostart|autostart]] option. +```yaml +options: + ... + quest-autostart: false +``` + +== Quest autotrack == +:''<code>options.quest-autotrack</code>'' +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 == +:''<code>options.verbose-logging-level</code>'' +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 == +:''<code>options.quests-use-placeholderapi</code>'' +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 == +:''<code>options.verify-quest-exists-on-load</code>'' +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 == +:''<code>options.performance-tweaking</code>'' +Set some specific options within the internals of Quests. + +The <code>queue executor interval</code> 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 <code>autosave interval</code> 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 == +:''<code>options.tab-completion</code>'' +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 <code>/quests admin</code> if they do not have the admin permission.) +```yaml +options: + ... + tab-completion: + enabled: true +``` + +== Error checking == +:''<code>options.error-checking</code>'' +Configure how Quests handles errors in your configuration. By default, Quests will not allow quests to be loaded if they contain an [[Configuration problems#Types of problem|error]], since this could lead to undefined behaviour. The option <code>override-errors</code> will ignore this behaviour and forcibly allow the quest to be registered. +```yaml +options: + ... + error-checking: + override-errors: false +``` + +== Placeholder cache time == +:''<code>options.placeholder-cache-time</code>" +Set how long Quests will retain parsed PlaceholderAPI strings in the cache, in seconds. See [[PlaceholderAPI#Caching placeholders|PlaceholderAPI § Caching placeholders]] for more information. +```yaml +options: + ... + placeholder-cache-time: 10 +``` + +== Global task configuration override == +:''<code>options.global-task-configuration-override</code>'' +Choose whether or not options set in the [[Global configurations#Global task configuration|global task configuration]] will override per-quest specific options. +```yaml +options: + ... + global-task-configuration-override: false +``` + + +== Global quest display configuration override == +:''<code>options.global-quest-display-configuration-override</code>'' +Choose whether or not the [[Global configurations#Global quest display configuration|global quest display configuration]] will override per-quest specific options. +```yaml +options: + ... + global-quest-display-configuration-override: false +``` + +== Storage == +:''<code>options.storage</code>'' +Configure how Quests will store playerdata. See [[Storage providers|storage providers]] 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_" +```
\ No newline at end of file diff --git a/docs/_old_mediawiki/Commands-and-permissions.mediawiki b/docs/_old_mediawiki/Commands-and-permissions.mediawiki new file mode 100644 index 00000000..c4f965d9 --- /dev/null +++ b/docs/_old_mediawiki/Commands-and-permissions.mediawiki @@ -0,0 +1,54 @@ +== Commands == + +* '''/quests <nowiki>[or /q]</nowiki>''' - opens quest GUI +* '''/quests help''' - view help screen for quests commands +* '''/quests started''' - view a menu of started quests +* '''/quests random <nowiki>[category]</nowiki>''' - start a random quest <nowiki>[in a random category]</nowiki> +* '''/quests cancel <nowiki><questid/*></nowiki>''' - cancel quest by id +* '''/quests q/quest <nowiki><questid></nowiki> <nowiki><start|track|cancel></nowiki>''' - start quest directly by ID. +* '''/quests c/category <nowiki><categoryid></nowiki>''' - 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 <nowiki><player></nowiki>''' - forcefully open quests GUI for player (bypassing quests.command permission) +*** '''/quests a/admin opengui c/category <nowiki><player></nowiki> <nowiki><categoryid></nowiki>''' - forcefully open category by ID for player (bypassing quests.command permission) +*** '''/quests a/admin opengui started <nowiki><player></nowiki>''' - forcefully open the started menu for player (bypassing quests.command permission) +** '''/quests a/admin moddata''' - view help for opengui +*** '''/quests a/admin moddata fullreset <nowiki><player></nowiki>''' - fully clear a players data file +*** '''/quests a/admin moddata reset <nowiki><player></nowiki> <nowiki><questid></nowiki>''' - clear a players data for a specifc quest +*** '''/quests a/admin moddata start <nowiki><player></nowiki> <nowiki><questid></nowiki>''' - start a quest for a player +*** '''/quests a/admin moddata complete <nowiki><player></nowiki> <nowiki><questid></nowiki>''' - complete a quest for a player +*** '''/quests a/admin moddata random <nowiki><player></nowiki> [category]''' - start a random a quest for a player <nowiki>[in a category]</nowiki> +*** ''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 <nowiki>import <id></nowiki>''' - import a held quest item. +*** '''/quests a/admin items <nowiki>give <player> <id> [amount]</nowiki>''' - give a player a quest item. +** '''/quests a/admin debug''' - view help for the [[quest debugger]]. +*** '''/quests a/admin debug report''' - generate a debug report. +*** '''/quests a/admin debug <nowiki>quest <quest/*> <all/self></nowiki>''' - enable debug messages for a specific quest, or all of them. +** '''/quests a/admin types <nowiki>[type]</nowiki>''' - view activated task types, and information on a specific one. +** '''/quests a/admin info <nowiki>[quest]</nowiki>''' - 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 == +* <code>quests.command</code> - to view the quest menu (/quests) +* <code>quests.command.category</code> - to view a specific category (/q category) +* <code>quests.command.started</code> - to view quest started menu (/q started) +* <code>quests.command.quest</code> - to use /q quest +* <code>quests.command.start</code> - to start a quest by command (/q start) +* <code>quests.command.track</code> - to cancel a quest by command (q track) +* <code>quests.command.cancel</code> - to cancel a quest by command (/q cancel) +* <code>quests.command.random</code> - to starting a random quest (/q random) +* <code>quests.admin</code> - for admin commands + +The following are dependent on specific quests & categories: + +* <code>quests.category.<nowiki><category></nowiki></code> - permission to start quests within <code>(category)</code>, if <code>permission-required</code> for the category is set to <code>true</code> +* <code>quests.quest.<nowiki><quest id></nowiki></code> - permission to start quest <code>(quest id)</code>, if <code>permission-required</code> for the quest is set to <code>true</code> + +The following are dependent on your configuration: + +* <code>quests.limit.<nowiki><limit group></nowiki></code> - permission to start a configured amount of quests for members of this limit group diff --git a/docs/_old_mediawiki/Contributing-to-the-wiki.mediawiki b/docs/_old_mediawiki/Contributing-to-the-wiki.mediawiki new file mode 100644 index 00000000..0d1a44b1 --- /dev/null +++ b/docs/_old_mediawiki/Contributing-to-the-wiki.mediawiki @@ -0,0 +1,21 @@ +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 [https://github.com/LMBishop/Quests/issues/new?assignees=&labels=docs%2Cstatus%3A+needs+investigating&template=documentation.yml on the issue tracker]. + +== 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. +<br><br> +You can view the raw source code of a wiki page by adding <code>.mediawiki</code> to the url, for example: <code>https://github.com/LMBishop/Quests/wiki/Storage-providers.mediawiki</code>. '''Note that some pages are edited using Markdown, if <code>.mediawiki</code> does not resolve then use <code>.md</code> instead. These pages do not use Wikitext but will soon be converted to it.''' +<br><br> +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 (<code>## Heading</code> or <code>== Heading ==</code>). H1 (<code># Heading</code> or <code>= Heading =</code>) 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.
\ No newline at end of file diff --git a/docs/_old_mediawiki/Creating-a-category.mediawiki b/docs/_old_mediawiki/Creating-a-category.mediawiki new file mode 100644 index 00000000..e5c1e05d --- /dev/null +++ b/docs/_old_mediawiki/Creating-a-category.mediawiki @@ -0,0 +1,36 @@ += Creating a category = + +Categories are stored in <code>categories.yml</code>. On older versions of Quests they were stored in the main <code>config.yml</code>; quests will read categories from <code>config.yml</code> if a <code>categories.yml</code> file is not present. + +== Category ID == +ID of category, this is the text you should enter when putting quests inside a category. + +== Display == +:''<code>display</code>'' + +The item that is shown in the GUI. + +=== Name === +:''<code>display.name</code>'' + +The name of the item. + +=== Lore === +:''<code>display.lore</code>'' + +The lore (description) of the item. + +=== Type === +:''<code>display.type</code>'' + +The type (material name/id) of item. + +== Permission required == +:''<code>permission-required</code>'' + +Whether permission is needed to open this category, or start quests within it. This permission will follow this format: <code><nowiki>quests.category.<category></nowiki></code>`. + +== Hidden == +:''<code>hidden</code>'' + +Whether this category is shown in the main quests menu.
\ No newline at end of file diff --git a/docs/_old_mediawiki/Creating-a-quest.mediawiki b/docs/_old_mediawiki/Creating-a-quest.mediawiki new file mode 100644 index 00000000..e4568271 --- /dev/null +++ b/docs/_old_mediawiki/Creating-a-quest.mediawiki @@ -0,0 +1,277 @@ +__NOTOC__ +Each file inside the <code>quests</code> 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 [https://github.com/LMBishop/Quests/blob/master/bukkit/src/main/resources/resources/bukkit/quests/example1.yml default configuration]. + +== Table of contents == + +* [[Creating a quest#Quest ID|Quest ID]] +* [[Creating a quest#Tasks|Tasks]] +* [[Creating a quest#Display|Display]] +** [[Creating a quest#Name|Name]] +** [[Creating a quest#Normal lore|Normal lore]] +** [[Creating a quest#Started lore|Started lore]] +** [[Creating a quest#Type|Type]] +* [[Creating a quest#Rewards|Rewards]] +* [[Creating a quest#Start commands|Start commands]] +* [[Creating a quest#Start string|Start string]] +* [[Creating a quest#Reward string|Reward string]] +* [[Creating a quest#Placeholders|Placeholders]] +* [[Creating a quest#Options|Options]] +** [[Creating a quest#Category|Category]] +** [[Creating a quest#Requirements|Requirements]] +** [[Creating a quest#Permission required|Permission required]] +** [[Creating a quest#Cancellable|Cancellable]] +** [[Creating a quest#Counts towards limit|Counts towards limit]] +** [[Creating a quest#Repeatable|Repeatable]] +** [[Creating a quest#Cooldown|Cooldown]] +** [[Creating a quest#Time limit|Time limit]] +** [[Creating a quest#Sort order|Sort order]] +** [[Creating a quest#Autostart|Autostart]] +** [[Creating a quest#completed display|Completed display]] +** [[Creating a quest#cooldown display|Cooldown display]] +** [[Creating a quest#permission display|Permission display]] +** [[Creating a quest#locked display|Locked display]] + +== 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 == +:''<code>tasks</code>'' +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]] +== Display == +:''<code>display</code>'' +This is the item which will be shown to the player in the quest GUI. +=== Name === +:''<code>display.name</code>'' +The name of the item. This is also the name used in chat messages. +```yaml +display: + name: "&cExample I (Single Task)" +``` +=== Normal lore === +:''<code>display.lore-normal</code>'' +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 === +:''<code>display.lore-started</code>'' +The lore (description) of the item '''appended to <code>lore-normal</code>''' 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 <code><nowiki>{TASKID:progress}</nowiki></code> and replace <code>TASKID</code> with the ID of the task you want to get the progress for. Alternatively, you can write <code><nowiki>{TASKID:complete}</nowiki></code> to get if the task is complete. + +```yaml +display: + ... + lore-started: + - "" + - "&7Your current progression:" + - "&7 - &f{mining:progress}&7/30 blocks broken." +``` +=== Type === +:''<code>display.type</code>'' +The type (material name) of item. + +```yaml +display: + ... + type: "WOODEN_PICKAXE" +``` +== Rewards == +:''<code>rewards</code>'' +'''Optional.''' This is a list of commands which will be executed when the player completes the quest. You can use <code><nowiki>{player}</nowiki></code> and the players name will be substituted in place. + +```yaml +rewards: + - "give {player} diamond 10" +``` +== Start commands == +:''<code>startcommands</code>'' +'''Optional.''' This is a list of commands which will be executed when the player starts the quest. You can use <code><nowiki>{player}</nowiki></code> and the player's name will be substituted in place. + +```yaml +startcommands: + - "broadcast {player} has started a quest" +``` +== Start string == +:''<code>startstring</code>'' +'''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 == +:''<code>rewardstring</code>'' +'''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 == +:''<code>placeholders</code>'' +'''Optional.''' This is a set of placeholders which can be accessed using PlaceholderAPI. To get the progression of a player in a task, write <code><nowiki>{TASKID:progress}</nowiki></code> and replace <code>TASKID</code> with the ID of the task you want to get the progress for. Alternatively, you can write <code><nowiki>{TASKID:complete}</nowiki></code> 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]] for a guide which utilises this feature. +== Options == +:''<code>options</code>'' +This section defines quest-specific options. +=== Category === +:''<code>options.category</code>'' +'''Optional.''' The category the quest will be in. You should put the ID of the category here. + + +```yaml +options: + ... + category: "example" +``` +=== Requirements === +:''<code>options.requires</code>'' +'''Optional.''' List of Quest IDs the player must complete before being able to start this quest. + +```yaml +options: + ... + requires: + - "quest-id" +``` +=== Permission required === +:''<code>options.permission-required</code>'' +'''Optional.''' Whether or not the quest should require a permission to start. The permission will be <code><nowiki>quests.quest.<id></nowiki></code>. + +```yaml +options: + ... + permission-required: false +``` +=== Cancellable === +:''<code>options.cancellable</code>'' +'''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 === +:''<code>options.counts-towards-limit</code>'' +'''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 === +:''<code>options.repeatable</code>'' +'''Optional.''' Whether or not the quest can be replayed. + +```yaml +options: + ... + repeatable: false +``` +=== Cooldown === +:''<code>options.cooldown</code>'' +'''Optional.''' Whether ot not the quest is placed on cooldown or is immediately replayable. + +```yaml +options: + ... + cooldown: + enabled: true + time: 1440 # minutes +``` +=== Time limit === +:''<code>options.time-limit</code>'' +'''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 === +:''<code>options.sort-order</code>'' +'''Optional.''' How the plugin sorts the quests in the GUI, lower numbers come first. + +```yaml +options: + ... + sort-order: 1 +``` +=== Autostart === +:''<code>options.autostart</code>'' +'''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 [[Creating a quest#Counts towards limit|§ counts towards limit]] if you do not want autostart quests to count towards the quest started limit. + +```yaml +options: + ... + autostart: true +``` + +=== Completed display === +:''<code>options.completed-display</code>'' +'''Optional.''' The display item this quest should take if it is completed. This accepts the standard ItemStack definition format described in [[Defining items]]. If this option is not specified, the display item [[GUI-configuration#quest-completed-display|defined in the main config.yml]] will be used. + +```yaml +options: + ... + completed-display: + type: "STEAK" +``` + +=== Cooldown display === +:''<code>options.cooldown-display</code>'' +'''Optional.''' The display item this quest should take if it is on cooldown. This accepts the standard ItemStack definition format described in [[Defining items]]. If this option is not specified, the display item [[GUI-configuration#quest-cooldown-display|defined in the main config.yml]] will be used. + +```yaml +options: + ... + cooldown-display: + type: "STEAK" +``` + +=== Permission display === +:''<code>options.permission-display</code>'' +'''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]]. If this option is not specified, the display item [[GUI-configuration#quest-permission-display|defined in the main config.yml]] will be used. + +```yaml +options: + ... + permission-display: + type: "STEAK" +``` + +=== Locked display === +:''<code>options.locked-display</code>'' +'''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]]. If this option is not specified, the display item [[GUI-configuration#quest-locked-display|defined in the main config.yml]] will be used. + +```yaml +options: + ... + locked-display: + type: "STEAK" +``` diff --git a/docs/_old_mediawiki/Custom-GUI-items.mediawiki b/docs/_old_mediawiki/Custom-GUI-items.mediawiki new file mode 100644 index 00000000..1ba33886 --- /dev/null +++ b/docs/_old_mediawiki/Custom-GUI-items.mediawiki @@ -0,0 +1,52 @@ +'''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 <code>config.yml</code>: + +```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 <code>repeat</code> field will repeat the item for consecutive slots after that. + +The optional <code>commands</code> list will execute commands if the player clicks on the item. The <code>{player}</code> 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. + +[[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:<category-name>": # apply to <category-name> menu + ... + "quests": # apply to whole quests menu if categories are disabled + ... +```
\ No newline at end of file diff --git a/docs/_old_mediawiki/Data-migration-tool.mediawiki b/docs/_old_mediawiki/Data-migration-tool.mediawiki new file mode 100644 index 00000000..909e29ef --- /dev/null +++ b/docs/_old_mediawiki/Data-migration-tool.mediawiki @@ -0,0 +1,13 @@ +The '''data migration tool''' is a tool that allows you to migrate your data from one [[Storage providers|storage provider]] to another. This can also be used as a backup tool. The tool can be accessed using <code>/quests admin migratedata</code>, which will generate a file [https://github.com/LMBishop/Quests/blob/master/bukkit/src/main/resources/resources/bukkit/migrate_data.yml migrate_data.yml], where you must configure both providers. + +The <code>from</code> section is the configuration for the storage provider you are migrating from. The <code>to</code> 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 <code>ready</code> 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.
\ No newline at end of file diff --git a/docs/_old_mediawiki/Defining-items.mediawiki b/docs/_old_mediawiki/Defining-items.mediawiki new file mode 100644 index 00000000..7d04a851 --- /dev/null +++ b/docs/_old_mediawiki/Defining-items.mediawiki @@ -0,0 +1,259 @@ +__NOTOC__ + +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 == +* [[Defining items#Configurable options|Configurable options]] +** [[Defining items#Configuration layout|Configuration layout]] +** [[Defining items#Examples|Examples]] +*** [[Defining items#Name|Name]] +*** [[Defining items#Item|Item]] +*** [[Defining items#Lore|Lore]] +*** [[Defining items#Enchantments|Enchantments]] +*** [[Defining items#Item flags|Item flags]] +*** [[Defining items#Unbreakable|Unbreakable]] +*** [[Defining items#Attribute modifiers|Attribute modifiers]] +*** [[Defining items#Custom model data|Custom model data]] +*** [[Defining items#Owner|Owner]] +* [[Defining items#Quest items|Quest items]] +** [[Defining items#Importing items|Importing items]] +** [[Defining items#Manually defined items|Manually defined items]] +*** [[Defining items#Defined|Defined]] +*** [[Defining items#MMOItems|MMOItems]] +*** [[Defining items#Slimefun|Slimefun]] +*** [[Defining items#ExecutableItems|ExecutableItems]] +** [[Defining items#Referencing a quest item|Referencing a quest item]] + +== Configurable options == +{| +|- +! Field !! Optional !! Minecraft Version !! More Information +|- +| <code>item</code> || ❌ || - || [[Defining items#Item|Jump]] +|- +| <code>name</code> || ✅ <sup>*</sup> || - || [[Defining items#Name|Jump]] +|- +| <code>lore</code> || ✅ || - || [[Defining items#Lore|Jump]] +|- +| <code>enchantments</code> || ✅ || - || [[Defining items#Enchantments|Jump]] +|- +| <code>itemflags</code> || ✅ || 1.8+ || [[Defining items#Item flags|Jump]] +|- +| <code>unbreakable</code> || ✅ || 1.13+ || [[Defining items#Unbreakable|Jump]] +|- +| <code>attributemodifiers</code> || ✅ || 1.13+ || [[Defining items#Attribute modifiers|Jump]] +|- +| <code>custommodeldata</code> || ✅ || 1.14+ || [[Defining items#Custom model data|Jump]] +|- +| <code>owner-<nowiki>[...]</nowiki></code> || ✅ || 1.8+ || [[Defining items#Owner (skulls)|Jump]] +|} +<sup>*: The name must be defined for the display item of Quests.</sup> + +=== Configuration layout === +```yaml +item: + name: "&6&lSuper Cool Stick" + item: STICK + lore: + - "&7Really cool lore." + # field4: value4 + # etc. +``` +=== Examples === + +==== Item ==== +:''<code>item</code> or <code>type</code or <code>material</code>'' + +The item is the material the itemstack is made out of. Please see the [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html latest javadocs] (1.13+) or the [https://helpch.at/docs/1.12.2/org/bukkit/Material.html 1.12 javadocs] (1.8-1.12) for item names. For 1.8-1.12, data codes can be added on at the end with a colon <code>:<nowiki><code></nowiki></code>. +```yaml +item: + item: "WHEAT" + ... +``` + +==== Name ==== +:''<code>name</code>'' + +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 ==== +:''<code>lore</code>'' +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 [https://hub.spigotmc.org/javadocs/spigot/org/bukkit/enchantments/Enchantment.html spigot names] -> 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 [https://hub.spigotmc.org/javadocs/spigot/org/bukkit/inventory/ItemFlag.html Spigot javadocs]. +```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 [https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html Spigot javadocs], along with full list of [https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/AttributeModifier.Operation.html operations]. +```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 (<code>PLAYER_HEAD</code> 1.13+, <code>SKULL_ITEM</code> 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: https://mineskin.org/. 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: +* <code>raw</code> (items imported using /q a items import) +* <code>defined</code> (items manually written following the format above) +* <code>mmoitems</code> (items from MMOItems) +* <code>slimefun</code> (items from Slimefun) +* <code>executableitems</code> (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 <code>/q a items import <nowiki><id></nowiki></code>, where <code><nowiki><id></nowiki></code> is the desired name of the item. Your item will be saved to file items/<nowiki><id></nowiki>.yml, '''with the type 'raw''''. + +[[https://i.imgur.com/6lsld61.png]] +[[https://i.imgur.com/Pg2eO9a.png]] + +=== Manually defining items === +You can manually define an item by creating a new <code>yml</code> file within the items/ directory. You must specify a <code>type</code> and the item itself under <code>item</code>. + +==== Defined ==== +'''Defined quest items''' are regular ItemStacks and follow the format defined under [[Defined items#Configurable options|§ Configurable options]]. +``` +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 <code><nowiki>quest-item</nowiki></code>. + +```yaml +# Within a task +type: "inventory" +item: + quest-item: "testitem" +```
\ No newline at end of file diff --git a/docs/_old_mediawiki/Download.mediawiki b/docs/_old_mediawiki/Download.mediawiki new file mode 100644 index 00000000..6990229a --- /dev/null +++ b/docs/_old_mediawiki/Download.mediawiki @@ -0,0 +1,49 @@ +__NOTOC__ +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 == + +* [https://www.spigotmc.org/resources/quests-1-8-1-19-set-up-goals-for-players.23696/ SpigotMC (preferred)] +* [https://modrinth.com/mod/quests Modrinth] +* [https://polymart.org/resource/quests.938 Polymart] +* [https://songoda.com/marketplace/product/quests-quests.544 Songoda] +* [https://github.com/LMBishop/Quests/releases GitHub] +* <s>[https://hangar.benndorf.dev/LMBishop/Quests Hangar (testing)]</s> + +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. + +<img src="https://mcbadges.leonardobishop.com/quests.svg"/> + +== Development builds == + +* [https://github.com/LMBishop/Quests/actions GitHub 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: https://github.com/LMBishop/Quests/blob/master/CONTRIBUTING.md + +== License == +The full license text is available here: https://github.com/LMBishop/Quests/blob/master/LICENSE.txt + +``` +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]. +```
\ No newline at end of file diff --git a/docs/_old_mediawiki/GUI-configuration.mediawiki b/docs/_old_mediawiki/GUI-configuration.mediawiki new file mode 100644 index 00000000..14628c01 --- /dev/null +++ b/docs/_old_mediawiki/GUI-configuration.mediawiki @@ -0,0 +1,191 @@ +:''See also [[Custom GUI items]] and [[Defining items]].'' + +The '''GUI configuration''' is defined in the <code>config.yml</code>. 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]]. + +== Back button == +:''<code>gui.back-button</code>'' +The back button displayed within sub menus. +```yaml +gui: + ... + back-button: + name: "&cReturn" + lore: + - "&7Return to the categories menu." + type: "ARROW" +``` + +== Page previous == +:''<code>gui.page-prev</code>'' +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 <code>{prevpage}</code> variable represents the page number for the previous page. + + +== Page next == +:''<code>gui.page-next</code>'' +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 <code>{nextpage}</code> variable represents the page number for the next page. + +== Page description == +:''<code>gui.page-next</code>'' +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 <code>{page}</code> variable represents the page number for the current page. + +== Quest locked display == +:''<code>gui.quest-locked-display</code>'' +The item is used to represent locked quests. A quest is locked if its [[Creating a quest#Requirements|requirements]] 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 <code>{quest}</code> variable represents the quest [[Creating a quest#name|display name]], with its formatting stripped. + +The <code>{questid}</code> variable represents the quest ID. + +The <code>{requirements}</code> 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]] + +== Quest permission display == +:''<code>gui.quest-permission-display</code>'' +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 <code>{quest}</code> variable represents the quest [[Creating a quest#name|display name]], with its formatting stripped. + +The <code>{questid}</code> variable represents the quest ID. + +== Quest cooldown display == +:''<code>gui.quest-cooldown-display</code>'' +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 <code>{quest}</code> variable represents the quest [[Creating a quest#name|display name]], with its formatting stripped. + +The <code>{questid}</code> variable represents the quest ID. + +The <code>{time}</code> variable represents the formatted time remaining until the cooldown period is over. This can be configured in the messages section. + +== Quest completed display == +:''<code>gui.quest-completed-display</code>'' +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 <code>{quest}</code> variable represents the quest [[Creating a quest#name|display name]], with its formatting stripped. + +The <code>{questid}</code> variable represents the quest ID. + +== No started quests == +:''<code>gui.no-started-quests</code>'' +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 == +:''<code>gui.quest-cancel-yes</code>'' +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 == +:''<code>gui.quest-cancel-no</code>'' +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 == +:''<code>gui.quest-cancel-background</code>'' +Background item in the quest cancel menu. +```yaml +gui: + ... + quest-cancel-background: + type: "GRAY_STAINED_GLASS_PANE" +```
\ No newline at end of file diff --git a/docs/_old_mediawiki/Global-configurations.mediawiki b/docs/_old_mediawiki/Global-configurations.mediawiki new file mode 100644 index 00000000..c381d491 --- /dev/null +++ b/docs/_old_mediawiki/Global-configurations.mediawiki @@ -0,0 +1,73 @@ +'''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 <code>config.yml</code>), +```yaml +... +global-task-configuration: + types: + inventory: + update-progress: true +... +``` + +This will add to ''all'' tasks configurations with <code>type: inventory</code> across ''all'' quests the following: <code>update-progress: true</code>. '''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 [[Basic options#Global task configuration override|global task configuration override]]. + +== 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." +``` + +[[https://i.imgur.com/l0FI5Ma.png]] + +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 <code>global-macros</code> section: +``` +global-macros: + ... + # <name of macro>: <string value of macro> + top-bar: "&6---&7---&6---" +``` + +To use these in your quests, simply reference it by using <code><nowiki><$m name-of-macro $m></nowiki></code>. Macro names '''cannot have spaces'''. + +For example, to use the <code>top-bar</code> macro in <code>example-quest.yml</code>: +```yaml +tasks: + ... +display: + ... + lore-normal: + - "<$m top-bar $>" + - "..." + ... +``` + + diff --git a/docs/_old_mediawiki/Home.mediawiki b/docs/_old_mediawiki/Home.mediawiki new file mode 100644 index 00000000..c046bd36 --- /dev/null +++ b/docs/_old_mediawiki/Home.mediawiki @@ -0,0 +1,59 @@ +__NOTOC__ += Quests = + +Welcome to the Quests Wiki! Please use the sidebar for navigation around the wiki. + +'''🌟 New & Highlighted Articles''' +* [[Tips]] +* [[Basic options]] +* [[Creating a quest]] +* [[Creating a category]] +* [[Custom GUI items]] +* [[Task types]] +* [[PlaceholderAPI]] + +Spot a mistake or ambiguous information? Please consider [[contributing to the wiki]]. + +== FAQs == + +;Q. What task types are there? + +:Many different [[task types]] are provided. Follow the links there to see how to format them. + +;Q. Can I use this plugin on a BungeeCord network/use MySQL? + +:Yes, refer to [[storage providers]]. + +;Q. Players are able to place blocks then break them to advance tasks! How do I stop this? + +:Take a look at the [[Task configuration layout#blockbreakcertain|Task configuration layout § blockbreakcertain]]. You can enable CoreProtect functionality to detect if a player has placed a block, or enable the <code>reverse-if-broken</code> flag which will subtract from task progress if a block is placed. + +;Q. How do I limit a quest to a certain world? + +:Most task types support world restrictions. Take a look at the task configuration in [[task configuration layout]] to see if your task does. + +;Q. How do I organise quests in the GUI? + +:Quests can have a <code>sort-order</code>, which organises them within the GUI. You can see it at [[creating a quest]]. + +:If you want to add custom elements to a quest GUI, you can refer to [[custom GUI items]]. + +;Q. How to I only let specific players do specific quests? + +:Specific quests can have permissions enabled for them. Take a look at [[creating a quest]] for more information. Alternatively, entire categories can have permissions enabled. + +;Q. Does this plugin support PlaceholderAPI? + +:Yes, see [[PlaceholderAPI]]. + +;Q. How do I get quest progress on a scoreboard? + +:I have written a guide for this: [[Quest progress in scoreboard]] + +;Q. I found a bug or have a feature request! Where do I report it? + +:Great! Go to the [https://github.com/LMBishop/Quests/issues issue tracker] to report bugs or create feature requests. Please avoid using Spigot's discussion pages or Discord for requests as I will most likely forget about it! + +;Q. I have a sizeable portion of money and I feel the need to donate it to you, where do I go? + +:Consider giving your money to [https://www.mind.org.uk/donate Mind]; [https://www.helpforheroes.org.uk/donate-online/ Help for Heroes]; [https://www.cancerresearchuk.org/ Cancer Research UK]; or, any other good cause in your country/local area. Or, if you are programmatically gifted, donating some of [https://github.com/LMBishop/Quests/pulls your time] instead.
\ No newline at end of file diff --git a/docs/_old_mediawiki/Quest-debugger.mediawiki b/docs/_old_mediawiki/Quest-debugger.mediawiki new file mode 100644 index 00000000..2b2cd243 --- /dev/null +++ b/docs/_old_mediawiki/Quest-debugger.mediawiki @@ -0,0 +1,35 @@ +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 <nowiki><quest/*> <all/self></nowiki>'''. Using * in place of <nowiki><quest></nowiki> 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. + +[[https://i.imgur.com/Sb5DrpJ.png]] + +== 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: +[[https://i.imgur.com/2GKba8i.png]] + +Here it is telling us that the task type is checking the broken block against all the blocks in the <code>blocks</code> list, and not finding a match, thus skipping this task. + +Now, when breaking DARK_OAK_PLANKS: + +[[https://i.imgur.com/2nI8uCH.png]] + +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.
\ No newline at end of file diff --git a/docs/_old_mediawiki/Quest-progress-in-scoreboard.mediawiki b/docs/_old_mediawiki/Quest-progress-in-scoreboard.mediawiki new file mode 100644 index 00000000..c168bc22 --- /dev/null +++ b/docs/_old_mediawiki/Quest-progress-in-scoreboard.mediawiki @@ -0,0 +1,143 @@ +This guide will show you how to show quest progress in a scoreboard. The plugin [[AnimatedScoreboard|https://www.spigotmc.org/resources/animatedscoreboard.20848/]] 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: + +[[https://i.imgur.com/NkcZTB2.png]] +[[https://i.imgur.com/EIWAwb2.png]] + +== 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 <code>%quests_q:example1_p:description%</code> with PlaceholderAPI will return <code>&7Break &f30 blocks &7of any type.</code>. These are known as [[PlaceholderAPI#Quest details|local quest placeholders]]. + +Our <code>description</code> 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 [[https://github.com/LMBishop/Quests/blob/master/src/main/resources/resources/bukkit/quests/example1.yml|here]]. + +== Configuring AnimatedScoreboard == +⚠️ '''This guide assumes you have a basic understanding of the plugin [[AnimatedScoreboard|https://www.spigotmc.org/resources/animatedscoreboard.20848/]].''' + +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 <code>%quests_tracked<...>%</code> 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 <code>description</code> and <code>progress</code> 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 <code>triggers</code>. + +Now, we must create two files <code>ontrack.yml</code> and <code>ontrackend.yml</code>. 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]] + diff --git a/docs/_old_mediawiki/Storage-providers.mediawiki b/docs/_old_mediawiki/Storage-providers.mediawiki new file mode 100644 index 00000000..7f33d985 --- /dev/null +++ b/docs/_old_mediawiki/Storage-providers.mediawiki @@ -0,0 +1,88 @@ +__NOTOC__ +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 (<code>yaml</code>) +* MySQL (<code>mysql</code>) + +When changing storage systems, '''the plugin must be restarted for the changes to have effect'''. + +== Table of contents == +* [[Storage providers#Supported storage systems|Supported storage systems]] +** [[Storage providers#Flatfile|Flatfile]] +*** [[Storage providers#YAML|YAML]] +** [[Storage providers#Network|Network]] +*** [[Storage providers#MySQL|MySQL]] +* [[Storage providers#Data synchronisation|Data synchronisation]] +** [[Storage providers#Delay loading|Delay loading]] + +== 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 [[Storage providers#Delay loading|delay the loading of player data]]. 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 [https://github.com/brettwooldridge/HikariCP HikariCP README]. +```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 [[Storage providers#Network|race condition]], 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: [https://github.com/LMBishop/Quests/issues/180] diff --git a/docs/_old_mediawiki/Tips.mediawiki b/docs/_old_mediawiki/Tips.mediawiki new file mode 100644 index 00000000..f7b605c5 --- /dev/null +++ b/docs/_old_mediawiki/Tips.mediawiki @@ -0,0 +1,12 @@ +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.
\ No newline at end of file diff --git a/docs/_old_mediawiki/_Templates.mediawiki b/docs/_old_mediawiki/_Templates.mediawiki new file mode 100644 index 00000000..a2bd3461 --- /dev/null +++ b/docs/_old_mediawiki/_Templates.mediawiki @@ -0,0 +1,16 @@ +__NOTOC__ +This page contains wikicode templates for use through the wiki. GitHub does not support page transclusion so instead they should be simply copied from here. + +== Dev build == +:'''⚙️ This section describes a feature currently only available in a [https://github.com/LMBishop/Quests/actions development build] of quests.''' + +== Under construction == +----- + +=== 🔨 '''This page is under construction''' === +''The information contained here may be inaccurate or incomplete. You can help by [https://github.com/LMBishop/Quests/wiki/Contributing-to-the-wiki contributing information to the wiki].'' + +----- + +== Removed option == +: ⛔️ '''This option has been removed in version {{{version}}} and this wiki entry is subject to removal.''' ''Please see [[{{{other}}}]] instead.''
\ No newline at end of file diff --git a/docs/_old_mediawiki/askyblock_level-(task-type).mediawiki b/docs/_old_mediawiki/askyblock_level-(task-type).mediawiki new file mode 100644 index 00000000..df42f6e6 --- /dev/null +++ b/docs/_old_mediawiki/askyblock_level-(task-type).mediawiki @@ -0,0 +1,30 @@ +: ''Requires the ASkyBlock plugin to activate.'' + +Reach a certain ASkyBlock level. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>level</code> +| The level to reach. +| Integer +| Yes +| - +| - +|} + +== Examples == +Reach island level 10: + +```yaml +askyblock: + type: "askyblock_level" + level: 10 # island level needed +``` diff --git a/docs/_old_mediawiki/bentobox_level-(task-type).mediawiki b/docs/_old_mediawiki/bentobox_level-(task-type).mediawiki new file mode 100644 index 00000000..ed906587 --- /dev/null +++ b/docs/_old_mediawiki/bentobox_level-(task-type).mediawiki @@ -0,0 +1,30 @@ +: ''Requires the BentoBox plugin to activate.'' + +Reach a certain BentoBox level. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>level</code> +| The level to reach. +| Integer +| Yes +| - +| - +|} + +== Examples == +Reach island level 10: + +```yaml +bentobox: + type: "bentobox_level" + level: 10 # island level needed +``` diff --git a/docs/_old_mediawiki/blockbreak-(task-type).mediawiki b/docs/_old_mediawiki/blockbreak-(task-type).mediawiki new file mode 100644 index 00000000..96bbcbf8 --- /dev/null +++ b/docs/_old_mediawiki/blockbreak-(task-type).mediawiki @@ -0,0 +1,105 @@ +Breaka set amount of blocks. + +Since Quests v3.13, <code>blockbreakcertain</code> and <code>blockbreak</code> have been merged into one. Both names can be used to refer to this task. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of blocks to break. +| Integer +| Yes +| - +| - +|- +| <code>block</code> +| The specific blocks to break. +| Material, or list of materials +| No +| - +| Not specifying this field will allow all blocks to count towards the task. Please see [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html this list] (1.13+) or [https://helpch.at/docs/1.12.2/org/bukkit/Material.html this list] (1.8-1.12) for block names. +|- +| <code>data</code> +| The data code for the block. +| Integer +| No +| 0 +| This field is not used in Minecraft versions 1.13+, nor is it compatible with lists of blocks. +|- +| <code>reverse-if-placed</code> +| Whether placing blocks should decrement from the quest progress. +| Boolean +| No +| false +| This allows negative quest progresses. +|- +| <code>check-coreprotect</code> +| Whether the plugin should query CoreProtect if a block has been recently placed. +| Boolean +| No +| false +| This requires the CoreProtect plugin. +|- +| <code>check-coreprotect-time</code> +| How long ago (in seconds) the plugin should check with CoreProtect whether a block was placed. +| Integer +| No +| - +| This requires the CoreProtect plugin. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Break 10 of any block: + +```yaml +mining: + type: "blockbreak" + amount: 10 # amount of blocks to be broken + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Break 10 of stone: + +```yaml +miningstone: + type: "blockbreakcertain" + amount: 10 # amount of blocks to be brkoen + block: STONE # name of block (can be id or minecraft name) + data: 1 # (OPTIONAL) data code + reverse-if-placed: false # (OPTIONAL) if true, blocks of same type placed will reverse progression (prevents silk-touch exploit) + check-coreprotect: false # (OPTIONAL) if true and CoreProtect is present, the plugin will check its logs for player placed blocks + check-coreprotect-time: 3600 # (OPTIONAL) time in seconds for the maximum logging period to check + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Break 10 of either stone or gold ore: + +```yaml +miningmultiple: + type: "blockbreakcertain" + amount: 10 # amount of blocks to be placed + blocks: # name of blocks which will count towards progress + - STONE + - GOLD_ORE + reverse-if-broken: false # (OPTIONAL) if true, blocks of same type broken will reverse progression (prevents silk-touch exploit) + check-coreprotect: false # (OPTIONAL) if true and CoreProtect is present, the plugin will check its logs for player placed blocks + check-coreprotect-time: 3600 # (OPTIONAL) time in seconds for the maximum logging period to check + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/blockplace-(task-type).mediawiki b/docs/_old_mediawiki/blockplace-(task-type).mediawiki new file mode 100644 index 00000000..4f8d62e6 --- /dev/null +++ b/docs/_old_mediawiki/blockplace-(task-type).mediawiki @@ -0,0 +1,87 @@ +Place a set amount of blocks. + +Since Quests v3.13, <code>blockplacecertain</code> and <code>blockplace</code> have been merged into one. Both names can be used to refer to this task. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of blocks to place. +| Integer +| Yes +| - +| - +|- +| <code>block</code> +| The specific blocks to place. +| Material, or list of materials +| No +| - +| Not specifying this field will allow all blocks to count towards the task. Please see [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html this list] (1.13+) or [https://helpch.at/docs/1.12.2/org/bukkit/Material.html this list] (1.8-1.12) for block names. +|- +| <code>data</code> +| The data code for the block. +| Integer +| No +| 0 +| This field is not used in Minecraft versions 1.13+, nor is it compatible with lists of blocks. +|- +| <code>reverse-if-broken</code> +| Whether breaking blocks should decrement from the quest progress. +| Boolean +| No +| false +| This allows negative quest progresses. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Place 10 of any block: + +```yaml +building: + type: "blockplace" + amount: 10 # amount of blocks to be placed + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Place 10 of stone: + +```yaml +buildingstone: + type: "blockplace" + amount: 10 # amount of blocks to be placed + block: STONE # name of block (minecraft name) + data: 1 # (OPTIONAL) data code + reverse-if-broken: false # (OPTIONAL) if true, blocks of same type broken will reverse progression (prevents silk-touch exploit) + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Place 10 of either stone or gold ore: + +```yaml +buildingmultiple: + type: "blockplace" + amount: 10 # amount of blocks to be placed + blocks: # name of blocks which will count towards progress + - STONE + - GOLD_ORE + reverse-if-broken: false # (OPTIONAL) if true, blocks of same type broken will reverse progression (prevents silk-touch exploit) + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/breeding-(task-type).mediawiki b/docs/_old_mediawiki/breeding-(task-type).mediawiki new file mode 100644 index 00000000..09feff48 --- /dev/null +++ b/docs/_old_mediawiki/breeding-(task-type).mediawiki @@ -0,0 +1,37 @@ +Breed a certain amount of animals. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of animals to breed. +| Integer +| Yes +| - +| - +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Breed 5 animals: + +```yaml +breeding: + type: "breeding" + amount: 5 # amount of animals bred + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/brewing-(task-type).mediawiki b/docs/_old_mediawiki/brewing-(task-type).mediawiki new file mode 100644 index 00000000..85500ab2 --- /dev/null +++ b/docs/_old_mediawiki/brewing-(task-type).mediawiki @@ -0,0 +1,37 @@ +Brew a set amount of potions. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of potions to brew. +| Integer +| Yes +| - +| - +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Brew 8 potions: + +```yaml +brewing: + type: "brewing" + amount: 10 # amount of potions brewed + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/bucketempty-(task-type).mediawiki b/docs/_old_mediawiki/bucketempty-(task-type).mediawiki new file mode 100644 index 00000000..3cfd1d9a --- /dev/null +++ b/docs/_old_mediawiki/bucketempty-(task-type).mediawiki @@ -0,0 +1,45 @@ +Empty a bucket. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of buckets to empty. +| Integer +| Yes +| - +| - +|- +| <code>item</code> +| The specific bucket to empty. +| Material, or ItemStack +| Yes +| - +| Accepts standard [[defining items|item definition]]. Please see [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html this list] (1.13+) or [https://helpch.at/docs/1.12.2/org/bukkit/Material.html this list] (1.8-1.12) for material names. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Empty 8 lava buckets: + +```yaml +bucketempty : + type: "bucketempty" + bucket: LAVA_BUCKET # bucket to empty + amount: 8 # amount of times to empty + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/bucketfill-(task-type).mediawiki b/docs/_old_mediawiki/bucketfill-(task-type).mediawiki new file mode 100644 index 00000000..fc6480fc --- /dev/null +++ b/docs/_old_mediawiki/bucketfill-(task-type).mediawiki @@ -0,0 +1,45 @@ +Fill a bucket up. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of buckets to fill. +| Integer +| Yes +| - +| - +|- +| <code>item</code> +| The specific bucket to fill. +| Material, or ItemStack +| Yes +| - +| Accepts standard [[defining items|item definition]]. Please see [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html this list] (1.13+) or [https://helpch.at/docs/1.12.2/org/bukkit/Material.html this list] (1.8-1.12) for material names. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Fill 8 lava buckets: + +```yaml +bucketfill: + type: "bucketfill" + bucket: LAVA_BUCKET # bucket to fill + amount: 8 # amount of times to fill + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/citizens_deliver-(task-type).mediawiki b/docs/_old_mediawiki/citizens_deliver-(task-type).mediawiki new file mode 100644 index 00000000..218b148c --- /dev/null +++ b/docs/_old_mediawiki/citizens_deliver-(task-type).mediawiki @@ -0,0 +1,120 @@ +: ''This requires the Citizens plugin to activate.'' + +Deliver a set of items to a Citizens NPC. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of items to deliver. +| Integer +| Yes +| - +| - +|- +| <code>item</code> +| The specific item to deliver. +| Material, or ItemStack +| Yes +| - +| Accepts standard [[defining items|item definition]]. Please see [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html this list] (1.13+) or [https://helpch.at/docs/1.12.2/org/bukkit/Material.html this list] (1.8-1.12) for material names. +|- +| <code>data</code> +| The data code for the item. +| Integer +| No +| 0 +| This field is not used in Minecraft versions 1.13+, nor is it compatible with ItemStack definitions. +|- +| <code>remove-items-when-complete</code> +| Whether the items should be taken from the player when complete. +| Boolean +| No +| false +| If <code>allow-partial-completion</code> is true, then this will also be set to true. +|- +| <code>allow-partial-completion</code> +| Whether any number of items counts towards the task progress. +| Boolean +| No +| true +| Setting to true will force <code>remove-items-when-complete</code> to true as well. If a player obtains any matching item, it will be immediately taken away from them and added towards the quest progress. +|- +| <code>npc-name</code> +| The name of the NPC to deliver to. +| Boolean +| No +| - +| Mutually exclusive with <code>npc-id</code>. +|- +| <code>npc-id</code> +| The id of the NPC to deliver to. +| Boolean +| No +| - +| Mutually exclusive with <code>npc-name</code>. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Deliver 8 of <code>BEEF</code> to an NPC named Gerald: + +```yaml +citizensdeliver: + type: "citizens_deliver" + npc-name: "Gerald" # name of NPC + # OR npc-id: "npc1" ID of NPC (mutally exclusive with npc-name) + item: BEEF # name of item (can be id or minecraft name) + amount: 8 # amount of item needed + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + allow-partial-completion: false # (OPTIONAL) allow partial deliveries - default: false + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Deliver 8 of a specific item to an NPC named Gerald: + +```yaml +beef: + type: "citizens_deliver" + npc-name: "Gerald" # name of NPC + item: # SPECIFIC item with name and lore + name: "&cSpecial Beef" + type: "BEEF" + lore: + - "&7This is a special type of beef" + amount: 8 # amount of item needed + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + accept-partial-completion: false # (OPTIONAL) allow partial deliveries - default: false + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Deliver 8 of [[Defining-items#quest-item|quest item]] <code>special_beef</code> to an NPC named Gerald: + +```yaml +beef: + type: "citizens_deliver" + npc-name: "Gerald" # name of NPC + # OR npc-id: "npc1" ID of NPC (mutally exclusive with npc-name) + item: # USING quest-item + quest-item: "special_beef" + amount: 8 # amount of item needed + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + accept-partial-completion: false # (OPTIONAL) allow partial deliveries - default: false + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/citizens_interact-(task-type).mediawiki b/docs/_old_mediawiki/citizens_interact-(task-type).mediawiki new file mode 100644 index 00000000..f08ae3dc --- /dev/null +++ b/docs/_old_mediawiki/citizens_interact-(task-type).mediawiki @@ -0,0 +1,47 @@ +: ''This requires the Citizens plugin to activate.'' + +Interact with a Citizens NPC. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>npc-name</code> +| The name of the NPC to deliver to. +| Boolean +| No +| - +| Mutually exclusive with <code>npc-id</code>. +|- +| <code>npc-id</code> +| The id of the NPC to deliver to. +| Boolean +| No +| - +| Mutually exclusive with <code>npc-name</code>. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Interact with an NPC named Gerald: + +```yaml +citizensinteract: + type: "citizens_interact" + npc-name: "Gerald" # name of NPC + # OR npc-id: "npc1" ID of NPC (mutally exclusive with npc-name) + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +```
\ No newline at end of file diff --git a/docs/_old_mediawiki/command-(task-type).mediawiki b/docs/_old_mediawiki/command-(task-type).mediawiki new file mode 100644 index 00000000..7129a5cf --- /dev/null +++ b/docs/_old_mediawiki/command-(task-type).mediawiki @@ -0,0 +1,47 @@ +Execute a specific command. + +This task may not work for commands not properly registered with the server (e.g. commands made with plugins like DeluxeMenu). + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>command</code> +| The command to execute. +| String +| Yes +| - +| - +|- +| <code>ignore-case</code> +| Whether the casing of the command should be ignored. +| Boolean +| No +| false +| - +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Ask for help: + +```yaml +command: + type: "command" + command: "help" # command to execute + ignore-case: true # (OPTIONAL) ignore capitalisation - default: false + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/consume-(task-type).mediawiki b/docs/_old_mediawiki/consume-(task-type).mediawiki new file mode 100644 index 00000000..13fda12b --- /dev/null +++ b/docs/_old_mediawiki/consume-(task-type).mediawiki @@ -0,0 +1,81 @@ +Consume a specific item. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of items to consume. +| Integer +| Yes +| - +| - +|- +| <code>item</code> +| The specific item to obtain. +| Material, or ItemStack +| Yes +| - +| Accepts standard [[defining items|item definition]]. Please see [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html this list] (1.13+) or [https://helpch.at/docs/1.12.2/org/bukkit/Material.html this list] (1.8-1.12) for material names. +|- +| <code>data</code> +| The data code for the item. +| Integer +| No +| 0 +| This field is not used in Minecraft versions 1.13+, nor is it compatible with ItemStack definitions. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Consume 8 of <code>BEEF</code>: + +```yaml +beef: + type: "consume" + item: BEEF # name of item (can be id or minecraft name) + amount: 8 # amount of item consumed + data: 0 # (OPTIONAL) data code + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Consume 8 of a specific item: + +```yaml +beef: + type: "consume" + item: # SPECIFIC item with name and lore + name: "&cSpecial Beef" + type: "RAW_BEEF" + lore: + - "&7This is a special type of beef" + amount: 8 # amount of item consumed + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Consume 8 of [[Defining-items#quest-items|quest item]] <code>special_beef</code>: + +```yaml +beef: + type: "consume" + item: # USING quest-item + quest-item: "special_beef" + amount: 8 # amount of item needed + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/crafting-(task-type).mediawiki b/docs/_old_mediawiki/crafting-(task-type).mediawiki new file mode 100644 index 00000000..5e7980bf --- /dev/null +++ b/docs/_old_mediawiki/crafting-(task-type).mediawiki @@ -0,0 +1,80 @@ +Craft a set of items. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of items to craft. +| Integer +| Yes +| - +| - +|- +| <code>item</code> +| The specific item to craft. +| Material, or ItemStack +| Yes +| - +| Accepts standard [[defining items|item definition]]. Please see [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html this list] (1.13+) or [https://helpch.at/docs/1.12.2/org/bukkit/Material.html this list] (1.8-1.12) for material names. +|- +| <code>data</code> +| The data code for the item. +| Integer +| No +| 0 +| This field is not used in Minecraft versions 1.13+, nor is it compatible with ItemStack definitions. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Craft 5 of <code>COMPASS</code>: + +```yaml +compass: + type: "crafting" + item: COMPASS # name of item (can be id or minecraft name) + amount: 5 # amount of item needed + data: 0 # (OPTIONAL) data code + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Craft 5 of a specific item: + +```yaml +compass: + type: "crafting" + item: # SPECIFIC item with name and lore + name: "&cSuper Compass" + type: "COMPASS" + lore: + - "&7This is special compass with a fancy name" + amount: 5 # amount of item needed + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Craft 5 of [[Defining-items#quest-item|quest item]] <code>super_compass</code>: + +```yaml +compass: + type: "crafting" + item: # USING quest-item + quest-item: "super_compass" + amount: 5 # amount of item needed + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/dealdamage-(task-type).mediawiki b/docs/_old_mediawiki/dealdamage-(task-type).mediawiki new file mode 100644 index 00000000..5bb75960 --- /dev/null +++ b/docs/_old_mediawiki/dealdamage-(task-type).mediawiki @@ -0,0 +1,38 @@ +Deal a certain amount of damage. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The amount of damage needed. +| Integer +| Yes +| - +| Damage is measured in HP, 1 heart = 2 HP. A player has 20 HP by default, with no status effects applied. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Deal 100 HP of damage: + +```yaml +dealdamage: + type: "dealdamage" + amount: 100 # amount of damage inflicted (HP) + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + diff --git a/docs/_old_mediawiki/distancefrom-(task-type).mediawiki b/docs/_old_mediawiki/distancefrom-(task-type).mediawiki new file mode 100644 index 00000000..d3da61cb --- /dev/null +++ b/docs/_old_mediawiki/distancefrom-(task-type).mediawiki @@ -0,0 +1,60 @@ +Travel away from a set of co-ordinates. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>x</code> +| The x co-ordinate. +| Integer +| Yes +| - +| - +|- +| <code>y</code> +| The y co-ordinate. +| Integer +| Yes +| - +| - +|- +| <code>z</code> +| The z co-ordinate. +| Integer +| Yes +| - +| - +|- +| <code>world</code> +| The name of the world. +| String +| Yes +| - +| - +|- +| <code>distance</code> +| The distance away from the co-ordinates the player must travel. +| Integer +| Yes +| - +| - +|} + +== Examples == +Travel at least 10 blocks away from (0, 0, 0) in world: + +```yaml +distancefrom: + type: "distancefrom" + x: 0 # x position + y: 0 # y position + z: 0 # z position + world: world # name of world + distance: 10 # required distance from coordinates +``` diff --git a/docs/_old_mediawiki/enchanting-(task-type).mediawiki b/docs/_old_mediawiki/enchanting-(task-type).mediawiki new file mode 100644 index 00000000..5a4ffc24 --- /dev/null +++ b/docs/_old_mediawiki/enchanting-(task-type).mediawiki @@ -0,0 +1,81 @@ +Enchant an item. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of items to obtain. +| Integer +| Yes +| - +| - +|- +| <code>item</code> +| The specific item to encahnt. +| Material, or ItemStack +| No +| - +| Accepts standard [[defining items|item definition]]. Please see [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html this list] (1.13+) or [https://helpch.at/docs/1.12.2/org/bukkit/Material.html this list] (1.8-1.12) for material names. If no item is specified, then any item can be enchanted. +|- +| <code>enchantment</code> +| The specific enchantment(s) to apply. +| Enchantment, or list of enchantments +| No +| - +| If no enchantments are specified, then any enchantment can be applied. +|- +| <code>min-level</code> +| The minimum level of the enchantments. +| Integer +| No +| - +| If no minimum level is specified, then any enchantment of any level can be applied. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Enchant 10 items: + +```yaml +enchanting: + type: "enchanting" + amount: 10 # amount of items enchanted + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Enchant 10 items with Protection: + +```yaml +beef: + type: "enchanting" + amount: 10 # amount of items + enchantment: PROTECTION_ENVIRONMENTAL # (OPTIONAL) enchantment to apply + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Enchant 10 items with Protection IV: + +```yaml +beef: + type: "enchanting" + amount: 10 # amount of items + enchantment: PROTECTION_ENVIRONMENTAL # (OPTIONAL) enchantment to apply + min-level: 4 # (OPTIONAL) the minimum level of enchantment to apply + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/essentials_balance-(task-type).mediawiki b/docs/_old_mediawiki/essentials_balance-(task-type).mediawiki new file mode 100644 index 00000000..f2c4b9f6 --- /dev/null +++ b/docs/_old_mediawiki/essentials_balance-(task-type).mediawiki @@ -0,0 +1,30 @@ +: ''Requires the Essentials plugin to activate.'' + +Reach a certain balance. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The amount to reach. +| Integer +| Yes +| - +| - +|} + +== Examples == +Reach a balance of $1000: + +```yaml +essentialsbalance: + type: "essentials_balance" + amount: 1000 # amount of money to rach +``` diff --git a/docs/_old_mediawiki/essentials_moneyearn-(task-type).mediawiki b/docs/_old_mediawiki/essentials_moneyearn-(task-type).mediawiki new file mode 100644 index 00000000..6593dbea --- /dev/null +++ b/docs/_old_mediawiki/essentials_moneyearn-(task-type).mediawiki @@ -0,0 +1,30 @@ +: ''Requires the Essentials plugin to activate.'' + +Earn a certain amount of money after starting quest. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The amount to earn. +| Integer +| Yes +| - +| - +|} + +== Examples == +Earn $1000: + +```yaml +essentialsbalance: + type: "essentials_moneyearn" + amount: 1000 # amount of money to earn +``` diff --git a/docs/_old_mediawiki/expearn-(task-type).mediawiki b/docs/_old_mediawiki/expearn-(task-type).mediawiki new file mode 100644 index 00000000..eb3f22d7 --- /dev/null +++ b/docs/_old_mediawiki/expearn-(task-type).mediawiki @@ -0,0 +1,37 @@ +Earn a set amount of exp after starting the quest. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The amount of experience to earn. +| Integer +| Yes +| - +| - +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Earn 20 experience: + +```yaml +expearn: + type: "expearn" + amount: 20 # amount of experience earned + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/fabledskyblock_level-(task-type).mediawiki b/docs/_old_mediawiki/fabledskyblock_level-(task-type).mediawiki new file mode 100644 index 00000000..7b1f6ed0 --- /dev/null +++ b/docs/_old_mediawiki/fabledskyblock_level-(task-type).mediawiki @@ -0,0 +1,30 @@ +: ''Requires the FabledSkyblock plugin to activate.'' + +Reach a certain FabledSkyblock level. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>level</code> +| The level to reach. +| Integer +| Yes +| - +| - +|} + +== Examples == +Reach island level 10: + +```yaml +fabledskyblock: + type: "fabledskyblock_level" + level: 10 # island level needed +``` diff --git a/docs/_old_mediawiki/farming-(task-type).mediawiki b/docs/_old_mediawiki/farming-(task-type).mediawiki new file mode 100644 index 00000000..244cb9f9 --- /dev/null +++ b/docs/_old_mediawiki/farming-(task-type).mediawiki @@ -0,0 +1,79 @@ +: ''Requires Minecraft 1.13+. For previous versions, use [[blockbreak (task type)|blockbreak]].'' + +Farm a set amount of crops. + +Since Quests v3.13, <code>farmingcertain</code> and <code>farming</code> have been merged into one. Both names can be used to refer to this task. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of crops to farm. +| Integer +| Yes +| - +| - +|- +| <code>block</code> +| The specific crop(s) to farm. +| Material, or list of material +| No +| - +| Please see [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html this list] (1.13+) or [https://helpch.at/docs/1.12.2/org/bukkit/Material.html this list] (1.8-1.12) for material names. Note that some items are confusingly named, they may refer to the held item or block instead of the crop block. +|- +| <code>mode</code> +| The mode to harvest crops. +| String +| No +| - +| One of: <code>break</code>, <code>harvest</code>. A harvest is where a block drops an item (usually a crop) but does not change state. If this is not specified, both will be accepted. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Farm 10 crops: + +```yaml +farming: + type: "farming" + amount: 10 # amount of blocks to be broken + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Farm 10 wheat: + +```yaml +farming: + type: "farming" + amount: 10 # amount of blocks to be brkoen + block: WHEAT # name of block (can be id or minecraft name) + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Farm 10 wheat or beetroot: + +```yaml +farmingmultiple: + type: "farming" + amount: 10 # amount of blocks to be placed + blocks: # name of blocks which will count towards progress + - WHEAT + - BEETROOT + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/fishing-(task-type).mediawiki b/docs/_old_mediawiki/fishing-(task-type).mediawiki new file mode 100644 index 00000000..8f0c17a8 --- /dev/null +++ b/docs/_old_mediawiki/fishing-(task-type).mediawiki @@ -0,0 +1,69 @@ +Fish a set amount of items. + +Since Quests v3.13, <code>fishingcertain</code> and <code>fishing</code> have been merged into one. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of fish to catch. +| Integer +| Yes +| - +| - +|- +| <code>item</code> +| Specific item which should be used to kill mobs. +| ItemStack +| No +| - +| Accepts standard [[defining items|item definition]]. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Fish 10 of any item: + +```yaml +fishing: + type: "fishing" + amount: 10 # amount of fish caught + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Fish 10 pufferfish: + +```yaml +fishingcertain: + type: "fishingcertain" + item: PUFFERFISH # type of item caught + amount: 10 # amount of item caught + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Fish 10 of [[Defining-items#Quest-items|quest item]] <code>super_fish</code>: + +```yaml +fishingcertain: + type: "fishingcertain" + item: # type of item caught + quest-item: "super_fish" + amount: 10 # amount of item caught + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/inventory-(task-type).mediawiki b/docs/_old_mediawiki/inventory-(task-type).mediawiki new file mode 100644 index 00000000..d557d887 --- /dev/null +++ b/docs/_old_mediawiki/inventory-(task-type).mediawiki @@ -0,0 +1,102 @@ +Obtain a set of items. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of items to obtain. +| Integer +| Yes +| - +| - +|- +| <code>item</code> +| The specific item to obtain. +| Material, or ItemStack +| Yes +| - +| Accepts standard [[defining items|item definition]]. Please see [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html this list] (1.13+) or [https://helpch.at/docs/1.12.2/org/bukkit/Material.html this list] (1.8-1.12) for material names. +|- +| <code>data</code> +| The data code for the item. +| Integer +| No +| 0 +| This field is not used in Minecraft versions 1.13+, nor is it compatible with ItemStack definitions. +|- +| <code>remove-items-when-complete</code> +| Whether the items should be taken from the player when complete. +| Boolean +| No +| false +| If <code>allow-partial-completion</code> is true, then this will also be set to true. +|- +| <code>allow-partial-completion</code> +| Whether any number of items counts towards the task progress. +| Boolean +| No +| true +| Setting to true will force <code>remove-items-when-complete</code> to true as well. If a player obtains any matching item, it will be immediately taken away from them and added towards the quest progress. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Obtain 8 of <code>BEEF</code>: + +```yaml +beef: + type: "inventory" + item: BEEF # name of item (can be id or minecraft name) + amount: 8 # amount of item needed + data: 0 # (OPTIONAL) data code + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + allow-partial-completion: false # (OPTIONAL) allow partial deliveries - default: true + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Obtain 8 of a specific item: + +```yaml +beef: + type: "inventory" + item: # SPECIFIC item with name and lore + name: "&cSpecial Beef" + type: "RAW_BEEF" + lore: + - "&7This is a special type of beef" + amount: 8 # amount of item needed + data: 0 # (OPTIONAL) data code + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + allow-partial-completion: false # (OPTIONAL) allow partial deliveries - default: true + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Obtain 8 of [[Defining-items#quest-item|quest item]] <code>special_beef</code>: + +```yaml +beef: + type: "inventory" + item: # USING quest-item + quest-item: "specialbeef" + amount: 8 # amount of item needed + data: 0 # (OPTIONAL) data code + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + allow-partial-completion: false # (OPTIONAL) allow partial deliveries - default: true + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/iridiumskyblock_value-(task-type).mediawiki b/docs/_old_mediawiki/iridiumskyblock_value-(task-type).mediawiki new file mode 100644 index 00000000..939732d1 --- /dev/null +++ b/docs/_old_mediawiki/iridiumskyblock_value-(task-type).mediawiki @@ -0,0 +1,30 @@ +: ''Requires the IridiumSkyblock plugin to activate.'' + +Reach a certain IridiumSkyblock value. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>value</code> +| The valueto reach. +| Integer +| Yes +| - +| - +|} + +== Examples == +Reach island value 10: + +```yaml +iridiumskyblock: + type: "iridiumskyblock_value" + value: 10 # island level needed +``` diff --git a/docs/_old_mediawiki/milking-(task-type).mediawiki b/docs/_old_mediawiki/milking-(task-type).mediawiki new file mode 100644 index 00000000..a42b5c4c --- /dev/null +++ b/docs/_old_mediawiki/milking-(task-type).mediawiki @@ -0,0 +1,37 @@ +Milk a set amount of cows. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of cows to milk. +| Integer +| Yes +| - +| - +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Milk 10 cows: + +```yaml +milking: + type: "milking" + amount: 10 # amount of cows milked + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/mobkilling-(task-type).mediawiki b/docs/_old_mediawiki/mobkilling-(task-type).mediawiki new file mode 100644 index 00000000..2497eb90 --- /dev/null +++ b/docs/_old_mediawiki/mobkilling-(task-type).mediawiki @@ -0,0 +1,128 @@ +Kill a set amount of mobs. + +Since Quests v3.13, <code>mobkillingcertain</code> and <code>mobkilling</code> have been merged into one. Both names can be used to refer to this task. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of mobs to kill. +| Integer +| Yes +| - +| - +|- +| <code>mob</code> +| The specific mob(s) to kill. +| Entity type, or list of entities +| No +| - +| Not specifying this field will allow all mob types to count towards the task. Please see [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/entity/EntityType.html this list] for entity types. +|- +| <code>name</code> +| The specific name(s) of mobs to kill. +| String, or list of strings +| No +| - +| Not specifying this field will allow mobs with any names to count towards the task. Ensure any colour codes in the name of the entity are specified, otherwise the match will not work. +|- +| <code>hostile</code> +| Whether the mob must be hostile. +| Boolean +| No +| - +| If specified and set to false, only non-hostile mobs will count. +|- +| <code>item</code> +| Specific item which should be used to kill mobs. +| ItemStack +| No +| - +| Accepts standard [[defining items|item definition]]. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Kill 10 of any mob: + +```yaml +mobkilling: + type: "mobkilling" + amount: 10 # amount of mobs to be killed + hostile: true # (OPTIONAL) whether or not the mob is hostile - default: both + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Kill 10 of a blaze named (red) "Inferno": + +```yaml +mobkillingblaze: + type: "mobkilling" + amount: 10 # amount of mobs to be killed + mob: BLAZE # (OPTIONAL) type of mob + name: &cInferno # (OPTIONAL) this only allows blazes called "&cInferno" - default: any name + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Kill 10 of a blade named either (red) "Inferno" or (orange) "Furnace": + +```yaml +mobkillingblazemultiple: + type: "mobkilling" + amount: 10 # amount of mobs to be killed + mob: BLAZE # (OPTIONAL) type of mob + names: # (OPTIONAL) this only allows blazes called "&cInferno" OR "&6Furnace" - default: any name + - "&cInferno" + - "&6Furnace" + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Kill 10 of a blaze or creeper named either (red) "Inferno" or (orange) "Furnace": + +```yaml +mobkillingblazemultiple: + type: "mobkilling" + amount: 10 # amount of mobs to be killed + mob: # (OPTIONAL) types of mobs + - BLAZE + - CREEPER + names: # (OPTIONAL) this only allows blazes called "&cInferno" OR "&6Furnace" - default: any name + - "&cInferno" + - "&6Furnace" + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Kill 10 of a blaze or creeper named either (red) "Inferno" or (orange) "Furnace" with [[Defining-items#Quest-items|quest item]] "super_sword": + +```yaml +mobkillingblazecreepermultiple: + type: "mobkilling" + amount: 10 # amount of mobs to be killed + mob: # (OPTIONAL) types of mobs + - BLAZE + - CREEPER + names: # (OPTIONAL) this only allows blazes called "&cInferno" OR "&6Furnace" - default: any name + - "&cInferno" + - "&6Furnace" + item: # (OPTIONAL) specific item to kill with + quest-item: "super_sword" + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +```
\ No newline at end of file diff --git a/docs/_old_mediawiki/mythicmobs_killing-(task-type).mediawiki b/docs/_old_mediawiki/mythicmobs_killing-(task-type).mediawiki new file mode 100644 index 00000000..bc8bf81e --- /dev/null +++ b/docs/_old_mediawiki/mythicmobs_killing-(task-type).mediawiki @@ -0,0 +1,63 @@ +: ''Requires the MythicMobs plugin to activate.'' + +Kill a certain MythicMobs mob. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of mobs to kill. +| Integer +| Yes +| - +| - +|- +| <code>name</code> +| The MythicMob ID. +| String +| Yes +| - +| - +|- +| <code>level</code> +| The level the mob must be at. +| Integer +| Yes +| - +| - +|- +| <code>min-level</code> +| The minimum level the mob must be at. +| Integer +| Yes +| - +| - +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Kill 1 mythic mob with the ID "SkeletalKnight": + +```yaml +mythicmobs: + type: "mythicmobs_killing" + amount: 1 # amount of mobs to be killed + name: "SkeletalKnight" # internal name of mob (name in config - NOT display name) + level: 1 # (OPTIONAL) the exact level the mob must be for it to count + min-level: 1 # (OPTIONAL) the minimum level the mob must be for it to count + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/permission-(task-type).mediawiki b/docs/_old_mediawiki/permission-(task-type).mediawiki new file mode 100644 index 00000000..2a77ff04 --- /dev/null +++ b/docs/_old_mediawiki/permission-(task-type).mediawiki @@ -0,0 +1,28 @@ +Test if a player has a permission. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>permission</code> +| The permission the player should have. +| String +| Yes +| - +| - +|} + +== Examples == +Check if player has permission <code>some.permission.name</code>: + +```yaml +permission: + type: "permission" + permission: "some.permission.name" # permission required to be marked as complete +``` diff --git a/docs/_old_mediawiki/placeholderapi_evaluate-(task-type).mediawiki b/docs/_old_mediawiki/placeholderapi_evaluate-(task-type).mediawiki new file mode 100644 index 00000000..09c441c4 --- /dev/null +++ b/docs/_old_mediawiki/placeholderapi_evaluate-(task-type).mediawiki @@ -0,0 +1,67 @@ +: ''Requires the PlaceholderAPI plugin to activate.'' + +Reach a certain PlaceholderAPI level. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>placeholder</code> +| The placeholder to evaluate. +| String +| Yes +| - +| - +|- +| <code>evaluates</code> +| The string the placeholder should evaluate to. +| String +| Yes +| - +| - +|- +| <code>operator</code> +| The comparative operator to use for numeric placeholders. +| String +| No +| - +| One of: <code>GREATER_THAN</code>, <code>LESS_THAN</code>, <code>GREATER_THAN_OR_EQUAL_TO</code>, <code>LESS_THAN_OR_EQUAL_TO</code>. The value in <code>evaluates</code> '''must''' be numeric. If this is not specified, then exact equality will be assumed. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Have a player name of "fatpigsarefat": + +```yaml +papieval: + type: "placeholderapi_evaluate" + placeholder: "%player_name%" # placeholder string + evaluates: "fatpigsarefat" # what it should evaluate as to be marked as complete + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Be online when there are more than 20 empty slots on the server: + +```yaml +papieval: + type: "placeholderapi_evaluate" + placeholder: "%player_empty_slots%" # placeholder string + evaluates: "20" # number to compare to + operator: "GREATER_THAN" # (OPTIONAL) numerical operator, "evaluates" MUST be an integer + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + diff --git a/docs/_old_mediawiki/playerkilling-(task-type).mediawiki b/docs/_old_mediawiki/playerkilling-(task-type).mediawiki new file mode 100644 index 00000000..088f944f --- /dev/null +++ b/docs/_old_mediawiki/playerkilling-(task-type).mediawiki @@ -0,0 +1,37 @@ +Kill a set amount of players. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of players to kill. +| Integer +| Yes +| - +| - +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Kill 10 of any player: + +```yaml +killplayers: + type: "playerkilling" + amount: 10 # amount of players to kill + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/playtime-(task-type).mediawiki b/docs/_old_mediawiki/playtime-(task-type).mediawiki new file mode 100644 index 00000000..471d6ec9 --- /dev/null +++ b/docs/_old_mediawiki/playtime-(task-type).mediawiki @@ -0,0 +1,36 @@ +Play for a certain amount of time after starting the quest. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>minutes</code> +| The number of minutes to play. +| Integer +| Yes +| - +| - +|- +| <code>ignore-afk</code> +| Whether AFK players should be ignored. +| Boolean +| Yes +| - +| Requires Essentials. +|} + +== Examples == +Play for 20 minutes: + +```yaml +playtime: + type: "playtime" + minutes: 10 # amount of minutes played + ignore-afk: false # (OPTIONAL) ignore players marked as AFK by essentials +``` diff --git a/docs/_old_mediawiki/position-(task-type).mediawiki b/docs/_old_mediawiki/position-(task-type).mediawiki new file mode 100644 index 00000000..307ee53d --- /dev/null +++ b/docs/_old_mediawiki/position-(task-type).mediawiki @@ -0,0 +1,60 @@ +Reach a set of co-ordinates. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>x</code> +| The x co-ordinate. +| Integer +| Yes +| - +| - +|- +| <code>y</code> +| The y co-ordinate. +| Integer +| Yes +| - +| - +|- +| <code>z</code> +| The z co-ordinate. +| Integer +| Yes +| - +| - +|- +| <code>world</code> +| The name of the world. +| String +| Yes +| - +| - +|- +| <code>distance-padding</code> +| The distance around the co-ordinate the player can reach. +| Integer +| No +| - +| Having no padding means the player must reach the exact co-ordinate. +|} + +== Examples == +Travel to within 10 blocks of (0, 0, 0) in world: + +```yaml +position: + type: "position" + x: 0 # x position + y: 0 # y position + z: 0 # z position + world: world # name of world + distance-padding: 10 # (OPTIONAL) padding zone in meters/blocks - this will allow within 10 blocks of 0, 0, 0 - default = 0 +``` diff --git a/docs/_old_mediawiki/shearing-(task-type).mediawiki b/docs/_old_mediawiki/shearing-(task-type).mediawiki new file mode 100644 index 00000000..6445c025 --- /dev/null +++ b/docs/_old_mediawiki/shearing-(task-type).mediawiki @@ -0,0 +1,37 @@ +Shear a set amount of sheep. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of sheep to shear. +| Integer +| Yes +| - +| - +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Shear 10 sheep: + +```yaml +shearing: + type: "shearing" + amount: 10 # amount of sheep sheared + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/shopguiplus_buy-(task-type).mediawiki b/docs/_old_mediawiki/shopguiplus_buy-(task-type).mediawiki new file mode 100644 index 00000000..b7c18257 --- /dev/null +++ b/docs/_old_mediawiki/shopguiplus_buy-(task-type).mediawiki @@ -0,0 +1,49 @@ +: ''Requires the ShopGUI+ plugin to activate.'' + +Buy a certain number of items from a ShopGUI+ shop. + +Since Quests v3.13, <code>shopguiplus_buycertain</code> and <code>shopguiplus_buy</code> have been merged into one. Both names can be used to refer to this task. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of items to buy. +| Integer +| Yes +| - +| - +|- +| <code>shop-id</code> +| The ID of the shop. +| String +| Yes +| - +| - +|- +| <code>item-id</code> +| The ID of the item to buy. +| String +| Yes +| - +| - +|} + +== Examples == +Buy 1000 of item_id from shop_id: + +```yaml +shopguiplusbuy: + type: "shopguiplus_buy" + shop-id: "shop_id" # shopgui+ id of the shop that contains the item. + item-id: "item_id" # shopgui+ id of item to sell + amount: 1000 # amount of thing to sell +``` + diff --git a/docs/_old_mediawiki/shopguiplus_sell-(task-type).mediawiki b/docs/_old_mediawiki/shopguiplus_sell-(task-type).mediawiki new file mode 100644 index 00000000..279743d9 --- /dev/null +++ b/docs/_old_mediawiki/shopguiplus_sell-(task-type).mediawiki @@ -0,0 +1,49 @@ +: ''Requires the ShopGUI+ plugin to activate.'' + +Sell a certain number of items to a ShopGUI+ shop. + +Since Quests v3.13, <code>shopguiplus_sellcertain</code> and <code>shopguiplus_sell</code> have been merged into one. Both names can be used to refer to this task. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of items to sell. +| Integer +| Yes +| - +| - +|- +| <code>shop-id</code> +| The ID of the shop. +| String +| Yes +| - +| - +|- +| <code>item-id</code> +| The ID of the item to sell. +| String +| Yes +| - +| - +|} + +== Examples == +Sell 1000 of item_id to shop_id: + +```yaml +shopguiplussell: + type: "shopguiplus_sell" + shop-id: "shop_id" # shopgui+ id of the shop that contains the item. + item-id: "item_id" # shopgui+ id of item to sell + amount: 1000 # amount of thing to sell +``` + diff --git a/docs/_old_mediawiki/smelting-(task-type).mediawiki b/docs/_old_mediawiki/smelting-(task-type).mediawiki new file mode 100644 index 00000000..9404af91 --- /dev/null +++ b/docs/_old_mediawiki/smelting-(task-type).mediawiki @@ -0,0 +1,91 @@ +Cook a set amount of an item. + +Since Quests v3.13, <code>smeltingcertain</code> and <code>smelting</code> have been merged into one. Both names can be used to refer to this task. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of items to smelt. +| Integer +| Yes +| - +| - +|- +| <code>item</code> +| The specific item to smelt. +| Material, or ItemStack +| No +| - +| Accepts standard [[defining items|item definition]]. Please see [https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html this list] (1.13+) or [https://helpch.at/docs/1.12.2/org/bukkit/Material.html this list] (1.8-1.12) for material names. If this is not specified, any item will count. +|- +| <code>mode</code> +| The specific mode of smelting. +| String +| No +| - +| One of: <code>smoker</code>, <code>blast_furnace</code>, <code>furnace</code>. If this is not specified, any furnace will count. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Smelt 10 items: + +```yaml +smelting: + type: "smelting" + amount: 10 # amount to smelt + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Cook 10 steak: + +```yaml +smeltingcertain: + type: "smeltingcertain" + amount: 10 # amount to smelt + item: STEAK # type of item + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Cook 10 of a specific item: + +```yaml +smeltingcertain: + type: "smeltingcertain" + amount: 10 # amount to smelt + item: # SPECIFIC item with name and lore + name: "&cSpecial Beef" + type: "RAW_BEEF" + lore: + - "&7This is a special type of beef" + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Cook 10 of [[Defining-items#quest-item|quest item]] <code>special_beef</code>: + +```yaml +smeltingcertain: + type: "smeltingcertain" + amount: 10 # amount to smelt + item: # type of item + quest-item: "special_beef" + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/superiorskyblock_level-(task-type).mediawiki b/docs/_old_mediawiki/superiorskyblock_level-(task-type).mediawiki new file mode 100644 index 00000000..3aa1ace0 --- /dev/null +++ b/docs/_old_mediawiki/superiorskyblock_level-(task-type).mediawiki @@ -0,0 +1,30 @@ +: ''Requires the SuperiorSkyblock plugin to activate.'' + +Reach a certain SuperiorSkyblock level. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>level</code> +| The level to reach. +| Integer +| Yes +| - +| - +|} + +== Examples == +Reach island level 10: + +```yaml +superiorskyblock: + type: "superiorskyblock_level" + level: 10 # island level needed +``` diff --git a/docs/_old_mediawiki/superiorskyblock_worth-(task-type).mediawiki b/docs/_old_mediawiki/superiorskyblock_worth-(task-type).mediawiki new file mode 100644 index 00000000..d995e7c2 --- /dev/null +++ b/docs/_old_mediawiki/superiorskyblock_worth-(task-type).mediawiki @@ -0,0 +1,30 @@ +: ''Requires the SuperiorSkyblock plugin to activate.'' + +Reach a certain SuperiorSkyblock worth. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>worth</code> +| The worth to worth. +| Integer +| Yes +| - +| - +|} + +== Examples == +Reach island worth 100: + +```yaml +superiorskyblock: + type: "superiorskyblock_worth" + level: 100 # island worth needed +``` diff --git a/docs/_old_mediawiki/taming-(task-type).mediawiki b/docs/_old_mediawiki/taming-(task-type).mediawiki new file mode 100644 index 00000000..8faab460 --- /dev/null +++ b/docs/_old_mediawiki/taming-(task-type).mediawiki @@ -0,0 +1,37 @@ +Tame a set amount of animals. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of animals to tame. +| Integer +| Yes +| - +| - +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Tame 10 animals: + +```yaml +taming: + type: "taming" + amount: 10 # amount of mobs tamed + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/_old_mediawiki/uskyblock_level-(task-type).mediawiki b/docs/_old_mediawiki/uskyblock_level-(task-type).mediawiki new file mode 100644 index 00000000..8eb53d7d --- /dev/null +++ b/docs/_old_mediawiki/uskyblock_level-(task-type).mediawiki @@ -0,0 +1,30 @@ +: ''Requires the uSkyBlock plugin to activate.'' + +Reach a certain uSkyBlock level. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>level</code> +| The level to reach. +| Integer +| Yes +| - +| - +|} + +== Examples == +Reach island level 10: + +```yaml +askyblock: + type: "uskyblock_level" + level: 10 # island level needed +``` diff --git a/docs/_old_mediawiki/votingplugin_vote-(task-type).mediawiki b/docs/_old_mediawiki/votingplugin_vote-(task-type).mediawiki new file mode 100644 index 00000000..71adb9c3 --- /dev/null +++ b/docs/_old_mediawiki/votingplugin_vote-(task-type).mediawiki @@ -0,0 +1,30 @@ +: ''Requires the VotingPlugin plugin to activate.'' + +Vote a number of times using VotingPlugin. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>amount</code> +| The number of votes. +| Integer +| Yes +| - +| - +|} + +== Examples == +Vote 10 times: + +```yaml +votingplugin: + type: "votingplugin_vote" + amount: 10 # number of times to vote +``` diff --git a/docs/_old_mediawiki/walking-(task-type).mediawiki b/docs/_old_mediawiki/walking-(task-type).mediawiki new file mode 100644 index 00000000..6cc4c33e --- /dev/null +++ b/docs/_old_mediawiki/walking-(task-type).mediawiki @@ -0,0 +1,57 @@ +Walk a set distance. + +== Options == +{| +|- +! Key +! Description +! Type +! Required +! Default +! Notes +|- +| <code>distance</code> +| The distance in metres to walk. +| Integer +| Yes +| - +| 1 metre is equivalent to 1 block. +|- +| <code>mode</code> +| The specific mode to travel +| String +| No +| - +| One of: <code>boat</code>, <code>horse</code>, <code>pig</code>, <code>minecart</code> <code>strider</code>, <code>sneaking</code>, <code>walking</code>, <code>running</code>, <code>swimming</code>, <code>flying</code>, <code>elytra</code>. Not specifying a mode will allow any of these modes to count. +|- +| <code>worlds</code> +| Worlds which should count towards the progress. +| List of world names +| No +| - +| - +|} + +== Examples == +Travel 1000 metres: + +```yaml +walking: + type: "walking" + distance: 1000 # distance in blocks travelled + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Travel 1000 metres by sprinting only: + +```yaml +walking: + type: "walking" + distance: 1000 # distance in blocks travelled + mode: running # (OPTIONAL) specific mode of transport + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + + diff --git a/docs/_scripts/convert-mediawiki-to-markdown.sh b/docs/_scripts/convert-mediawiki-to-markdown.sh new file mode 100755 index 00000000..25f9afd4 --- /dev/null +++ b/docs/_scripts/convert-mediawiki-to-markdown.sh @@ -0,0 +1,10 @@ +#!/bin/bash + +# This script converts mediawiki formatted files in the current +# working directory to markdown using pandoc. + +for FILE in *.mediawiki; do + echo "Processing $FILE" + FILENAME=$(basename $FILE .mediawiki) + sed ':a; N; $!ba; s/```yaml\([^`]*\)```/<syntaxhighlight lang="yaml">\1<\/syntaxhighlight>/g; s/```\([^`]*\)```/<syntaxhighlight>\1<\/syntaxhighlight>/g' $FILE | pandoc -f mediawiki -t gfm -o "$FILENAME.md" +done diff --git a/docs/task-type/askyblock_level-(task-type).md b/docs/task-type/askyblock_level-(task-type).md new file mode 100644 index 00000000..11a46bf0 --- /dev/null +++ b/docs/task-type/askyblock_level-(task-type).md @@ -0,0 +1,20 @@ + +*Requires the ASkyBlock plugin to activate.* + +Reach a certain ASkyBlock level. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|---------|---------------------|---------|----------|---------|-------| +| `level` | The level to reach. | Integer | Yes | \- | \- | + +## Examples + +Reach island level 10: + +``` yaml +askyblock: + type: "askyblock_level" + level: 10 # island level needed +``` diff --git a/docs/task-type/bentobox_level-(task-type).md b/docs/task-type/bentobox_level-(task-type).md new file mode 100644 index 00000000..1abc4302 --- /dev/null +++ b/docs/task-type/bentobox_level-(task-type).md @@ -0,0 +1,20 @@ + +*Requires the BentoBox plugin to activate.* + +Reach a certain BentoBox level. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|---------|---------------------|---------|----------|---------|-------| +| `level` | The level to reach. | Integer | Yes | \- | \- | + +## Examples + +Reach island level 10: + +``` yaml +bentobox: + type: "bentobox_level" + level: 10 # island level needed +``` diff --git a/docs/task-type/blockbreak-(task-type).md b/docs/task-type/blockbreak-(task-type).md new file mode 100644 index 00000000..a719bcb1 --- /dev/null +++ b/docs/task-type/blockbreak-(task-type).md @@ -0,0 +1,59 @@ +Breaka set amount of blocks. + +Since Quests v3.13, `blockbreakcertain` and `blockbreak` have been +merged into one. Both names can be used to refer to this task. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|--------------------------|------------------------------------------------------------------------------------------------|--------------------------------|----------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `amount` | The number of blocks to break. | Integer | Yes | \- | \- | +| `block` | The specific blocks to break. | Material, or list of materials | No | \- | Not specifying this field will allow all blocks to count towards the task. Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) (1.13+) or [this list](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) (1.8-1.12) for block names. | +| `data` | The data code for the block. | Integer | No | 0 | This field is not used in Minecraft versions 1.13+, nor is it compatible with lists of blocks. | +| `reverse-if-placed` | Whether placing blocks should decrement from the quest progress. | Boolean | No | false | This allows negative quest progresses. | +| `check-coreprotect` | Whether the plugin should query CoreProtect if a block has been recently placed. | Boolean | No | false | This requires the CoreProtect plugin. | +| `check-coreprotect-time` | How long ago (in seconds) the plugin should check with CoreProtect whether a block was placed. | Integer | No | \- | This requires the CoreProtect plugin. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Break 10 of any block: + +``` yaml +mining: + type: "blockbreak" + amount: 10 # amount of blocks to be broken + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Break 10 of stone: + +``` yaml +miningstone: + type: "blockbreakcertain" + amount: 10 # amount of blocks to be brkoen + block: STONE # name of block (can be id or minecraft name) + data: 1 # (OPTIONAL) data code + reverse-if-placed: false # (OPTIONAL) if true, blocks of same type placed will reverse progression (prevents silk-touch exploit) + check-coreprotect: false # (OPTIONAL) if true and CoreProtect is present, the plugin will check its logs for player placed blocks + check-coreprotect-time: 3600 # (OPTIONAL) time in seconds for the maximum logging period to check + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Break 10 of either stone or gold ore: + +``` yaml +miningmultiple: + type: "blockbreakcertain" + amount: 10 # amount of blocks to be placed + blocks: # name of blocks which will count towards progress + - STONE + - GOLD_ORE + reverse-if-broken: false # (OPTIONAL) if true, blocks of same type broken will reverse progression (prevents silk-touch exploit) + check-coreprotect: false # (OPTIONAL) if true and CoreProtect is present, the plugin will check its logs for player placed blocks + check-coreprotect-time: 3600 # (OPTIONAL) time in seconds for the maximum logging period to check + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/blockplace-(task-type).md b/docs/task-type/blockplace-(task-type).md new file mode 100644 index 00000000..d5892423 --- /dev/null +++ b/docs/task-type/blockplace-(task-type).md @@ -0,0 +1,53 @@ +Place a set amount of blocks. + +Since Quests v3.13, `blockplacecertain` and `blockplace` have been +merged into one. Both names can be used to refer to this task. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|---------------------|-------------------------------------------------------------------|--------------------------------|----------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `amount` | The number of blocks to place. | Integer | Yes | \- | \- | +| `block` | The specific blocks to place. | Material, or list of materials | No | \- | Not specifying this field will allow all blocks to count towards the task. Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) (1.13+) or [this list](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) (1.8-1.12) for block names. | +| `data` | The data code for the block. | Integer | No | 0 | This field is not used in Minecraft versions 1.13+, nor is it compatible with lists of blocks. | +| `reverse-if-broken` | Whether breaking blocks should decrement from the quest progress. | Boolean | No | false | This allows negative quest progresses. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Place 10 of any block: + +``` yaml +building: + type: "blockplace" + amount: 10 # amount of blocks to be placed + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Place 10 of stone: + +``` yaml +buildingstone: + type: "blockplace" + amount: 10 # amount of blocks to be placed + block: STONE # name of block (minecraft name) + data: 1 # (OPTIONAL) data code + reverse-if-broken: false # (OPTIONAL) if true, blocks of same type broken will reverse progression (prevents silk-touch exploit) + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Place 10 of either stone or gold ore: + +``` yaml +buildingmultiple: + type: "blockplace" + amount: 10 # amount of blocks to be placed + blocks: # name of blocks which will count towards progress + - STONE + - GOLD_ORE + reverse-if-broken: false # (OPTIONAL) if true, blocks of same type broken will reverse progression (prevents silk-touch exploit) + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/breeding-(task-type).md b/docs/task-type/breeding-(task-type).md new file mode 100644 index 00000000..58797cb4 --- /dev/null +++ b/docs/task-type/breeding-(task-type).md @@ -0,0 +1,20 @@ +Breed a certain amount of animals. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|---------------------|----------|---------|-------| +| `amount` | The number of animals to breed. | Integer | Yes | \- | \- | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Breed 5 animals: + +``` yaml +breeding: + type: "breeding" + amount: 5 # amount of animals bred + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/brewing-(task-type).md b/docs/task-type/brewing-(task-type).md new file mode 100644 index 00000000..d7fc9f28 --- /dev/null +++ b/docs/task-type/brewing-(task-type).md @@ -0,0 +1,20 @@ +Brew a set amount of potions. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|---------------------|----------|---------|-------| +| `amount` | The number of potions to brew. | Integer | Yes | \- | \- | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Brew 8 potions: + +``` yaml +brewing: + type: "brewing" + amount: 10 # amount of potions brewed + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/bucketempty-(task-type).md b/docs/task-type/bucketempty-(task-type).md new file mode 100644 index 00000000..cbce8af8 --- /dev/null +++ b/docs/task-type/bucketempty-(task-type).md @@ -0,0 +1,22 @@ +Empty a bucket. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|------------------------|----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `amount` | The number of buckets to empty. | Integer | Yes | \- | \- | +| `item` | The specific bucket to empty. | Material, or ItemStack | Yes | \- | Accepts standard [item definition](defining_items "wikilink"). Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) (1.13+) or [this list](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) (1.8-1.12) for material names. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Empty 8 lava buckets: + +``` yaml +bucketempty : + type: "bucketempty" + bucket: LAVA_BUCKET # bucket to empty + amount: 8 # amount of times to empty + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/bucketfill-(task-type).md b/docs/task-type/bucketfill-(task-type).md new file mode 100644 index 00000000..d9969808 --- /dev/null +++ b/docs/task-type/bucketfill-(task-type).md @@ -0,0 +1,22 @@ +Fill a bucket up. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|------------------------|----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `amount` | The number of buckets to fill. | Integer | Yes | \- | \- | +| `item` | The specific bucket to fill. | Material, or ItemStack | Yes | \- | Accepts standard [item definition](defining_items "wikilink"). Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) (1.13+) or [this list](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) (1.8-1.12) for material names. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Fill 8 lava buckets: + +``` yaml +bucketfill: + type: "bucketfill" + bucket: LAVA_BUCKET # bucket to fill + amount: 8 # amount of times to fill + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/citizens_deliver-(task-type).md b/docs/task-type/citizens_deliver-(task-type).md new file mode 100644 index 00000000..3be9cdaa --- /dev/null +++ b/docs/task-type/citizens_deliver-(task-type).md @@ -0,0 +1,69 @@ + +*This requires the Citizens plugin to activate.* + +Deliver a set of items to a Citizens NPC. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|------------------------------|------------------------------------------------------------------|------------------------|----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `amount` | The number of items to deliver. | Integer | Yes | \- | \- | +| `item` | The specific item to deliver. | Material, or ItemStack | Yes | \- | Accepts standard [item definition](defining_items "wikilink"). Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) (1.13+) or [this list](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) (1.8-1.12) for material names. | +| `data` | The data code for the item. | Integer | No | 0 | This field is not used in Minecraft versions 1.13+, nor is it compatible with ItemStack definitions. | +| `remove-items-when-complete` | Whether the items should be taken from the player when complete. | Boolean | No | false | If `allow-partial-completion` is true, then this will also be set to true. | +| `allow-partial-completion` | Whether any number of items counts towards the task progress. | Boolean | No | true | Setting to true will force `remove-items-when-complete` to true as well. If a player obtains any matching item, it will be immediately taken away from them and added towards the quest progress. | +| `npc-name` | The name of the NPC to deliver to. | Boolean | No | \- | Mutually exclusive with `npc-id`. | +| `npc-id` | The id of the NPC to deliver to. | Boolean | No | \- | Mutually exclusive with `npc-name`. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Deliver 8 of `BEEF` to an NPC named Gerald: + +``` yaml +citizensdeliver: + type: "citizens_deliver" + npc-name: "Gerald" # name of NPC + # OR npc-id: "npc1" ID of NPC (mutally exclusive with npc-name) + item: BEEF # name of item (can be id or minecraft name) + amount: 8 # amount of item needed + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + allow-partial-completion: false # (OPTIONAL) allow partial deliveries - default: false + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Deliver 8 of a specific item to an NPC named Gerald: + +``` yaml +beef: + type: "citizens_deliver" + npc-name: "Gerald" # name of NPC + item: # SPECIFIC item with name and lore + name: "&cSpecial Beef" + type: "BEEF" + lore: + - "&7This is a special type of beef" + amount: 8 # amount of item needed + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + accept-partial-completion: false # (OPTIONAL) allow partial deliveries - default: false + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Deliver 8 of [quest item](Defining-items#quest-item "wikilink") +`special_beef` to an NPC named Gerald: + +``` yaml +beef: + type: "citizens_deliver" + npc-name: "Gerald" # name of NPC + # OR npc-id: "npc1" ID of NPC (mutally exclusive with npc-name) + item: # USING quest-item + quest-item: "special_beef" + amount: 8 # amount of item needed + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + accept-partial-completion: false # (OPTIONAL) allow partial deliveries - default: false + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/citizens_interact-(task-type).md b/docs/task-type/citizens_interact-(task-type).md new file mode 100644 index 00000000..eb744f27 --- /dev/null +++ b/docs/task-type/citizens_interact-(task-type).md @@ -0,0 +1,25 @@ + +*This requires the Citizens plugin to activate.* + +Interact with a Citizens NPC. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|------------|-------------------------------------------------|---------------------|----------|---------|-------------------------------------| +| `npc-name` | The name of the NPC to deliver to. | Boolean | No | \- | Mutually exclusive with `npc-id`. | +| `npc-id` | The id of the NPC to deliver to. | Boolean | No | \- | Mutually exclusive with `npc-name`. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Interact with an NPC named Gerald: + +``` yaml +citizensinteract: + type: "citizens_interact" + npc-name: "Gerald" # name of NPC + # OR npc-id: "npc1" ID of NPC (mutally exclusive with npc-name) + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/command-(task-type).md b/docs/task-type/command-(task-type).md new file mode 100644 index 00000000..a5a42960 --- /dev/null +++ b/docs/task-type/command-(task-type).md @@ -0,0 +1,25 @@ +Execute a specific command. + +This task may not work for commands not properly registered with the +server (e.g. commands made with plugins like DeluxeMenu). + +## Options + +| Key | Description | Type | Required | Default | Notes | +|---------------|------------------------------------------------------|---------------------|----------|---------|-------| +| `command` | The command to execute. | String | Yes | \- | \- | +| `ignore-case` | Whether the casing of the command should be ignored. | Boolean | No | false | \- | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Ask for help: + +``` yaml +command: + type: "command" + command: "help" # command to execute + ignore-case: true # (OPTIONAL) ignore capitalisation - default: false + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/consume-(task-type).md b/docs/task-type/consume-(task-type).md new file mode 100644 index 00000000..b0d3acd4 --- /dev/null +++ b/docs/task-type/consume-(task-type).md @@ -0,0 +1,53 @@ +Consume a specific item. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|------------------------|----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `amount` | The number of items to consume. | Integer | Yes | \- | \- | +| `item` | The specific item to obtain. | Material, or ItemStack | Yes | \- | Accepts standard [item definition](defining_items "wikilink"). Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) (1.13+) or [this list](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) (1.8-1.12) for material names. | +| `data` | The data code for the item. | Integer | No | 0 | This field is not used in Minecraft versions 1.13+, nor is it compatible with ItemStack definitions. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Consume 8 of `BEEF`: + +``` yaml +beef: + type: "consume" + item: BEEF # name of item (can be id or minecraft name) + amount: 8 # amount of item consumed + data: 0 # (OPTIONAL) data code + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Consume 8 of a specific item: + +``` yaml +beef: + type: "consume" + item: # SPECIFIC item with name and lore + name: "&cSpecial Beef" + type: "RAW_BEEF" + lore: + - "&7This is a special type of beef" + amount: 8 # amount of item consumed + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Consume 8 of [quest item](Defining-items#quest-items "wikilink") +`special_beef`: + +``` yaml +beef: + type: "consume" + item: # USING quest-item + quest-item: "special_beef" + amount: 8 # amount of item needed + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/crafting-(task-type).md b/docs/task-type/crafting-(task-type).md new file mode 100644 index 00000000..de9147b0 --- /dev/null +++ b/docs/task-type/crafting-(task-type).md @@ -0,0 +1,52 @@ +Craft a set of items. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|------------------------|----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `amount` | The number of items to craft. | Integer | Yes | \- | \- | +| `item` | The specific item to craft. | Material, or ItemStack | Yes | \- | Accepts standard [item definition](defining_items "wikilink"). Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) (1.13+) or [this list](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) (1.8-1.12) for material names. | +| `data` | The data code for the item. | Integer | No | 0 | This field is not used in Minecraft versions 1.13+, nor is it compatible with ItemStack definitions. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Craft 5 of `COMPASS`: + +``` yaml +compass: + type: "crafting" + item: COMPASS # name of item (can be id or minecraft name) + amount: 5 # amount of item needed + data: 0 # (OPTIONAL) data code + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Craft 5 of a specific item: + +``` yaml +compass: + type: "crafting" + item: # SPECIFIC item with name and lore + name: "&cSuper Compass" + type: "COMPASS" + lore: + - "&7This is special compass with a fancy name" + amount: 5 # amount of item needed + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Craft 5 of [quest item](Defining-items#quest-item "wikilink") +`super_compass`: + +``` yaml +compass: + type: "crafting" + item: # USING quest-item + quest-item: "super_compass" + amount: 5 # amount of item needed + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/dealdamage-(task-type).md b/docs/task-type/dealdamage-(task-type).md new file mode 100644 index 00000000..2683e647 --- /dev/null +++ b/docs/task-type/dealdamage-(task-type).md @@ -0,0 +1,20 @@ +Deal a certain amount of damage. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|---------------------|----------|---------|----------------------------------------------------------------------------------------------------------| +| `amount` | The amount of damage needed. | Integer | Yes | \- | Damage is measured in HP, 1 heart = 2 HP. A player has 20 HP by default, with no status effects applied. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Deal 100 HP of damage: + +``` yaml +dealdamage: + type: "dealdamage" + amount: 100 # amount of damage inflicted (HP) + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/distancefrom-(task-type).md b/docs/task-type/distancefrom-(task-type).md new file mode 100644 index 00000000..3fa7fdae --- /dev/null +++ b/docs/task-type/distancefrom-(task-type).md @@ -0,0 +1,25 @@ +Travel away from a set of co-ordinates. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|------------|-----------------------------------------------------------------|---------|----------|---------|-------| +| `x` | The x co-ordinate. | Integer | Yes | \- | \- | +| `y` | The y co-ordinate. | Integer | Yes | \- | \- | +| `z` | The z co-ordinate. | Integer | Yes | \- | \- | +| `world` | The name of the world. | String | Yes | \- | \- | +| `distance` | The distance away from the co-ordinates the player must travel. | Integer | Yes | \- | \- | + +## Examples + +Travel at least 10 blocks away from (0, 0, 0) in world: + +``` yaml +distancefrom: + type: "distancefrom" + x: 0 # x position + y: 0 # y position + z: 0 # z position + world: world # name of world + distance: 10 # required distance from coordinates +``` diff --git a/docs/task-type/enchanting-(task-type).md b/docs/task-type/enchanting-(task-type).md new file mode 100644 index 00000000..c22907b7 --- /dev/null +++ b/docs/task-type/enchanting-(task-type).md @@ -0,0 +1,46 @@ +Enchant an item. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|---------------|-------------------------------------------------|--------------------------------------|----------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `amount` | The number of items to obtain. | Integer | Yes | \- | \- | +| `item` | The specific item to encahnt. | Material, or ItemStack | No | \- | Accepts standard [item definition](defining_items "wikilink"). Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) (1.13+) or [this list](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) (1.8-1.12) for material names. If no item is specified, then any item can be enchanted. | +| `enchantment` | The specific enchantment(s) to apply. | Enchantment, or list of enchantments | No | \- | If no enchantments are specified, then any enchantment can be applied. | +| `min-level` | The minimum level of the enchantments. | Integer | No | \- | If no minimum level is specified, then any enchantment of any level can be applied. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Enchant 10 items: + +``` yaml +enchanting: + type: "enchanting" + amount: 10 # amount of items enchanted + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Enchant 10 items with Protection: + +``` yaml +beef: + type: "enchanting" + amount: 10 # amount of items + enchantment: PROTECTION_ENVIRONMENTAL # (OPTIONAL) enchantment to apply + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Enchant 10 items with Protection IV: + +``` yaml +beef: + type: "enchanting" + amount: 10 # amount of items + enchantment: PROTECTION_ENVIRONMENTAL # (OPTIONAL) enchantment to apply + min-level: 4 # (OPTIONAL) the minimum level of enchantment to apply + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/essentials_balance-(task-type).md b/docs/task-type/essentials_balance-(task-type).md new file mode 100644 index 00000000..ab600bc1 --- /dev/null +++ b/docs/task-type/essentials_balance-(task-type).md @@ -0,0 +1,20 @@ + +*Requires the Essentials plugin to activate.* + +Reach a certain balance. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|----------------------|---------|----------|---------|-------| +| `amount` | The amount to reach. | Integer | Yes | \- | \- | + +## Examples + +Reach a balance of \$1000: + +``` yaml +essentialsbalance: + type: "essentials_balance" + amount: 1000 # amount of money to rach +``` diff --git a/docs/task-type/essentials_moneyearn-(task-type).md b/docs/task-type/essentials_moneyearn-(task-type).md new file mode 100644 index 00000000..bf5c8efd --- /dev/null +++ b/docs/task-type/essentials_moneyearn-(task-type).md @@ -0,0 +1,20 @@ + +*Requires the Essentials plugin to activate.* + +Earn a certain amount of money after starting quest. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|---------------------|---------|----------|---------|-------| +| `amount` | The amount to earn. | Integer | Yes | \- | \- | + +## Examples + +Earn \$1000: + +``` yaml +essentialsbalance: + type: "essentials_moneyearn" + amount: 1000 # amount of money to earn +``` diff --git a/docs/task-type/expearn-(task-type).md b/docs/task-type/expearn-(task-type).md new file mode 100644 index 00000000..f4de7c5b --- /dev/null +++ b/docs/task-type/expearn-(task-type).md @@ -0,0 +1,20 @@ +Earn a set amount of exp after starting the quest. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|---------------------|----------|---------|-------| +| `amount` | The amount of experience to earn. | Integer | Yes | \- | \- | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Earn 20 experience: + +``` yaml +expearn: + type: "expearn" + amount: 20 # amount of experience earned + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/fabledskyblock_level-(task-type).md b/docs/task-type/fabledskyblock_level-(task-type).md new file mode 100644 index 00000000..ec689b56 --- /dev/null +++ b/docs/task-type/fabledskyblock_level-(task-type).md @@ -0,0 +1,20 @@ + +*Requires the FabledSkyblock plugin to activate.* + +Reach a certain FabledSkyblock level. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|---------|---------------------|---------|----------|---------|-------| +| `level` | The level to reach. | Integer | Yes | \- | \- | + +## Examples + +Reach island level 10: + +``` yaml +fabledskyblock: + type: "fabledskyblock_level" + level: 10 # island level needed +``` diff --git a/docs/task-type/farming-(task-type).md b/docs/task-type/farming-(task-type).md new file mode 100644 index 00000000..de5c5d6a --- /dev/null +++ b/docs/task-type/farming-(task-type).md @@ -0,0 +1,53 @@ + +*Requires Minecraft 1.13+. For previous versions, use +[blockbreak](blockbreak_(task_type) "wikilink").* + +Farm a set amount of crops. + +Since Quests v3.13, `farmingcertain` and `farming` have been merged into +one. Both names can be used to refer to this task. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|-------------------------------|----------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `amount` | The number of crops to farm. | Integer | Yes | \- | \- | +| `block` | The specific crop(s) to farm. | Material, or list of material | No | \- | Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) (1.13+) or [this list](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) (1.8-1.12) for material names. Note that some items are confusingly named, they may refer to the held item or block instead of the crop block. | +| `mode` | The mode to harvest crops. | String | No | \- | One of: `break`, `harvest`. A harvest is where a block drops an item (usually a crop) but does not change state. If this is not specified, both will be accepted. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Farm 10 crops: + +``` yaml +farming: + type: "farming" + amount: 10 # amount of blocks to be broken + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Farm 10 wheat: + +``` yaml +farming: + type: "farming" + amount: 10 # amount of blocks to be brkoen + block: WHEAT # name of block (can be id or minecraft name) + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Farm 10 wheat or beetroot: + +``` yaml +farmingmultiple: + type: "farming" + amount: 10 # amount of blocks to be placed + blocks: # name of blocks which will count towards progress + - WHEAT + - BEETROOT + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/fishing-(task-type).md b/docs/task-type/fishing-(task-type).md new file mode 100644 index 00000000..fa63358f --- /dev/null +++ b/docs/task-type/fishing-(task-type).md @@ -0,0 +1,48 @@ +Fish a set amount of items. + +Since Quests v3.13, `fishingcertain` and `fishing` have been merged into +one. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|--------------------------------------------------|---------------------|----------|---------|----------------------------------------------------------------| +| `amount` | The number of fish to catch. | Integer | Yes | \- | \- | +| `item` | Specific item which should be used to kill mobs. | ItemStack | No | \- | Accepts standard [item definition](defining_items "wikilink"). | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Fish 10 of any item: + +``` yaml +fishing: + type: "fishing" + amount: 10 # amount of fish caught + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Fish 10 pufferfish: + +``` yaml +fishingcertain: + type: "fishingcertain" + item: PUFFERFISH # type of item caught + amount: 10 # amount of item caught + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Fish 10 of [quest item](Defining-items#Quest-items "wikilink") +`super_fish`: + +``` yaml +fishingcertain: + type: "fishingcertain" + item: # type of item caught + quest-item: "super_fish" + amount: 10 # amount of item caught + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/inventory-(task-type).md b/docs/task-type/inventory-(task-type).md new file mode 100644 index 00000000..e5e22b15 --- /dev/null +++ b/docs/task-type/inventory-(task-type).md @@ -0,0 +1,62 @@ +Obtain a set of items. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|------------------------------|------------------------------------------------------------------|------------------------|----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `amount` | The number of items to obtain. | Integer | Yes | \- | \- | +| `item` | The specific item to obtain. | Material, or ItemStack | Yes | \- | Accepts standard [item definition](defining_items "wikilink"). Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) (1.13+) or [this list](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) (1.8-1.12) for material names. | +| `data` | The data code for the item. | Integer | No | 0 | This field is not used in Minecraft versions 1.13+, nor is it compatible with ItemStack definitions. | +| `remove-items-when-complete` | Whether the items should be taken from the player when complete. | Boolean | No | false | If `allow-partial-completion` is true, then this will also be set to true. | +| `allow-partial-completion` | Whether any number of items counts towards the task progress. | Boolean | No | true | Setting to true will force `remove-items-when-complete` to true as well. If a player obtains any matching item, it will be immediately taken away from them and added towards the quest progress. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Obtain 8 of `BEEF`: + +``` yaml +beef: + type: "inventory" + item: BEEF # name of item (can be id or minecraft name) + amount: 8 # amount of item needed + data: 0 # (OPTIONAL) data code + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + allow-partial-completion: false # (OPTIONAL) allow partial deliveries - default: true + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Obtain 8 of a specific item: + +``` yaml +beef: + type: "inventory" + item: # SPECIFIC item with name and lore + name: "&cSpecial Beef" + type: "RAW_BEEF" + lore: + - "&7This is a special type of beef" + amount: 8 # amount of item needed + data: 0 # (OPTIONAL) data code + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + allow-partial-completion: false # (OPTIONAL) allow partial deliveries - default: true + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Obtain 8 of [quest item](Defining-items#quest-item "wikilink") +`special_beef`: + +``` yaml +beef: + type: "inventory" + item: # USING quest-item + quest-item: "specialbeef" + amount: 8 # amount of item needed + data: 0 # (OPTIONAL) data code + remove-items-when-complete: false # (OPTIONAL) take the items away from the player on completion - default: false + allow-partial-completion: false # (OPTIONAL) allow partial deliveries - default: true + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/iridiumskyblock_value-(task-type).md b/docs/task-type/iridiumskyblock_value-(task-type).md new file mode 100644 index 00000000..c465c049 --- /dev/null +++ b/docs/task-type/iridiumskyblock_value-(task-type).md @@ -0,0 +1,20 @@ + +*Requires the IridiumSkyblock plugin to activate.* + +Reach a certain IridiumSkyblock value. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|---------|--------------------|---------|----------|---------|-------| +| `value` | The valueto reach. | Integer | Yes | \- | \- | + +## Examples + +Reach island value 10: + +``` yaml +iridiumskyblock: + type: "iridiumskyblock_value" + value: 10 # island level needed +``` diff --git a/docs/task-type/milking-(task-type).md b/docs/task-type/milking-(task-type).md new file mode 100644 index 00000000..dcf296b2 --- /dev/null +++ b/docs/task-type/milking-(task-type).md @@ -0,0 +1,20 @@ +Milk a set amount of cows. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|---------------------|----------|---------|-------| +| `amount` | The number of cows to milk. | Integer | Yes | \- | \- | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Milk 10 cows: + +``` yaml +milking: + type: "milking" + amount: 10 # amount of cows milked + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/mobkilling-(task-type).md b/docs/task-type/mobkilling-(task-type).md new file mode 100644 index 00000000..6b7565d7 --- /dev/null +++ b/docs/task-type/mobkilling-(task-type).md @@ -0,0 +1,91 @@ +Kill a set amount of mobs. + +Since Quests v3.13, `mobkillingcertain` and `mobkilling` have been +merged into one. Both names can be used to refer to this task. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|-----------|--------------------------------------------------|----------------------------------|----------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `amount` | The number of mobs to kill. | Integer | Yes | \- | \- | +| `mob` | The specific mob(s) to kill. | Entity type, or list of entities | No | \- | Not specifying this field will allow all mob types to count towards the task. Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/entity/EntityType.html) for entity types. | +| `name` | The specific name(s) of mobs to kill. | String, or list of strings | No | \- | Not specifying this field will allow mobs with any names to count towards the task. Ensure any colour codes in the name of the entity are specified, otherwise the match will not work. | +| `hostile` | Whether the mob must be hostile. | Boolean | No | \- | If specified and set to false, only non-hostile mobs will count. | +| `item` | Specific item which should be used to kill mobs. | ItemStack | No | \- | Accepts standard [item definition](defining_items "wikilink"). | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Kill 10 of any mob: + +``` yaml +mobkilling: + type: "mobkilling" + amount: 10 # amount of mobs to be killed + hostile: true # (OPTIONAL) whether or not the mob is hostile - default: both + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Kill 10 of a blaze named (red) "Inferno": + +``` yaml +mobkillingblaze: + type: "mobkilling" + amount: 10 # amount of mobs to be killed + mob: BLAZE # (OPTIONAL) type of mob + name: &cInferno # (OPTIONAL) this only allows blazes called "&cInferno" - default: any name + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Kill 10 of a blade named either (red) "Inferno" or (orange) "Furnace": + +``` yaml +mobkillingblazemultiple: + type: "mobkilling" + amount: 10 # amount of mobs to be killed + mob: BLAZE # (OPTIONAL) type of mob + names: # (OPTIONAL) this only allows blazes called "&cInferno" OR "&6Furnace" - default: any name + - "&cInferno" + - "&6Furnace" + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Kill 10 of a blaze or creeper named either (red) "Inferno" or (orange) +"Furnace": + +``` yaml +mobkillingblazemultiple: + type: "mobkilling" + amount: 10 # amount of mobs to be killed + mob: # (OPTIONAL) types of mobs + - BLAZE + - CREEPER + names: # (OPTIONAL) this only allows blazes called "&cInferno" OR "&6Furnace" - default: any name + - "&cInferno" + - "&6Furnace" + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Kill 10 of a blaze or creeper named either (red) "Inferno" or (orange) +"Furnace" with [quest item](Defining-items#Quest-items "wikilink") +"super_sword": + +``` yaml +mobkillingblazecreepermultiple: + type: "mobkilling" + amount: 10 # amount of mobs to be killed + mob: # (OPTIONAL) types of mobs + - BLAZE + - CREEPER + names: # (OPTIONAL) this only allows blazes called "&cInferno" OR "&6Furnace" - default: any name + - "&cInferno" + - "&6Furnace" + item: # (OPTIONAL) specific item to kill with + quest-item: "super_sword" + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/mythicmobs_killing-(task-type).md b/docs/task-type/mythicmobs_killing-(task-type).md new file mode 100644 index 00000000..14f1a0ee --- /dev/null +++ b/docs/task-type/mythicmobs_killing-(task-type).md @@ -0,0 +1,29 @@ + +*Requires the MythicMobs plugin to activate.* + +Kill a certain MythicMobs mob. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|-------------|-------------------------------------------------|---------------------|----------|---------|-------| +| `amount` | The number of mobs to kill. | Integer | Yes | \- | \- | +| `name` | The MythicMob ID. | String | Yes | \- | \- | +| `level` | The level the mob must be at. | Integer | Yes | \- | \- | +| `min-level` | The minimum level the mob must be at. | Integer | Yes | \- | \- | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Kill 1 mythic mob with the ID "SkeletalKnight": + +``` yaml +mythicmobs: + type: "mythicmobs_killing" + amount: 1 # amount of mobs to be killed + name: "SkeletalKnight" # internal name of mob (name in config - NOT display name) + level: 1 # (OPTIONAL) the exact level the mob must be for it to count + min-level: 1 # (OPTIONAL) the minimum level the mob must be for it to count + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/permission-(task-type).md b/docs/task-type/permission-(task-type).md new file mode 100644 index 00000000..631a462e --- /dev/null +++ b/docs/task-type/permission-(task-type).md @@ -0,0 +1,17 @@ +Test if a player has a permission. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|--------------|----------------------------------------|--------|----------|---------|-------| +| `permission` | The permission the player should have. | String | Yes | \- | \- | + +## Examples + +Check if player has permission `some.permission.name`: + +``` yaml +permission: + type: "permission" + permission: "some.permission.name" # permission required to be marked as complete +``` diff --git a/docs/task-type/placeholderapi_evaluate-(task-type).md b/docs/task-type/placeholderapi_evaluate-(task-type).md new file mode 100644 index 00000000..ae678193 --- /dev/null +++ b/docs/task-type/placeholderapi_evaluate-(task-type).md @@ -0,0 +1,38 @@ + +*Requires the PlaceholderAPI plugin to activate.* + +Reach a certain PlaceholderAPI level. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|---------------|-----------------------------------------------------------|---------------------|----------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `placeholder` | The placeholder to evaluate. | String | Yes | \- | \- | +| `evaluates` | The string the placeholder should evaluate to. | String | Yes | \- | \- | +| `operator` | The comparative operator to use for numeric placeholders. | String | No | \- | One of: `GREATER_THAN`, `LESS_THAN`, `GREATER_THAN_OR_EQUAL_TO`, `LESS_THAN_OR_EQUAL_TO`. The value in `evaluates` **must** be numeric. If this is not specified, then exact equality will be assumed. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Have a player name of "fatpigsarefat": + +``` yaml +papieval: + type: "placeholderapi_evaluate" + placeholder: "%player_name%" # placeholder string + evaluates: "fatpigsarefat" # what it should evaluate as to be marked as complete + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Be online when there are more than 20 empty slots on the server: + +``` yaml +papieval: + type: "placeholderapi_evaluate" + placeholder: "%player_empty_slots%" # placeholder string + evaluates: "20" # number to compare to + operator: "GREATER_THAN" # (OPTIONAL) numerical operator, "evaluates" MUST be an integer + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/playerkilling-(task-type).md b/docs/task-type/playerkilling-(task-type).md new file mode 100644 index 00000000..62cc2343 --- /dev/null +++ b/docs/task-type/playerkilling-(task-type).md @@ -0,0 +1,20 @@ +Kill a set amount of players. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|---------------------|----------|---------|-------| +| `amount` | The number of players to kill. | Integer | Yes | \- | \- | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Kill 10 of any player: + +``` yaml +killplayers: + type: "playerkilling" + amount: 10 # amount of players to kill + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/playtime-(task-type).md b/docs/task-type/playtime-(task-type).md new file mode 100644 index 00000000..f3b827df --- /dev/null +++ b/docs/task-type/playtime-(task-type).md @@ -0,0 +1,19 @@ +Play for a certain amount of time after starting the quest. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|--------------|----------------------------------------|---------|----------|---------|----------------------| +| `minutes` | The number of minutes to play. | Integer | Yes | \- | \- | +| `ignore-afk` | Whether AFK players should be ignored. | Boolean | Yes | \- | Requires Essentials. | + +## Examples + +Play for 20 minutes: + +``` yaml +playtime: + type: "playtime" + minutes: 10 # amount of minutes played + ignore-afk: false # (OPTIONAL) ignore players marked as AFK by essentials +``` diff --git a/docs/task-type/position-(task-type).md b/docs/task-type/position-(task-type).md new file mode 100644 index 00000000..dfa85e9a --- /dev/null +++ b/docs/task-type/position-(task-type).md @@ -0,0 +1,25 @@ +Reach a set of co-ordinates. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|--------------------|-----------------------------------------------------------|---------|----------|---------|----------------------------------------------------------------------| +| `x` | The x co-ordinate. | Integer | Yes | \- | \- | +| `y` | The y co-ordinate. | Integer | Yes | \- | \- | +| `z` | The z co-ordinate. | Integer | Yes | \- | \- | +| `world` | The name of the world. | String | Yes | \- | \- | +| `distance-padding` | The distance around the co-ordinate the player can reach. | Integer | No | \- | Having no padding means the player must reach the exact co-ordinate. | + +## Examples + +Travel to within 10 blocks of (0, 0, 0) in world: + +``` yaml +position: + type: "position" + x: 0 # x position + y: 0 # y position + z: 0 # z position + world: world # name of world + distance-padding: 10 # (OPTIONAL) padding zone in meters/blocks - this will allow within 10 blocks of 0, 0, 0 - default = 0 +``` diff --git a/docs/task-type/shearing-(task-type).md b/docs/task-type/shearing-(task-type).md new file mode 100644 index 00000000..4d65861d --- /dev/null +++ b/docs/task-type/shearing-(task-type).md @@ -0,0 +1,20 @@ +Shear a set amount of sheep. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|---------------------|----------|---------|-------| +| `amount` | The number of sheep to shear. | Integer | Yes | \- | \- | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Shear 10 sheep: + +``` yaml +shearing: + type: "shearing" + amount: 10 # amount of sheep sheared + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/shopguiplus_buy-(task-type).md b/docs/task-type/shopguiplus_buy-(task-type).md new file mode 100644 index 00000000..888a1384 --- /dev/null +++ b/docs/task-type/shopguiplus_buy-(task-type).md @@ -0,0 +1,27 @@ + +*Requires the ShopGUI+ plugin to activate.* + +Buy a certain number of items from a ShopGUI+ shop. + +Since Quests v3.13, `shopguiplus_buycertain` and `shopguiplus_buy` have +been merged into one. Both names can be used to refer to this task. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|-----------|-----------------------------|---------|----------|---------|-------| +| `amount` | The number of items to buy. | Integer | Yes | \- | \- | +| `shop-id` | The ID of the shop. | String | Yes | \- | \- | +| `item-id` | The ID of the item to buy. | String | Yes | \- | \- | + +## Examples + +Buy 1000 of item_id from shop_id: + +``` yaml +shopguiplusbuy: + type: "shopguiplus_buy" + shop-id: "shop_id" # shopgui+ id of the shop that contains the item. + item-id: "item_id" # shopgui+ id of item to sell + amount: 1000 # amount of thing to sell +``` diff --git a/docs/task-type/shopguiplus_sell-(task-type).md b/docs/task-type/shopguiplus_sell-(task-type).md new file mode 100644 index 00000000..144e2a42 --- /dev/null +++ b/docs/task-type/shopguiplus_sell-(task-type).md @@ -0,0 +1,27 @@ + +*Requires the ShopGUI+ plugin to activate.* + +Sell a certain number of items to a ShopGUI+ shop. + +Since Quests v3.13, `shopguiplus_sellcertain` and `shopguiplus_sell` +have been merged into one. Both names can be used to refer to this task. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|-----------|------------------------------|---------|----------|---------|-------| +| `amount` | The number of items to sell. | Integer | Yes | \- | \- | +| `shop-id` | The ID of the shop. | String | Yes | \- | \- | +| `item-id` | The ID of the item to sell. | String | Yes | \- | \- | + +## Examples + +Sell 1000 of item_id to shop_id: + +``` yaml +shopguiplussell: + type: "shopguiplus_sell" + shop-id: "shop_id" # shopgui+ id of the shop that contains the item. + item-id: "item_id" # shopgui+ id of item to sell + amount: 1000 # amount of thing to sell +``` diff --git a/docs/task-type/smelting-(task-type).md b/docs/task-type/smelting-(task-type).md new file mode 100644 index 00000000..edfd41d9 --- /dev/null +++ b/docs/task-type/smelting-(task-type).md @@ -0,0 +1,64 @@ +Cook a set amount of an item. + +Since Quests v3.13, `smeltingcertain` and `smelting` have been merged +into one. Both names can be used to refer to this task. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|------------------------|----------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `amount` | The number of items to smelt. | Integer | Yes | \- | \- | +| `item` | The specific item to smelt. | Material, or ItemStack | No | \- | Accepts standard [item definition](defining_items "wikilink"). Please see [this list](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) (1.13+) or [this list](https://helpch.at/docs/1.12.2/org/bukkit/Material.html) (1.8-1.12) for material names. If this is not specified, any item will count. | +| `mode` | The specific mode of smelting. | String | No | \- | One of: `smoker`, `blast_furnace`, `furnace`. If this is not specified, any furnace will count. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Smelt 10 items: + +``` yaml +smelting: + type: "smelting" + amount: 10 # amount to smelt + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Cook 10 steak: + +``` yaml +smeltingcertain: + type: "smeltingcertain" + amount: 10 # amount to smelt + item: STEAK # type of item + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Cook 10 of a specific item: + +``` yaml +smeltingcertain: + type: "smeltingcertain" + amount: 10 # amount to smelt + item: # SPECIFIC item with name and lore + name: "&cSpecial Beef" + type: "RAW_BEEF" + lore: + - "&7This is a special type of beef" + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Cook 10 of [quest item](Defining-items#quest-item "wikilink") +`special_beef`: + +``` yaml +smeltingcertain: + type: "smeltingcertain" + amount: 10 # amount to smelt + item: # type of item + quest-item: "special_beef" + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/superiorskyblock_level-(task-type).md b/docs/task-type/superiorskyblock_level-(task-type).md new file mode 100644 index 00000000..6289fc83 --- /dev/null +++ b/docs/task-type/superiorskyblock_level-(task-type).md @@ -0,0 +1,20 @@ + +*Requires the SuperiorSkyblock plugin to activate.* + +Reach a certain SuperiorSkyblock level. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|---------|---------------------|---------|----------|---------|-------| +| `level` | The level to reach. | Integer | Yes | \- | \- | + +## Examples + +Reach island level 10: + +``` yaml +superiorskyblock: + type: "superiorskyblock_level" + level: 10 # island level needed +``` diff --git a/docs/task-type/superiorskyblock_worth-(task-type).md b/docs/task-type/superiorskyblock_worth-(task-type).md new file mode 100644 index 00000000..51572258 --- /dev/null +++ b/docs/task-type/superiorskyblock_worth-(task-type).md @@ -0,0 +1,20 @@ + +*Requires the SuperiorSkyblock plugin to activate.* + +Reach a certain SuperiorSkyblock worth. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|---------|---------------------|---------|----------|---------|-------| +| `worth` | The worth to worth. | Integer | Yes | \- | \- | + +## Examples + +Reach island worth 100: + +``` yaml +superiorskyblock: + type: "superiorskyblock_worth" + level: 100 # island worth needed +``` diff --git a/docs/task-type/taming-(task-type).md b/docs/task-type/taming-(task-type).md new file mode 100644 index 00000000..775ff567 --- /dev/null +++ b/docs/task-type/taming-(task-type).md @@ -0,0 +1,20 @@ +Tame a set amount of animals. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|-------------------------------------------------|---------------------|----------|---------|-------| +| `amount` | The number of animals to tame. | Integer | Yes | \- | \- | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Tame 10 animals: + +``` yaml +taming: + type: "taming" + amount: 10 # amount of mobs tamed + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` diff --git a/docs/task-type/uskyblock_level-(task-type).md b/docs/task-type/uskyblock_level-(task-type).md new file mode 100644 index 00000000..2ae22ca4 --- /dev/null +++ b/docs/task-type/uskyblock_level-(task-type).md @@ -0,0 +1,20 @@ + +*Requires the uSkyBlock plugin to activate.* + +Reach a certain uSkyBlock level. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|---------|---------------------|---------|----------|---------|-------| +| `level` | The level to reach. | Integer | Yes | \- | \- | + +## Examples + +Reach island level 10: + +``` yaml +askyblock: + type: "uskyblock_level" + level: 10 # island level needed +``` diff --git a/docs/task-type/votingplugin_vote-(task-type).md b/docs/task-type/votingplugin_vote-(task-type).md new file mode 100644 index 00000000..fec37347 --- /dev/null +++ b/docs/task-type/votingplugin_vote-(task-type).md @@ -0,0 +1,20 @@ + +*Requires the VotingPlugin plugin to activate.* + +Vote a number of times using VotingPlugin. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|----------|----------------------|---------|----------|---------|-------| +| `amount` | The number of votes. | Integer | Yes | \- | \- | + +## Examples + +Vote 10 times: + +``` yaml +votingplugin: + type: "votingplugin_vote" + amount: 10 # number of times to vote +``` diff --git a/docs/task-type/walking-(task-type).md b/docs/task-type/walking-(task-type).md new file mode 100644 index 00000000..c2bc492e --- /dev/null +++ b/docs/task-type/walking-(task-type).md @@ -0,0 +1,32 @@ +Walk a set distance. + +## Options + +| Key | Description | Type | Required | Default | Notes | +|------------|-------------------------------------------------|---------------------|----------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `distance` | The distance in metres to walk. | Integer | Yes | \- | 1 metre is equivalent to 1 block. | +| `mode` | The specific mode to travel | String | No | \- | One of: `boat`, `horse`, `pig`, `minecart` `strider`, `sneaking`, `walking`, `running`, `swimming`, `flying`, `elytra`. Not specifying a mode will allow any of these modes to count. | +| `worlds` | Worlds which should count towards the progress. | List of world names | No | \- | \- | + +## Examples + +Travel 1000 metres: + +``` yaml +walking: + type: "walking" + distance: 1000 # distance in blocks travelled + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` + +Travel 1000 metres by sprinting only: + +``` yaml +walking: + type: "walking" + distance: 1000 # distance in blocks travelled + mode: running # (OPTIONAL) specific mode of transport + worlds: # (OPTIONAL) restrict to certain worlds + - "world" +``` |