Skip to content

Quest + NPC Workflow

This guide walks you through a complete side quest with an NPC quest giver: the player accepts it from the NPC, chops wood, brings logs back and gets a reward. You can do everything in game with the admin windows (recommended) or with files.

You will create:

  • A citizen (NPC) that stands in the world (KyuubiSoft Core)
  • A quest with objectives and rewards (KyuubiSoft Quests)
  • An NPC quest profile that links the citizen to the quest with dialogs
  • Texts for every language you want

You need ks.quest.admin for the Quests admin window and ks.citizen.admin (or ks.admin) for Core’s NPC tools.


  1. Stand where the NPC should be and run /kscitizen create woodcutter_wren.
  2. Run /kscitizen edit woodcutter_wren to open Core’s NPC management window. Set the name (“Wren”), the appearance and the behaviour, then Save.

See Citizens & NPCs for everything the NPC window can do.

  1. Open the Quests admin window with /ksquestadmin panel.
  2. On Quests, choose New quest, pick a template and give it the ID wren_firewood.
  3. In the quest editor:
    • Basics: type Side, category, difficulty, icon.
    • Texts: name and description per language. Missing languages fall back to English.
    • Objectives: Chop wood Wood_Oak* × 20, then Deliver Wood_Oak_Trunk × 10 with Deliver to woodcutter_wren.
    • Rewards: for example 5 quest tokens and 5 Food_Bread. The editor shows the final values after the tier factor.
    • NPC phases: Wren offers the quest and takes it in.
  4. Save. The check blocks saving if something is wrong and shows where.
  1. Back in Core’s NPC management (/kscitizen edit woodcutter_wren), open the Talk tab and press Quest profile …. This opens the Quests profile editor for Wren; Create profile for this NPC creates the profile file.
  2. The quest entry for wren_firewood has three phase cards: offer, active and complete. Write the lines per language. In the node editor, give the accept choice the action Accept quest and the last node of the complete dialog Turn in quest.
  3. Optional: proximity whispers (range, pause and texts) and a default dialog for when no quest fits.
  4. Save, then Back returns you to the NPC.
  • Test dialog in the profile editor plays the dialog without running any action.
  • Test for me in the quest editor: Start for me, Nearly done (every objective one step from the end) and Reset.
  • Then talk to Wren as a player: accept, chop, come back. The delivery confirmation shows the logs Wren takes; Hand in, then claim the reward.

Create the NPC in game with /kscitizen create woodcutter_wren (it is saved to Core’s custom/custom_citizens.json), or write it into that file by hand. The fields are described in Citizen Configuration.

Create or edit mods/kyuubisoft_questbook/custom/custom_quests.json:

{
"quests": [
{
"id": "wren_firewood",
"type": "side",
"category": "gathering",
"icon_item": "Wood_Oak_Trunk",
"name": { "en-US": "Firewood for Wren", "de-DE": "Feuerholz für Wren" },
"description": {
"en-US": "Wren needs oak logs for the winter.",
"de-DE": "Wren braucht Eichenstämme für den Winter."
},
"objectives": [
{ "id": "chop", "type": "blocks_chopped", "target": "Wood_Oak*", "count": 20 },
{ "id": "bring", "type": "deliver", "target": "Wood_Oak_Trunk", "count": 10, "deliverTo": "woodcutter_wren" }
],
"rewards": [
{ "type": "quest_tokens", "amount": 5 },
{ "type": "item", "item_id": "Food_Bread", "amount": 5 }
]
}
]
}
FieldDescription
idUnique quest ID (snake_case)
typeside, story, daily or weekly
icon_itemItem ID shown as the quest icon
name, descriptionTexts per language (or use translation keys, see Step 3)
objectivesWhat the player must do: type, target, count. See Objectives
rewardsWhat the player gets. See Rewards
prerequisitesOptional: quests, facts, level or permission needed first. See Story Quests

Instead of inline texts you can use translation keys in mods/kyuubisoft_questbook/localization/custom_en-US.json (and custom_de-DE.json and so on):

{
"quest.wren_firewood.name": "Firewood for Wren",
"quest.wren_firewood.description": "Wren needs oak logs for the winter.",
"quest.wren_firewood.obj.chop": "Chop oak trees",
"quest.wren_firewood.obj.bring": "Bring 10 oak logs to Wren"
}
KeyUsage
quest.<questId>.nameQuest name
quest.<questId>.descriptionQuest description
quest.<questId>.obj.<objectiveId>Objective text

Custom files (custom_<lang>.json) are never overwritten by updates.

Create mods/kyuubisoft_questbook/quest_npc_profiles/woodcutter_wren.json:

{
"citizenId": "woodcutter_wren",
"quests": [
{
"questId": "wren_firewood",
"priority": 10,
"offer": {
"speaker": "Wren",
"nodes": [
{ "id": "greeting", "type": "TEXT", "lines": ["Winter is coming and my woodpile is empty."], "next": "ask" },
{
"id": "ask", "type": "CHOICE", "lines": ["Could you bring me ten oak logs?"],
"choices": [
{ "text": "I'll do it!", "macro": "start_quest" },
{ "text": "Not right now." }
]
}
]
},
"active": { "speaker": "Wren", "lines": ["Still need those ten oak logs."] },
"complete": { "speaker": "Wren", "lines": ["Wonderful, that will keep me warm!"], "action": "complete_quest" }
}
],
"defaultDialog": { "speaker": "Wren", "lines": ["Thanks again for the firewood!"] }
}
FieldDescription
citizenIdMust match the NPC ID
questsOne entry per quest, with offer, active and complete dialogs
macro / actionstart_quest accepts, complete_quest claims the quest (objectives and consumed items are checked), set_fact:name=value sets a story fact. Any other text runs as a console command and needs ks.core.admin.dialog.console
defaultDialogShown when no entry fits. Without it, the NPC keeps its shop, bank and Core dialogs

Lines can be plain text or translation keys. See NPC Quest Profiles for every field, proximity whispers and the full node format.

  1. /ksquestadmin reload reloads quests, NPC profiles and texts.
  2. If you edited Core’s NPC file by hand, /kscitizen reload loads it.
  3. /ksquestadmin debugmode shows live tracking events in the server console.
  4. Talk to the NPC, accept the quest, chop, deliver, claim.
  5. /ksquestadmin reset <yourname> wren_firewood resets the quest so you can test again.

ProblemSolution
NPC does not appearCheck the NPC’s world and position in Core’s NPC management, or /kscitizen respawn <id>
NPC has no quest dialogcitizenId must match the NPC ID; the profile editor lists “Profile without NPC”
Quest does not startCheck the prerequisites; the Questbook shows the reason a quest is locked
Objectives do not countCheck objective type and target; use the admin window’s pickers or /ksquestadmin debugmode
Delivery takes nothingThe player must carry the item and the objective’s deliverTo must be this NPC
Rewards not givenCheck reward type and item_id; a full inventory keeps the rest as a pending reward

The admin window’s check finds most of these problems before you test.

The browser-based Mod Editor at modeditor.kyuubisoft.com can also create quests, NPC profiles and translations and export them as files or ZIP. See the Mod Editor Workflow guide.