📜 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:

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

• 🔔 Level-up style chat message when a quest is completed, listing all rewards
• 📺 Screen title on completion
• 📊 Action bar progress updates every time an objective advances
• 🔊 Sounds on quest accept and completion
• 🔁 Repeatable quests — configure any quest to be completable multiple times
• 🌐 Server broadcast 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

• Minecraft: 1.21.x
• Server software: Spigot or Paper 1.21+
• Java: 21+
• No required dependencies
• 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