Skip to content

NPC Quest Profiles

NPC Quest Profiles connect Citizens (NPCs from KyuubiSoft Core) to quests. Each profile defines which quests an NPC offers, what it says in each phase, and how it behaves when a player is nearby. Profiles are JSON files in the quest_npc_profiles/ folder, and since 2.1.0 they are edited in game on the NPC profiles tab of the admin window.

When a player talks to an NPC that has a quest profile, the first step that fits wins:

  1. Delivery open — the player has a deliver objective for this NPC and carries items for it: the delivery confirmation opens.
  2. Turn-in ready — the player has finished a quest this NPC takes in: the completion dialog (or the “ready to claim” strip of the quest giver window).
  3. Offer — the NPC has a quest the player can start. With two or more at once, the quest giver window opens with all of them as cards.
  4. Quest running — the player has an active quest from this NPC: the reminder dialog.
  5. Not ready — quests exist but no requirement is met yet: the “not ready” dialog.
  6. Default — the default dialog.
  7. Otherwise — without a default dialog, the NPC does what Core’s NPC management set up: shop, bank or Core dialogs.

Each profile is a single JSON file per NPC:

{
"citizenId": "smith_gorn",
"quests": [
{
"questId": "story_iron_forge",
"priority": 10,
"requires": ["tutorial_sustainability"],
"offer": { "speaker": "Gorn", "nodes": [/* ... */] },
"active": { "speaker": "Gorn", "lines": ["npc.smith_gorn.active.1"] },
"complete": { "speaker": "Gorn", "lines": ["..."], "action": "complete_quest" }
}
],
"proximityMessages": {
"offer": "npc.smith_gorn.proximity.offer",
"active": "npc.smith_gorn.proximity.active",
"complete": "npc.smith_gorn.proximity.complete",
"defaultMsg": "npc.smith_gorn.proximity.default"
},
"proximityRange": 20,
"proximityCooldown": 300,
"defaultDialog": { "speaker": "Gorn", "lines": ["npc.smith_gorn.default.1"] },
"notReadyDialog": { "speaker": "Gorn", "lines": ["npc.smith_gorn.not_ready.1"] }
}
FieldRequiredDescription
citizenIdYesMust match the Citizen ID from the Citizens system
_config_versionNoSchema version for auto-update detection (current: “2”)
questsYesArray of quest dialog entries
selectionIntroNoGreeting above the quest choice when the NPC offers several quests at once (empty = first line of the default dialog)
defaultDialogNoDialog when no entry fits. Without it, the NPC keeps opening its shop, bank and Core dialogs
notReadyDialogNoShown when entries are open but none fits yet
proximityMessagesNoChat whisper messages for proximity detection
proximityRangeNoWhisper range in blocks, 1 to 64 (default: 12)
proximityCooldownNoSeconds between whispers per player, 0 to 86400 (default: 300)

Each entry in the quests array ties a quest to this NPC with phase-specific dialogs:

FieldRequiredDescription
questIdYesQuest definition ID to link
priorityNoLower number = checked first (default: 10)
requiresNoArray of quest IDs that must be completed first
offerNoDialog shown when quest is available to accept
activeNoDialog shown while quest is in progress
completeNoDialog shown when objectives are done and quest can be turned in

Uses a flat list of text lines. For offer dialogs, add acceptButton/declineButton:

{
"speaker": "Gorn",
"lines": ["Would you like to help me forge some iron?"],
"acceptButton": "Sure!",
"declineButton": "Maybe later.",
"action": "start_quest"
}

Uses a tree of dialog nodes for branching conversations. Node types: TEXT (shows lines, advances to next) and CHOICE (shows clickable options):

{
"speaker": "Gorn",
"nodes": [
{ "id": "greeting", "type": "TEXT", "lines": ["Welcome!"], "next": "accept" },
{
"id": "accept", "type": "CHOICE", "lines": ["Will you help me?"],
"choices": [
{ "text": "Of course!", "macro": "start_quest" },
{ "text": "Not now." }
]
}
]
}
ActionDescription
start_questStarts the linked quest for the player. All requirements apply
complete_questClaims the linked quest like the Claim button: objectives are checked and consumed items are verified, then the rewards are paid
set_fact:name=valueSets a story fact for the player (set_fact:name sets it to true). Also read as set_fact name=value
any other textRuns as a console command. Adding, changing or removing it needs ks.core.admin.dialog.console (see Permissions)

