> For the complete documentation index, see [llms.txt](https://questborn.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://questborn.gitbook.io/docs/getting-started.md).

# Getting Started

Welcome to **Questborn**! Questborn is a powerful, flexible, and high-performance quest plugin for Minecraft servers. It allows you to create dynamic quest pools (daily/weekly), storyline quest chains, server-wide global community objectives, interactive NPC dialogues, and custom reward systems—all using simple YAML configuration files without writing any code.

## ⚡ Compatibility & Requirements

Questborn is designed for high performance and modern Minecraft server architectures:

* **Supported Platforms**: Paper, Purpur, Spigot, and **Folia** (multi-threaded servers).
* **Minecraft Versions**: **1.16+** up to the latest releases (26.2).
* **Required Java Version**: Java 16 or higher (depending on your Minecraft server version).

### Optional Dependencies & Integrations

* **Vault** & Economy Plugin (e.g., EssentialsX): Required for cash/money rewards.
* **PlaceholderAPI (PAPI)**: Required for placeholders in descriptions, dialogues, titles, and rewards.
* **FancyNpcs** or **Citizens**: Required for binding quest menus and interactive dialogues to physical NPCs.
* **ItemsAdder**: Supported for custom item icons and reward items (`itemsadder_id`).
* **WorldGuard**: Supported for region-based movement/exploration objectives.
* **Developer API**: Extensible robust Bukkit Events, Registries, and Managers. See page `API Reference` for details.

## 📦 Installation & Initial Launch

Follow these simple steps to install Questborn on your server:

{% stepper %}
{% step %}

## Download Plugin

Obtain the latest `Questborn.jar` file.
{% endstep %}

{% step %}

## Place in Plugins Folder

Copy `Questborn.jar` into your server's `plugins/` directory.
{% endstep %}

{% step %}

## Start the Server

Boot up your server to allow Questborn to generate its default file structure.
{% endstep %}

{% step %}

## Locate Data Folder

Open `plugins/Questborn/` in your server directory.
{% endstep %}
{% endstepper %}

## 📁 File & Folder Hierarchy

Upon first launch, Questborn generates the following directory structure:

```
plugins/Questborn/
├── config.yml              # Core plugin settings & visual delays
├── quest-effects.yml       # Preset effects (titles, sounds, particles, potions)
├── npc/                    # NPC 2.0 & dialogue configurations
│   ├── npcs.yml            # Linked NPC settings, moods, & quest assignments
│   └── dialogues.yml       # Interactive GUI dialogue tree definitions
├── language/               # Localization files (messages, GUI titles)
│   └── minecraft/          # Vanilla item & entity name translations
├── types/                  # Quest engine & category configurations
│   ├── daily.yml           # Example: Daily quest type
│   └── weekly.yml          # Example: Weekly rotation quest type
└── quests/                 # Quests categorized into subfolders
    ├── daily/              # Individual quest YAML files for daily type
    └── weekly/             # Individual quest YAML files for weekly type
```

### Core Concepts Overview

* **In-Game GUI Editor (`/quest editor`)**: A powerful visual interface that allows administrators to create and modify quest configurations, rewards, and objectives directly from within the game without touching YAML files.
* **Quest Type (`types/*.yml`)**: Defines a quest category, its GUI slot and icon, reset cooldowns, and the **Quest Engine** (`DEFAULT`, `CHAIN`, `ROTATION`, or `GLOBAL`).
* **Quest (`quests/*/*.yml`)**: An individual task definition containing objectives, requirements, description text, rewards, and visual effects.
* **NPC 2.0 (`npc/npcs.yml` & `npc/dialogues.yml`)**: Binds quest types and interactive GUI dialogue trees to Citizens or FancyNpcs entities.

## 🚀 Creating Your First Quest in 5 Minutes

Here is a quick step-by-step tutorial for creating a simple daily mining quest:

{% stepper %}
{% step %}

## Verify or Create a Quest Type

Ensure you have a type file at `plugins/Questborn/types/daily.yml`:

```yaml
id: daily
folder: "quests/daily"
display-name: "<#fffb99>☀ Daily Quests"
lore:
  - "<#cccccc>Complete daily tasks to earn rewards!"
  - ""
  - "<#7dd3ff>Click to view active daily tasks"
material: "DIAMOND_PICKAXE"
slot: 11
cooldown: 24h
engine: DEFAULT
enabled: true
```

{% endstep %}

{% step %}

## Create the Quest File

Create a new YAML file at `plugins/Questborn/quests/daily/mine_stone.yml`:

```yaml
id: "mine_stone"
name: "<#ffe08a>⛏ Stone Cutter"
icon-material: "STONE"

description:
  - "<#cccccc>Break 64 Stone blocks in the world."
  - ""
  - "<#a7ff99>Objective: <#ffffff>Break 64 Stone"

rewards-description:
  - "<#a7ff99>+250 Coins"
  - "<#ffe08a>+100 XP"

quest-path:
  stage-1:
    objective:
      type: BLOCK_BREAK
      amount: 64
      target-materials:
        - STONE

rewards:
  money:
    amount: 250
  xp:
    points: 100

quest-effects:
  activate: "quest_activate_start"
  complete: "quest_complete_success"
```

{% endstep %}

{% step %}

## Reload & Test In-Game

1. Run `/quest reload` in server console or in-game (requires `questborn.command.reload`).
2. Run `/quest` to open the Quests GUI.
3. Click on **Daily Quests** and select **Stone Cutter** to start!
   {% endstep %}
   {% endstepper %}