NPC Setup

Supported NPC Types

Any entity in the world can be a quest giver in QuestLines. Two NPC types are supported:

• HyCitizens NPCs — managed by the HyCitizens plugin. QuestLines listens to the CitizenInteractEvent to intercept interactions. Each HyCitizens NPC has a unique citizen ID (e.g. f48f7eaa-512e-415d-bfdb-f53d2ea0b991) which is used as the key in npcs.json.
• Standard Hytale NPCs — any non-HyCitizens entity. QuestLines intercepts interactions via the SyncInteractionChains packet watcher. The entity's UUID is used as the key in npcs.json.

Both NPC types use the same npcs.json mapping format and identical quest logic. You don't need to configure anything in HyCitizens or elsewhere — all the linkage lives in QuestLines.

HyCitizens Overview

HyCitizens is the NPC framework for Hytale servers. It manages NPC spawning, appearance, and interaction events. QuestLines listens to the CitizenInteractEvent emitted by HyCitizens to intercept player interactions and open the appropriate dialogue.

Each NPC in HyCitizens has a unique citizen ID (e.g. f48f7eaa-512e-415d-bfdb-f53d2ea0b991). This ID is used as the key in QuestLines' npcs.json to map that NPC to one or more quests. You don't need to configure anything in HyCitizens itself — all the linkage lives in QuestLines.

Linking Quests to an NPC

There are two methods to link a quest to an NPC:

Method 1 — Wand Mode (Recommended)

1. Enter wand mode.

   Run /ql wand <questId> in chat. You'll receive a confirmation that wand mode is active.

2. Punch the target NPC.

   Left-click (punch) the HyCitizens NPC in the world. QuestLines reads the citizen's ID and adds it to npcs.json automatically.

3. Wand mode ends.

   The assignment is saved immediately. Run /ql wandcancel at any time to abort without making changes.

Method 2 — Editor UI

Open the editor with /ql ui and navigate to the NPC tab. From there you can manually type the citizen id in.

npcs.json Format

The npcs.json file is the source of truth for NPC-to-quest mappings. It has two top-level maps: Npcs for direct quest assignments and RandomGroups for random quest pools.

// npcs.json
{
  "Npcs": {
    "citizen_42": "lost_sword,daily_reward",
    "citizen_07": "goblin_king"
  },
  "RandomGroups": {
    "citizen_10": "questA|questB;questC|questD"
  }
}

Multiple Quests on One NPC

The value in Npcs is a comma-separated list of quest IDs. When a player interacts with that NPC, QuestLines evaluates the quests in this order — first quest first. The page resolution algorithm stops as soon as a matching page is found, across all quests and their pages.

Random Quest Pools

The RandomGroups assigns quests randomly per player. This is used to create variety — different players get different bounties, tasks, or story paths from the same NPC.

Format

In the example above, the player is assigned one quest from pool 1 (either questA or questB) and one from pool 2 (either questC or questD), for a total of two assigned quests.

Assignment Tags

When a player is assigned a random quest, QuestLines stores the result as a tag:

// Tag format for random assignment
"assigned_quest:questId:citizenId"

// Example: player was assigned questA from citizen_10
"assigned_quest:questA:citizen_10"

Use hasTag:assigned_quest:questA:citizen_10 in page requirements to show quest-variant-specific content. See Quest Patterns → Random Quest Pool for a full worked example.

Wand Mode

Wand mode is the fastest way to link quests to NPCs in-world without editing JSON directly.

While wand mode is active, a pending assignment is stored in memory keyed to your player UUID. Punching any NPC (HyCitizens or standard) will:

1. Read the NPC's citizen ID.
2. Append the quest ID to that NPC's entry in Npcs.
3. Save npcs.json to disk.
4. Exit wand mode and confirm the link in chat.

Talk Tracking

QuestLines automatically tracks how many times each player has interacted with each NPC. No setup or tracking tag is required — the counter increments on every interaction, before the page resolution algorithm runs.

Use the talk:citizenName:qty requirement to gate content on visit count. Use the NPC's display name — the same name shown above their head (e.g. Elder Maren):

// This page only shows after the player's third visit
"Requirements": ["talk:Elder Maren:3"]

// A "returning visitor" page for visits 2+
"Requirements": ["talk:Elder Maren:2"]

Text Variables

Variables can be embedded in any Dialog or response Text field. They are substituted at render time with live player data.

Example Usage

// In a kill quest progress page
"Dialog": "You've slain {track:goblin_kills} of 10 goblins. Keep going, {username}!"

// In a cooldown waiting page
"Dialog": "You've already claimed your reward. Come back in {cooldown:daily_reward:86400}."

// In a timed quest active page
"Dialog": "Hurry! You have {timeleft:courier_timer:300} to make the delivery."

// Showing a named variable
"Dialog": "Your score is {variable:score}. Reach 5 to complete the challenge!"

Inline Text Formatting

Dialog and response text supports inline rich-text formatting tags. These are processed by QuestLines' TextFormatter before the text is rendered in the UI.

Example

"Dialog": "The {b}Sunstone Amulet{/} glows with a {#FFD700}golden light{/}. Bring it to me, {username}."

"Text": "{i}I've already lost one today — I won't risk another.{/}"

Quick Setup Checklist

When creating a new quest and linking it to an NPC for the first time, run through this checklist:

1. Create the quest file with a title and ordered page IDs via /ql create or manually.
2. Create all page files. Ensure the most specific requirements come first in the Pages list.
3. Run /ql wand <questId> and punch the NPC in-world to link it.
4. Verify the NPC entry in /ql ui shows the quest ID correctly.
5. Test the full quest flow by interacting with the NPC as a player. Check all stages.
6. Confirm tracking tags are added on quest start and removed on quest complete.
7. Run /ql reload if you edited JSON files directly on disk.