Levelable System

Levelable System

Levelables are RPG-style skills that level up from gameplay. Players gain XP from events you define — mining blocks, winning battles, catching Pokemon, walking around — and earn rewards at each level.

Want a Mining skill that levels up from breaking ores? A Combat skill from winning battles? An Exploration skill from walking? Levelables do all of that.

---

Quick Start

Here’s a simple combat levelable that gives XP for winning battles:

File: config/journey/levelables/combat.json

{
  "name": "Combat",
  "description": [
    "Improve your battle prowess through combat experience."
  ],
  "icon": {
    "item_id": "minecraft:diamond_sword",
    "item_display_name": "<red>Combat",
    "item_lore": [
      "<gray>Become a master of battle!"
    ]
  },
  "sources": [
    "<red>Winning Battles",
    "<red>Landing Super Effective Hits"
  ],
  "levels": [
    {"level": 1, "required_experience": 0, "rewards": []},
    {
      "level": 2,
      "required_experience": 100,
      "rewards": [
        {
          "type": "currency",
          "data": {
            "currency_id": "impactor:pokedollars",
            "amount": 200
          }
        }
      ]
    },
    {
      "level": 5,
      "required_experience": 500,
      "rewards": [
        {
          "type": "script",
          "data": {
            "scripts": [
              "q.player.add_flag('combat_level_5');",
              "q.player.tell_minimessage('<gold>Combat Level 5 Reached!');"
            ]
          }
        }
      ]
    }
  ],
  "events": [
    {
      "type": "battle_victory",
      "filter": {
        "type": "script",
        "filter": "q.battle.is_pvw"
      },
      "experience": 10.0
    },
    {
      "type": "super_effective_move_used",
      "filter": {
        "type": "script",
        "filter": "1.0 == 1.0"
      },
      "experience": 2.0
    }
  ]
}

Win a wild battle, get 10 XP. Land a super effective move, get 2 XP. At 100 total XP, reach level 2 and earn 200 Pokedollars.

---

Levelable Structure

Field	Type	Description
name	String	Display name (used in commands and GUIs)
description	String[]	Description lines (supports MiniMessage)
icon	Object	Item icon for GUIs
sources	String[]	Display-only list of XP sources
levels	Array	Level definitions with XP thresholds and rewards
events	Array	Event definitions that award XP

Icon

{
  "item_id": "minecraft:diamond_pickaxe",
  "item_display_name": "<green>Miner",
  "item_lore": [
    "<gray>Excavate the earth to find precious ores."
  ]
}

---

Levels

Each level defines a cumulative XP requirement and optional rewards:

{
  "level": 10,
  "required_experience": 1000,
  "rewards": [
    {
      "type": "command",
      "data": {
        "reward_string": "<gold>1x Diamond",
        "command": "give {player} minecraft:diamond 1"
      }
    }
  ]
}

Note

required_experience is cumulative — it’s the total XP to reach that level from zero, not the XP needed from the previous level.

XP Progression Curves

Linear (steady increase):

{"level": 1, "required_experience": 0},
{"level": 2, "required_experience": 100},
{"level": 3, "required_experience": 200},
{"level": 4, "required_experience": 300},
{"level": 5, "required_experience": 400}

Exponential (gets harder over time):

{"level": 1, "required_experience": 0},
{"level": 2, "required_experience": 100},
{"level": 3, "required_experience": 250},
{"level": 4, "required_experience": 500},
{"level": 5, "required_experience": 1000}

Tip

Use a spreadsheet to plan XP curves for many levels. Common formulas:

• Linear: level * 100
• Quadratic: level^2 * 25
• Exponential: 100 * 1.5^level

---

Events

Events define how players gain XP. Each event specifies a trigger, a filter, and an XP amount:

{
  "type": "break_block",
  "filter": {
    "type": "script",
    "filter": "q.block.id == 'minecraft:diamond_ore'"
  },
  "experience": 25.0,
  "sends_notification": true
}

Field	Type	Description
type	String	Event type (lowercase with underscores)
filter	Object	Filter object with type and filter fields
experience	Number	XP to award when event matches
sends_notification	Boolean	Show boss bar XP notification (default: true)

Important: Levelable Filter Format

Levelable filters use an object format (not a plain string like task filters):

{
  "filter": {
    "type": "script",
    "filter": "q.block.id == 'minecraft:stone'"
  }
}

To match any event (no filtering), use:

{
  "filter": {
    "type": "script",
    "filter": "1.0 == 1.0"
  }
}

Event Type Names

Event types in levelable configs use lowercase with underscores:

Levelable Event Type	Task Event Type
pokemon_capture	POKEMON_CAPTURE
battle_victory	BATTLE_VICTORY
break_block	BREAK_BLOCK
enter_zone	ENTER_ZONE
step	(walking - unique to levelables)

The step event fires every time the player takes a step — great for exploration skills.

See the Events page for the full list. All event types work in levelables.

---

Rewards

Levelable rewards support all the same types as task rewards:

Command Reward

{
  "type": "command",
  "data": {
    "reward_string": "<green>1x Diamond",
    "command": "give {player} minecraft:diamond 1"
  }
}

The optional reward_string is display text shown in the level-up notification.

Currency Reward

{
  "type": "currency",
  "data": {
    "currency_id": "impactor:pokedollars",
    "amount": 500
  }
}

Script Reward

{
  "type": "script",
  "data": {
    "scripts": [
      "q.player.add_flag('miner_level_50');",
      "q.player.tell_minimessage('<gold>Milestone: Master Miner!');"
    ]
  }
}

Timeline Reward

