zyraquests

📜 ZyraQuests

> A fully custom quest plugin with beautiful GUI menus, 6 objective types, flexible rewards, and native ZyraJobs integration — built for Spigot 1.21.

---

✨ Overview

ZyraQuests lets you create any quest you can imagine directly from a single YAML file — no commands, no in-game editor required. Players browse quests through polished inventory menus, track their progress in real time via action bar indicators, and earn XP, items, or custom commands as rewards.

Works perfectly standalone, and unlocks extra features when paired with ZyraJobs.

---

🖥️ GUI Menus

ZyraQuests is built around three fully interactive inventory menus:

📋 Quest Browser — Browse all quests sorted by category (Mining, Farming, Hunting, Brewing, General). Each quest shows its difficulty color, objectives count, your current status (not started / in progress / completed), and a live XP progress bar if active. Paginated for large quest collections.

🔍 Quest Detail — Opens on click. Shows the full quest description, each objective with its own progress bar, all rewards previewed as items, and the Accept / Abandon button. Border color changes based on difficulty (green = Easy, yellow = Medium, red = Hard, orange = Legendary).

⚡ Active Quests — See all your quests in progress at a glance, with per-objective progress bars. Quick-navigate back to any quest's detail view.

---

📋 Creating Quests

Everything lives in `quests.yml`. One quest looks like this:

```yaml quests: diamond_hunter: display-name: "Diamond Hunter" description: - "The real treasure lies deep below." - "Find and mine diamonds." icon: DIAMOND category: MINING difficulty: HARD repeatable: false objectives: - type: MINE_BLOCK block: DIAMOND_ORE amount: 10 display: "Mine Diamond Ore" - type: REACH_JOB_LEVEL job: miner level: 20 display: "Be Miner Level 20" rewards: - type: XP amount: 20 - type: JOB_XP job: miner amount: 1000 - type: ITEM material: DIAMOND_PICKAXE amount: 1 name: "&b&lDeep Earth Pickaxe" lore: - "&7Forged from the deepest veins." ```

That's it — reload with `/qadmin reload` and the quest is live.

---

🎯 Objective Types

| Type | What it tracks | |------|---------------| | `MINE_BLOCK` | Breaking specific blocks underground | | `HARVEST_CROP` | Harvesting fully grown crops | | `KILL_MOB` | Killing any entity by type | | `BREW_POTION` | Brewing potions at a brewing stand | | `COLLECT_ITEM` | Picking up or crafting specific items | | `REACH_JOB_LEVEL` | Reaching a level in ZyraJobs *(ZyraJobs required)* |

---

🎁 Reward Types

| Type | Effect | |------|--------| | `XP` | Give vanilla experience levels | | `JOB_XP` | Add ZyraJobs XP to a specific job *(ZyraJobs required)* | | `ITEM` | Give an ItemStack with optional custom name & lore | | `COMMAND` | Run any console command with `%player%` placeholder |

---

🔗 ZyraJobs Integration

ZyraQuests integrates with ZyraJobs as a soft-dependency — install both plugins and the integration activates automatically. No configuration needed.

When ZyraJobs is present: - `JOB_XP` rewards give XP directly into the player's job level - `REACH_JOB_LEVEL` objectives track job progression in real time - If ZyraJobs is absent, `JOB_XP` rewards fall back to vanilla XP automatically

---

📈 Player Experience

- 🔔 Join message when a quest is completed, listing all rewards - 📺 Join message on completion - 📊 Join message updates every time an objective advances - 🔊 Join message on quest accept and completion - 🔁 Join message — configure any quest to be completable multiple times - 🌐 Join message on completion (optional, disabled by default) - 💬 Join message reminding players of their active quests

---

🏷️ Quest Difficulties

| Difficulty | Color | Border | |-----------|-------|--------| | Easy | 🟢 Green | Lime glass | | Medium | 🟡 Yellow | Yellow glass | | Hard | 🔴 Red | Red glass | | Legendary | 🟠 Orange | Orange glass |

---

⚙️ Configuration

`config.yml` — Global settings: - `max-active-quests` — how many quests a player can track at once (default: 3) - `actionbar-progress` — show action bar updates on objective progress - `sounds` — toggle all sounds - `broadcast-completion` — announce completions server-wide - All chat messages fully customizable with color codes

`quests.yml` — All quests. Add, remove, or edit quests freely. No restart needed — just `/qadmin reload`.

---

🛠️ Commands

| Command | Description | |---------|-------------| | `/quests [category]` | Open the quest browser | | `/qadmin reload` | Reload config and all quests | | `/qadmin list` | List all quest IDs | | `/qadmin give <player> <id>` | Force-start a quest for a player | | `/qadmin complete <player> <id>` | Force-complete a quest | | `/qadmin reset <player> [id]` | Reset one quest or all quests | | `/qadmin info <player>` | View a player's quest progress |

Tab-completion is supported on all commands.

---

🔑 Permissions

| Permission | Default | Description | |-----------|---------|-------------| | `zyraquests.use` | Everyone | Access to `/quests` | | `zyraquests.admin` | OP | Access to `/qadmin` |

---

📦 Requirements

- Optional: 1.21.x - Optional: Spigot or Paper 1.21+ - Optional: 21+ - Optional - Optional: ZyraJobs (for `JOB_XP` rewards and `REACH_JOB_LEVEL` objectives)

---

🤝 Part of the Zyra Suite

ZyraQuests is designed to work alongside ZyraJobs as a unified gameplay ecosystem. Install both for the full experience — quests that reward job XP, objectives that track job levels, and a consistent GUI style across both plugins.

---

👤 Credits

Made with by sti_moi — *zyrajobs's group*