From 0aac85ff5c27e98564243a9f43ae58685bd18ff2 Mon Sep 17 00:00:00 2001 From: LMBishop <13875753+LMBishop@users.noreply.github.com> Date: Thu, 6 Jul 2023 14:10:24 +0100 Subject: Migrate docs to GitHub pages --- docs/tools/placeholderapi.md | 148 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 148 insertions(+) create mode 100644 docs/tools/placeholderapi.md (limited to 'docs/tools/placeholderapi.md') diff --git a/docs/tools/placeholderapi.md b/docs/tools/placeholderapi.md new file mode 100644 index 00000000..cc932600 --- /dev/null +++ b/docs/tools/placeholderapi.md @@ -0,0 +1,148 @@ +--- +title: PlaceholderAPI +parent: Tools +--- + +# PlaceholderAPI +{: .no_toc } + +This plugin integrates with PlaceholderAPI and exposes certain values via +placeholders. This can be used with other plugins. + +{: .important } +> **No PAPI eCloud download is necessary - placeholders come with the plugin.** +The eCloud extension called 'Quests' is not for this plugin, do not download it! +> +> {: .warning } +> > Once again, **do not download the eCloud extension**. There will be errors +> > if you do so. + +## Table of contents +{: .no_toc .text-delta } + +1. TOC +{:toc} + + +## Common placeholders + +### Quest counters + +| Placeholder | Description | +|----------------------------|------------------------------------------------------------------------------| +| `%quests_all%` | Returns the **number** of quests on the server. | +| `%quests_completed%` | **\*** Returns the **number** of quests the player has completed. | +| `%quests_completedbefore%` | Returns the **number** of quests the player has completed **at least once**. | +| `%quests_started%` | Returns the **number** of quests which are active for the player. | +| `%quests_categories%` | Returns the **number** of categories on the server. | + +### Quest lists + +| Placeholder | Description | +|---------------------------------|-------------------------------------------------------------------------------------------------------| +| `%quests_all_list%` | Returns a **comma-seperated\*\* list** of quest **names** on the server. | +| `%quests_completed_list%` | \* Returns a **comma-seperated\*\* list** of quest **names** the player has completed. | +| `%quests_completedbefore_list%` | Returns a **comma-seperated\*\* list** of quest **names** the player has completed **at least once**. | +| `%quests_started_list%` | Returns a **comma-seperated\*\* list** of quest **names** which are active for the player. | +| `%quests_categories_list%` | Returns a **comma-seperated\*\* list** of category **names** on the server. | + +### Quest ID lists + +| Placeholder | Description | +|-----------------------------------|-----------------------------------------------------------------------------------------------------| +| `%quests_all_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** on the server. | +| `%quests_completed_listid%` | \* Returns a **comma-seperated\*\* list** of quest **IDs** the player has completed. | +| `%quests_completedbefore_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** the player has completed **at least once**. | +| `%quests_started_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** which are active for the player. | +| `%quests_categories_listid%` | Returns a **comma-seperated\*\* list** of category **IDs** on the server. | + +**\*** *this does not include quests which have been repeated and not yet completed* + +**\*\*** *the delimiter can be changed by adding it in at the end: for example `%quests_completed_listid_ / %` will return a list of completed quests **seperated by the characters ` / ` (including the spaces around it)*** + +## Advanced placeholders + +### Quest details + +| Placeholder | Description | +|------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| +| `%quests_quest:%` | Returns the **display name** of the quest **``**. | +| `%quests_quest:_started%` | Returns **true/false** on whether or not the quest **``** is started by the player. | +| `%quests_quest:_starteddate%` | Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the quest **``** was started by the player. | +| `%quests_quest:_completed%` | **\*** Returns **true/false** on whether or not the quest **``** is completed by the player. | +| `%quests_quest:_completedbefore%` | Returns **true/false** on whether or not the quest **``** is completed by the player **at least once**. | +| `%quests_quest:_completiondate%` | Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the quest **``** was completed by the player. | +| `%quests_quest:_cooldown%` | Returns a **time in seconds** of the cooldown for quest **``**. | +| `%quests_quest:_canaccept%` | Returns **true/false** on whether or not the quest **``** can be started by the player. | +| `%quests_quest:_meetsrequirements%` | Returns **true/false** on whether or not the player has completed the required quests for the quest **``**. | +| `%quests_quest:_task:_progress%` | Returns the **progress** of task **`task-id`** on the quest **``**. | +| `%quests_quest:_task:_completed%` | Returns **true/false** on whether or not the task **`task-id`** on the quest **``** is completed by the player. | +| `%quests_quest:_p:%` | Returns the **local quest placeholder ``** for the quest **``**. | + +| Placeholder | Description | +|---------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------| +| `%quests_tracked%` | Returns the **display name** of the **players tracked quest** (or "No tracked quest"). | +| `%quests_tracked_started%` | Returns **true/false** on whether or not the **players tracked quest** is started. | +| `%quests_tracked_starteddate%` | Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the **players tracked quest** was started by the player. | +| `%quests_tracked_completed%` | **\*** Returns **true/false** on whether or not the **players tracked quest** is completed. | +| `%quests_tracked_completedbefore%` | Returns **true/false** on whether or not the **players tracked quest** is completed **at least once**. | +| `%quests_tracked_completiondate%` | Returns a **date formatted as DD/MM/YYYY\*\*\*, or "Never"** on when the **players tracked quest** was completed by the player. | +| `%quests_tracked_cooldown%` | Returns a **time in seconds** of the cooldown for the **players tracked quest**. | +| `%quests_tracked_canaccept%` | Returns **true/false** on whether or not the **players tracked quest** can be started by the player. | +| `%quests_tracked_meetsrequirements%` | Returns **true/false** on whether or not the player has completed the required quests for the **players tracked quest**. | +| `%quests_tracked_task:_progress%` | Returns the **progress** of task **`task-id`** on the **players tracked quest**. | +| `%quests_tracked_task:_completed%` | Returns **true/false** on whether or not the task **`task-id`** on the **players tracked quest** is completed by the player. | +| `%quests_tracked_p:%` | Returns the **local quest placeholder ``** for the **players tracked quest**. | + +### Per-category quest counters + +| Placeholder | Description | +|---------------------------------------------------|------------------------------------------------------------------------------------------------------------------| +| `%quests_category:%` | Returns the **id** of the category **``** (useful to check if it is a valid reference). | +| `%quests_category:_all%` | Returns the **number** of quests in the category **``**. | +| `%quests_category:_completed%` | **\*** Returns the **number** of quests in the category **``** the player has completed. | +| `%quests_category:_completedbefore%` | Returns the **number** of quests in the category **``** the player has completed **at least once**. | +| `%quests_category:_started%` | Returns the **number** of quests in the category **``** which are active for the player. | + +### Per-category quest lists + +|Placeholder|Description| +|---|---| +|`%quests_category:_all_list%`|Returns a **comma-seperated\*\* list** of quest **names** on the server.| +|`%quests_category:_completed_list%`|\* Returns a **comma-seperated\*\* list** of quest **names** in the category **``** the player has completed.| +|`%quests_category:_completedbefore_list%`|Returns a **comma-seperated\*\* list** of quest **names** in the category **``** the player has completed **at least once**.| +|`%quests_category:_started_list%`|Returns a **comma-seperated\*\* list** of quest **names** in the category **``** which are active for the player.| + +### Per-category quest ID lists + +| Placeholder | Description | +|----------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| +| `%quests_category:_all_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** on the server. | +| `%quests_category:_completed_listid%` | \* Returns a **comma-seperated\*\* list** of quest **IDs** in the category **``** the player has completed. | +| `%quests_category:_completedbefore_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** in the category **``** the player has completed **at least once**. | +| `%quests_category:_started_listid%` | Returns a **comma-seperated\*\* list** of quest **IDs** in the category **``** which are active for the player. | + +**\*** *this does not include quests which have been repeated and not yet completed* + +**\*\*** *the delimiter can be changed by adding it in at the end: for example `%quests_category:_completed_listid_ / %` will return a list of completed quests **seperated by the characters ` / ` (including the spaces around it)*** + +**\*\*\*** *the date format may be adjusted by including it at the end: for example `%quests_q:_completiondate_dd/MM HH:mm:ss%` will return a the date of compltion **formatted as `dd/MM HH:mm:ss`** - you may use any letter listed [here](https://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html)* + +## Caching placeholders + +Placeholders may be cached for a short period (10 seconds by default) to help improve performance. To do this, **simply add `_cache` to the end of any placeholder**. Note: date formats are automatically cached as parsing them may be heavy. + +**Examples:** +``` +%quests_all_cache% +%quests_completedbefore_listid_cache% +%quests_quest:_task:_progress_cache% +``` + +The length of time Quests retains this cache can be configured in the configuration under `options.placeholder-cache-time`. By default, this cache is **10 seconds**. + +```yaml +options: + ... + placeholder-cache-time: 10 +``` \ No newline at end of file -- cgit v1.2.3-70-g09d2