Levelable System

The Levelable System provides RPG-style skill progression for players. Define skills that gain experience from gameplay events, level up, and grant rewards at specific levels.

🛠️ Visual Levelable Builder Create levelable configurations with an easy-to-use visual interface and event builder

Overview

Levelables offer:

Experience-Based Progression: Players gain XP from defined events and level up
Level Rewards: Commands, currency, scripts, or timelines granted upon leveling
Event Integration: Use any of Journey’s 28 event types to award experience
Boss Bar Notifications: Visual XP progress feedback
MoLang Functions: Check levels and award XP via scripting

Common Use Cases:

Mining skills that level up from breaking blocks
Combat skills from battle victories
Exploration skills from discovering zones
Crafting professions from item creation

Levelable Structure

Every levelable follows this structure:

{
  "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": [],
  "events": []
}

Fields:

name - Display name for the levelable (used in commands and GUIs)
description - Array of description lines (supports MiniMessage)
icon - Icon configuration (see Icon section)
sources - Array of strings describing XP sources (display only)
levels - Array of level definitions with XP requirements and rewards
events - Array of event progress definitions that award experience

Icon Configuration

Icons are displayed in GUIs and notifications:

{
  "item_id": "minecraft:compass",
  "item_display_name": "<green>Explorer",
  "item_lore": [
    "<gray>Explore the world and discover its treasures!"
  ]
}

Fields:

item_id - Minecraft item resource location
item_display_name - Display name (supports MiniMessage)
item_lore - Array of lore lines (supports MiniMessage)

All fields support MiniMessage formatting (<gold>, <gray>, etc.).

Level Definitions

Each level specifies the total experience required to reach it and rewards granted:

{
  "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": 3,
      "required_experience": 250,
      "rewards": [
        {
          "type": "currency",
          "data": {
            "currency": "impactor:pokedollars",
            "amount": 500
          }
        }
      ]
    }
  ]
}

Level Fields:

level - Level number (sequential starting from 1)
required_experience - Total XP needed to reach this level from level 0
rewards - Array of rewards granted when reaching this level

Important: required_experience is cumulative. To reach level 3 (250 XP), player needs 250 total XP, not 250 + 100.

Experience Progression

Experience requirements are defined per-level. You manually set the total XP for each level.

Example Progression Curves

Linear (constant increase):

