diff options
Diffstat (limited to 'docs/tools')
| -rw-r--r-- | docs/tools/data-migration-tool.md | 35 | ||||
| -rw-r--r-- | docs/tools/index.md | 7 | ||||
| -rw-r--r-- | docs/tools/placeholderapi.md | 148 | ||||
| -rw-r--r-- | docs/tools/quest-debugger.md | 54 |
4 files changed, 244 insertions, 0 deletions
diff --git a/docs/tools/data-migration-tool.md b/docs/tools/data-migration-tool.md new file mode 100644 index 00000000..891862c7 --- /dev/null +++ b/docs/tools/data-migration-tool.md @@ -0,0 +1,35 @@ +--- +title: Data migration tool +parent: Tools +--- + +# Data migration tool + +The **data migration tool** is a tool that allows you to migrate your +data from one [storage provider](Storage_providers "wikilink") to +another. This can also be used as a backup tool. The tool can be +accessed using `/quests admin migratedata`, which will generate a file +[migrate_data.yml](https://github.com/LMBishop/Quests/blob/master/bukkit/src/main/resources/resources/bukkit/migrate_data.yml), +where you must configure both providers. + +The `from` section is the configuration for the storage provider you are +migrating from. The `to` section is the configuration for the storage +provider you are migrating to. Both sections are required. + +When you have entered the information for both systems, you must set the +`ready` flag to **true** at the end of the file. Then, to execute the +migration, run the following command: + + /quests admin migratedata execute + + +{: .warning } +**It is advised that you do this process on a server with no players +online.** You should set a whitelist, or turn on maintenence mode, +before migrating data, and these commands should be done through your +server console. Trying this process with players online may result in +unexpected behaviour, or worse, potential data corruption! + +Once the migration has finished, you can safely delete migrate_data.yml. +You may also want to manually update your main configuration to point to +the new data provider. diff --git a/docs/tools/index.md b/docs/tools/index.md new file mode 100644 index 00000000..83c7f894 --- /dev/null +++ b/docs/tools/index.md @@ -0,0 +1,7 @@ +--- +title: Tools +has_children: true +nav_order: 7 +--- + +# Tools
\ No newline at end of file diff --git a/docs/tools/placeholderapi.md b/docs/tools/placeholderapi.md new file mode 100644 index 00000000..cc932600 --- /dev/null +++ b/docs/tools/placeholderapi.md @@ -0,0 +1,148 @@ +--- +title: PlaceholderAPI +parent: Tools +--- + +# PlaceholderAPI +{: .no_toc } + +This plugin integrates with PlaceholderAPI and exposes certain values via +placeholders. This can be used with other plugins. + +{: .important } +> **No PAPI eCloud download is necessary - placeholders come with the plugin.** +The eCloud extension called 'Quests' is not for this plugin, do not download it! +> +> {: .warning } +> > Once again, **do not download the eCloud extension**. There will be errors +> > if you do so. + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + + +## Common placeholders + +### Quest counters + +| Placeholder | Description | +|----------------------------|------------------------------------------------------------------------------| +| `%quests_all%` | Returns the **number** of quests on the server. | +| `%quests_completed%` | **\*** Returns the **number** of quests the player has completed. | +| `%quests_completedbefore%` | Returns the **number** of quests the player has completed **at least once**. | +| `%quests_started%` | Returns the **number** of quests which are active for the player. | +| `%quests_categories%` | Returns the **number** of categories on the server. | + +### Quest lists + +| Placeholder | Description | +|---------------------------------|-------------------------------------------------------------------------------------------------------| +| `%quests_all_list%` | Returns a **comma-seperated\*\* list** of quest **names** on the server. | +| `%quests_completed_list%` | \* Returns a **comma-seperated\*\* list** of quest **names** the player has completed. | +| `%quests_completedbefore_list%` | Returns a **comma-seperated\*\* list** of quest **names** the player has completed **at least once**. | +| `%quests_started_list%` | Returns a **comma-seperated\*\* list** of quest **names** which are active for the player. | +| `%quests_categories_list%` | Returns a **comma-seperated\*\* list** of category **names** on the server. | + +### Quest ID lists + +| Placeholder | Description | +|-----------------------------------|-----------------------------------------------------------------------------------------------------| +| `%quests_all_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** on the server. | +| `%quests_completed_listid%` | \* Returns a **comma-seperated\*\* list** of quest **IDs** the player has completed. | +| `%quests_completedbefore_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** the player has completed **at least once**. | +| `%quests_started_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** which are active for the player. | +| `%quests_categories_listid%` | Returns a **comma-seperated\*\* list** of category **IDs** on the server. | + +**\*** *this does not include quests which have been repeated and not yet completed* + +**\*\*** *the delimiter can be changed by adding it in at the end: for example `%quests_completed_listid_ / %` will return a list of completed quests **seperated by the characters ` / ` (including the spaces around it)*** + +## Advanced placeholders + +### Quest details + +| Placeholder | Description | +|------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| +| `%quests_quest:<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/tools/quest-debugger.md b/docs/tools/quest-debugger.md new file mode 100644 index 00000000..1ffcaabd --- /dev/null +++ b/docs/tools/quest-debugger.md @@ -0,0 +1,54 @@ +--- +title: Quest debugger +parent: Tools +--- + +# Quest debugger + +The **quests debugger** allows you to see why a quest may not be working +as intended. When turned on for a quest, it will print out what a task +type is doing and how it is evaluating it. This can be helpful to see +why a specific quest is not accepting a specific action. + +## Using the debugger + +The debugger can be enabled with **/q a debug quest \<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. + +<img src="https://i.imgur.com/Sb5DrpJ.png" height=50> + +## 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: + +<img src="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`: + +<img src="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. |