Configuration

Configuration

The Quest System is configured through config.json in the root of your quest data folder. This file controls reset schedules, economy, streaks, the HUD tracker, anti-exploit settings and more.

After editing config.json, run /ksquestadmin reload in-game to apply changes without restarting the server.

Full Config Structure

Below is the complete config.json with all available fields and their default values:

{
  "_config_version": 5,
  "language": "en-US",
  "timezone": "Europe/Berlin",
  "dailyResetTime": "04:00",
  "weeklyResetDay": "MONDAY",
  "dailyQuestCount": 3,
  "weeklyQuestCount": 5,
  "saveIntervalSeconds": 300,
  "debug": false,
  "useCustomContent": true,
  "loadDefaultQuests": true,
  "loadDefaultStoryQuests": true,
  "loadDefaultDailyPool": true,
  "loadDefaultWeeklyPool": true,
  "loadDefaultChapters": true,

  "streak": { ... },
  "questItem": { ... },
  "questTracker": { ... },
  "notifications": { ... },
  "economy": { ... },
  "tierSystem": { ... },
  "reroll": { ... },
  "placedBlockTracker": { ... },
  "proximityToast": { ... }
}

General Settings

Field	Type	Default	Description
language	string	"en-US"	UI and localization language. Supported: en-US, de-DE
timezone	string	"Europe/Berlin"	Timezone for reset calculations (Java ZoneId format)
dailyResetTime	string	"04:00"	Time when daily quests rotate (24h format, e.g. "04:00")
weeklyResetDay	string	"MONDAY"	Day when weekly quests rotate (e.g. MONDAY, FRIDAY)
dailyQuestCount	int	3	Number of daily quests assigned to each player
weeklyQuestCount	int	5	Number of weekly quests assigned to each player
saveIntervalSeconds	int	300	Auto-save interval for player data in seconds
debug	bool	false	Enable verbose debug logging to console
useCustomContent	bool	true	Load content from the custom/ folder
loadDefaultQuests	bool	true	Load base quests from quests.json. Set false to only use custom quests
loadDefaultStoryQuests	bool	true	Load base story quests from story_quests.json. Set false to only use custom story quests
loadDefaultDailyPool	bool	true	Load base daily quest pool from daily_pool.json. Set false to only use custom pool
loadDefaultWeeklyPool	bool	true	Load base weekly quest pool from weekly_pool.json. Set false to only use custom pool
loadDefaultChapters	bool	true	Load base chapters from chapters.json. Set false to only use custom chapters

Streak System

The streak system rewards players for completing at least one quest per day. It uses a cumulative model with a grace period to avoid punishing missed days.

"streak": {
  "enabled": true,
  "cumulative": true,
  "gracePeriodDays": 7,
  "gracePeriodWindow": 14,
  "milestones": [
    { "days": 7,  "lootbagId": "streak_reward_7",  "tier": "bronze" },
    { "days": 14, "lootbagId": "streak_reward_14", "tier": "silver" },
    { "days": 21, "lootbagId": "streak_reward_21", "tier": "gold" },
    { "days": 28, "lootbagId": "streak_reward_28", "tier": "platinum" }
  ]
}

Field	Type	Default	Description
enabled	bool	true	Enable/disable the streak system
cumulative	bool	true	Anti-FOMO mode: days don’t need to be consecutive
gracePeriodDays	int	7	Required active days within the window
gracePeriodWindow	int	14	Rolling window in days (e.g. 7 days out of 14)
milestones	array	4 tiers	Milestone rewards at specific day counts

Each milestone grants a loot bag reward when the player reaches the specified day count.

Quest Item

Controls the physical Quest Book item given to players.

"questItem": {
  "enabled": true,
  "itemId": "QuestBook",
  "hotbarSlot": 8,
  "giveOnJoin": true,
  "giveDelay": 500
}

Field	Type	Default	Description
enabled	bool	true	Give players a quest book item
itemId	string	"QuestBook"	The item ID to use
hotbarSlot	int	8	Hotbar slot (0-8) to place the item
giveOnJoin	bool	true	Automatically give item when player joins
giveDelay	int	500	Delay in ms before giving the item after join

Quest Tracker (HUD)

Controls the on-screen HUD that displays tracked quest progress.

"questTracker": {
  "enabled": true,
  "maxDisplayedQuests": 5,
  "maxDisplayedObjectives": 5,
  "showOnJoin": true,
  "position": "right",
  "maxTrackedQuests": 5,
  "autoUntrackCompleted": true,
  "defaultPositionPreset": "top_right",
  "defaultShowEmptyState": true
}

Field	Type	Default	Description
enabled	bool	true	Enable the HUD tracker
maxDisplayedQuests	int	5	Max quests shown on the HUD at once
maxDisplayedObjectives	int	5	Max objectives shown per quest
showOnJoin	bool	true	Show tracker automatically when player joins
position	string	"right"	HUD side: "left" or "right"
maxTrackedQuests	int	5	Max quests a player can track simultaneously
autoUntrackCompleted	bool	true	Auto-remove completed quests from tracker
defaultPositionPreset	string	"top_right"	Default position for new players. Options: top_left, top_right, middle_left, middle_right, bottom_left, bottom_right
defaultShowEmptyState	bool	true	Show the HUD even when no quests are tracked

Tip

Use "position": "left" if you have other mods (like a minimap) using the right side of the screen.

Notifications

