# Quest System

**KyuubiSoft Quests adds a full quest book to a Hytale server. Players follow a story across six chapters, pick up side quests from NPC quest givers, get fresh daily and weekly quests from weighted pools, track their quests on a HUD and earn quest tokens for a token shop. Server owners edit every quest, chapter, pool, NPC profile and setting in game in one admin window.**

---

## How it works

- Players open the **Questbook** with `/ksquest` (or the Quest Book item). It has the tabs **Daily**, **Weekly**, **Story**, **Side quests**, **Active** and **Chronicle**, and a detail panel for the selected quest.
- **Daily and weekly quests** are drawn per player from weighted pools at the reset time (default: 3 dailies every day at 04:00, 5 weeklies every Monday). Unwanted ones can be rerolled.
- **Story quests** run through six chapters, from the prologue to the Devastated Lands. Most of them are handed out and turned in at **NPC quest givers**.
- Progress counts on its own while players mine, chop, fight, craft, explore or talk to NPCs. Up to 5 tracked quests show on the **quest tracker HUD**.
- Finished quests pay **quest tokens**, items, lootbags, XP and more. Tokens buy items in the **Quest Token Shop**, a Core NPC shop.
- Admins open the **admin window** with `/ksquestadmin panel`, the `/ksadmin` hub or the `showcase_quests` NPC and change everything there. Every change is a draft until **Save**.

---

## Features

### Content

- **213 quests** ship with the mod: 31 story quests in 6 chapters, 14 side quests, 120 daily quests and 48 weekly quests, each daily and weekly in Common, Rare, Epic and Legendary variants.
- **17 NPC quest profiles** for the shipped quest givers, with offer, progress and turn-in dialogs and proximity whispers.
- **20 objective types**: mining, chopping, digging, placing, harvesting, picking flowers, kills, player kills, damage dealt and taken, crafting, collecting, delivering items to an NPC, talking to an NPC, zones, distance, playtime, commands, reaching a level and waiting. See [Objectives](./objectives).
- **11 reward types**: quest tokens, items, lootbags, currency, four kinds of XP, titles, achievements and commands. See [Rewards](./rewards).
- Your own quests, chapters and pool entries live in `custom/` and survive updates. See [Custom Content](./custom-quest-content) and [Quest Packs](./quest-packs).

### For players

- **Questbook** with a quest list, a detail panel (objectives with progress bars, rewards as item slots with tooltips, quest giver with portrait) and buttons for start, claim, reroll, abandon and track. See [Quest Book UI](./quest-book-ui).
- **Story tab** with a chapter map and **Chronicle tab** with lifetime totals and every completed quest grouped by day.
- **Quest giver window** at NPCs: all offered quests as cards, a "ready to claim" strip and the reason a quest is still locked.
- **Delivery confirmation**: an NPC that needs items shows exactly what it takes, and takes nothing before you press **Hand in**.
- **Quest tracker HUD** with one card per tracked quest, and a proximity hint near quest NPCs. See [HUD Tracker](./hud-tracker).
- Tracker settings in the book and in the shared KS settings window (`/kssettings`).

### Systems

