> For the complete documentation index, see [llms.txt](https://ordwenplugins.gitbook.io/odailyquests/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ordwenplugins.gitbook.io/odailyquests/quests/create-a-quest.md). # Create a quest ## Summary 1. [How to create a quest](#how-to-create-a-quest) 1. [Mandatory parameters](#mandatory-parameters) 2. [Important things to note](#important-things-to-note) 2. [Placeholders](#placeholders) 3. [Menu item](#menu-item) 1. [Oraxen, ItemsAdder, Nexo, MMOItems](#oraxen-itemsadder-nexo-mmoitems) 2. [Custom head texture](#custom-head-texture) 3. [Custom model data](#custom-model-data) 4. [Item model](#item-model) 5. [Menu item amount](#menu-item-amount) 6. [Achived menu item](#achieved-menu-item) 4. [Optional parameters](#optional-parameters) 1. [Required worlds](#required-worlds) 2. [Required regions](#required-regions) 3. [Required permissions](#required-permissions) 4. [Protection bypass](#protection-bypass) 5. [Multiple requirements](#multiple-requirements) 6. [Dynamic required amount](#dynamic-required-amount) 7. [Random required](#random-required) ## How to create a quest Quests are defined in YAML files, organized by category. \ For example, if you want to add a quest to the **easy** category, you must edit the `easy.yml` file.\ Each quest follows the same structure, regardless of the file it belongs to. More information about the categories on [this page](/odailyquests/quests/create-a-category.md). ### Mandatory parameters * **name**\ The quest’s title, shown in menus and messages.\ Supports **`&`** color codes and **`HEX`** color codes. * **description**\ A short text displayed alongside the quest’s name.\ Formatting supports the same color options as above. * **type**\ The action the player must perform (e.g., `KILL`, `BREAK`, `GET`).\ The full list of quest types and their meaning is documented [here](/odailyquests/quests/available-types.md). * **required**\ Specifies the item or entity concerned by the quest. * Some types require this parameter (e.g., `GET` quests always need a required item).\ To make **global quests** (any item or entity), simply remove this line. * **required\_amount**\ The number of actions required (items to collect, blocks to break, mobs to kill, etc.).\ The required amount can also be dynamic, more details [here](#dynamic-required-amount). * **reward**\ Defines what the player receives when completing the quest. A reward must have a **type** (e.g., `MONEY`, `COMMAND`, `ITEM`) and either an amount or associated actions. Full details are available on the [Rewards page](/odailyquests/quests/rewards.md). ### Important things to note * Indentation in YAML files is critical. Even a single misplaced space may cause errors. * Some types of quests have very specific parameters. Please refer to the associated page. ## Placeholders You can use placeholders in the quest name or description. They will be displayed automatically. ```yaml 1: name: "&f%player_name%" ... description: - "%player_name%" ... ``` ## Menu Item {% hint style="info" %} Each parameter mentioned below as functional on the `menu_item` parameter is also functional on the `menu_achieved_item` and `required` parameters. {% endhint %} ### Oraxen, ItemsAdder, Nexo, MMOItems You can specify for the menu item an item from Oraxen, ItemsAdder, Nexo or MMOItems. It's really simple, you just need to add `oraxen:`, `itemsadder:`, `nexo:` or `mmoitems:` before the name of the item. For **Oraxen**, you need to set `use_oraxen` to `true` in the configuration file. For **ItemsAdder**, you need to specify the namespace before the name of the item, like the example below. You also need to set `use_itemsadder` to `true` in the configuration file. For **Nexo**, you need to set `use_nexo` to `true` in the configuration file. For **MMOItems**, you need to specify the category and the id of the item. ```yaml menu_item: "oraxen:my_item" menu_item: "itemsadder:namespace:my_item" menu_item: "nexo:my_item" menu_item: "mmoitems:category:id" ``` Don't forget to enclose the item names in inverted commas (`"..."`), otherwise the file will be formatted incorrectly and the plugin will crash! ### Custom head texture You can also use custom head textures, from [this website](https://minecraft-heads.com/). The value to put here is the `Minecraft-URL` at the bottom of the head page. Be sure to use the `Minecraft-URL` and **NOT** the `Value` that is just before! ```yaml // from https://minecraft-heads.com/custom-heads/decoration/60568-coin menu_item: "customhead:ebda5f31937b2ff755271d97f01be84d52a407b36ca77451856162ac6cfbb34f" ``` ### Custom model data You can specify for the menu item a custom model data. You need to add `custommodeldata:` before the type of the item, and then add the corresponding number just after, as the following example. ```yaml menu_item: "custommodeldata:paper:1234" ``` ### Item model You can specify for the menu item an item model. You need to add `itemmodel:` before the type of the item, and then add the corresponding namespace just after, as the following example. ```yaml menu_item: "itemmodel:odailyquests:easyquest" ``` ### Menu item amount By default, the `menu_item` has an amount of 1 in the interface. \ If you want to change its amount, you can use the `menu_item_amount` parameter. ```yaml ... menu_item: NETHER_QUARTZ_ORE menu_item_amount: 10 required_amount: 10 ... ``` The maximum amount is **64** (the maximum stack size), due to Minecraft limitations. You also have the option to set the value to **0**, which will automatically apply the value of `required_amount` to the item. ``` ... menu_item: NETHER_QUARTZ_ORE menu_item_amount: 0 # will be equal to 10 in the menu required_amount: 10 ... ``` ### Achieved menu item You may also want the item displayed in the menu to be different when a player completes a quest. To do this, you can use the `achieved_menu_item` parameter, which works exactly like the `menu_item` parameter. ``` ... menu_item: NETHER_QUARTZ_ORE achieved_menu_item: "customhead:b5a3b49beec3ab23ae0b60dab56e9cc8fa16769a25830b5d8d6c46378f54430" # checkmark head ... ``` ## Optional parameters ### Required worlds For each quest, you can specify the worlds where the player have to be in order to complete the objective, with the `required_worlds` parameter. Here is an example: ```yaml 1: name: "&aMiner of hell" menu_item: NETHER_QUARTZ_ORE description: - "&bMine 10 quartz ore in the Nether." - "&bWin &c500$&b." quest_type: BREAK required: NETHER_QUARTZ_ORE required_amount: 10 reward: reward_type: MONEY amount: 500 # simply add this section required_worlds: - world_nether ``` ### Required regions You can also specify the regions in which a quest can progress with the **`required_regions`** parameter. Only compatible with **WorldGuard**. ```yaml 1: name: "&aCow Breeder" menu_item: WHEAT description: - "&bBreed &e5 &bcows inside the &6Cow Farm&b region." - "&bReward: &c$500&b." quest_type: BREED required: COW required_amount: 5 reward: reward_type: MONEY amount: 500 # simply add this section required_regions: - cow_farm ``` ### Required permissions You can restrict quests to players who have specific permissions.\ This is useful for creating VIP-only quests or quests limited to certain groups. * The parameter is called **`required_permissions`**. * It accepts **a single permission** (string) or **a list of permissions** (array). * A quest will only be assigned to a player if they have **all** the listed permissions. ```yaml 1: name: "&6&l[VIP] &aDiamonds" menu_item: DIAMOND description: - "&bGet 50 diamonds." - "&bWin &c5000$&b." quest_type: GET required: DIAMOND required_amount: 50 reward: reward_type: MONEY amount: 5000 # simply add this section required_permissions: - "odailyquests.vip" ``` ### Protection bypass By default, progress is only made in an authorized region if **WorldGuard** or **Towny** are present on the server, notably by checking the **BLOCK\_PLACE** and **BLOCK\_BREAK** flags. If for some reason you want the quest to progress even when the player doesn't have permission, you can add the **`protection_bypass`** parameter.\ \ This parameter can be combined with the **required regions**. For example : ```yaml 1: name: "&aMine mine mine" menu_item: REDSTONE description: - "&bMine 500 blocks in the Spawn generator." - "&bWin &c500$&b." quest_type: BREAK required_amount: 10 reward: reward_type: MONEY amount: 500 protection_bypass: true required_regions: - cow_farm ``` ### Multiple requirements It is possible to assign multiple items/entities to a same quest. Thus, all items/entities in the list will count towards the quest's progress. However, it is not possible to specify a required number for each attribute in the list. To add multiple items/entities to a quest, the syntax is as follows: ```yaml required: - COAL_ORE - GOLD_ORE - ... ``` ### Dynamic required amount The **`required_amount`** parameter can be written as a **range** (e.g., `10-50`).\ When the quest is assigned, the plugin randomly selects a number within this range for that player. ```yaml 1: name: "&aStone Collector" menu_item: STONE description: - "&bMine %required% stone blocks." - "&bReward: &c250$&b." quest_type: BREAK required: STONE required_amount: 10-50 reward: reward_type: MONEY amount: 250 ``` In this example, each player gets a quest with a random requirement between 10 and 50 stone blocks. ### Random required The **`random_required`** parameter allows you to create dynamic quests by letting the plugin randomly select one item (or entity) from a predefined list when the quest is assigned to a player. This makes it possible to generate many unique quests at once with a single configuration. It can also be combined with a **dynamic range** for `required_amount` (e.g., `10-50`) to increase variability. **Key points** * Each entry in `random_required` has the format: ```yml MATERIAL: "display name" ``` * The **material/entity** is what the quest tracks. * The **string value** is used for display in menus and messages (`%displayName%` placeholder). * Works with both **items** and **entities**. * Only **one item/entity** from the list is chosen per player when the quest is assigned. * Do **not** use the `required` parameter in the same quest. \ If both are present, `random_required` will be ignored. ```yaml 1: name: "&a%displayName" menu_item: STONE_PICKAXE description: - "&bMine %required% %displayName%." - "&bWin &c500$&b." quest_type: BREAK random_required: - STONE: "stone" - GRANITE: "granite" - DIORITE: "diorite" - COAL_ORE: "coal ore" - IRON_ORE: "iron ore" required_amount: 64 reward: reward_type: MONEY amount: 500 ``` In this example, when a player receives the quest, the plugin randomly picks **one block type** from the list. `%displayName%` is replaced by the corresponding string (e.g., "coal ore").\ `%required%` is replaced by the required amount. ### Conditions Similar to the [required permissions](#required-permissions), you can define conditions with placeholders that must be met in order to obtain quests. It works like the [PLACEHOLDER](/odailyquests/quests/available-types/other-plugin-types.md#placeholder) quest type: same [operators](/odailyquests/quests/available-types/other-plugin-types.md#operators) and similar configuration. ```yaml 1: name: "&6&l[VIP] &aDiamonds" menu_item: DIAMOND description: - "&bGet 50 diamonds." - "&bWin &c5000$&b." quest_type: GET required: DIAMOND required_amount: 50 conditions: vip_condition: placeholder: "%luckperms_in_group_vip%" operator: EQUALS expected: "yes" error_message: "&cYou must be VIP to get this quest!" reward: reward_type: MONEY amount: 5000 ``` You can define as many conditions as you want.