Quests

Overview

A quest is a task for players to complete: gather resources, reach a level, kill something, deliver something. Quests are written as JSON, loaded at startup, and hot-reloadable with /mmoquestadmin reload. Players interact with them through the Quests tab, a character in the world, or /quest.

The current format is one file per quest, in the shared format quests, achievements and bounties all speak, and your own quests live in mods/ziggfreedcommon/quests/, the shared library's folder, one file per quest named after the quest id. The older "a file holding a quests array" shape under mods/mmoskilltree/quests/ is migrated into that folder once, on the first start after upgrading, and never read again - see The older shape below for what the first start does and how the old fields map across.

A quest ships as an installable add-on by living in a content pack: a folder you zip and drop into Mods/ - see Building the zip. Inside it, quests go at Server/ZiggfreedCommon/Quests/<YourPack>/...; see the quest pack authoring reference for the full field set and worked bounty examples. For a single server, mods/ziggfreedcommon/quests/ is the quick-tweak alternative to a pack.

The quest file

There is no envelope and no id field: the file is the quest, and its id is its filename, lower-cased. Trork_Hunter.json is the quest trork_hunter. Folders under the type root are yours to arrange and change nothing about the id, so keep basenames unique across the whole store; two files landing on one id are reported at load, naming both.

Every worked example on this page carries a "Name" leaf, but that field is a human-readable label kept in the file for readability - it sets nothing. The id is still the filename, and a Name that disagrees with the filename changes nothing about which quest it is.

// Server/ZiggfreedCommon/Quests/MyPack/Mining/Novice_Miner.json
{
  "Name": "Novice_Miner",
  "Text":     { "TitleKey": "quest.novice_miner.title",
                "FlavorKey": "quest.novice_miner.flavor" },
  "Listing":  { "Category": "main", "SortOrder": 10 },
  "Flow":     { "AutoAccept": true },
  "Requires": { "Quests": ["getting_started"] },
  "Npc":      { "ViewId": "Mmo_Hub" },
  "Objectives": {
    "mine_stone": { "Kind": "BREAK_BLOCK", "Target": "Rock", "Amount": 150,
                    "MatchMode": "CONTAINS" }
  },
  "Rewards": {
    "Claim": [
      { "Kind": "Item",   "Params": { "Item": "Tool_Pickaxe_Iron", "Count": "1" } },
      { "Kind": "Mmo_Xp", "Params": { "Skill": "MINING", "Amount": "200" } }
    ]
  },
  "Meta": { "mmoskilltree": { "NpcOnly": false } }
}

The same shape from the owner folder, retuning one shipped quest by naming it: every leaf you leave out keeps the shipped value, so this file changes one amount and nothing else.

// mods/ziggfreedcommon/quests/Novice_Miner.json
{
  "Objectives": {
    "mine_stone": { "Amount": 300 }
  }
}

The groups, and where each is documented

The schema itself has ONE home: the quest authoring reference (with the shared sub-schemas on Shared Schemas). The same file you author there is the file you drop in mods/ziggfreedcommon/quests/, so nothing on those pages is pack-only. In brief, with each group linked to its reference:

• The groups - Text, Listing, Flow, Npc, Objectives, Rewards, Meta: every group on a quest file.
• Listing - the category and sort order, plus three independent visibility switches: Hidden (off every open list), RequirePrerequisites (listed once it can be taken) and ShowWhen (listed once a requirement block of its own passes, whatever is needed to take it).
• Requires - the one gate: factor bounds (a skill level is a hytale:stat bound), finished quests, permission, and the AllOf/AnyOf/Not combinators.
• Repeat - what brings a quest back around: calendar windows of any length (a day, a week, a fortnight, eight hours), rolling cooldowns, allowances and lifetime caps, and the one rule that decides whether a quest reads as daily or weekly.
• Meta.mmoskilltree - the one knob specific to this mod, NpcOnly. A feature a quest needs is a mmoskilltree:feature factor in Requires.
• Quest generators - one file that writes a whole family of quests.

Switching one quest off

