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.

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",
      "displayName": "Novice Miner",
      "description": "Prove your mining skills by breaking some stone.",
      "category": "main",
      "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": [
        {
          "command": "/give {player} Tool_Pickaxe_Iron --quantity=1",
          "runAs": "CONSOLE",
          "delayTicks": 0,
          "queueIfOffline": false,
          "displayName": "Iron Pickaxe",
          "description": "A sturdy pickaxe for your efforts"
        }
      ]
    }
  ]
}

Quest Fields

Basic Fields

Behavior Fields

Requirements

The requirements object gates who can accept the quest. All conditions must be met before the quest becomes available.

The prerequisites array lists quest IDs that must be completed before this quest becomes available:

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

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. When sequential is enabled, objectives must be completed in the order they are listed.

Objective Types

Objective Fields

Match Modes

Rewards

Quest rewards are commands executed when the quest is completed (or claimed, if autoClaimRewards is false). Each quest can have multiple rewards.

Command Placeholders

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"
    }
  ]
}

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"
    }
  ]
}

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"
    }
  ]
}