3. Add Mara and the Tavern

Mara Vey gives Greyhaven a human voice. This chapter places her in the tavern and creates a small dialogue root that can be tested before quests are introduced.

Start from Checkpoint 2 or download Checkpoint 3.

What you will learn

How an NPC points to a dialogue root
How to place a character in a town service
How NPC appearance metadata selects a generic fallback sprite
How greetings and topics are structured
Why dialogue arrays need an unconditional fallback
How to keep optional custom artwork separate from progression data

Add clear opening direction

Append this paragraph to intro.text:

"Begin at Greyhaven's tavern. Speak with Mara Vey, the innkeeper, about the missing courier."

Also add these intro properties:

"showMessage": "Begin at Greyhaven's tavern. Speak with Mara Vey about the missing courier.",
"playSFX": "quest_progress"

The campaign does not start a quest automatically. It gives the player an understandable first action while preserving the possibility of exploring before speaking with Mara.

Add Mara

Replace the empty npcs object with:

"npcs": {
  "tutorial_codex:mara_vey": {
    "id": "tutorial_codex:mara_vey",
    "name": "Mara Vey",
    "role": "innkeeper",
    "bark": "If you hear the bell, count the tolls—and pray it stops at three.",
    "dialogueRoot": "tutorial_codex:mara_vey_dialogue",
    "appearance": {
      "ageGroup": "adult",
      "presentation": "feminine"
    },
    "placement": {
      "target": "map:112,96:tavern"
    }
  }
}

The appearance object

appearance guides the generic NPC sprite used when no nonempty custom sprite array is supplied.

Supported values are:

ageGroup: child, adult, or elder
presentation: feminine, masculine, or neutral

When either field is omitted, the runtime defaults to adult and neutral. The chosen generic sprite is deterministic from the NPC’s full ID, so Mara keeps the same fallback appearance across map visits, reloads, and saves.

An authored sprite always takes precedence. This appearance fallback applies to entries in npcs only. Companions use their class-template sprites instead.

The placement target

map:112,96:tavern means the tavern service associated with the map area around Greyhaven’s approved center.

It is not a general promise that every arbitrary string ending in :tavern works. Use the verified format and test the result.

The dialogue reference

dialogueRoot must match a key and id in the dialogue collection. A typo creates a broken reference even when both strings look plausible at a glance.

Add Mara’s dialogue

Replace the empty dialogue object with:

"dialogue": {
  "tutorial_codex:mara_vey_dialogue": {
    "id": "tutorial_codex:mara_vey_dialogue",
    "npcId": "tutorial_codex:mara_vey",
    "greeting": [
      {
        "text": "Mara sets down a cup she has forgotten to fill. “You heard it too, then.”"
      }
    ],
    "topics": {
      "name": {
        "text": "Mara Vey. I keep the Greyhaven tavern open, even when nobody is sleeping."
      },
      "job": {
        "text": "I feed travelers, remember who came through town, and notice when one of them does not arrive."
      },
      "quest": [
        {
          "text": "A courier from the eastern shrine never reached Greyhaven. The north road may hold the answer.",
          "actions": [
            {
              "endDialogue": true
            }
          ]
        }
      ]
    },
    "keywords": {}
  }
}

Understand dialogue selection

greeting is an ordered array. Later chapters add conditional greetings above the fallback greeting.

The quest topic is also an ordered array. The runtime selects the first branch whose condition matches. A final branch without when acts as the fallback.

Even though this checkpoint has only one branch, establish the fallback habit now. Conditional dialogue without a reachable fallback tends to become brittle as state grows.

Why this checkpoint uses a generic sprite

Character sprite arrays can be large enough to bury the lesson on placement and dialogue. The teaching checkpoint therefore supplies appearance metadata and lets the runtime select Mara’s stable generic adult/feminine sprite.

The finished canonical Drowned Bell payload includes custom artwork. A later recipe will cover generating, converting, and testing a custom 40×40 sprite without mixing that work into the quest-state lessons.

Validate

The validator should now be able to resolve this chain:

npcs["tutorial_codex:mara_vey"]
→ dialogueRoot
→ dialogue["tutorial_codex:mara_vey_dialogue"]
→ npcId
→ npcs["tutorial_codex:mara_vey"]

It also checks that Mara’s appearance values are supported. Correct any mismatch before importing.

Playtest Mara

Import Checkpoint 3 and begin a new game.

Verify:

the intro directs you to the tavern,
Mara is visible with a generic character sprite,
Mara appears in the tavern rather than somewhere arbitrary near town,
her bark is visible through normal interaction,
the greeting appears,
name, job, and quest topics respond,
repeated conversation still reaches a sensible response.

Checkpoint 3

Your campaign now includes:

explicit first-step guidance,
Mara’s NPC record,
a stable generic appearance,
the verified tavern target,
a dialogue root with greeting and topics,
a fallback quest response.

Continue to Chapter 4: Add the First Quest and Letter.