Quests

Overview

The quest system lets you create tasks for players to complete - gathering resources, reaching skill levels, killing entities, and more. Quests are defined as JSON files in mods/mmoskilltree/quests/ and loaded automatically on startup.

Quests are organized into categories (e.g., main, daily, misc) and can have prerequisites, level requirements, and permission gates. Players interact with quests via the Quests UI tab or /quest, and admins manage them with /mmoquestadmin.

Want to ship quests as an installable add-on? Bundle them in a content pack - see the quest pack authoring reference for the full field set, the extends/params template DSL, and worked bounty-template examples, and templates for repeatable quest families in general.

Default Quests & Customization

On every server start, default quests are written to mods/mmoskilltree/quests/_defaults/default-quests.json. This file is always overwritten, so defaults stay up-to-date with new mod versions automatically.

To customize quests, create your own .json files anywhere in the quests/ folder (or subdirectories). If any user files exist outside of _defaults/ and backups/, the default quests are ignored entirely. The generated default file remains as a reference you can copy and customize.

Servers upgrading from older versions will have their example-quests.json automatically moved to quests/backups/.

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

File Structure

Each JSON file in the quests/ directory contains a schemaVersion and a quests array. You can split quests across multiple files (e.g., one per category). The directory is scanned recursively.

{
  "schemaVersion": 1,
  "quests": [
    {
      "id": "mining_beginner",
      "titleKey": "quest.mining_beginner.title",
      "flavorKey": "quest.mining_beginner.flavor",
      "category": "main",
      "tags": ["gathering", "beginner"],
      "enabled": true,
      "sortOrder": 1,
      "autoAccept": true,
      "sequential": false,
      "repeatable": false,
      "cooldownSeconds": 0,
      "autoClaimRewards": true,
      "permission": null,
      "prerequisites": [],
      "requirements": { "minLevel": 0, "minSkill": null, "minSkillLevel": 0 },
      "objectives": [
        {
          "id": "mine_stone",
          "type": "BREAK_BLOCK",
          "target": "Stone",
          "amount": 150,
          "displayText": "Mine 150 Stone blocks",
          "matchMode": "CONTAINS"
        }
      ],
      "rewards": [
        {
          "type": "COMMAND",
          "command": "/give {player} Tool_Pickaxe_Iron --quantity=1",
          "displayName": "Iron Pickaxe",
          "description": "A sturdy pickaxe for your efforts"
        },
        {
          "type": "XP",
          "skill": "MINING",
          "amount": 200,
          "displayName": "+200 Mining XP"
        }
      ]
    }
  ]
}

This example authors autoClaimRewards: true explicitly to opt into auto-claim. Omitting the field (or setting it false) is the current default and parks the quest at COMPLETED_UNCLAIMED until the player runs /quest claim. It also uses titleKey/flavorKey localization keys rather than the raw displayName/description literals - see Localization.

Quest Fields

Basic Fields

Behavior Fields

Requirements

The requirements field gates who can accept the quest. It accepts either a single object or an array of objects. All conditions must be met before the quest becomes available.

Single Object (one skill)

The simplest format - a single object with an optional total level gate and one skill requirement:

"requirements": {
  "minLevel": 25,
  "minSkill": "MINING",
  "minSkillLevel": 15
}

Array Format (multiple skills)

To require multiple skills, use an array of requirement objects. Each entry can specify a minLevel, a minSkill/minSkillLevel pair, or both. The highest minLevel across all entries is used as the total level gate, and every skill requirement must be met.

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

In this example, the player needs total level 25, Mining level 15, and Crafting level 20 to accept the quest. All skill requirements are displayed in the quest log's “Requires:” line.

Both formats are fully supported. Use the single object when you only need one skill gate, and the array when you need multiple.

Prerequisites

Prerequisites control which quests must be completed before this quest becomes available. There are two formats: a simple array (AND-all) and a structured object (AND/OR grouping).

Simple Format (AND)

A plain array of quest IDs - all must be completed:

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

Branching Format (AND/OR)

For branching storylines, use an object with mode and nested groups. This lets you create quest paths where players can choose between different branches:

"prerequisites": {
  "mode": "AND",
  "quests": ["quest_intro"],
  "groups": [
    {
      "mode": "OR",
      "quests": ["quest_path_warrior", "quest_path_mage"]
    }
  ]
}