{
  "type": "timeline",
  "data": {
    "timeline": "journey:level_up_celebration"
  }
}

Buff Reward

{
  "type": "buff",
  "data": {
    "buff_id": "mining_haste",
    "duration": -1,
    "amplifier": 0,
    "source": "miner_levelable"
  }
}

Caution

Permanent buffs granted from levelable rewards are automatically removed if the player loses that levelable. Use the source field consistently so Journey can track which buffs came from which levelable.

---

Boss Bar Notifications

When sends_notification is true, players see a boss bar showing their XP progress:

[=======>     ] Miner: 450 / 500 XP

The bar appears for 5 seconds and updates with each XP gain. Set sends_notification: false for frequent events (like walking) to avoid spamming the player:

{
  "type": "step",
  "filter": {"type": "script", "filter": "1.0 == 1.0"},
  "experience": 0.01,
  "sends_notification": false
}

---

Complete Examples

Mining Skill

File: config/journey/levelables/miner.json

{
  "name": "Miner",
  "description": [
    "Mine resources from the ground to gather materials for crafting."
  ],
  "icon": {
    "item_id": "minecraft:diamond_pickaxe",
    "item_display_name": "<green>Miner",
    "item_lore": [
      "<gray>Excavate the earth to find precious ores and gems."
    ]
  },
  "sources": [
    "<green>Mining Ores",
    "<green>Mining Stone"
  ],
  "levels": [
    {"level": 1, "required_experience": 0, "rewards": []},
    {
      "level": 2,
      "required_experience": 100,
      "rewards": [
        {
          "type": "command",
          "data": {
            "reward_string": "<green>1x Iron Ore",
            "command": "give {player} minecraft:iron_ore 1"
          }
        }
      ]
    },
    {
      "level": 10,
      "required_experience": 1000,
      "rewards": [
        {
          "type": "command",
          "data": {
            "reward_string": "<gold>Milestone: 1x Diamond",
            "command": "give {player} minecraft:diamond 1"
          }
        },
        {
          "type": "script",
          "data": {
            "scripts": ["q.player.add_flag('miner_level_10');"]
          }
        }
      ]
    }
  ],
  "events": [
    {
      "type": "break_block",
      "filter": {"type": "script", "filter": "q.block.id == 'minecraft:stone'"},
      "experience": 0.1,
      "sends_notification": false
    },
    {
      "type": "break_block",
      "filter": {"type": "script", "filter": "q.block.id == 'minecraft:iron_ore'"},
      "experience": 5.0
    },
    {
      "type": "break_block",
      "filter": {"type": "script", "filter": "q.block.id == 'minecraft:diamond_ore'"},
      "experience": 25.0
    },
    {
      "type": "break_block",
      "filter": {"type": "script", "filter": "q.block.id == 'minecraft:emerald_ore'"},
      "experience": 10.0
    }
  ]
}

Explorer Skill

File: config/journey/levelables/explorer.json

{
  "name": "Explorer",
  "description": [
    "Explore the world and discover new locations."
  ],
  "icon": {
    "item_id": "minecraft:compass",
    "item_display_name": "<green>Explorer",
    "item_lore": [
      "<gray>Every step brings new discovery."
    ]
  },
  "sources": [
    "<green>Walking",
    "<green>Entering Zones"
  ],
  "levels": [
    {"level": 1, "required_experience": 0, "rewards": []},
    {"level": 2, "required_experience": 100, "rewards": []},
    {
      "level": 5,
      "required_experience": 500,
      "rewards": [
        {
          "type": "currency",
          "data": {
            "currency_id": "impactor:pokedollars",
            "amount": 500
          }
        }
      ]
    }
  ],
  "events": [
    {
      "type": "step",
      "filter": {"type": "script", "filter": "1.0 == 1.0"},
      "experience": 0.01,
      "sends_notification": false
    },
    {
      "type": "enter_zone",
      "filter": {"type": "script", "filter": "1.0 == 1.0"},
      "experience": 50.0
    }
  ]
}

At 0.01 XP per step, it takes 10,000 steps (about 5 minutes of walking) to gain 100 XP. Entering any zone gives a big 50 XP bonus.

---

Molang Functions

Checking Progress

q.player.has_levelable('Miner')               Is the skill unlocked?
q.player.levelable_level('Miner')              Current level
q.player.levelable_experience('Miner')         Current XP

Managing Levelables

q.player.give_levelable('Miner')               Unlock a skill
q.player.progress_levelable('Miner', 50)       Add 50 XP
q.player.remove_levelable('Miner')             Remove a skill

In Task Requirements

{
  "start_requirement": "q.player.levelable_level('Combat') >= 25"
}

---

File Location

Levelable configs go in config/journey/levelables/:

config/journey/levelables/
├── miner.json
├── explorer.json
├── combat.json
└── breeder.json

---

Commands

Command	Description
/levelable give <player> <levelable>	Unlock a levelable for a player
/levelable remove <player> <levelable>	Remove a levelable from a player
/levelable progress <player> <levelable> <amount>	Award XP
/levelable open <player>	Open the levelable GUI
/levelable switch <player> <levelable>	Switch active levelable
/levelable respec <player> [levelable]	Reset progress

---

Tips

• Balance XP amounts: Rare events (diamond ore) should give much more XP than common ones (stone)
• Use sends_notification: false for frequent events like walking or stone mining to avoid notification spam
• Put rewards at milestones: Every 5 or 10 levels works well
• Use the source field on buff rewards so they get cleaned up properly
• Test your XP curve in-game: Make sure early levels feel achievable and later levels feel rewarding