# 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](https://ordwenplugins.gitbook.io/odailyquests/quests/create-a-category). ### 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](https://ordwenplugins.gitbook.io/odailyquests/quests/available-types). * **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](https://ordwenplugins.gitbook.io/odailyquests/quests/rewards). ### 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](https://ordwenplugins.gitbook.io/odailyquests/available-types/other-plugin-types#placeholder) quest type: same [operators](https://ordwenplugins.gitbook.io/odailyquests/available-types/other-plugin-types#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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://ordwenplugins.gitbook.io/odailyquests/quests/create-a-quest.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.