Add /docs directory

This is part of a migration from GitHub wikis to GitHub pages

1 files changed, 444 insertions, 0 deletions

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"
+```