To take a shipped quest out of circulation, put a file named after it in mods/ziggfreedcommon/quests/ carrying the flag and nothing else. A disabled quest needs no objectives, and every other leaf stays as shipped:

// mods/ziggfreedcommon/quests/Forgot_Something.json
{ "Enabled": false }

A player who already holds the quest can still finish it. An older-shape file carrying { "id": "forgot_something", "enabled": false } becomes exactly this file on the first start.

What the validator reports

The startup audit and /mmoconfig validate check every quest file, owner and pack alike. Each finding the quest validator raises, and what it means, is documented with the authoring reference on Authoring Quests & Bounties: validation.

Default Quests & Customization

Every quest the mod ships is a readable asset in the jar under Server/ZiggfreedCommon/Quests/MMOSkillTree/, so you can open a built-in, copy it, and override it.

• Override one by name. Put a file named after the quest in mods/ziggfreedcommon/quests/: the leaves you write win for that quest and the rest stay as shipped.
• Your own files no longer hide the built-ins. Adding a quest of your own adds to the shipped set instead of replacing it.
• The generated defaults copy is retired. The old quests/_defaults/default-quests.json echo renames itself to .legacy on the first start after upgrading, with one line in the log saying where to read the built-ins instead. It used to be regenerated every start and then read straight back in as the owner layer, which meant a stale copy could quietly outrank the real quest.
• Upgrading from much older versions: an example-quests.json is moved to quests/backups/ automatically.

After editing quest files, run /mmoquestadmin reload to apply changes without restarting the server.

The older shape (migrated on the first start)

A file in mods/mmoskilltree/quests/ holding a schemaVersion and a quests array is the older owner shape. It is not read any more: on the first start after upgrading, every quest in every such file (sub-folders included) is rewritten in the shared shape into mods/ziggfreedcommon/quests/<Id>.json, one file per quest named after the quest id, and the original is renamed .legacy beside itself. One startup notice lists every file that moved, every quest it became, and every field the shared shape has no home for. A second start finds nothing to do.

• A file moves whole or not at all. A quest the converter refuses (a template no pack provides, a quest with nothing to do, a body the shared codec rejects) or a target file that already exists (a quest you already wrote in the new folder, or an earlier file on the same start) leaves its file exactly where it is, named in the notice with the reason, so you decide which copy wins. Fix it and restart.
• A file already in the shared shape is moved across untouched, name and all.
• The .legacy leftovers are never read. Keep them until you have checked the new folder, then delete them. /mmomigrate lists each one as a file the server already handled, and a not-yet-converted quests/ file as one it will handle on the next start.
• The docs site's Migration Converter performs the same rewrite on a zip of your mods/mmoskilltree/ folder, so either route leaves the same files.

The rest of this section is the old shape as it was written, and what each field became, so a .legacy file and the startup notice can be read side by side.

File Structure

{
  "schemaVersion": 1,
  "quests": [
    {
      "id": "mining_beginner",
      "titleKey": "quest.mining_beginner.title",
      "flavorKey": "quest.mining_beginner.flavor",
      "category": "main",
      "enabled": true,
      "sortOrder": 1,
      "autoAccept": true,
      "autoClaimRewards": true,
      "prerequisites": [],
      "requirements": { "minLevel": 0, "minSkill": "MINING", "minSkillLevel": 5 },
      "objectives": [
        {
          "id": "mine_stone",
          "type": "BREAK_BLOCK",
          "target": "Rock",
          "amount": 150,
          "matchMode": "CONTAINS"
        }
      ],
      "rewards": [
        { "type": "XP", "skill": "MINING", "amount": 200 }
      ]
    }
  ]
}

The folder was scanned recursively, so quests could be split across files; each quest becomes its own file in the new folder whatever file it came from. A titleKey/flavorKey is carried as Text.TitleKey/FlavorKey, and the convention keys quest.<id>.title / .flavor are written when the file named none - see Localization.

Quest Fields

Behavior Fields

Requirements (older shorthand)

requirements takes a single object or an array of objects, and every entry can set a total-level gate, a skill gate, or both. The highest minLevel across the entries is the total-level gate, and every skill requirement must be met:

"requirements": [
  { "minLevel": 25 },
  { "minSkill": "MINING", "minSkillLevel": 15 },
  { "minSkill": "CRAFTING", "minSkillLevel": 20 }
]

Prerequisites

A plain array of quest ids means all of them must be finished and their rewards collected:

"prerequisites": ["mining_beginner", "combat_initiate"]

The object form is now written in the Requires vocabulary. Where an older file wrote mode and groups, write the leaves and combinators instead - AnyOf is the OR:

"prerequisites": {
  "Quests": ["chapter1_intro"],
  "AnyOf": [
    { "Quests": ["path_warrior_complete"] },
    { "Quests": ["path_mage_complete"] }
  ]
}

The player must complete chapter1_intro and either path. Keys are read case-insensitively, so quests and Quests are the same leaf. The quest UI labels an either-or as "Unlocked by: A or B", and a permission requirement as its own line.

Tags & Variables

tags categorize a quest (they render as chips under the description and drive the filters on the docs site Quest Gallery), and variables was a free key-value map for your own metadata. Tags become Listing.Tags (and Listing.Chains is the leaf for saying a quest is one rung of a questline); variables has no home in the shared shape and is dropped with a note.

{
  "id": "dragon_slayer",
  "titleKey": "quest.dragon_slayer.title",
  "tags": ["epic", "combat", "chapter-2"],
  "variables": { "difficulty": "hard", "region": "mountains" }
}

Visibility

The optional visibility object controls whether a quest appears in the quest log before it can be taken. By default every quest is visible. Once a quest is started it is always visible, whatever this says.

All the conditions set must pass for the quest to show. On the current shape the same answers live on Listing, and the conversion writes them there: hidden alone, or with requirePrerequisites, becomes RequirePrerequisites; hidden with requireLevel becomes a ShowWhen block carrying the quest's level floors; hidden with permission becomes ShowWhen with that node. A permission or requireLevel on a quest that was never hidden gated nothing, and is dropped with a note saying so.

Objectives

A quest step is the same objective shape every content kind shares: a Kind, a Target matched case-insensitively under a MatchMode, an optional Qualifier and Zone, and an Amount. The field-by-field reference, the one matching rule, and the full objective-kind roster live on Shared Schemas: objectives and criteria; the quest-file authoring page walks the same fields in place on Authoring Quests & Bounties.

Rewards

A quest pays through the one shared reward model: an open vocabulary of kinds under an Auto bucket (paid the instant the quest settles) and a Claim bucket (parked until collected, the default). The kind roster, the two buckets, writing a reward kind of your own, and the offline spool are documented once on Shared Schemas: rewards.

Quest States

Quest notices

Every quest notice, a progress tick, an objective finishing, the quest itself completing, parking, or being claimed, is its own editable file under Server/ZiggfreedCommon/FeedbackMoments/ (Quest_Objective_Progressed, Quest_Completed, Quest_Parked, Quest_Claimed). Reword, recolour, silence, or add a console broadcast to any of them by dropping a same-named file into a pack. See Authored feedback moments.

Admin Commands

/mmoquestadmin requires OP or mmoskilltree.admin. Except reload and list, it is an alias over the shared library's /zigprogress quest verbs (and resetdialogues over /zigprogress memory forget): same names, same arguments, same wording, and every verb speaks to the one quest engine the library owns, so a script may use either spelling. Two behaviours worth knowing: give settles a step the player already satisfies the moment the quest is taken on (a quest given to somebody past its finish line pays or parks at once), and reset wipes a record for a quest id the catalogue no longer knows instead of refusing it.

The library's own spelling of the same verbs is named-arg throughout: /zigprogress quest give --quest=<id> --player=<name> (or --everyone), reset --quest=<id|all> --player=<name>, complete --quest=<id> --player=<name>, status [--quest=<id>] [--player=<name>], list [--tag=<tag>], plus /zigprogress reload and /zigprogress memory forget --player=<name>. Those carry the library's own permission nodes rather than mmoskilltree.admin; see ZiggfreedCommon commands.

Player Commands

