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.
Overview
Section titled “Overview”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.
Route A: in game (recommended)
Section titled “Route A: in game (recommended)”Step 1: Create the NPC
Section titled “Step 1: Create the NPC”- Stand where the NPC should be and run
/kscitizen create woodcutter_wren. - Run
/kscitizen edit woodcutter_wrento 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.
Step 2: Create the quest
Section titled “Step 2: Create the quest”- Open the Quests admin window with
/ksquestadmin panel. - On Quests, choose New quest, pick a template and give it the ID
wren_firewood. - 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 DeliverWood_Oak_Trunk× 10 with Deliver towoodcutter_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.
- Save. The check blocks saving if something is wrong and shows where.
Step 3: Set up the NPC profile
Section titled “Step 3: Set up the NPC profile”- 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. - The quest entry for
wren_firewoodhas 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. - Optional: proximity whispers (range, pause and texts) and a default dialog for when no quest fits.
- Save, then Back returns you to the NPC.
Step 4: Test
Section titled “Step 4: Test”- 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.
Route B: with files
Section titled “Route B: with files”Step 1: Create the NPC
Section titled “Step 1: Create the NPC”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.
Step 2: Create the quest
Section titled “Step 2: Create the quest”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 } ] } ]}| Field | Description |
|---|---|
id | Unique quest ID (snake_case) |
type | side, story, daily or weekly |
icon_item | Item ID shown as the quest icon |
name, description | Texts per language (or use translation keys, see Step 3) |
objectives | What the player must do: type, target, count. See Objectives |
rewards | What the player gets. See Rewards |
prerequisites | Optional: quests, facts, level or permission needed first. See Story Quests |
Step 3: Texts (optional)
Section titled “Step 3: Texts (optional)”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"}| Key | Usage |
|---|---|
quest.<questId>.name | Quest name |
quest.<questId>.description | Quest description |
quest.<questId>.obj.<objectiveId> | Objective text |
Custom files (custom_<lang>.json) are never overwritten by updates.
Step 4: Create the NPC quest profile
Section titled “Step 4: Create the NPC quest profile”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!"] }}| Field | Description |
|---|---|
citizenId | Must match the NPC ID |
quests | One entry per quest, with offer, active and complete dialogs |
macro / action | start_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 |
defaultDialog | Shown 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.
Step 5: Reload and test
Section titled “Step 5: Reload and test”/ksquestadmin reloadreloads quests, NPC profiles and texts.- If you edited Core’s NPC file by hand,
/kscitizen reloadloads it. /ksquestadmin debugmodeshows live tracking events in the server console.- Talk to the NPC, accept the quest, chop, deliver, claim.
/ksquestadmin reset <yourname> wren_firewoodresets the quest so you can test again.
Troubleshooting
Section titled “Troubleshooting”| Problem | Solution |
|---|---|
| NPC does not appear | Check the NPC’s world and position in Core’s NPC management, or /kscitizen respawn <id> |
| NPC has no quest dialog | citizenId must match the NPC ID; the profile editor lists “Profile without NPC” |
| Quest does not start | Check the prerequisites; the Questbook shows the reason a quest is locked |
| Objectives do not count | Check objective type and target; use the admin window’s pickers or /ksquestadmin debugmode |
| Delivery takes nothing | The player must carry the item and the objective’s deliverTo must be this NPC |
| Rewards not given | Check 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.
Mod Editor alternative
Section titled “Mod Editor alternative”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.