{
  "levels": [
    {"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 (accelerating increase):

{
  "levels": [
    {"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}
  ]
}

Custom (any curve you want):

{
  "levels": [
    {"level": 1, "required_experience": 0},
    {"level": 2, "required_experience": 83},
    {"level": 3, "required_experience": 174},
    {"level": 4, "required_experience": 276},
    {"level": 5, "required_experience": 388}
  ]
}

Tip: Use a spreadsheet or calculator to generate XP curves for many levels. See the “Miner” levelable config for a 100-level example.

Event Progress Definitions

Events define how players gain experience. Use Journey’s event system to award XP:

{
  "events": [
    {
      "type": "block_break",
      "filter": {
        "type": "script",
        "filter": "q.block.id == 'minecraft:stone'"
      },
      "experience": 0.1,
      "sends_notification": false
    },
    {
      "type": "block_break",
      "filter": {
        "type": "script",
        "filter": "q.block.id == 'minecraft:diamond_ore'"
      },
      "experience": 25.0,
      "sends_notification": true
    },
    {
      "type": "pokemon_caught",
      "filter": {
        "type": "script",
        "filter": "1.0 == 1.0"
      },
      "experience": 10.0
    }
  ]
}

Event Definition Fields:

type - Event type (any of Journey’s 28 events - lowercase with underscores)
filter - Event filter (same as task event filters)
experience - XP amount to award when event matches
sends_notification - Show boss bar XP notification (optional, default: true)

Available Event Types:

pokemon_caught, pokemon_evolve, pokemon_level_up, hatch_egg
battle_victory, battle_fled, move_used, super_effective_move_used
enter_zone, leave_zone, enter_zone_area
item_pickup, item_throw, entity_interact
break_block, block_placed, block_use
step (every step player takes)
mega_evolution, terastallization, zpower_used, fossil_revived
experience_candy_used, apricorn_harvested, berry_harvested, egg_collected
run_command, kill_entity, starter_chosen
And more - see Events documentation

Filters

Filters use MoLang expressions to determine if an event should award XP:

Filter Types

Script Filter (Most Common):

{
  "filter": {
    "type": "script",
    "filter": "q.pokemon.species.identifier == 'cobblemon:pikachu'"
  }
}

Always Match:

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

Filter Examples

Block Breaking:

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

Battle Victories:

{
  "type": "battle_victory",
  "filter": {
    "type": "script",
    "filter": "q.battle.is_wild"
  },
  "experience": 5.0
}

Zone Entry:

{
  "type": "enter_zone",
  "filter": {
    "type": "script",
    "filter": "q.zone.uuid == 'zone-uuid-here'"
  },
  "experience": 100.0
}

Step Tracking (Exploration):

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

Rewards

Levelables support all Journey reward types:

Command Rewards

Execute commands when level is reached:

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

{player} is replaced with player name
reward_string is optional display text

Currency Rewards

Award Impactor economy currency:

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

Script Rewards

Execute MoLang scripts:

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

Timeline Rewards

Launch timelines (orchestrated sequences of actions):

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

MoLang Integration

Checking Levelable Progress

// Check if player has a levelable
q.player.has_levelable('Miner')  // Returns 1.0 or 0.0

// Get current level
q.player.levelable_level('Miner')  // Returns level number (0 if not has)

// Get current experience
q.player.levelable_experience('Miner')  // Returns XP amount

Managing Levelables

// Give a levelable to player
q.player.give_levelable('Miner')

// Award experience
q.player.progress_levelable('Miner', 50.0)  // Add 50 XP

// Remove a levelable
q.player.remove_levelable('Miner')

Usage in Task Start Requirements

{
  "start_requirement": "q.player.levelable_level('Miner') >= 10.0"
}

Usage in Event Filters

{
  "event": "BREAK_BLOCK",
  "filter": "q.player.levelable_level('Miner') >= 25.0",
  "target": 1
}

Complete Examples

Example 1: Mining Skill

Config: 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": [
        {
          "type": "command",
          "data": {
            "reward_string": "<green>1x Iron Ore",
            "command": "give {player} minecraft:iron_ore 1"
          }
        }
      ]
    },
    {
      "level": 2,
      "required_experience": 100,
      "rewards": [
        {
          "type": "command",
          "data": {
            "reward_string": "<green>1x Gold Ore",
            "command": "give {player} minecraft:gold_ore 1"
          }
        }
      ]
    },
    {
      "level": 10,
      "required_experience": 996,
      "rewards": [
        {
          "type": "command",
          "data": {
            "reward_string": "<green>1x Redstone",
            "command": "give {player} minecraft:redstone 1"
          }
        },
        {
          "type": "command",
          "data": {
            "reward_string": "<gold>Milestone: 1x Diamond",
            "command": "give {player} minecraft:diamond 1"
          }
        }
      ]
    }
  ],
  "events": [
    {
      "type": "break_block",
      "filter": {
        "type": "script",
        "filter": "q.block.id == 'minecraft:stone'"
      },
      "experience": 0.1
    },
    {
      "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
    }
  ]
}

Example 2: Explorer Skill

Config: config/journey/levelables/explorer.json

