KyuubiSoft Quest System

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

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

• 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

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:

• 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

Admin Commands

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