Skip to content

API Reference

Technical reference for plugin developers and advanced users. Includes the public API for external plugin integration.


External plugins can interact with the Quest System through a stable public API.

import com.kyuubisoft.quests.api.QuestAPI;
// Get API instance
QuestAPI api = QuestAPI.getInstance();
if (api == null) {
// Quest plugin not loaded
return;
}
// Or with availability check
if (QuestAPI.isAvailable()) {
QuestAPI api = QuestAPI.getInstance();
// ...
}
MethodDescription
getActiveQuests(UUID)Map of active quest IDs to QuestProgress
getCompletedQuests(UUID)Set of completed quest IDs
hasActiveQuest(UUID, String)Check if quest is active
hasCompletedQuest(UUID, String)Check if quest is completed
getQuestProgress(UUID, String)Get QuestProgress for a quest
getQuestDefinition(String)Get quest definition by ID
getAllQuestIds()List of all available quest IDs
getQuestsByType(String)Get quests by type (daily/weekly/story/side/hub)
MethodDescription
getCurrentDailyQuests(UUID)Current daily quest IDs for player
getCurrentWeeklyQuests(UUID)Current weekly quest IDs for player
getTimeUntilDailyReset()Duration until next daily reset
getTimeUntilWeeklyReset()Duration until next weekly reset
MethodDescription
getCurrentStreak(UUID)Player’s current completion streak
getLongestStreak(UUID)Player’s longest streak ever
MethodDescription
startQuest(Player, String)Start a quest (returns success)
abandonQuest(Player, String)Abandon an active quest
updateProgress(Player, String, String, int)Update objective progress (questId, objectiveId, amount)
processTrigger(Player, String, String, int)Process trigger for all active quests (type, target, amount)
MethodDescription
getQuestTokens(UUID)Get token balance
addQuestTokens(UUID, int)Add tokens
spendQuestTokens(UUID, int)Spend tokens (returns false if insufficient)
MethodDescription
onQuestStarted(BiConsumer<Player, String>)Listen for quest start events
onQuestCompleted(BiConsumer<Player, String>)Listen for quest completion events
onQuestAbandoned(BiConsumer<Player, String>)Listen for quest abandon events
removeStartListener(BiConsumer)Remove start listener
removeCompleteListener(BiConsumer)Remove complete listener
removeAbandonListener(BiConsumer)Remove abandon listener
MethodDescription
getPlayerFact(UUID, String)Get a story fact value
setPlayerFact(UUID, String, Object)Set a story fact value
checkFactConditions(UUID, List<String>)Check fact conditions
QuestAPI api = QuestAPI.getInstance();
// Does the player have an active quest?
if (api.hasActiveQuest(player.getUUID(), "merchant_delivery")) {
player.sendMessage("You still have a delivery to complete!");
}
// Check completion
if (api.hasCompletedQuest(player.getUUID(), "main_story_01")) {
player.sendMessage("Chapter 1 complete!");
}
// Show progress
QuestProgress progress = api.getQuestProgress(player.getUUID(), "kill_spiders");
if (progress != null) {
player.sendMessage("Quest progress: " + progress.getCurrentProgress() + "/" + progress.getRequiredProgress());
}
QuestAPI api = QuestAPI.getInstance();
api.onQuestCompleted((player, questId) -> {
// Firework effect or similar
spawnFirework(player.getLocation());
// Logging
LOGGER.info(player.getDisplayName() + " completed quest " + questId + "!");
// Chain into next quest
if (questId.equals("main_story_01")) {
api.startQuest(player, "main_story_02");
}
});
api.onQuestAbandoned((player, questId) -> {
LOGGER.info(player.getDisplayName() + " abandoned quest " + questId);
});
QuestAPI api = QuestAPI.getInstance();
// Start quest on special event
if (specialEventTriggered) {
boolean started = api.startQuest(player, "special_event_quest");
if (started) {
player.sendMessage("New quest started!");
} else {
// Player already has quest, quest doesn't exist, or prerequisites not met
player.sendMessage("Could not start quest.");
}
}
// Update progress manually
api.updateProgress(player, "gather_resources", "collect_wood", 5);
// Process a trigger across all active quests
api.processTrigger(player, "kills", "Spider", 1);
QuestAPI api = QuestAPI.getInstance();
// Check balance
int tokens = api.getQuestTokens(player.getUUID());
player.sendMessage("Quest Tokens: " + tokens);
// Spend tokens for a reward
if (api.spendQuestTokens(player.getUUID(), 50)) {
grantReward(player);
} else {
player.sendMessage("Not enough tokens! Need 50, have " + tokens);
}
// Grant bonus tokens
api.addQuestTokens(player.getUUID(), 25);
QuestAPI api = QuestAPI.getInstance();
// Set a story fact
api.setPlayerFact(player.getUUID(), "rescued_villager", true);
api.setPlayerFact(player.getUUID(), "chosen_faction", "rebels");
// Read a fact
Object faction = api.getPlayerFact(player.getUUID(), "chosen_faction");
if ("rebels".equals(faction)) {
player.sendMessage("The rebels welcome you back!");
}
// Check multiple conditions at once
List<String> conditions = List.of("rescued_villager=true", "chosen_faction=rebels");
if (api.checkFactConditions(player.getUUID(), conditions)) {
// All conditions met - unlock special dialogue
api.startQuest(player, "rebel_secret_mission");
}
  • The API is thread-safe using CopyOnWriteArrayList for listeners
  • All query methods can be called from any thread
  • Modification methods should be called on the player’s world thread
  • Facts database access is synchronized