/quest is the player-side alias over /zigprogress quest accept|claim|abandon|status, under this mod's own mmoskilltree.command.quest node. It adds two bits of MMO policy: a quest authored as handed over only in conversation is refused from chat, and a claim checks for inventory room first so a full bag reads as "make room" rather than a refused button.

Examples

A daily quest

Once a day on the calendar, in UTC, taken manually:

// Server/ZiggfreedCommon/Quests/MyPack/Daily/Daily_Lumber.json
{
  "Name": "Daily_Lumber",
  "Text":    { "TitleKey": "quest.daily_lumber.title",
               "FlavorKey": "quest.daily_lumber.flavor" },
  "Listing": { "Category": "daily", "SortOrder": 100 },
  "Repeat":  { "Reset": { "Period": "Daily" } },
  "Objectives": {
    "chop_logs": { "Kind": "BREAK_BLOCK", "Target": "Wood", "Amount": 30 }
  },
  "Rewards": {
    "Claim": [
      { "Kind": "Item", "Params": { "Item": "XpToken_Woodcutting_Fragment", "Count": "2" } }
    ]
  }
}

A weekly that re-arms its dailies

{
  "Name": "Weekly_Master",
  "Text":    { "TitleKey": "quest.weekly_master.title" },
  "Listing": { "Category": "main" },
  "Repeat":  {
    "Reset": { "Period": "Weekly", "Weekday": "Monday" },
    "ResetsOnComplete": ["daily_lumber", "daily_mining", "daily_combat"]
  },
  "Objectives": {
    "kill_boss": { "Kind": "KILL_ENTITY", "Target": "Trork_Chieftain", "Amount": 1,
                   "MatchMode": "EXACT" }
  },
  "Rewards": {
    "Auto": [
      { "Kind": "Mmo_Xp", "Params": { "Skill": "SWORDS", "Amount": "50000" } }
    ]
  }
}

A quest behind either of two routes

{
  "Name": "Chapter2_Start",
  "Text":     { "TitleKey": "quest.chapter2_start.title" },
  "Listing":  { "Category": "main", "SortOrder": 10, "Tags": ["chapter-2"] },
  "Requires": {
    "Quests": ["chapter1_intro"],
    "AnyOf": [
      { "Quests": ["path_warrior_complete"] },
      { "Quests": ["path_mage_complete"] }
    ]
  },
  "Objectives": {
    "talk_elder": { "Kind": "TALK_TO_NPC", "Target": "Elder_Sages", "Amount": 1 }
  },
  "Rewards": {
    "Claim": [
      { "Kind": "Mmo_Boost_Token",
        "Params": { "Skill": "ALL", "Multiplier": "2.0", "DurationMinutes": "60" } }
    ]
  }
}

A delivery quest handed in at a character

The hand-in step removes the items from the player's bag when they deliver. Partial delivery is supported, so a player can hand over what they have and come back with the rest. Because the quest names a giver and asks for something to be delivered, that character offers a hand-in; a quest whose only step is talking to somebody does not, since nothing changes hands.

{
  "Name": "Blacksmith_Delivery",
  "Text":     { "TitleKey": "quest.blacksmith_delivery.title",
                "FlavorKey": "quest.blacksmith_delivery.flavor" },
  "Listing":  { "Category": "main" },
  "Npc":      { "ViewId": "Blacksmith_01" },
  "CompletionDialogue": "Blacksmith_Thanks",
  "Objectives": {
    "deliver_iron": { "Kind": "TURN_IN", "Target": "Ore_Iron", "Amount": 10,
                      "MatchMode": "EXACT" }
  },
  "Rewards": {
    "Claim": [
      { "Kind": "Mmo_Xp", "Params": { "Skill": "MINING", "Amount": "500" } }
    ]
  },
  "Meta": { "mmoskilltree": { "NpcOnly": true } }
}

The character themselves is a placement file, and their conversation is a dialogue file - see Placed NPCs and NPC Dialogue & Quest Givers. If you would rather drive characters through an external dialogue mod such as HyCitizens, point one of its buttons at /mmoquestui <player> <npc_id> to open the same quest panel.