{
  "name": "Explorer",
  "description": [
    "The Explorer is a journey that rewards players for exploring the world."
  ],
  "icon": {
    "item_id": "minecraft:compass",
    "item_display_name": "<green>Explorer",
    "item_lore": [
      "<gray>Explore the world and discover its treasures!"
    ]
  },
  "sources": [
    "<green>Exploring the world"
  ],
  "levels": [
    {
      "level": 1,
      "required_experience": 0,
      "rewards": []
    },
    {
      "level": 2,
      "required_experience": 83,
      "rewards": [
        {
          "type": "command",
          "data": {
            "command": "give {player} minecraft:iron_ore 1"
          }
        }
      ]
    },
    {
      "level": 5,
      "required_experience": 388,
      "rewards": [
        {
          "type": "command",
          "data": {
            "command": "give {player} minecraft:emerald_ore 1"
          }
        }
      ]
    }
  ],
  "events": [
    {
      "type": "step",
      "filter": {
        "type": "script",
        "filter": "1.0 == 1.0"
      },
      "experience": 0.01,
      "sends_notification": false
    }
  ]
}

Result: Player gains 0.01 XP per step. At 100 steps = 1 XP. Quiet progression without spam.

Example 3: Combat Skill

{
  "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>Using Super Effective Moves"
  ],
  "levels": [
    {
      "level": 1,
      "required_experience": 0,
      "rewards": []
    },
    {
      "level": 5,
      "required_experience": 500,
      "rewards": [
        {
          "type": "script",
          "data": {
            "scripts": [
              "q.player.tell_minimessage('<gold>Combat Level 5 Reached!');"
            ]
          }
        }
      ]
    }
  ],
  "events": [
    {
      "type": "battle_victory",
      "filter": {
        "type": "script",
        "filter": "q.battle.is_wild"
      },
      "experience": 10.0
    },
    {
      "type": "super_effective_move_used",
      "filter": {
        "type": "script",
        "filter": "1.0 == 1.0"
      },
      "experience": 2.0
    }
  ]
}

Boss Bar Notifications

When sends_notification is true (default), players see a boss bar showing XP progress:

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

Bar color: Green
Bar overlay: Progress
Duration: 100 ticks (5 seconds)
Updates with each XP gain

Disable for quiet progression:

{
  "experience": 0.01,
  "sends_notification": false
}

Storage Location

Levelable configurations are stored in:

config/journey/levelables/<name>.json

Player progress is automatically saved in player data files.

Commands

# Give levelable to player
/journey levelable give <player> <levelable>

# Remove levelable from player
/journey levelable remove <player> <levelable>

# Award experience
/journey levelable progress <player> <levelable> <amount>

# Open levelable GUI
/journey levelable gui <player>

Integration with Tasks

Use levelables as task requirements or rewards:

Task Start Requirement

{
  "start_requirement": "q.player.levelable_level('Miner') >= 25.0"
}

Task Reward

{
  "rewards": [
    {
      "type": "script",
      "data": {
        "scripts": [
          "q.player.give_levelable('Miner');",
          "q.player.progress_levelable('Miner', 100.0);"
        ]
      }
    }
  ]
}

Best Practices

Progression Design

✅ Balance XP gains:

Rare events → High XP
Common events → Low XP
Very frequent events (steps) → Tiny XP with sends_notification: false

✅ Reward milestones:

Every 10 levels for major rewards
Every 5 levels for minor rewards
Every level for tiny rewards

✅ Use meaningful rewards:

Items that help with the skill (pickaxes for mining)
Currency to encourage trading
Flags/scripts to unlock content

Performance

✅ Disable notifications for frequent events:

{
  "type": "step",
  "experience": 0.01,
  "sends_notification": false
}

✅ Use specific filters:

// Better (specific)
"filter": "q.block.id == 'minecraft:diamond_ore'"

// Worse (catches everything)
"filter": "1.0 == 1.0"

Organization

✅ One levelable per file:

levelables/
  miner.json
  explorer.json
  combat.json
  fishing.json

✅ Consistent naming:

File name matches levelable name field
Use singular nouns (“Miner” not “Miners”)

The Levelable System provides flexible RPG-style progression for any gameplay activity. Combine with tasks, zones, and timelines to create comprehensive progression systems.