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.
Overview
Section titled “Overview”When a player talks to an NPC that has a quest profile, the first step that fits wins:
- Delivery open — the player has a
deliverobjective for this NPC and carries items for it: the delivery confirmation opens. - 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).
- 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.
- Quest running — the player has an active quest from this NPC: the reminder dialog.
- Not ready — quests exist but no requirement is met yet: the “not ready” dialog.
- Default — the default dialog.
- Otherwise — without a default dialog, the NPC does what Core’s NPC management set up: shop, bank or Core dialogs.
Profile JSON Structure
Section titled “Profile JSON Structure”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"] }}Top-Level Fields
Section titled “Top-Level Fields”| Field | Required | Description |
|---|---|---|
citizenId | Yes | Must match the Citizen ID from the Citizens system |
_config_version | No | Schema version for auto-update detection (current: “2”) |
quests | Yes | Array of quest dialog entries |
selectionIntro | No | Greeting above the quest choice when the NPC offers several quests at once (empty = first line of the default dialog) |
defaultDialog | No | Dialog when no entry fits. Without it, the NPC keeps opening its shop, bank and Core dialogs |
notReadyDialog | No | Shown when entries are open but none fits yet |
proximityMessages | No | Chat whisper messages for proximity detection |
proximityRange | No | Whisper range in blocks, 1 to 64 (default: 12) |
proximityCooldown | No | Seconds between whispers per player, 0 to 86400 (default: 300) |
Quest Dialog Entry
Section titled “Quest Dialog Entry”Each entry in the quests array ties a quest to this NPC with phase-specific dialogs:
| Field | Required | Description |
|---|---|---|
questId | Yes | Quest definition ID to link |
priority | No | Lower number = checked first (default: 10) |
requires | No | Array of quest IDs that must be completed first |
offer | No | Dialog shown when quest is available to accept |
active | No | Dialog shown while quest is in progress |
complete | No | Dialog shown when objectives are done and quest can be turned in |
Dialog Formats
Section titled “Dialog Formats”Simple Format
Section titled “Simple Format”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"}Full Format (Nodes)
Section titled “Full Format (Nodes)”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." } ] } ]}Actions and Macros
Section titled “Actions and Macros”| Action | Description |
|---|---|
start_quest | Starts the linked quest for the player. All requirements apply |
complete_quest | Claims the linked quest like the Claim button: objectives are checked and consumed items are verified, then the rewards are paid |
set_fact:name=value | Sets a story fact for the player (set_fact:name sets it to true). Also read as set_fact name=value |
| any other text | Runs 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.
Multiple Quests Per NPC
Section titled “Multiple Quests Per NPC”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"] } ]}Proximity Detection
Section titled “Proximity Detection”Chat Whispers
Section titled “Chat Whispers”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.
Proximity Hint HUD
Section titled “Proximity Hint HUD”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 } }World Map Markers
Section titled “World Map Markers”Quest NPCs automatically receive world map markers based on the player’s quest status:
| Marker | Meaning |
|---|---|
quest_available | NPC has a quest the player can accept |
quest_turn_in | NPC can receive a completed quest |
quest_progress | Player 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.
Editing in game
Section titled “Editing in game”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 dialogs and quests
Section titled “Core dialogs and quests”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
questbookorquestbook.settings. - Conditions:
quest_active,quest_completed,quest_available,quest_ready(active and every objective done) andfact(reads the Quests facts, for examplechapter_<id>_completed).
File Location
Section titled “File Location”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”.