- [Daily & weekly pools](./daily-weekly-pools) with weights, rerolls (free and paid) and reset announcements.
- [Tier system](./tier-system) that scales rewards by difficulty (up to ×5).
- [Quest streak](./streak-system): days in a row with at least one finished daily, with milestone rewards. Off by default.
- [Story facts](./story-quests#the-facts-system) that quests, chapters and Core NPC dialogs can set and check.
- **Economy mode**: quest tokens can be paid as coins of an economy plugin instead.
- Player data in files or in MySQL (through KyuubiSoft Core).

### For admins

- **One admin window** for quests, chapters, pools, NPC profiles, players, statistics and all settings, with a draft, a change list, backups and "Undo last save". See [Admin Window](./admin-panel).
- **Players tool** for online and offline players: start quests, give tokens, set facts and streaks, fix progress, view the player's questbook (read only). Actions for offline players run at their next login.
- **Check view** with about 75 rules that finds broken references before you save.
- Core dialog integration: **Start quest** and **Set fact** as dialog actions, and the conditions `quest_active`, `quest_completed`, `quest_available`, `quest_ready` and `fact` in Core's dialog editor.
- Cross-mod API with events and a facts API. See [API Reference](./api-reference).

---

## What's new in 2.1

- **New admin window** in the KyuubiSoft look. It replaces the old 7-tab admin panel completely. Every change is a draft until **Save**; errors block saving, warnings only ask. Each save makes a backup set, and the last 20 are kept.
- **Quest editor** with six sections (basics, texts per language, objectives, rewards, flow, NPC phases), a player preview and **Test for me**.
- **NPC profiles** are a tab of the admin window, with a node editor for dialogs, phase preview and **Test dialog**. Core's NPC management window opens them, and **Back** returns to the same NPC on its Talk tab (reliable in every case since 2.1.2).
- **Players tool** with 11 actions, a log that can revert each action, and **View questbook**, which since 2.1.1 also works for offline players (read only, saved state).
- **Pools** with a "chance approx. %" per quest and a rotation preview. **Weight 0** now means "never drawn".
- **Repeat cooldown** for repeatable quests (`options.repeat_cooldown_hours`).
- Dialog action **Set fact** in NPC profiles and the Core dialog condition **Quest ready to turn in** (`quest_ready`).
- **Console rule**: anything that runs as the server console (command rewards, console actions in NPC profiles) needs `ks.core.admin.dialog.console` in addition to `ks.quest.admin`. This is checked again on save and on web editor imports.

Version 2.0 before it brought the new Questbook, the quest giver and delivery windows, the new tracker HUD, the real quest streak and 27 bug fixes. See the [Changelog](./changelog).

:::note
The admin window (2.1.0) and the offline questbook view (2.1.1) have not been tested in game yet.
:::

---

## Where to go

| Page | Read it for |
|------|-------------|
| [Getting Started](./getting-started) | Installing, the data folder, the first test |
| [Configuration](./configuration) | Every option in `config.json` |
| [Quest Types](./quest-types) | Daily, weekly, story, side and hub quests, quest options and triggers |
| [Objectives](./objectives) | Objective types, targets and options |
| [Rewards](./rewards) | Reward types, tier factor, fallbacks |
| [Daily & Weekly Pools](./daily-weekly-pools) | Pool weights, resets and rerolls |
| [Tier System](./tier-system) | Difficulty tiers and reward factors |
| [Story Quests](./story-quests) | Prerequisites, facts, NPC turn-ins |
| [Chapters](./chapters) | Chapter chains, unlock rules, chapter rewards |
| [NPC Quest Profiles](./npc-quest-profiles) | Quest givers, dialogs, proximity whispers |
| [Quest Book UI](./quest-book-ui) | What players see in the Questbook and at NPCs |
| [HUD Tracker](./hud-tracker) | The tracker HUD and its settings |
| [Streak System](./streak-system) | The quest streak and its milestones |
| [Admin Window](./admin-panel) | Everything in `/ksquestadmin panel` |
| [Commands](./commands) | Every player and admin command |
| [Permissions](./permissions) | Permission nodes and the console rule |
| [Custom Content](./custom-quest-content) | Own quests that survive updates |
| [Quest Packs](./quest-packs) | Shareable content bundles |
| [Localization](./localization) | Languages and translation files |
| [API Reference](./api-reference) | Java API for other plugins |
| [Troubleshooting](./troubleshooting) | Common problems |
| [Changelog](./changelog) | What changed in each version |

---

## Quick Reference

| Item | Details |
|------|---------|
| **Plugin** | KyuubiSoft Quests (manifest `kyuubisoft:questbook`) |
| **Version** | 2.1.8 (2026-11-09) |
| **Player commands** | `/ksquest` (aliases `ksquests`, `ksquestbook`, `kqb`, `questbook`, `qb`), `/ksquestsettings` |
| **Admin command** | `/ksquestadmin` (alias `qadmin`) |
| **Data folder** | `mods/kyuubisoft_questbook/` |
| **Config** | `config.json` |
| **Player data** | `players/<uuid>.json`, or the MySQL table `quest_players` (with Core's table prefix, default `ks_quest_players`) |
| **Localization** | `localization/<lang>.json`, 9 languages |
| **Required** | KyuubiSoft Core (2.9.9 or newer; on older Core versions the newer hooks, such as the dialog actions, are skipped with one log line) |
| **Optional** | KyuubiSoft Achievements (achievement and title rewards and prerequisites), LuckPerms, an economy plugin (economy mode), leveling or skill plugins (XP rewards, level objectives) |

---

## Requirements

- Hytale server 0.7.x (built against 0.7.0)
- Java 25
- KyuubiSoft Core. Quests uses it for tracking, NPCs and dialogs, the token shop, lootbags, the economy bridge, player data storage and the admin hub.