Quests

Quests

Edit tabs/quests.json.

Required Fields

Conditional Fields

Never Include

Omit these fields (auto-set or runtime-only):

• questType
• id, definitionKey, creationTick, status, detectionTick, acceptedTick
• expiryTick, completedTick, abandonedTick, rejectedTick
• startingArea, connectingAreaName, questAreas
• questStepPhase, hasVisitedLocation, hasVisitedStartingArea, objectiveCompleted
• offeredAtLocation, questGiverNPCKey, arcQuestOrdinal, contentOrigin
• conclusive, arcId, arcEscalationAtCreation

detailType Selection

Use detailed for hand-crafted narrative quests. Use basic for procedural or emergent quests.

A basic quest whose questLocation is blank counts as "already at the location" and advances straight to objectives instead of waiting for travel. A detailed quest without a questLocation skips travel the same way: it starts directly in objective mode with its mainObjective as the current step, and no location is revealed on accept.

Gating Travel to Quest Locations

Travel to a quest location is treated as simple by default. The narrator only makes it impossible when the destination's text explicitly establishes a lock: a boss guarding it, sealed access, a required access item, or authority clearance. A destination that is merely unestablished or dangerous costs at most a skill check. If a quest is meant to gate an area, write the lock into the location or area text (and the quest's questDesignBrief) rather than relying on the quest alone.

spatialRelationship Values

For basic quests only - defines where the AI generates the quest location:

mainObjective Format

Write as a player action in imperative form. Shown in the quest log UI.

Format: "[Verb] the [target]" or "[Verb] [what] from/in/at [where]"

completionCondition Format

An optional object with one of two forms:

• { "type": "story", "query": "..." } — the query is a natural-language description of what "done" looks like; the trigger system matches it semantically against the story. If the query is left empty, no auto-trigger is generated. (Legacy plain-string conditions are auto-converted to this form.)
• { "type": "narrative-event-completed", "eventId": "..." } — the quest completes when the referenced narrative event completes. No auto-trigger is generated. See the narrative-events skill.

Omitting completionCondition is a first-class choice for trigger-driven quests: the quest then completes only through explicit effects (quest-progress reaching completion, or quest-complete) fired by triggers, narrative events, or another quest's onCompleteEffects.

Objectives and Next Steps

Author objectives as a record keyed by objective id, typically with status: 'hidden', and reveal/complete them via the quest-objective-reveal and quest-objective-complete trigger effects — objectives never advance on their own. An objective authored active is live from the start; point activeObjectiveId at it. nextStep is short imperative guidance shown on the quest UI and injected into prompts; it is normally managed automatically by objective effects and the quest-next-step-set / quest-next-step-clear effects, so only author it for initial guidance. See the reference doc and the triggers skill for full semantics.

questStatement Format

One sentence describing the situation that creates the quest.

Format: "[Subject] [situation that creates urgency or motivation]"

Starting Statuses and Making Quests Available

Quests start hidden unless initialStatus sets a different starting status, applied at world start:

The AI quest generator avoids duplicating planned and available quests. To reserve a future quest's storyline, author it planned (via initialStatus or a quest-plan effect); hidden keeps it purely invisible.

Via Story Start (recommended for starting quests):

"storyStarts": {
  "adventure": {
    "startingQuests": ["rescue-princess", "investigate-ruins"]
  }
}

startingQuests entries resolve by quest file id or unique name. Hidden quests are promoted to available at start; quests already accepted are skipped.

Note: firstQuest is a separate freeform text field for AI quest generation - it doesn't reference predefined quests. See the story-starts skill for details.

Via Trigger (for unlockable quests):

"triggers": {
  "unlock-quest": {
    "conditions": [{ "type": "story", "query": "Player speaks to the king" }],
    "effects": [{ "type": "quest-init", "operator": "set", "value": "rescue-princess" }]
  }
}

Status-moving effects: quest-plan (hidden to planned), quest-init (hidden or planned to available), quest-accept (hidden, planned, or available to accepted; predefined quests only). See the reference doc and the triggers skill.

Quest Lifecycle

Definition -> hidden -> planned -> available -> accepted -> completed
                                       |  \         |
                                       |   rejected |
                                       |       abandoned
                                       |
                                    expired

quest-accept can move a hidden or planned quest straight to accepted. Re-accepting a concluded quest (completed, abandoned, rejected, expired) starts a fresh run: objectives reset to hidden and the previous outcome is cleared, while progress made before first acceptance is kept. Hidden and planned quests can accumulate objective progress silently.

When an available quest is offered, the player accepts or rejects it as a single step. An available quest with an expiry lapses to expired when its expiry tick is reached, the party leaves the location where the quest was offered, or the quest giver dies/leaves the scene. A standing offer without an expiry stays valid indefinitely and keeps discouraging duplicate AI generation.

Detailed quests with a story-type completionCondition auto-generate a completion trigger from the query. Basic quests need manual triggers. If the query is empty, no auto-trigger is created for either type. Quests with a narrative-event-completed condition get no auto-trigger — they complete (if accepted) when the referenced narrative event completes.

Schema

interface QuestDefinition {
  name: string
  questSource: string
  questStatement: string
  mainObjective: string
  completionCondition?: QuestCompletionCondition
  initialStatus?: 'hidden' | 'planned' | 'available' | 'accepted'
  questDesignBrief?: string
  detailType: 'basic' | 'detailed'
  spatialRelationship?: SpatialRelationship
  questLocation?: string
  questGiverNPC?: string
  objectives?: Record<string, QuestObjective>
  activeObjectiveId?: string
  nextStep?: QuestNextStep
  onCompleteEffects?: Effect[]
}

type QuestCompletionCondition =
  | { type: 'story'; query: string }
  | { type: 'narrative-event-completed'; eventId: string }

interface QuestObjective {
  id: string
  text: string
  status: 'hidden' | 'active' | 'completed'
}

interface QuestNextStep {
  text: string
  source: 'objective' | 'narrative-event'
}

type SpatialRelationship =
  | 'existingLocalArea'
  | 'newLocalArea'
  | 'nearbyNewLocation'
  | 'distantNewLocation'
  | 'existingLocationNewAreas'

Reference

For detailed documentation, see quests-reference.md.