KyuubiSoft Quest System

kyuubisoft

A complete quest framework for Hytale servers — daily & weekly rotations, a 6-chapter storyline with 31 story quests, NPC quest givers with full dialog trees, a tier-based reward economy, an in-game token shop, HUD tracking, proximity notifications, and a full visual admin panel. Everything players and admins need, right out of the box.

Features

Daily & Weekly Quests

3 daily quests rotating every day at a configurable reset time (default: 04:00)
5 weekly quests rotating every week on a configurable day (default: Monday)
120 daily quests in 10 pools (Mining, Woodcutting, Digging, Harvesting, Combat, Damage, Crafting, Building, Exploration, Playtime)
48 weekly quests in 3 categories (Mastery, Challenge, Journey) with up to 5 objectives per quest
Tier-based selection — quests are drawn from weighted pools: Common, Rare, Epic, Legendary
Reroll system — 1 free reroll per period, then paid rerolls with escalating token costs (10 > 20 > 40 > …)
Lazy reset — players who were offline during reset receive new quests on next login
Earn Quest Tokens on every completion
Quests are turned in via the QuestBook or at the assigned NPC

Story & Chapter Quests

31 story quests across 6 chapters — from Awakening to the Devastated Lands
Linear storyline progression with quest chains and prerequisite gating
Facts database — tracks story state (e.g. "met_npc_aldric", "discovered_temple")
Trigger system — quests auto-start on events: FirstJoin, ZoneEnter, NpcInteract, QuestComplete, FactChange
Sequential objectives — force players to complete objectives in order
Prerequisites — unlock quests based on completed quests, chapters, achievements, or facts
Chapter rewards — bonus lootbags, titles, and tokens on chapter completion

Side Quests

14 side quests — optional standalone quests tied to specific NPCs and regions
Prerequisites based on story progress
Mixed objective types: combat, gathering, crafting, exploration

NPC Quest Givers

17 unique quest NPCs with full dialog trees (Offer, Active, Complete phases)
Priority-based selection — NPCs with multiple quests offer the most relevant one first
Quest selection dialog — when 2+ quests are available, players pick via a selection screen
Multi-NPC quests — different NPCs for quest accept and turn-in (split NPC mode)
Proximity whisper — NPCs whisper context-aware messages when players walk nearby
Wave animation — NPCs wave when they have a quest to offer
306 localized dialog keys — all NPC text fully translated (EN + DE)

Proximity Notifications

Proximity toast HUD — shows nearby quest NPCs with distance and compass direction
Toast pop-ups — quest started, progress milestones (25%, 50%, 75%), quest complete
Login notifications — available and turn-in-ready quests shown on login (with NPC skin icons)
Chat messages — progress updates, token balance changes, reroll confirmations
Server broadcasts — optional server-wide announcements for completions

Objective Types

Type	Description	Anti-Exploit
`blocks_mined`	Mine specific blocks (wildcards: `Ore_*`)	PlacedBlockTracker prevents mining self-placed blocks
`blocks_chopped`	Chop trees and wood	—
`blocks_dug`	Dig dirt, sand or gravel	—
`blocks_placed`	Place specific blocks	—
`blocks_harvested`	Harvest crops with F-key	—
`flowers_picked`	Pick flowers	—
`kills`	Kill specific mobs (wildcards: `Goblin_*`)	—
`player_kills`	PvP kills	—
`damage_dealt`	Deal X total damage	—
`damage_taken`	Survive X total damage	—
`items_collected`	Have X items in inventory (real-time scan)	—
`items_crafted`	Craft specific items	—
`items_consumed`	Consume food or potions	—
`distance_traveled`	Walk or run distance (blocks)	—
`zones_discovered`	Discover named zones (deduplicated)	—
`playtime_minutes`	Play for a duration	—
`interact_npc`	Talk to a specific NPC	—

