Quests & Missions

Players take on authored and Dungeon-Master-generated work: discover → accept → progress → complete, with repeatable periods and global first-finisher rewards. Quests are data, not code — a new quest is a YAML file under the content files (schema: schemas/quest.schema.json; example: the content files).

Lifecycle

Discover — NPC talk (quest verb) or a quest board lists what is available.
Accept — the client sends AcceptQuest; the quest becomes active.
Progress — kill / talk / harvest / give objectives advance ordered steps.
Complete — the final step grants rewards. Repeatable quests use period_key.
Withdraw — resets progress (step rewards already earned are kept) and the quest returns to available.

Players must accept explicitly — there is no silent auto-accept. Global-scope quests can be progressed by everyone, but only the first finisher gets the final-step reward for that period.

Repeats

`repeat`	Meaning
`once`	Never again after completion — use for unique named hunts and one-shot bosses
`daily` / `1`	Once per game day
`weekly` / `7`	Once per 7 game days
any positive integer `N`	Once every `N` game days

Completing a repeating quest hides it from the board until the next period, so it cannot be farmed on the same day. An accepted daily/weekly quest stays active across a game-day rollover: credit still counts, and the next period's copy cannot be picked up until the active one is completed or withdrawn.

When a quest is listed

availability decides whether anyone can newly find the quest. repeat still decides how often a player may finish it while it is listed. Listing uses real UTC dates, not the 90-minute game day. Leave availability out and the quest is listed every day.

A quest is listed only when it is enabled, today is on or before expires_on (that date counts), and the schedule matches today.

Schedule	Listed when
`expires_on`	Through that UTC date (`YYYY-MM-DD`). The next date it is hidden until someone sets a later date and turns it back on
`every_n_days`	`(today − anchor)` is a multiple of `every_days`. `2` with an anchor is every other day
`weekdays`	The UTC weekday is one of `mon` … `sun`
`random_daily`	A chance from 0 to 1. Every player sees the same result for that quest on that date

enabled: false hides it immediately and keeps the schedule. A player who already accepted the quest keeps it and can still finish it. Boards and NPC offers stop presenting it until it is listed again.

availability:
  enabled: true
  expires_on: "2026-11-03"
  schedule:
    kind: every_n_days   # or weekdays, random_daily
    every_days: 2
    anchor: "2026-10-26"

Objective kinds

content editor pickers only list targets the sim and play client can actually complete.

Kind	Fields	Wired targets
`talk_npc`	`npc_ref`, `line_id`	Placed town NPCs. `line_id` is a dialogue-pack line the NPC says when the player chooses this quest's verb on that step — that completes the objective and grants step rewards. Optional `on_complete.dialogue_reply_line_id` appends a thanks line. Live LLM chat is bypassed for this greeting; casual Talk does not deliver it.
`kill_npc`	`npc_ref`, `count`	Wildlife / encounter spawns
`harvest_item`	`item_template`, `count`	Resource nodes and world item spawns
`give_item`	`npc_ref`, `item_template`, `count`	Placed NPCs + obtainable items (harvest, loot, shops, craft). In play: Turn in on the NPC verb menu
`interact`	`interactable_id`	Quest boards, wells, or Open water (`water_source`). Filling a vessel still counts
`craft`	`blueprint_id`, `count`	Craft-book recipes the player already knows
`buy_item`	`npc_ref`, `item_template`, `count`	Items that NPC sells (Trade shop)
`sell_item`	`npc_ref`, `item_template`, `count`	Items that NPC buys (Trade shop)
`enter_building`	`building_id`	Authored buildings with a door — Enter on an exterior door
`use_item`	`item_template`, `count`	Consumables, recipe books, skill books, liquid vessels (Use from inventory)
`pickup_item`	`item_template`, `count`	World item spawns and wildlife loot piles
`learn_blueprint`	`npc_ref`, `blueprint_id`	Recipes an NPC teaches (buy from their shop) or that the player learns from a blueprint item. Already-known recipes auto-complete when the step becomes active, when the NPC's shop opens, or when a matching scroll is studied

Free-form NPC / item / board ids do not progress if they are not in the wired lists above. Wildlife cannot receive give_item or talk_npc. Generic interactables (signs, doors-as-interact) are not quest-progressed except the targets listed for interact.

Quest boards

Place an interactable on a segment:

interactables:
  - id: starter_town_quest_board
    kind: quest_board
    board_id: starter_town_board
    label: Job Board
    x: 148.0
    y: 118.0

Client

Sidebar Quests panel (right of Location); key v opens the quest menu.
NPC verb menu: available quests appear as named verbs (authored talk_verb, else the quest title). Choosing one opens talk with the pitch and the accept/decline overlay. Casual Talk does not pop offers.
NPC / board: Accept / Decline offer overlay (a board interact offers immediately; NPC talk does so only after the quest verb).
Active list: withdraw with x + confirm.
Per-kind completion in play: give_item → Turn in (not Trade); buy_item / sell_item / learn_blueprint → Trade with the NPC; craft → finish the selected recipe; enter_building → Enter through an exterior door; use_item → Use from inventory; pickup_item → pick up the pile; interact → use the board, or fill a vessel beside a well / open water.

live quest authoring & live overlay

DM drafts live in the content files until you Promote to live (live quest authoring tab, or flatland-dm quest promote --id). Promote copies the YAML into the authored collection and applies it in-game.
Overlay quests (from flatland-dm quest once generate --publish) live in data/dm/quest-delta.json and appear on the town board without a YAML file.
Deleting retires the overlay copy so the board cannot keep a duplicate title.

Authoring and generation: the specification

Persistence

schema updates schema updates/a script:

Table	Holds
`character_quest_progress`	per-character step counters and status
`character_quest_discovered`	discovered quest ids
`global_quest_claims`	first finisher for global final rewards

The region worker syncs on accept, withdraw and step complete.

the specification — live questing quest pipeline
Town wire — public board quests feed the town gossip wire
schemas/quest.schema.json · the content files · content editor Quests tab