The QuestAPI provides cross-mod integration for the quest system. Other mods can listen for quest events and query quest data.

Register callbacks that fire when quest state changes:

MethodParametersDescription
onQuestStarted(listener)BiConsumer<Player, String>Fires when a player starts a quest
onQuestCompleted(listener)BiConsumer<Player, String>Fires when a player completes a quest
onQuestAbandoned(listener)BiConsumer<Player, String>Fires when a player abandons a quest
QuestAPI.getInstance().onQuestCompleted((player, questId) -> {
logger.info(player.getDisplayName() + " completed " + questId);
});
MethodReturnsDescription
getAllQuestIds()List<String>All registered quest IDs
getQuestsByType(type)List<QuestDefinition>Quests filtered by type (story, daily, weekly, side)

Facts are per-player key-value pairs used for story state tracking:

MethodReturnsDescription
getPlayerFact(playerId, key)ObjectGet a fact value for a player
setPlayerFact(playerId, key, value)voidSet a fact value
checkFactConditions(playerId, conditions)booleanCheck if all fact conditions are met

With KyuubiSoft Core 2.9.0 or newer, Quests registers itself in Core’s dialog system:

HookKindWhat it does
start_questDialog actionStarts a quest through the normal start (all requirements apply)
set_factDialog actionWrites into the Quests facts while Quests is loaded
questbook, questbook.settingsWindow for “Open window”Opens the Questbook or its settings
quest_active, quest_completed, quest_available, quest_readyDialog conditionsQuest state of the player
factDialog conditionReads the Quests facts while Quests is loaded
NPC referencesReference providerLists everything Quests links to an NPC before Core renames or deletes it

On older Core versions these hooks are skipped with one log line.


mods/kyuubisoft_questbook/
├── config.json - Main configuration
├── configs/ - Shipped content (quests, story quests, chapters, pools, token shop)
├── custom/ - Your content and quest packs
├── quest_npc_profiles/ - NPC quest profiles
├── localization/ - Language files
├── backups/ - Admin window backup sets
├── exports/ - Exports and import files
├── players/ - Player data (file storage)
└── server_stats.json - Server statistics

With Core’s MySQL storage, player data is stored in the table quest_players (with Core’s table prefix, default ks_quest_players).

For translation keys, see Localization.