In the full format, macros are set on individual nodes or choices via the "macro" field. In defaultDialog and notReadyDialog, which belong to no quest, only set_fact and console commands run.

Before 2.0.0, complete_quest force-completed every objective. It now claims normally; story turn-ins with their own dialog steps stay dialogs.

Dialog text values can be literal strings or localization keys (e.g., npc.smith_gorn.default.1). If a matching key exists in the localization files, the translated text is shown.

A single NPC can offer multiple quests. The requires field controls ordering and priority determines check order. When two or more quests are available at the same time, the quest giver window opens with every offered quest as a card (three per page), its objectives, rewards and, for locked quests, the reason.

Example of a sequential quest chain (quests unlock one after another):

{
"citizenId": "guide_finn",
"quests": [
{ "questId": "tutorial_awakening", "priority": 1, "requires": [] },
{ "questId": "tutorial_first_steps", "priority": 2, "requires": ["tutorial_awakening"] },
{ "questId": "tutorial_workbench", "priority": 3, "requires": ["tutorial_first_steps"] }
]
}

When a player comes within proximityRange, a chat whisper is sent based on the current quest phase (offer open, quest running, turn-in ready, otherwise). The message appears as [NPC Name] text. The NPC plays a wave animation when a quest is available. Placeholders {PlayerName} and {CitizenName} are replaced automatically. The cooldown prevents spam (default: 300 seconds per NPC per player). An empty text means no whisper in that situation.

Nearby quest NPCs also show a hint with the NPC’s picture on the HUD. It is set server-wide in config.json:

{ "proximityToast": { "enabled": true, "toastRange": 20.0 } }

Quest NPCs automatically receive world map markers based on the player’s quest status:

MarkerMeaning
quest_availableNPC has a quest the player can accept
quest_turn_inNPC can receive a completed quest
quest_progressPlayer has an active quest from this NPC

Markers update automatically when a player accepts, completes, or abandons a quest. They are per-player, so different players see different markers on the same NPC.

The NPC profiles tab of the admin window (/ksquestadmin npcprofile [citizenId]) edits everything on this page:

  • A list of all profiles with Profile without NPC, Give to another NPC and Who uses this NPC?.
  • Quest entries with phase cards, and a node editor for the offer, active and complete dialogs.
  • Default, “not ready” and proximity texts per language. Shared texts apply everywhere, and every NPC can have its own text.
  • Phase preview for a chosen player and Test dialog, which runs no actions.
  • Open in Core’s dialog editor for the NPC’s Core dialogs.

From Core’s NPC management window, Quest profile … on the Talk tab opens the profile of that NPC, and Back returns to that NPC on the Talk tab, also after the questbook view or Core’s dialog editor was open in between. An NPC without a profile gets a Create profile for this NPC button. Before an NPC’s ID is changed or the NPC is deleted in Core, the NPC management lists everything Quests links to it.

Core’s own dialog editor can also drive quests (with Core 2.9.0 or newer):

  • Actions: Start quest (all requirements apply; the player is told why when it cannot start), Set fact (writes into the Quests facts) and Open window with questbook or questbook.settings.
  • Conditions: quest_active, quest_completed, quest_available, quest_ready (active and every objective done) and fact (reads the Quests facts, for example chapter_<id>_completed).

Profile files are stored in mods/kyuubisoft_questbook/quest_npc_profiles/. Default profiles are extracted from the mod JAR on first startup. You can edit existing profiles or add new ones by creating additional JSON files in this folder. Shipped profiles you delete stay deleted.

The citizenId in the profile must match an existing Citizen in the Citizens system. If the Citizen does not exist, the profile is loaded but has no effect. The admin window lists such profiles as “Profile without NPC”.