Quest Structure

This page provides a comprehensive breakdown of the quest data structures and their properties.

Quest Interface

The core quest definition that contains all quest metadata and progression:

interface Quest {
  name: string; // Internal identifier used in code references
  displayName?: Translatable; // Optional player-facing name (falls back to name)
  description: Translatable; // Quest summary in quest log
  category: QuestCategory; // Determines where quest appears
  guild?: string; // Required for guild category quests
  steps: QuestStep[]; // Sequential objectives
  rewards: QuestReward[]; // Benefits upon completion
  failureCondition?: string; // Optional failure trigger
  cost?: number; // Optional cost to accept quest
}

Name and Description

Name: The internal identifier for the quest. Used in code references, flags, and the quest registry. Must be unique.

Display Name: Optional player-facing title. When set, this is shown in the quest log and notifications instead of name. Supports the Translatable type, so it can be a plain string or a translation key object.

Description: Brief summary that explains the quest’s purpose and context. Should intrigue players without spoiling story beats.

name: 'theWanderingHerb',          // Internal ID (used in code)
displayName: 'The Wandering Herb', // Shown to players (optional)
description: 'Hua Tong has tasked you with finding and returning a sentient herb that escaped his gardens.'

If displayName is omitted, the player sees name directly.

Category System

Determines quest organization and availability:

type QuestCategory =
  | 'main'
  | 'side'
  | 'missionHall'
  | 'craftingHall'
  | 'requestBoard'
  | 'guild';

Main Quests

  • Core storyline progression
  • Typically linear and required
  • Unlock major game features
  • High narrative importance

Side Quests

  • Optional character stories
  • World building and lore
  • Recurring characters
  • Multi-part questlines

Mission Hall Quests

  • Sect-based assignments
  • Regular income source
  • Combat and exploration focus
  • Reputation building

Crafting Hall Quests

  • Artisan skill development
  • Technique acquisition
  • Master-apprentice relationships
  • Crafting system integration

Request Board Quests

  • Community needs
  • Quick objectives
  • Immediate rewards
  • Social system integration

Guild Quests

  • Organization-specific content
  • Exclusive storylines
  • Guild advancement
  • Factional conflicts

Guild Specification

For guild category quests, specify the organization:

category: 'guild',
guild: 'ShadowMoonSect' // Must match guild identifier

Cost System

Optional upfront payment required to accept the quest. Only used by the Crafting Hall at this time:

cost: 500; // Player pays 500 sect favour to start quest

Failure Conditions

Optional string expression that causes quests to be removed from the quest list early:

failureCondition: 'realm > 3 || someQuestFlag == 1';

Common patterns:

  • Mutually exclusive quests: otherQuestCompletedFlag == 1 — remove the quest when a competing questline resolves first
  • Realm gates: realm > 3 — fail a low-realm quest if the player over-levels past the intended range
  • Reputation thresholds: Nine_Mountain_Sect < -50 — use the faction flag name directly (faction name with spaces replaced by underscores)
  • Time limits: month > questStartMonth + 12 — where questStartMonth is a flag you set via a flag step when the quest begins

All condition variables are numeric. Reputation values are stored as flat flags using the faction name with spaces replaced by underscores (e.g. Nine_Mountain_Sect). Item quantities use the item’s flag name (e.g. Spirit_Herb). String comparisons are not supported.

Note quests are also removed when all the steps in the quest are completed. This is simply a way to remove the quest early.

Reward System

Quests can show a preview of the rewards to be gained on quest completion. Note, the quest WILL NOT grant these itself, they need to be scripted in as part of an event. This is just a way to indicate this to the player:

type QuestReward =
  | ItemQuestReward
  | MoneyQuestReward
  | FavourQuestReward
  | ReputationQuestReward
  | GuildApprovalQuestReward;

Item Rewards

Grant specific items and quantities:

{
  kind: 'item',
  item: { name: 'HealingPill' }, // Item descriptor
  amount: 5 // Quantity to give
}

Spirit Stone Rewards

Provide direct currency:

{
  kind: 'money',
  amount: 1000
}

Favour Rewards

Grant sect favour points:

{
  kind: 'favour',
  amount: 500
}

Reputation Rewards

Modify standing with specific factions:

{
  kind: 'reputation',
  amount: 25, // Reputation change
  name: 'NineMountainSect', // Faction identifier
  max?: 100 // Optional maximum reputation
}

Guild Approval Rewards

Advance standing within guilds:

{
  kind: 'approval',
  amount: 10, // Approval points
  guild: 'CraftingGuild' // Guild identifier
}

Quest Design Philosophy

Player Agency

Good quests provide meaningful choices that affect outcomes and character development. Use branching dialogue and multiple solution paths.

Narrative Integration

Quests should feel natural within the world and contribute to character relationships, faction dynamics, and personal growth.

Progressive Difficulty

Structure quests to match player progression, introducing new mechanics and challenges as cultivation advances.

Emotional Investment

Create memorable characters and situations that players care about. The best quests have stakes beyond just mechanical rewards.

Getting Started with Quests

See Quest Examples for complete annotated implementations, and Quest Steps for detailed documentation on each step type.