"notifications": {
  "enabled": true,
  "showProgress": true,
  "progressThreshold": 25,
  "broadcastCompletion": false
}

Field	Type	Default	Description
enabled	bool	true	Enable quest notifications
showProgress	bool	true	Show progress milestones (25%, 50%, 75%)
progressThreshold	int	25	Percentage interval for progress notifications
broadcastCompletion	bool	false	Broadcast quest completions to all players

Economy

Controls quest economy, currency display, reroll costs, and token earnings.

"economy": {
  "provider": "auto",
  "primaryCurrency": "quest_tokens",
  "alternativeCurrency": "gold",
  "rewardCurrency": "quest_tokens",
  "tokenExchangeRate": 100,
  "rerollCostTokens": 5,
  "rerollCostGold": 200,
  "tokenEarnings": {
    "dailyQuestComplete": 1,
    "allDailiesBonus": 2,
    "weeklyQuestComplete": 5,
    "streakBronze": 5,
    "streakSilver": 10,
    "streakGold": 15,
    "streakPlatinum": 20
  }
}

Field	Type	Default	Description
provider	string	"auto"	Economy provider. auto detects VaultUnlocked → EliteEssentials. Options: auto, vaultunlocked, eliteessentials, internal, command
primaryCurrency	string	"quest_tokens"	Primary currency identifier
alternativeCurrency	string	"gold"	Alternative currency identifier (used for gold rerolls)
rewardCurrency	string	"quest_tokens"	Currency used for quest rewards. Set to "economy" to grant external currency (e.g. Gold) instead of tokens. Token amounts are converted via tokenExchangeRate
tokenExchangeRate	int	100	Conversion rate: 1 Quest Token = X Gold. Only used when rewardCurrency = "economy"
rerollCostTokens	int	5	Token cost per quest reroll. Set to 0 to disable token rerolls
rerollCostGold	int	200	Gold cost per quest reroll. Set to 0 to disable gold rerolls. Requires external economy
tokenEarnings.dailyQuestComplete	int	1	Tokens earned per daily quest completed
tokenEarnings.allDailiesBonus	int	2	Bonus tokens for completing ALL daily quests
tokenEarnings.weeklyQuestComplete	int	5	Tokens earned per weekly quest completed

Tier System

The tier system assigns rarity tiers to daily/weekly quests. Higher tiers have harder objectives but better rewards.

"tierSystem": {
  "enabled": true,
  "tiers": [
    { "id": "common",    "difficulty": "easy",      "color": "#A0A0A0", "multiplier": 1.0, "weight": 50, "name": { "en": "Common",    "de": "Gewoehnlich" } },
    { "id": "rare",      "difficulty": "medium",    "color": "#4169E1", "multiplier": 2.0, "weight": 30, "name": { "en": "Rare",      "de": "Selten" } },
    { "id": "epic",      "difficulty": "hard",      "color": "#9932CC", "multiplier": 3.0, "weight": 15, "name": { "en": "Epic",      "de": "Episch" } },
    { "id": "legendary", "difficulty": "legendary", "color": "#FFD700", "multiplier": 5.0, "weight": 5,  "name": { "en": "Legendary", "de": "Legendaer" } }
  ]
}

Field	Type	Description
id	string	Unique tier identifier (referenced in quest definitions)
difficulty	string	Difficulty label
color	string	Hex color code for UI display
multiplier	float	Reward multiplier for this tier
weight	int	Selection weight (higher = more likely to appear)
name	object	Localized display name

Tip

You can define as many custom tiers as you want. The weight values determine how often each tier appears when daily/weekly quests are assigned.

Reroll System

Allows players to re-roll their daily quests.

"reroll": {
  "enabled": true,
  "freeRerollsPerDay": 1,
  "paidRerollCost": 10,
  "maxPaidRerollsPerDay": 5,
  "allowRerollStarted": false
}

Field	Type	Default	Description
enabled	bool	true	Enable quest rerolling
freeRerollsPerDay	int	1	Free rerolls per day
paidRerollCost	int	10	Quest token cost for a paid reroll (doubles each time)
maxPaidRerollsPerDay	int	5	Maximum paid rerolls per day
allowRerollStarted	bool	false	Allow rerolling quests that have progress

Paid reroll costs double with each use: 10 -> 20 -> 40 -> 80 -> 160. This prevents abuse while still giving players flexibility.

:::tip Per-Quest Reroll Limit Individual quests can set their own reroll limit via options.maxRerolls in the quest definition. This overrides the global maxPaidRerollsPerDay setting for that specific quest. Default per-quest limit is 1. :::

Placed Block Tracker (Anti-Exploit)

Prevents players from gaining quest progress by placing and breaking their own blocks.

"placedBlockTracker": {
  "enabled": true,
  "expiryMinutes": 30
}

Field	Type	Default	Description
enabled	bool	true	Enable the anti-exploit tracker
expiryMinutes	int	30	After this time, placed blocks count as natural again

Proximity Toast

Shows an NPC toast notification on the HUD when a player approaches a quest NPC.

"proximityToast": {
  "enabled": true,
  "range": 20,
  "cooldown": 300,
  "durationMs": 0
}

Field	Type	Default	Description
enabled	bool	true	Enable proximity toast notifications
range	int	20	Detection radius in blocks
cooldown	int	300	Seconds between proximity toasts per NPC per player
durationMs	int	0	Display duration. 0 = stays while in range, >0 = auto-hide after N ms