Target matching: Exact (Rock_Stone), Wildcard (Ore_*), Group (group:Stone), Property (@consumable matches all edible items), Multi-target (["Ore_Iron", "Ore_Copper"]), or any.

Conditional objectives — restrict progress to specific biomes, zones, weather, time of day, tools, or minimum level.

Reward Types

Type	Description
Items	Grant items with quantity — scales with tier multiplier
Quest Tokens	Internal currency for the Token Shop
Lootbags	Random loot via KyuubiSoft Core's lootbag system
Achievements	Unlock achievements (Achievement System integration)
Titles	Grant in-game titles
Commands	Execute console or player commands

Tier multiplier — higher-tier quests scale reward quantities automatically
Auto-pending — if inventory is full, rewards are saved and can be claimed later

Quest Tiers

Tier	Color	Weight	Reward Multiplier
Common	Gray	50	1.0x
Rare	Blue	30	2.0x
Epic	Purple	15	3.0x
Legendary	Orange	5	5.0x

Tiers are fully configurable — add, remove, or rename them in config.json. Lower weight means rarer appearance in daily/weekly pools.

Streak System

Stay active and earn bonus rewards:

Milestone	Days Required	Reward
Bronze	7 days	Lootbag + Tokens
Silver	14 days	Lootbag + Tokens
Gold	21 days	Lootbag + Tokens
Platinum	28 days	Lootbag + Tokens

Anti-FOMO — "7 days within 14 days" model. Missing a day doesn't break your streak immediately.
Grace period — configurable buffer before streak resets
Tracks current streak and longest streak per player

Quest Token Shop

Spend your earned tokens on exclusive items.

Persistent section — always-available items
Daily rotation — configurable rotating items per day
Purchase limits — max purchases per item per day
NPC merchant — dedicated token shop NPC (citizen_5)
Custom items — add your own items via custom/custom_quest_token_shop.json

Quest Book UI

Open with /ksquest — the central place for all quest content.

Tab navigation: Daily, Weekly, Story, Active, Stats
Active quest sidebar — shows up to 20 active quests with individual objective progress
Quest details — objectives with progress, rewards, prerequisites, difficulty badge
Turn-in info — shows where to complete each quest (NPC name + coordinates or QuestBook)
Tier badges with color coding
Claim rewards button (NPC turn-in quests show "Turn in at NPC" instead)
Reroll button with cost display
Quest tracking — pin up to 5 quests to the HUD
Stats tab — streak, tokens, completed count, active count, daily/weekly progress
Fully localized — all text supports multiple languages

HUD Tracker

Real-time quest progress on screen.

Track up to 5 quests simultaneously (configurable)
Shows quest name, up to 5 objectives per quest, and progress
Turn-in hints — shows "Turn in at NPC-Name" or "Open QuestBook" when all objectives complete
Color-coded by tier
6 position presets + custom X/Y positioning
Per-player settings — each player saves their own HUD preferences
MHUD integration for compatibility with other HUD mods

Player HUD Settings (`/ksquestsettings`)

Toggle HUD on/off
Choose position preset or set custom coordinates
Adjust max displayed quests (1-10) and max objectives per quest (1-5)
Toggle progress display and empty-state message

Admin Panel

Accessible through the KyuubiSoft Core dashboard or /ksquestadmin panel — manage everything in-game.

Quest Editor

Create, edit, duplicate, delete quests via a visual editor
Multi-language name & description fields
Objective builder — pick type, set targets, amounts, and conditions
Reward builder — pick type, set items, amounts, and multipliers
Prerequisites editor — chain quests, require achievements or facts
Tier assignment, sequential toggle, difficulty setting

Pool Management

View and edit daily/weekly quest pools
Add or remove quests from rotation
Adjust tier weights

Player Management

View any player's quest data
Reset data, grant/revoke quests, adjust tokens
View completion statistics

Settings Editor

Edit all config values via UI
Reset times, quest counts, streak settings, tier system, notification thresholds
Live reload — changes apply immediately after save
Default config disable flags — skip base quests and load only custom content

