MigratingMarkets Docs

Configuration and usage reference for traveling caravans, dynamic markets, customer progression, reputation, economy providers, LuckyBlock integration, and administration.

Getting Started

MigratingMarkets is a traveling-caravan economy plugin for Paper 1.21.x. Caravans are real NPCs that move between configured waypoints and establish temporary markets when they arrive.

Each caravan has its own route, specialty, inventory, stock, prices, reputation, and customer progression.

The plugin stores runtime data persistently, allowing caravan state and player progression to survive server restarts.

Requirements

Requirement Version
Server Paper 1.21.x
Java 21+
Vault Optional
LuckyBlock Optional

MigratingMarkets uses Paper-specific APIs including Mob#getPathfinder() and Adventure Component. Plain Spigot/Bukkit is not supported.

Caravans

Caravans travel between an ordered list of waypoints. When they reach a waypoint, they remain there for the configured number of market days before continuing.

Feature Description
Real Movement Caravans physically travel between configured waypoints.
Terrain Detection The caravan resolves its Y position against actual terrain to avoid floating or buried NPCs.
Villager AI AI remains enabled while parked, allowing natural wandering.
Multiple Routes Any number of caravans can be configured with their own routes and specialties.
Destination Hints Players receive a rough compass direction when a caravan departs.

Destination hints intentionally do not provide exact coordinates, encouraging players to scout for caravans.

Markets

Every caravan establishes a temporary market when it reaches a waypoint. The market uses stock limits and dynamic pricing to react to player activity.

Supply & Demand

Action Result
Buy Item price increases.
Sell Item price decreases.
New Market Day Prices decay toward their baseline.
New Market Day Stock is replenished.

Item Levels

Every item has a level from 1 to 5. Stock capacity is calculated from the item's level and the configured stock-per-level value.

stock cap = item level × stock-per-level

Higher-level items therefore receive larger stock caps while remaining limited compared to ordinary goods.

Customer Levels

Every player has a separate customer level for each caravan. Trading with one caravan does not affect their standing with another.

Setting Default
Starting Level 1
Maximum Level 5
Purchases Per Level 8 units

Customer progression is based on the number of items purchased from that specific caravan.

Item Gating

Players cannot purchase items with a level higher than their current customer level.

Player Level 1 → Item Levels 1
Player Level 2 → Item Levels 1-2
Player Level 3 → Item Levels 1-3
Player Level 4 → Item Levels 1-4
Player Level 5 → Item Levels 1-5

Locked items are shown greyed out with a lock icon. Buy and sell information is hidden and the server rejects unauthorized transactions.

Your Standing

The shop GUI contains a Your Standing item showing the player's current customer level and progress toward the next level.

Escort Reputation

Escort reputation rewards players who help protect caravans while they are traveling.

Killing hostile mobs near a traveling caravan increases reputation with that specific caravan.

Reputation Tiers

Value Description
Threshold Number of qualifying kills required.
Discount Discount applied at the caravan market.
Title Display name for the reputation tier.

Reputation is stored independently for every player and caravan.

Economy

MigratingMarkets supports physical emeralds by default and can optionally use an economy registered through Vault.

Emerald Economy

No additional dependency is required when using emeralds.

economy:
  provider: emerald

Vault Economy

Set the provider to vault to use the economy registered through Vault.

economy:
  provider: vault

If Vault is selected but cannot be found, MigratingMarkets automatically falls back to emeralds and logs a warning.

LuckyBlock Bridge

The optional Fortune caravan integrates directly with PluggLab Studio's LuckyBlock 2.0 developer API.

The integration creates real LuckyBlock ItemStacks instead of relying on guessed console commands.

API

com.lucky.luckyblock.api.LuckyBlockAPI

The API JAR is bundled at:

libs/LuckyBlock-2.0.jar

The actual implementation is provided by the LuckyBlock plugin at runtime.

LuckyBlockAPI.getOrNull()

Supported Rarities

Rarity
COMMON
RARE
EPIC
LEGENDARY

Fortune Configuration

Fortune items use a rarity field.

rarity: COMMON

Buying a LuckyBlock calls:

LuckyBlockAPI.buildLuckyBlockItem(rarity, amount)

The resulting item retains its LuckyBlock name and lore and can be sold back through the market.

Plugin Detection

lucky-block-bridge:
  plugin-name: LuckyBlock

The Fortune caravan only activates when the configured LuckyBlock plugin is installed.

Command Fallback

A generic give-command fallback is available for other command-driven plugins. Items created through this method cannot automatically be sold back.

When using LuckyBlock 2.0, use rarity instead.

Commands

Player Commands

Command Description Permission
/market info Lists all caravans and their status. migratingmarkets.use
/market browse Opens the GUI of a nearby caravan. migratingmarkets.use
/market track Shows rough caravan locations and remaining days. migratingmarkets.use

Admin Commands