In this example, the player must complete quest_intro AND either quest_path_warrior OR quest_path_mage.

Groups can be nested to any depth. The simple array format is fully backward compatible and equivalent to { "mode": "AND", "quests": [...] }. This is the same PrerequisiteGroup schema shared by Mastery track/node requirements, ShopEntry/ ShopPool/BountyBoard gates, and Currency visibility - see the content-pack schemas reference if it documents the shared shape.

The quest UI displays branching prerequisites with "OR" labels so players can see which paths are available. Permission requirements display as "Permission: node.name".

Permission Prerequisites

Add a permissions array to any prerequisite group to require permission nodes alongside quest completions. Permissions and quests can be freely mixed in AND/OR logic:

"prerequisites": {
  "mode": "AND",
  "quests": ["first_blood"],
  "permissions": ["rank.vip", "server.quest.unlock"]
}

In this example, the player must have completed first_blood AND hold both rank.vip and server.quest.unlock permissions. In OR mode, completing any quest or holding any permission in the group would be enough.

Permissions work at any nesting level, so you can create complex gates like "complete quest_a AND (have rank.vip OR complete quest_b)".

Visibility

The optional visibility object controls whether a quest appears in the quest log. By default, all quests are visible. Hidden quests remain invisible until their conditions are met - but once a quest is started (active, completed, or on cooldown), it is always visible regardless of visibility settings.

When multiple conditions are set, all must pass for the quest to be visible. If hidden is true with no other conditions, the quest falls back to the standard acceptance check - it becomes visible when the player meets all requirements and prerequisites.

"visibility": {
  "hidden": true,
  "requirePrerequisites": true
}

This is useful for quest chains where you don't want players to see future quests until they've completed the current step.

Objectives

Each quest has one or more objectives. Objective ordering can be controlled in two ways:

• sequential: true - All objectives must be completed top-to-bottom (legacy behavior, still supported)
• Per-objective order field - Group objectives into stages for mixed sequential/parallel completion

Objective text is auto-generated and localized from the objective type, target, and amount, so each player sees it in their own client language. The displayText field is an optional override; leave it out to use the localized default.

Objective Types

REACH_LEVEL and BOUNTY_STREAK are value-based (they track a high-water mark, not an accumulating delta) - every other type accumulates toward amount.

Objective Fields

Objective Ordering

The order field lets you create quests with mixed sequential and parallel objectives. Objectives with the same order value can be completed in any order (parallel). Objectives with a higher order value are locked until all lower-order objectives are complete.

"objectives": [
  { "id": "gather_ore", "type": "BREAK_BLOCK", "target": "Ore_Iron", "amount": 10, "order": 1 },
  { "id": "craft_ingots", "type": "CRAFT_ITEM", "target": "Ingot_Iron", "amount": 5, "order": 1 },
  { "id": "kill_boss", "type": "KILL_ENTITY", "target": "Skeleton", "amount": 3, "order": 2 }
]

In this example, the first two objectives (order 1) can be done in any order. The third objective (order 2) only becomes active after both order-1 objectives are complete. The quest UI groups objectives by stage and shows which are currently active.

• order: 0 or omitted - No ordering constraint (parallel with everything)
• Using sequential: true auto-assigns incrementing order values for backward compatibility

Match Modes

Qualifier (Secondary Filter)

The qualifier field adds a secondary filter beyond target. When set, both the target and qualifier must match for progress to count. This is useful for filtering by elite mob tier, weapon type, or other event metadata.

{
  "id": "kill_legendary_bears",
  "type": "KILL_ENTITY",
  "target": "Bear",
  "qualifier": "Legendary",
  "amount": 3,
  "displayText": "Defeat 3 Legendary Bears"
}

• Omitted or null - matches any event (backward compatible)
• Empty string "" - only matches events with no qualifier (e.g., normal mobs)
• Any other value - case-insensitive exact match against the event qualifier

Rewards

Quest rewards are delivered when the quest is completed (or claimed, if autoClaimRewards is false). Each quest can have multiple rewards. Rewards support four types: commands, XP grants, boost tokens, and currency.

Reward Types

If type is omitted, the reward defaults to COMMAND for backward compatibility. Existing command-based rewards continue to work unchanged.

Reward Examples