Debug Tools

/ksquestadmin debugmode — live tracking in chat showing all events and quest matches
/ksquestadmin complete — force-complete any quest for testing

Commands

Player Commands

Command	Aliases	Description
`/ksquest`	`/questbook`, `/qb`	Open the Quest Book
`/ksquestsettings`	—	Open HUD settings

Admin Commands

Command	Description
`/ksquestadmin panel`	Open Admin Panel
`/ksquestadmin reload`	Reload configuration
`/ksquestadmin resetme`	Reset own quest data (testing)
`/ksquestadmin debugmode`	Toggle live debug tracking
`/ksquestadmin tokens [amount]`	Give yourself tokens
`/ksquestadmin complete <questId>`	Force-complete a quest
`/ksquestadmin start <questId>`	Force-start a quest
`/ksquestadmin testfirstjoin`	Simulate first-join trigger
`/ksquestadmin testzone <zone>`	Simulate zone discovery
`/ksquestadmin testnpc <npcId>`	Simulate NPC interaction

Permission: questbook.admin

Configuration

KyuubiSoft-Quests/
├── config.json                  # Main settings (resets, tiers, economy, HUD)
├── quests.json                  # Daily, weekly and side quest definitions
├── story_quests.json            # Story quest definitions
├── chapters.json                # Chapter definitions & progression
├── daily_pool.json              # Daily rotation pool
├── weekly_pool.json             # Weekly rotation pool
├── quest_npc_profiles/          # NPC quest giver profiles
│   ├── guide_finn.json          # Example: Guide Finn (tutorial quests)
│   └── ...                      # 17 NPC profiles included
├── data/
│   └── <uuid>.json              # Per-player quest data (auto-managed)
├── custom/
│   └── custom_*.json            # Custom overrides for quests and pools
└── localization/
    ├── en-US.json               # English translations (~800 keys)
    └── de-DE.json               # German translations (~800 keys)

Quest Definition Example

{
  "id": "daily_mine_stone",
  "type": "daily",
  "category": "gathering",
  "difficulty": "easy",
  "icon_item": "Tool_Pickaxe_Iron",
  "objectives": [
    {
      "id": "obj_1",
      "type": "blocks_mined",
      "target": "Rock_Stone*",
      "count": 50
    }
  ],
  "rewards": [
    { "type": "quest_tokens", "amount": 3 },
    { "type": "item", "item_id": "Ore_Iron", "amount": 5 }
  ],
  "options": {
    "repeatable": true,
    "tier": "common",
    "weight": 50,
    "pool": "mining"
  }
}

For Mod Developers

Access the Quest System through the public QuestAPI:

QuestAPI api = QuestAPI.getInstance();

// Event Listeners
api.onQuestStarted((player, questId) -> { ... });
api.onQuestCompleted((player, questId) -> { ... });
api.onQuestAbandoned((player, questId) -> { ... });

// Queries
Set<String> allQuests = api.getAllQuestIds();
Set<String> dailyQuests = api.getQuestsByType("daily");

// Facts Database
String value = api.getPlayerFact(player, "met_finn");
api.setPlayerFact(player, "discovered_temple", "true");
boolean result = api.checkFactConditions(player, conditions);

Anti-Exploit

PlacedBlockTracker — prevents mining self-placed blocks for quest credit (30min expiry, configurable)
Zone deduplication — each zone counts only once per objective (no portal spam)
Prerequisite validation — can't start locked quests
Completion checks — can't claim rewards without finishing all objectives
NPC turn-in protection — quests assigned to NPCs can't be claimed via QuestBook
Reroll guards — can't reroll started quests, max rerolls per day

Compatibility

Integrates with: Achievement System, MHUD
Server: Hytale Dedicated Server
Java: 21+

Support

Discord: KyuubiSoft Discord

Made with Love by KyuubiSoft

KyuubiSoft Quest System (Story, Daily, Weekly, Quest Store)