Quests

#name

The quest's display name. Unlike most keyed sections, quests do not have to match their key to name; matching them anyway keeps quests easy to find. Quest references (quest-init / quest-plan / quest-accept values, questId fields, startingQuests) resolve by quest key first, then by unique display name, so the key is the stable reference to author.

#completionCondition

Optional, and omitting it is a deliberate choice for trigger-driven quests. When present it is an object in one of two shapes:

• { "type": "story", "query": "..." } -- a story-completion check; query is the situation that marks the quest done, in plain language ("The documents have been delivered to the dock contact."). This is the common form.
• { "type": "narrative-event-completed", "eventId": "..." } -- the quest completes when the named narrative event completes. Use this to end a quest on the resolution of a multi-turn arc rather than a single detected moment.

📋

Note: A plain string is also accepted and wrapped into { "type": "story", "query": <string> } on load. Author the object form directly.

Detailed quests auto-generate a hidden completion trigger named __generated_quest_progress__/<quest> from a story condition; don't give your own triggers names starting with that prefix. Basic quests and narrative-event-completed conditions build no trigger.

#detailType

Determines which location field is required and how the AI handles quest location:

Valid detailType values: Only "basic" and "detailed". "brief" is not valid — using it causes a decoder error listing every expected field. The error message is misleading (it looks like the whole quest schema is wrong) but the root cause is always the invalid detailType string.

#questLocation

Used when detailType is "detailed". Must be a location, not a region. Must match a key in locations — a specific location like "Capital City Docks", not its parent region name like "The Capital Region". Region names cause "Invalid questLocation" warnings. Always use the specific location, not its parent region.

#spatialRelationship

Required when detailType is "basic". Codec enum with five accepted values:

existingLocalArea | newLocalArea | nearbyNewLocation | distantNewLocation | existingLocationNewAreas

What each tells the narrator to construct: existingLocalArea - the quest stays in the current area (no travel needed); newLocalArea - moving to a new part of the current location that didn't previously exist (e.g. a hidden basement); nearbyNewLocation - travel within the same region, framed as a short trip; distantNewLocation - a journey to a different region or far-off part of the world; existingLocationNewAreas - returning to a known location and discovering entirely new sections of it.

#questStatement

The situation that creates the quest. A strong one reads as a briefing: who is involved, what the player must do, where it happens, and how success is judged.

📋

Note: questStatement and the global storySettings.questGenerationGuidance work as a general-to-specific pair. The global guidance carries world-wide quest tone so any quest feels like it belongs in the scenario; questStatement carries the mission-specific context so the objective lands with the right weight. questDesignBrief adds tone and feel guidance on top of that when the quest's emotional register is non-obvious from the other fields.

#questDesignBrief

Optional string — authoring notes about how the quest should feel and be run. Not player-visible. Include it for quests where the tone or pacing is non-obvious from the other fields alone.

"questDesignBrief": "Direct confrontation with the mastermind at their stronghold. They are willing to negotiate - this should feel like a revelation, not an automatic fight. No violence unless the player chooses it. Their account should answer questions and raise new ones."

#Validation gotchas

⚠️

Warning:

• The correct trigger effect format for quest-init is { "type": "quest-init", "operator": "set", "value": "Quest Name" } - "operator": "set" must be present.
• questLocation must be a location key, not a region. Region names produce "Invalid questLocation" warnings.
• detailType accepts only "basic" and "detailed" - "brief" is invalid.

#Quest lifecycle

#Status flow

Hidden → (optionally quest-plan) → Planned → (quest-init) → Available → Accepted → Completed. A story start's startingQuests makes hidden quests available at game start.

planned is invisible to players but reserves the storyline: the AI quest generator won't generate a duplicate of it. From Available the player may also reject the offer (→ rejected) or the offer may expire (→ expired). From Accepted the player may abandon it (→ abandoned). A hidden or planned quest can still accumulate objective progress silently.

Valid quest statuses: hidden, planned, available, accepted, completed, abandoned, rejected, expired.

#Step phases

Once accepted, a quest moves through goToLocation (reach the quest's location), goToArea (reach a specific area in it), and completeObjectives, advancing automatically as the party arrives. Where it starts follows spatialRelationship: existingLocalArea and newLocalArea start at goToArea; existingLocationNewAreas starts at goToLocation and then goToArea; nearbyNewLocation and distantNewLocation start at goToLocation and skip straight to completeObjectives on arrival. A quest with a blank questLocation starts in completeObjectives.

#Expiry conditions

From available state, a quest expires when:

• Its expiry tick is reached, if it has one
• Party leaves the location where the quest was offered
• Quest giver dies, becomes incapacitated, or is no longer near the party

A standing offer without an expiry stays valid indefinitely. Acceptance and rejection are immediate; there is no pending state between offer and decision.

#Three ways to move a quest forward

Three trigger effects act on a quest by key, and they differ in how visible the result is:

More than one quest can be accepted at a time, so accepting a new one does not close out the others. A quest planned, offered, or accepted by an effect this turn suppresses the AI's generated quest for that turn.

#Quest chains

Give the finishing quest an onCompleteEffects entry naming its successor — quest-accept to hand it straight over, quest-init to offer it. Nothing has to watch for the completion.

A quests-completed trigger condition still works when the follow-up depends on more than one quest being done, or on conditions the finishing quest cannot see.

#acceptQuest UI prompt

When a quest becomes available, the engine surfaces an accept prompt to the player as a UI element after the turn ends — accepted quests are tracked in the journal (top-left in the game). Use quest-init triggers with story conditions for quest discovery logic rather than relying on prose dialogue.

#Trigger naming convention

Use the pattern {questId}_objective or {questId}_objective_N (e.g. the_missing_documents_objective, the_missing_documents_objective_2) to name objective-phase triggers consistently. The name is a label only: gate the trigger on the quest's status yourself if it should not fire before the quest is accepted.

#Authoring tips

#Activation coverage

A quest starts hidden. The two deliberate activation paths are a trigger with a quest-init effect and a story start's startingQuests entry.

The working method is to gate quest-init behind a two-step discovery trigger -- an arrival trigger that sets a flag, then a story-condition trigger that fires quest-init once the player has actually met the hook (see the pattern on the Triggers page) -- so the quest surfaces naturally and reliably.

Light or missing gating does not keep a quest hidden: engaging the NPC the quest originates from can surface it immediately, landing it on the player with no narrative lead-in.

#Quality checklist

• questStatement — reads as a briefing: who, what, where, why, and how success is judged. One sentence to a full paragraph depending on quest complexity.
• mainObjective — starts with an imperative verb; it is the step players see when nothing more specific applies.
• completionCondition — write what "done" looks like in plain language. Be specific.
• detailType: "detailed" + questLocation for pre-built locations; detailType: "basic" + spatialRelationship for AI-generated locations.

#Discovery pattern (first quests at a location)

1. Arrival trigger (start_[location]) sets scene and writes a boolean flag — no quest-init.
2. Discovery trigger (discover_[quest_slug]) checks the flag + a story AI condition ("has the player spoken with the quest-giver?") → fires quest-init.
3. The quest appears in the player's journal only after they have organically encountered the hook.

#Chain pattern (multi-step storylines)

1. Quest A surfaces via the two-step discovery pattern above.
2. Quest A's onCompleteEffects offers or accepts Quest B, or a trigger with quests-completed contains "Quest A" does when B depends on more than A.
3. Quest C chains from B in the same way.

This creates a natural investigation/escalation arc without the player being handed everything at once.