Quests

#name

Display name of the quest. Quests are exempt from the key/name parity the other keyed sections enforce — the engine's parity check skips them, so a key that differs from name is not reported. Building the map as { quest["name"]: quest } anyway keeps quests consistent with the rest of the world and easier to find.

#completionCondition

Required. Missing it causes a deeply nested decoder error like quests.Name.1.0.0.completionCondition.

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 completion trigger from completionCondition. Basic quests need manual triggers. If completionCondition is empty, no auto-trigger is created for either type.

#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

Required when detailType is "detailed". Must be a location name, not a region name. Must exactly match a key in locations — a specific location display name 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.

For basic quests, use existingLocalArea (or make the quest detailType: "detailed" with a questLocation). The location-generating values nearbyNewLocation and distantNewLocation resolve a new location relative to the player's current position, which can fail when the quest is accepted — the engine aborts with "Failed to accept quest". This bites starting quests (accepted at spawn, before any movement) and arc/chained quests offered before the player has travelled. Anchor the quest at the player's area and let outward travel emerge through play; reserve named destinations for detailType: "detailed" + questLocation.

#questStatement

In practice carries most of the AI guidance load for individual quests — not just "the situation that creates the quest" but the full scene context: who is involved, what the player must do, where the encounter happens, and how success is judged. A well-written questStatement runs 100–500 characters. For authored quest chains, many authors open questStatement with a category label on its own line (Premade Questline: Arc Name, AI Generated Quest) before the narrative setup paragraph — this helps the AI understand the quest's origin and treat it accordingly.

📋

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:

• completionCondition is required - omitting it causes a deeply nested decoder error.
• 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 name (a key in locations), not a region name. Region names produce "Invalid questLocation" warnings.
• detailType accepts only "basic" and "detailed" - "brief" is invalid.

#Quest lifecycle

#Status flow

Hidden → (trigger fires quest-init, or a story start's startingQuests) → Available → Accepted → Phase 1: goToLocation (move to the quest's region/location) → Phase 2: goToArea (move to the specific area within that location) → Phase 3: completeObjectives (player completes mainObjective) → Completed.

From Available the player may also reject the offer (→ rejected) or the quest may expire. From Accepted the player may abandon (→ abandoned).

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

#Expiry conditions

From available state, a quest expires when:

• Expiry tick reached (3 ticks after offer)
• Party leaves the location where the quest was offered
• Quest giver dies, becomes incapacitated, or is no longer near the party

Acceptance and rejection are immediate — there is no pending state between offer and decision.

#Quest chains

Use a quests-completed trigger condition to detect completion, then fire quest-init for the next quest.

#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. For authored quest chains, consider opening with a category label (Premade Quest, AI Generated Quest) on its own line before the narrative setup.
• mainObjective — starts with an imperative verb. The engine parses this to evaluate completion.
• 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 B trigger has condition quests-completed contains "Quest A" — fires only after A is done.
3. Quest C trigger chains from B in the same way.

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

#Encounter quests

For encounter/spawn-able enemies: create one quest per enemy faction with questSource: "Regional Danger". These quests don't need complex objectives — they serve as AI context for encounter spawning.

#NPC reference warnings

The editor shows "NPC X is not referenced by any story start or quest" for NPCs that have no structural linkage in the scenario. The quest schema has no built-in NPC linkage field — questSource is intentionally a plain string. To resolve these warnings, add every NPC to the npcs array of at least one quest. For enemy/encounter NPCs, create dedicated encounter quests (questSource: "Regional Danger") with an npcs array listing the enemies. These quests give the AI context for encounter spawning and resolve the warnings entirely.