"rewards": [
  {
    "type": "COMMAND",
    "command": "/give {player} Tool_Pickaxe_Iron --quantity=1",
    "displayName": "Iron Pickaxe"
  },
  {
    "type": "XP",
    "skill": "MINING",
    "amount": 500,
    "displayName": "+500 Mining XP"
  },
  {
    "type": "BOOST_TOKEN",
    "skill": "ALL",
    "multiplier": 2.0,
    "durationMinutes": 30,
    "displayName": "2x All XP (30m)"
  },
  {
    "type": "CURRENCY",
    "currencyId": "gold",
    "amount": 100,
    "displayName": "100 Gold"
  }
]

Common Reward Fields

An OPAQUE (non-/give) COMMAND reward MUST carry a nameKey (validator-enforced) since it cannot auto-render a display line from the command text. A /give {player} <item> --quantity=N command is the one form that DOES auto-render (parsed for its item icon/name) - --quantity=N is the only accepted quantity form; a positional quantity is silently ignored by Hytale's /give.

Command Reward Fields

Command Placeholders

XP Reward Fields

Boost Token Reward Fields

Currency Reward Fields

Tags & Variables

Quests can include tags for categorization and variables for custom metadata. Tags are displayed as chips below the quest description in the quest UI and are also used for filtering on the docs site Quest Gallery.

{
  "id": "dragon_slayer",
  "displayName": "Dragon Slayer",
  "tags": ["epic", "combat", "chapter-2"],
  "variables": {
    "difficulty": "hard",
    "region": "mountains"
  }
}

Variables are stored as key-value pairs and are available for future conditional logic and filtering on the docs site quest gallery.

Quest States

Each quest tracks a per-player state:

Flow: NOT_STARTED → ACTIVE → COMPLETED (auto-claim) or COMPLETED_UNCLAIMED → COMPLETED (manual claim). For repeatable quests, the cycle resets after the cooldown period.

Admin Commands

The /mmoquestadmin command requires OP or mmoskilltree.admin permission. Arguments are pipe-separated.

Player Commands

The /quest command is available to all players.

Examples

Simple Gathering Quest

A beginner quest that auto-accepts and rewards an iron pickaxe:

{
  "id": "mining_beginner",
  "displayName": "Novice Miner",
  "description": "Prove your mining skills by breaking some stone.",
  "category": "main",
  "sortOrder": 1,
  "autoAccept": true,
  "objectives": [
    {
      "id": "mine_stone",
      "type": "BREAK_BLOCK",
      "target": "Stone",
      "amount": 150,
      "displayText": "Mine 150 Stone blocks"
    }
  ],
  "rewards": [
    {
      "command": "/give {player} Tool_Pickaxe_Iron --quantity=1",
      "displayName": "Iron Pickaxe",
      "description": "A sturdy pickaxe for your efforts"
    }
  ]
}

Sequential Quest with Prerequisites

Requires the mining_beginner quest to be completed first and Mining level 5. Objectives must be completed in order:

{
  "id": "mining_journeyman",
  "displayName": "Journeyman Miner",
  "description": "Advance your mining career with harder materials.",
  "category": "main",
  "sortOrder": 2,
  "autoAccept": true,
  "sequential": true,
  "prerequisites": ["mining_beginner"],
  "requirements": {
    "minSkill": "MINING",
    "minSkillLevel": 5
  },
  "objectives": [
    {
      "id": "mine_iron",
      "type": "BREAK_BLOCK",
      "target": "Ore_Iron",
      "amount": 25,
      "displayText": "Mine 25 Iron Ore"
    },
    {
      "id": "reach_mining_10",
      "type": "REACH_LEVEL",
      "target": "MINING",
      "amount": 10,
      "displayText": "Reach Mining level 10"
    }
  ],
  "rewards": [
    {
      "command": "/give {player} XpToken_Unarmed_Shard --quantity=2",
      "queueIfOffline": true,
      "displayName": "Unarmed XP Shards x2"
    }
  ]
}

Repeatable Daily Quest

Repeatable every 24 hours (86400 seconds). Not auto-accepted - players must start it manually or via admin command:

{
  "id": "daily_woodcutting",
  "displayName": "Daily Lumber",
  "description": "Chop some wood for daily rewards.",
  "category": "daily",
  "sortOrder": 100,
  "autoAccept": false,
  "repeatable": true,
  "cooldownSeconds": 86400,
  "objectives": [
    {
      "id": "chop_logs",
      "type": "BREAK_BLOCK",
      "target": "Wood",
      "amount": 30,
      "displayText": "Chop 30 logs"
    }
  ],
  "rewards": [
    {
      "command": "/give {player} XpToken_Woodcutting_Fragment --quantity=2",
      "queueIfOffline": true,
      "displayName": "2 Woodcutting XP Fragments",
      "description": "Daily woodcutting payment"
    }
  ]
}

Weekly Quest That Resets Dailies

A weekly "master" quest that fully resets a group of daily quests when claimed - clearing their state, progress, and cooldown so players can run the dailies again immediately. Pair this with repeatable: true so the master itself can be completed every cycle:

{
  "id": "weekly_master",
  "displayName": "Weekly Master",
  "description": "Complete the weekly challenge to reset your daily quests.",
  "category": "main",
  "repeatable": true,
  "cooldownSeconds": 604800,
  "resetsOnComplete": ["daily_mining", "daily_combat", "daily_woodcutting"],
  "objectives": [
    {
      "id": "kill_boss",
      "type": "KILL_ENTITY",
      "target": "Dragon",
      "amount": 1,
      "displayText": "Defeat a Dragon"
    }
  ],
  "rewards": [
    {
      "type": "XP",
      "skill": "SWORDS",
      "amount": 50000,
      "displayName": "50,000 Swords XP"
    }
  ]
}

Hidden Quest Chain

This quest is invisible until the player completes mining_journeyman. The visibility object with requirePrerequisites: true prevents spoilers for future quest steps:

{
  "id": "mining_expert",
  "displayName": "Mining Expert",
  "description": "Prove yourself as a true mining expert.",
  "category": "main",
  "sortOrder": 3,
  "sequential": true,
  "prerequisites": ["mining_journeyman"],
  "requirements": {
    "minSkill": "MINING",
    "minSkillLevel": 15
  },
  "visibility": {
    "hidden": true,
    "requirePrerequisites": true
  },
  "objectives": [
    {
      "id": "mine_gold",
      "type": "BREAK_BLOCK",
      "target": "Ore_Gold",
      "amount": 50,
      "displayText": "Mine 50 Gold Ore"
    },
    {
      "id": "reach_mining_20",
      "type": "REACH_LEVEL",
      "target": "MINING",
      "amount": 20,
      "displayText": "Reach Mining level 20"
    }
  ],
  "rewards": [
    {
      "command": "/give {player} XpToken_Mining_Token --quantity=3",
      "queueIfOffline": true,
      "displayName": "3 Mining XP Tokens",
      "description": "A reward for the dedicated miner"
    }
  ]
}

Multi-Skill Requirements

This quest requires both Mining 30 and Crafting 20 before it can be accepted. The array format lets you gate quests behind any combination of skills:

{
  "id": "master_smith",
  "displayName": "Master Smith",
  "description": "Only a skilled miner and crafter can forge the ultimate blade.",
  "category": "main",
  "sortOrder": 20,
  "requirements": [
    { "minSkill": "MINING", "minSkillLevel": 30 },
    { "minSkill": "CRAFTING", "minSkillLevel": 20 }
  ],
  "objectives": [
    {
      "id": "craft_blade",
      "type": "CRAFT_ITEM",
      "target": "Weapon_Longsword",
      "amount": 1,
      "displayText": "Craft a Longsword"
    }
  ],
  "rewards": [
    {
      "command": "/give {player} XpToken_Crafting_Token --quantity=2",
      "queueIfOffline": true,
      "displayName": "2 Crafting XP Tokens",
      "description": "A reward for the master smith"
    }
  ]
}

Branching Prerequisites

A quest that requires completing an intro quest AND choosing one of two class paths. Players who completed either the warrior or mage path can continue to this quest:

{
  "id": "chapter2_start",
  "displayName": "Chapter 2: The Convergence",
  "description": "Both paths lead here. Your journey continues.",
  "category": "main",
  "sortOrder": 10,
  "tags": ["chapter-2", "epic"],
  "prerequisites": {
    "mode": "AND",
    "quests": ["chapter1_intro"],
    "groups": [
      {
        "mode": "OR",
        "quests": ["path_warrior_complete", "path_mage_complete"]
      }
    ]
  },
  "objectives": [
    {
      "id": "talk_elder",
      "type": "KILL_ENTITY",
      "target": "Elder_NPC",
      "amount": 1,
      "displayText": "Speak with the Elder"
    }
  ],
  "rewards": [
    {
      "type": "BOOST_TOKEN",
      "skill": "ALL",
      "multiplier": 2.0,
      "durationMinutes": 60,
      "displayName": "2x All XP (1hr)"
    }
  ]
}

Mixed Sequential/Parallel Objectives

Objectives with the same order value can be completed in any order. Higher order values unlock after lower ones are done:

{
  "id": "forge_master",
  "displayName": "Forge Master",
  "description": "Gather materials, then forge the blade.",
  "category": "main",
  "sortOrder": 15,
  "objectives": [
    {
      "id": "mine_ore",
      "type": "BREAK_BLOCK",
      "target": "Ore_Iron",
      "amount": 20,
      "displayText": "Mine 20 Iron Ore",
      "order": 1
    },
    {
      "id": "chop_wood",
      "type": "BREAK_BLOCK",
      "target": "Wood",
      "amount": 10,
      "displayText": "Gather 10 Wood",
      "order": 1
    },
    {
      "id": "craft_blade",
      "type": "CRAFT_ITEM",
      "target": "Weapon_Longsword_Iron",
      "amount": 1,
      "displayText": "Forge an Iron Longsword",
      "order": 2
    }
  ],
  "rewards": [
    {
      "type": "XP",
      "skill": "CRAFTING",
      "amount": 1000,
      "displayName": "+1000 Crafting XP"
    },
    {
      "type": "CURRENCY",
      "currencyId": "gold",
      "amount": 50,
      "displayName": "50 Gold"
    }
  ]
}

Quest with Manual Claim

With autoClaimRewards: false, the quest enters the COMPLETED_UNCLAIMED state when objectives are done. Players must use /quest claim to receive rewards - useful when inventory space matters:

{
  "id": "boss_bounty",
  "displayName": "Boss Bounty",
  "description": "Defeat a powerful boss. Return to claim your reward.",
  "category": "main",
  "sortOrder": 6,
  "autoClaimRewards": false,
  "objectives": [
    {
      "id": "slay_boss",
      "type": "KILL_ENTITY",
      "target": "Trork_Chieftain",
      "amount": 1,
      "displayText": "Defeat the Trork Chieftain",
      "matchMode": "EXACT"
    }
  ],
  "rewards": [
    {
      "command": "/give {player} Diamond_Sword --quantity=1",
      "queueIfOffline": true,
      "displayName": "Diamond Sword",
      "description": "A legendary blade for the champion"
    }
  ]
}

NPC Quest with Turn In

Quests can be tied to NPCs using npcViewId. The built-in native dialogue engine and quest-giver runtime NPC roles let you spawn a quest giver and have players discover, accept, and turn in these quests through NPC interaction (opened via /mmoquestui) - no third-party mod required. The TURN_IN objective type removes items from the player's inventory when they click the Turn In button. Partial turn-in is supported - players can submit what they have and return later with more.

{
  "id": "blacksmith_delivery",
  "displayName": "The Blacksmith's Order",
  "description": "Gorrath needs iron ore for his forge.",
  "category": "main",
  "npcViewId": "blacksmith_01",
  "npcDisplayName": "Gorrath the Blacksmith",
  "npcRequiredToAccept": true,
  "incompleteMarkdown": "# The Blacksmith's Request\n\n**Gorrath** looks up from his anvil.\n\n\"I need iron ore. Can you help?\"",
  "activeMarkdown": "\"Still gathering? I'll be here.\"",
  "completeMarkdown": "\"Excellent work! These will do nicely.\"",
  "objectives": [
    {
      "id": "deliver_iron",
      "type": "TURN_IN",
      "target": "Ore_Iron",
      "amount": 10,
      "displayText": "Deliver 10 Iron Ore",
      "matchMode": "EXACT",
      "detailMarkdown": "\"Bring me **10 Iron Ore** from the northern mines.\""
    }
  ],
  "rewards": [
    {
      "type": "XP",
      "skill": "MINING",
      "amount": 500,
      "displayName": "500 Mining XP"
    }
  ]
}