> For the complete documentation index, see [llms.txt](https://docs.mongenscave.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mongenscave.com/premium-products/quests/features/create-a-quest.md).

# Create a Quest

All quests are defined in `quests.yml`. Every quest is a section under the top-level `quests:` key, and the section name is the quest ID (used in commands, placeholders and storage — pick something short and lowercase, like `beginner_miner`).

You don't need to touch any code. Create the section, run `/quests reload`, and the quest is live.

### A complete example <a href="#a-complete-example" id="a-complete-example"></a>

```yaml
quests:
  beginner_miner:
    display:
      name: "&#B8FFF2&lBeginner Miner"
      material: AMETHYST_SHARD
      custom-model-data: 358

    level: 1
    daily: true

    objectives:
      stone:
        name: "&#D3DBE3&lStone Veins"
        description:
          - "&#C7D0D9Mine stone blocks to gather"
          - "&#C7D0D9your first resources."
          - ""
          - "&#8A8F98Progress: &#FFFFFF{progress}&#8A8F98/&#FFFFFF{required}"
        trigger: block_break
        target: STONE
        required: 64

      craft_pickaxe:
        name: "&#FFD86E&lFirst Upgrade"
        description:
          - "&#C7D0D9Craft a stone pickaxe."
        trigger: craft_item
        target: STONE_PICKAXE
        required: 1

    rewards:
      - type: message
        value: "&#B8FFF2You learned the basics of mining."
      - type: command
        value: give %player% iron_pickaxe 1

    accept-expire: -1
    active-expire: 1800
```

This quest asks the player to mine 64 stone and craft a stone pickaxe. Once both objectives are done, the rewards run automatically.

### Quest options <a href="#quest-options" id="quest-options"></a>

| Key             | Description                                                                                                                            | Default |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `display`       | How the quest looks in the quest board GUI (see below).                                                                                | –       |
| `level`         | The quest level. The daily board only offers quests within `level-range` (set in `config.yml`) of the player's own level.              | `1`     |
| `daily`         | Whether the quest can appear on the daily quest board. Set to `false` for quests you only hand out manually (e.g. via admin commands). | `true`  |
| `objectives`    | The tasks the player has to complete. At least one is required.                                                                        | –       |
| `conditions`    | Extra requirements checked when the player tries to accept the quest.                                                                  | none    |
| `rewards`       | What the player gets when every objective is complete.                                                                                 | none    |
| `accept-expire` | Seconds the player has to **start** the quest after accepting it. `-1` means no limit.                                                 | `-1`    |
| `active-expire` | Seconds the player has to **finish** the quest once it becomes active. `-1` means no limit.                                            | `-1`    |

{% hint style="info" %}
Both expire values are in **seconds**. `active-expire: 1800` gives the player 30 minutes to finish. Players get warnings as the timer runs down — configurable under `quests.expire-warning` in `config.yml`.
{% endhint %}

#### Display <a href="#display" id="display"></a>

The `display` section controls the item shown for the quest in the board GUI:

```yaml
display:
  name: "&#FF6B6B&lMonster Hunter"
  material: MACE
  custom-model-data: 358   # optional, for resource pack icons
```

`name` supports legacy color codes (`&a`) and hex colors (`&#FF6B6B`). `material` is any [Bukkit Material](https://jd.papermc.io/paper/1.21/org/bukkit/Material.html) name.

### Objectives <a href="#objectives" id="objectives"></a>

Each objective is a named section under `objectives:`. The section name (e.g. `stone`) is the objective ID — it's used to track progress, so don't rename it after players have started the quest.

```yaml
objectives:
  zombies:
    name: "&#8DFFB3&lRotten Threat"
    description:
      - "&#C7D0D9Defeat zombies before they"
      - "&#C7D0D9overrun the area."
      - ""
      - "&#8A8F98Progress: &#FFFFFF{progress}&#8A8F98/&#FFFFFF{required}"
    trigger: kill_entity
    target: ZOMBIE
    required: 15
```

| Key           | Description                                                                                                                   |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `trigger`     | What kind of action counts (see the trigger list below).                                                                      |
| `target`      | What exactly the action must involve — a block, item, entity, world, etc. Depends on the trigger. Some triggers accept `any`. |
| `required`    | How many times the action must happen (or the total amount, for damage/distance/XP based triggers).                           |
| `name`        | Objective name shown in GUIs and completion messages.                                                                         |
| `description` | Lore lines shown in GUIs. `{progress}` and `{required}` are replaced with the player's live progress.                         |

A quest is complete when **all** of its objectives are complete. Objectives progress in parallel — there's no fixed order.

#### Triggers <a href="#triggers" id="triggers"></a>

**Vanilla triggers** (no extra plugin needed):

| Trigger                | Counts when the player...               | `target`                            |
| ---------------------- | --------------------------------------- | ----------------------------------- |
| `block_break`          | breaks a block                          | block material, e.g. `STONE`        |
| `place_block`          | places a block                          | block material                      |
| `interact_block`       | right-clicks a block                    | block material, e.g. `CHEST`        |
| `kill_entity`          | kills a mob                             | entity type, e.g. `ZOMBIE`          |
| `deal_damage`          | deals damage (progress = damage dealt)  | `any`                               |
| `take_damage`          | takes damage (progress = damage taken)  | `any`                               |
| `move`                 | walks (progress = blocks traveled)      | `any`                               |
| `move_while_sprinting` | sprints                                 | `any`                               |
| `move_while_sneaking`  | sneaks while moving                     | `any`                               |
| `move_while_flying`    | flies                                   | `any`                               |
| `move_while_swimming`  | swims                                   | `any`                               |
| `fish`                 | catches something while fishing         | `any`                               |
| `craft_item`           | crafts an item                          | item material, e.g. `STONE_PICKAXE` |
| `smelt_item`           | takes an item out of a furnace          | item material or `any`              |
| `consume`              | eats or drinks an item                  | item material, e.g. `COOKED_BEEF`   |
| `change_world`         | switches world                          | world name or `any`                 |
| `gain_exp`             | gains vanilla XP (progress = XP gained) | `any`                               |
| `gain_quest_xp`        | gains quest XP                          | `any`                               |
| `level_up`             | levels up in the quest leveling system  | `any`                               |

{% hint style="warning" %}
`target` values for vanilla triggers must be exact material/entity names (`IRON_ORE`, `SKELETON`, ...). A typo means the objective simply never progresses — no error is thrown.
{% endhint %}

### Rewards <a href="#rewards" id="rewards"></a>

Rewards run once, when the last objective is completed. They can be written as a list:

```yaml
rewards:
  - type: message
    value: "&#B8FFF2Well done!"
  - type: command
    value: eco give %player% 500
```

or as named sections, which lets you add a `display-name` (shown in GUIs instead of the raw value):

```yaml
rewards:
  money:
    type: command
    display-name: "&a$500"
    value: eco give %player% 500
  bonus_xp:
    type: quest_xp
    value: 250
```

Available reward types:

| Type       | `value`                                   | What it does                                                               |
| ---------- | ----------------------------------------- | -------------------------------------------------------------------------- |
| `message`  | text (colors supported)                   | Sends a chat message to the player.                                        |
| `command`  | console command, `%player%` = player name | Runs the command from console.                                             |
| `item`     | `MATERIAL:amount`, e.g. `DIAMOND:3`       | Puts the item in the player's inventory.                                   |
| `xp`       | number                                    | Gives vanilla experience.                                                  |
| `quest_xp` | number                                    | Gives quest XP (multiplied by the player's premium XP multiplier, if any). |

The `command` type is the most flexible — anything a console command can do (economy, crates, permissions, custom items) can be a reward.

### Conditions <a href="#conditions" id="conditions"></a>

Conditions are checked when a player tries to **accept** the quest. If any condition fails, the quest can't be accepted.

```yaml
conditions:
  - type: permission
    value: quests.vip
  - type: world
    value: world_nether
```

| Type         | `value`         | Requirement                           |
| ------------ | --------------- | ------------------------------------- |
| `permission` | permission node | The player must have this permission. |
| `world`      | world name      | The player must be in this world.     |

### Applying your changes <a href="#applying-your-changes" id="applying-your-changes"></a>

After editing `quests.yml`, run:

```
/quests reload
```

Quests already accepted by players keep running with the definition they were started with; new accepts use the updated config.

{% hint style="info" %}
You can hand out any quest directly with `/quests force give <player> <quest>` or `/quests force start <player> <quest>` (permission `mcquests.admin.force`), even quests with `daily: false` that never appear on the board — handy for testing a new quest before players see it.
{% endhint %}