# Getting started

> From install to your first working quest

This page walks you through the core concepts and gets a working quest on your server from scratch. For the exhaustive reference of every option, follow the links to the dedicated pages.

# Concepts

- **Quest pool** — a group of quests. A pool is either:
  - `global` — a fixed quest line. Players see every (unlocked) quest in the pool; good for story / progression chains.
  - `timed-random` — the plugin randomly picks a set of quests for each player and refreshes them on a schedule (daily, weekly, etc.).
- **Quest** — a single objective set inside a pool. One quest can have several **tasks**.
- **Task** — one objective to complete (break 10 stone, kill 5 zombies, …). See [Task objective types](../auroraquests/task-objective-types.md).
- **Reward** — what the player gets for finishing a quest (or a pool level). See [Rewards](../auroraquests/rewards.md).

# File layout

Everything lives in the plugin's data folder, `plugins/AuroraQuests/`:

```
plugins/AuroraQuests/
├── config.yml            # global settings  (see "Main configuration")
├── menu_main.yml         # the /quests menu  (see "Main menu configuration")
├── menu_common.yml       # items shared by all menus  (see "Common menu configuration")
└── quest_pools/
    └── <pool_id>/        # the folder name IS the pool id
        ├── config.yml    # pool settings  (see "Quest pool configuration")
        └── quests/
            ├── quest_one.yml   # the file name (without .yml) IS the quest id
            └── quest_two.yml
```

:::callout{type="warning"}
The **folder name** under `quest_pools/` is the pool's id, and each quest **file name** is that quest's id. Quest ids must be unique within a pool — a duplicate id is logged and skipped. Ids are also what you reference in unlock requirements (`pool_id:quest_id`) and placeholders.
:::

The plugin ships with three example pools (`daily`, `weekly`, `global`) already set up — the fastest way to learn is to open those and tweak them.

# Your first quest, step by step

### 1. Create the pool folder

Make a folder for the pool, e.g. `plugins/AuroraQuests/quest_pools/weekly_pvp/`.

### 2. Add the pool `config.yml`

`quest_pools/weekly_pvp/config.yml` — a minimal timed-random pool that rolls one quest every Monday:

```yaml
type: timed-random
name: "Weekly PvP"

difficulties:
  medium: 1

reset-frequency: 0 0 0 ? * MON

menu-item:
  show-in-main-menu: true
  page: 1
  item:
    material: iron_sword
    slot: 13
    name: "&c{name}"
    lore:
      - "&7Weekly combat challenges."
      - "&7Completed: &f{total_completed}"
      - ""
      - "&eClick to view!"

menu:
  title: "{name}"
  rows: 6
  display-area: [ 20, 21, 22, 23, 24 ]
  has-back-button: true
  has-close-button: true
  filler:
    enabled: true
    item:
      material: black_stained_glass_pane
      name: " "
```

See [Quest pool configuration](../auroraquests/configuration/quest-pool-configuration.md) for every pool option (leveling, unlock requirements, completed-quest handling, …).

### 3. Add a quest

`quest_pools/weekly_pvp/quests/hunt_zombies.yml`:

```yaml
name: "Zombie Hunter"
difficulty: medium

menu-item:
  material: zombie_head
  name: "&f{name}"
  lore:
    - "&7Tasks:"
    - "  &f{task_kills}"
    - ""
    - "&7Rewards:"
    - "  {reward_money}"

tasks:
  kills:
    task: KILL_MOB
    display: "{status} &fKill {required} zombies &b{current}&f/&b{required}"
    args:
      amount: 25
      types:
        - "minecraft:zombie"

rewards:
  money:
    type: money
    amount: 5000
    display: "&8+&a{value_formatted}$"
```

Note how the task id `kills` and reward id `money` turn into the `{task_kills}` and `{reward_money}` placeholders used in the quest's `menu-item` lore. See [Quest configuration](../auroraquests/configuration/quest-configuration.md) for the full quest format (filters, locked/completed lore, per-quest completed appearance, start requirements, …).

### 4. Reload and test

Run `/quests reload`, then `/quests` to open the menu. For the `difficulties` picker to have quests to choose from, make sure the pool's `difficulties` keys (here `medium`) match the `difficulty` of at least one quest in the folder, and that those difficulty ids exist in `config.yml`'s `difficulties` / `sort-order`.

# Where to go next

- [Task objective types](../auroraquests/task-objective-types.md) — every objective and its arguments.
- [Task progression filters](../auroraquests/task-progression-filters.md) — restrict when a task counts (world, region, biome, Y-level, held item, requirements).
- [Rewards](../auroraquests/rewards.md) — money, items, permissions, stats, XP, commands.
- [Quest pool configuration](../auroraquests/configuration/quest-pool-configuration.md) / [Quest configuration](../auroraquests/configuration/quest-configuration.md) — full config reference.
- [Commands](../auroraquests/commands.md) and [Permissions](../auroraquests/permissions.md).