Command Description Permission
/caravanadmin list Lists all caravans with internal state. migratingmarkets.admin
/caravanadmin reload Reloads config and respawns caravans. migratingmarkets.admin
/caravanadmin forcemove <id> Forces a caravan to depart immediately. migratingmarkets.admin
/caravanadmin teleport <id> <waypointIndex> Moves a caravan to a specific waypoint. migratingmarkets.admin
/caravanadmin stop Despawns all caravans and saves state. migratingmarkets.admin
/caravanadmin edit <id> Opens the shop editor. migratingmarkets.admin
/caravanadmin additem <id> <material> <price> <level> [category...] Adds an item without opening the editor. migratingmarkets.admin
/caravanadmin removeitem <id> <slot> Removes an item by slot. migratingmarkets.admin
/caravanadmin setprice <id> <slot> <price> Changes an item's base price. migratingmarkets.admin
/caravanadmin setlevel <id> <slot> <level> Changes an item's level. migratingmarkets.admin
/caravanadmin createroute <id> <specialty> <displayName...> Creates an owner-managed caravan. migratingmarkets.admin
/caravanadmin addwaypoint <id> <name...> Adds a waypoint at your current location. migratingmarkets.admin
/caravanadmin removewaypoint <id> <index> Removes a custom waypoint. migratingmarkets.admin
/caravanadmin deleteroute <id> Permanently deletes an owner-created caravan. migratingmarkets.admin

All commands support tab completion for subcommands, caravan IDs, and waypoint indices.

Players can also right-click a parked caravan villager to open its shop directly.

Custom Caravans

Owner-created caravans can be created entirely in-game without editing config.yml.

/caravanadmin createroute nightmarket blacksmith &8Night Market
/caravanadmin addwaypoint nightmarket Town Square
/caravanadmin addwaypoint nightmarket Old Bridge
/caravanadmin edit nightmarket

Creating a Route

/caravanadmin createroute <id> <specialty> <displayName...>

The specialty can reference an existing specialty from config.yml or be any custom value.

Existing specialties provide a themed starter inventory. Unknown specialties start with an empty shop.

Adding Waypoints

/caravanadmin addwaypoint <id> <name...>

The waypoint is created at the command sender's current location.

A custom caravan will not spawn until it has at least one waypoint.

Custom Route Storage

Owner-created caravans are stored separately in:

custom-routes.yml

Routes defined in config.yml cannot be modified using these commands. Edit the configuration and use /caravanadmin reload instead.

Shop Editor

Open the editor with:

/caravanadmin edit <id>

Adding Items

Hold an item in your main hand and left-click an empty slot.

Property Default
Price 10
Level 1
Category custom

Removing Items

Right-click an existing item to remove it immediately.

Changing Prices

/caravanadmin setprice <id> <slot> <price>

Changing Levels

/caravanadmin setlevel <id> <slot> <level>

Persistence

Runtime-added items are stored in caravan-state.yml and survive server restarts.

They do not survive an explicit /caravanadmin reload, because the reload rebuilds caravans from config.yml.

Use the configuration for permanent shop additions.

Configuration

The main MigratingMarkets configuration is stored in config.yml.

settings

Controls global market behavior.

Setting Description
Market day duration Minutes required for one market day.
Days per stop How long a caravan remains at a waypoint.
Interaction radius Distance at which players can interact with a caravan.
Escort radius Distance used when detecting escort kills.
Broadcast Controls caravan-related broadcasts.
Price shift Price change caused by trading.
Price decay How quickly prices return toward baseline.
Min/max multiplier Limits the dynamic price range.

routes

Defines caravans, their specialties, and ordered waypoints.

routes:
  blacksmith:
    display-name: "&6Blacksmith"
    specialty: blacksmith
    waypoints:
      - world: world
        x: 100
        y: 64
        z: 100
        name: "Town Square"

specialties

Defines reusable item pools that can be shared by multiple caravan routes.

specialties:
  blacksmith:
    items:
      - material: DIAMOND
        base-price: 100
        level: 3
        category: weapons

escort-reputation

Defines reputation thresholds, discounts, and tier titles.

escort-reputation:
  tiers:

economy

economy:
  provider: emerald

Available providers are emerald and vault.

Persistence

MigratingMarkets separates static configuration from runtime and custom caravan data.

File Purpose
config.yml Main settings, routes, specialties, economy, pricing, and reputation configuration.
caravan-state.yml Runtime caravan state, prices, stock, reputation, customer progression, and runtime-added items.
custom-routes.yml Owner-created caravans and their custom routes.

Saved Caravan State

  • Caravan position
  • Current waypoint
  • Days at stop
  • Live prices
  • Stock levels
  • Escort reputation
  • Customer levels
  • Runtime-added shop items

Building

MigratingMarkets is distributed as source code and can be built with Maven.

mvn clean package

The generated JAR is located at:

target/MigratingMarkets-1.0.0.jar

Place the resulting JAR in your server's plugins/ directory and restart the server.

Requirements

  • Java 21
  • Paper 1.21.x
  • Maven
  • Internet access for dependency resolution

Paper API

The plugin uses Paper-specific functionality including mob pathfinding and Adventure Components.

Mob#getPathfinder()
Component

Because these APIs are Paper-specific, plain Spigot/Bukkit is not supported.