Documentation
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.