Authoring Dialogues & Quest Givers

A Dialogue is a node graph of NPC lines and player-selectable options. A QuestGiver is a separate content type: the NPC's spawn placement, role, and appearance. NPCs never own a dialogue file directly - a QuestGiver.Dialogue field (or a spawn-hub.json dialogue key) attaches one by id, so one dialogue tree can serve many NPCs.

Configuration seam

Dialogue file shape

Folder: Server/MMOSkillTree/Dialogues/<id>.json (id = filename, lowercased).

{
  "Name": "guide_wilds_dialogue",
  "Payload": {
    "Parent": "questgiver_standard",
    "Start": [
      { "Node": "greet", "Conditions": [ { "Type": "QuestState", "Quest": "...", "State": "ACTIVE" } ] }
    ],
    "Nodes": { "greet": { "TextKey": "...", "Options": [ ... ] } },
    "Fragments": { "hub_footer": [ { "LabelKey": "...", "Open": "hub" } ] }
  }
}

A DialogueEntry (one Start row) has Node (string, required) and an optional Conditions array (AND-combined).

DialogueNode fields

DialogueOption fields

When Style/Presentation are absent, each registered action type carries a default style resolved from the option's decisive action: AcceptQuest/CompleteQuest → accept (green), TurnInQuest → turn-in (blue), OpenPage/RunCommand → neutral (steel), the engine's default Farewell → muted X. An option with no Goto/Close action just re-renders the same node - useful for a conditions-gated informational line.

Option sugar

A pre-codec rewrite (DialogueSugar) turns flat option keys into canonical Actions, then strips the consumed keys - the codec/validator/executor only ever see canonical actions. Bare (non-Do) sugar keys on one option expand in the fixed order below regardless of authored key order. Sugar appends after any explicit Actions array, so both can be mixed.

{ "LabelKey": "...", "Do": [ { "Talk": "" }, { "TurnIn": "wilds_call_of_the_dunes" }, { "Goto": "desert_lore" } ] }

Actions

Generic actions come from ziggfreed-common: Goto{Node}, Close{}, SetFlag{Flag}, Talk{Target?} (carrier only - the MMO overrides the handler), OpenPage{Target}.

Runtime conditions

Generic conditions ship Flag/NotFlag/AllOf/AnyOf/Not combinators. Combine them freely with the MMO-registered conditions below to express state-varied beats without duplicating nodes.

Fragments and IncludeOptions

Payload.Fragments is a map of reusable option lists a node splices in via IncludeOptions (spliced AFTER the node's own Options, so a node's own lead trails into a shared footer). Fragments resolve within the same body only - a fragment defined in a Parent is not visible to a child. Keep shared footers in the body that uses them, or in a base the child fully inherits.

"Fragments": {
  "footer": [
    { "LabelKey": "dialogue.my_scout_dialogue.opt.open", "Style": "neutral", "Open": "hub" }
  ]
}

Reward action semantics

The Reward action grants a unified content/reward object, decoded directly through Reward.CODEC. Once (default true) guards an implicit per-player flag reward:<dialogueId>:<node>:<optionIndex>- keyed on the dialogue, not the NPC, so a shared dialogue's gift can't be farmed across every NPC it's attached to. This flag is a normal dialogue flag: it can be read with NotFlag/Flag in another Conditions block, which is real shipped-pack usage (hiding a gift option after it's claimed).

Native Parent inheritance Since 1.5.0

How resolution works, in order:

• DialogueBodyResolver resolves the Parent chain (topological, memoized, cycle-guarded with a warning) before the option-sugar pre-pass.
• Start/Nodes are appendInherited at the top level: an omitted field inherits the parent's value wholesale.
• Nodes keyed-merges per entry: a child Nodes entry overrides/adds by key while parent-only node ids inherit unchanged. Each DialogueNode's own fields (TextKey/Conditions/Options) are themselves appendInherited, so a child node can override just TextKey and still inherit the parent's Options.
• Fragments/IncludeOptions resolve within the same body only (repeated from above, since it matters most here: a base's Fragments is invisible to its children).
• Base skeletons should omit TextKey/LabelKey so each concrete child gets its own convention loc-namespace for free (dialogue.<childId>.<node>.text), rather than hardcoding a namespace the base's own id would produce.

{
  "Name": "Guide_Sands_Dialogue",
  "Payload": {
    "Parent": "questgiver_standard",
    "Nodes": { "lore": { "TextKey": "dialogue.guide_sands.desert_lore.text" } }
  }
}

Self-heal convention

Localization keys

Convention: dialogue.<dialogueId>.<node>.text (node text) and dialogue.<dialogueId>.<node>.opt.<index> (index is the option's position in the decoded node, after IncludeOptions splicing - so a fragment option's key namespace belongs to whichever body it lives in). Author these in the pack .lang file; never author a raw Text/Label. A Parent-inheriting child gets its own namespace from its own filename id.

Minimal dialogue example

{
  "Name": "my_hermit_dialogue",
  "Payload": {
    "Start": [ { "Node": "greet" } ],
    "Nodes": {
      "greet": {
        "TextKey": "dialogue.my_hermit_dialogue.greet.text",
        "Options": [
          { "LabelKey": "dialogue.my_hermit_dialogue.greet.opt.leave", "Close": true }
        ]
      }
    }
  }
}

Kitchen-sink dialogue example

Fragments, node self-gating, style, a once-only gift reward read back through a flag condition, and a gate condition:

{
  "Name": "my_scout_dialogue",
  "Payload": {
    "Start": [
      { "Node": "greet_active",
        "Conditions": [ { "Type": "QuestState", "Quest": "scout_favor", "State": "ACTIVE" } ] },
      { "Node": "greet" }
    ],
    "Nodes": {
      "greet": {
        "TextKey": "dialogue.my_scout_dialogue.greet.text",
        "Options": [
          { "LabelKey": "dialogue.my_scout_dialogue.greet.opt.accept",
            "Conditions": [ { "Type": "Gate", "Requirements": { "minCombatLevel": 5 } } ],
            "Style": "accept",
            "Do": [ { "Accept": "scout_favor" }, { "Goto": "greet_active" } ] }
        ],
        "IncludeOptions": [ "footer" ]
      },
      "greet_active": {
        "TextKey": "dialogue.my_scout_dialogue.greet_active.text",
        "Options": [
          { "LabelKey": "dialogue.my_scout_dialogue.opt.gift",
            "Conditions": [ { "Type": "NotFlag", "Flag": "reward:my_scout_dialogue:greet_active:0" } ],
            "Presentation": { "Color": "#5ab0ff", "Icon": { "Item": "hytale:iron_arrow" } },
            "Reward": { "Type": "COMMAND", "Command": "/give {player} Item_Arrow_Iron --quantity=8" },
            "Once": true }
        ],
        "IncludeOptions": [ "footer" ]
      }
    },
    "Fragments": {
      "footer": [
        { "LabelKey": "dialogue.my_scout_dialogue.opt.open", "Style": "neutral", "Open": "hub" }
      ]
    }
  }
}

Quest-giver authoring

Folder: Server/MMOSkillTree/QuestGivers/<id>.json (id = filename). Pattern A - QuestGiverAsset.CODEC decodes typed PascalCase fields directly (no Payload wrapper), the same codec used for the owner layer mods/mmoskilltree/quest-givers.json.

Practical minimum: Appearance plus the npcs.<id>.name lang value it reuses for objective text - NameKey/HintKey are optional overrides.

Minimal quest-giver example

{
  "Name": "My_Camp_Elder",
  "NpcId": "my_camp_elder",
  "Appearance": "Feran_Windwalker",
  "Placement": "manual"
}

Kitchen-sink quest-giver example

Structure-anchored placement, a per-world allow-list, and a dialogue attach - the real shipped shape:

{
  "Name": "Guide_Wilds",
  "NpcId": "guide_wilds",
  "Dialogue": "guide_wilds_dialogue",
  "Appearance": "Feran_Windwalker",
  "NameKey": "npcs.guide_wilds.name",
  "HintKey": "npcs.questgiver.hint",
  "Placement": "structure",
  "Worlds": ["default"],
  "Match": { "MarkerIds": ["Kweebec"] },
  "SpawnChance": 1.0,
  "MaxPerWorld": 1,
  "Offset": { "X": 2.0, "Y": 0.0, "Z": 1.5 },
  "Yaw": 180.0
}

Pack folder layout

MyQuestGiverPack/
├── manifest.json
└── Server/
    └── MMOSkillTree/
        ├── Dialogues/
        │   └── My_Scout_Dialogue.json
        ├── DialogueTemplates/
        │   └── Questgiver_Standard.json
        └── QuestGivers/
            └── My_Camp_Elder.json

See Content Types for the full pack asset-type catalog and feature-gating, and Quests for the quest objectives a dialogue's Accept/TurnIn/Complete actions drive.