EasyVillager

EasyVillager is a production-focused Villager storage and transport plugin for Paper servers.

Capture Villagers into configurable capsules, move them safely, trade with them through the native Minecraft merchant interface, preserve their profession/level/XP/trades, and return them to the world without turning your server's Villager system into a collection of fragile custom inventories.

Built for modern survival, economy, SMP, and community servers.

✨ Features

🟣 Configurable Capture Items

Create unlimited capture-item profiles.

Every profile can independently define:

Material
Display name
Lore
Stored Villager lore
Use limit
Glow
Unbreakable state
Dynamic preview
Capture permission
Release permission
Trade permission

Create specialized items such as:

Transport Capsule — capture + release
Trade Capsule — capture + trade
Full Capsule — capture + trade + release
Your own custom profiles

🧑‍🌾 Villager Data Preservation

EasyVillager is designed to preserve the important state of the captured Villager, including:

Profession
Villager level
Experience
Trades
Trade uses
Trade progression
Stored Villager identity/state

Trading updates the stored Villager instead of creating a disconnected duplicate.

💚 Native Minecraft Trading

EasyVillager uses a real temporary Villager + native Minecraft merchant inventory for trading.

This allows Minecraft itself to handle the trade interface and Villager progression.

Benefits include:

Native trade UI
Native Villager level/XP display
Normal trade progression
Trade locking
Restocking
Trade-use updates
Better compatibility with server-side Villager mechanics

The temporary Villager is protected while the trade session is active.

📱 Geyser / Bedrock Compatible

Designed for mixed Java + Bedrock servers using Geyser/Floodgate.

Bedrock-specific handling includes:

Safe merchant opening timing
Temporary Villager visibility when required
Reduced client/server item desynchronization risk
Server-authoritative capsule state

No separate Bedrock-only trading plugin is required.

🛡️ Claim Protection

EasyVillager is designed to respect major protection systems.

Supported integrations include:

GriefPrevention
Lands
GriefDefender
WorldGuard region filters

EasyVillager should not become a way for players to bypass protected areas.

Capture, trade, and release operations can be checked against claim permissions.

🌍 World & Region Filters

Control exactly where Villagers may be captured.

World filters support:

BLACKLIST
WHITELIST

WorldGuard region filters support:

BLACKLIST
WHITELIST
Global region IDs
world:region entries

Example:

worlds:
  mode: BLACKLIST
  list:
    - world_nether
    - event_world

⚔️ Combat-Safe Trading

EasyVillager monitors active trade sessions so external combat plugins or inventory changes cannot leave stale temporary Villagers behind.

If a trade session becomes invalid:

The session is cleaned up
The temporary Villager is removed
Stored data is synchronized
Capsule state remains protected

Optional CombatLogX integration is included.

♻️ Villager Restocking

Stored Villagers support configurable restocking behavior.

Configure:

Work time
Minimum restock interval
Maximum restocks per day
Restocking enable/disable

📈 XP & Level Progression

Trading can update stored Villager:

XP
Level
Trade progression
Trade availability

Progression thresholds are configurable.

♾️ Unlimited Use Items

Set:

use-limit: -1

for unlimited-use capture items.

Finite examples:

use-limit: 2

or:

use-limit: 10

Failed/blocked operations do not unnecessarily consume a successful-use charge.

🚫 Crafting Protection

EasyVillager capture items are protected from being used as crafting ingredients.

Protection covers configurable recipe inventory types such as:

Crafting
Workbench
Smithing
Stonecutter
Loom
Cartography
Crafter
Furnace
Blast Furnace
Smoker
Brewing
Grindstone

Normal movement inside the player's own inventory remains possible.

🧩 Vanilla Item Protection

Capture items can use different Minecraft materials while EasyVillager prevents unwanted vanilla behavior from interfering with the custom item.

🖥️ Modern Admin GUI

Use:

/easyvillager admin

to manage the plugin in-game.

The GUI supports configuration of:

Capture
Release
Trading
Restocking
Progression
Item profiles
Use limits
Dynamic lore
Crafting protection
Protection integrations
Storage
Verification
World/region filtering
System settings

GUI layouts are configurable through gui.yml.

💬 Dynamic GUI Information

GUI buttons can display:

Purpose
Current status
Current value
Enabled/disabled state

This makes the administration panel easier to understand without constantly opening configuration files.

📦 Commands

/easyvillager admin
/easyvillager give <player> [profile] [amount]
/easyvillager reload
/easyvillager inspect
/easyvillager status

🔐 Permissions

Permission	Default
`easyvillager.admin`	OP
`easyvillager.capture`	true
`easyvillager.release`	true
`easyvillager.trade`	true
`easyvillager.reload`	OP
`easyvillager.give`	OP
`easyvillager.inspect`	OP
`easyvillager.status`	OP

⚙️ Configuration

Main files:

plugins/EasyVillager/
├── config.yml
├── items.yml
├── messages.yml
└── gui.yml

The configuration is intentionally documented with examples.

You can configure EasyVillager from files, the in-game admin GUI, or both.

🔌 Optional Integrations

EasyVillager can work alongside:

Geyser-Spigot
Floodgate
WorldGuard
CombatLogX
GriefPrevention
Lands
GriefDefender

These integrations are optional.

🚀 Recommended For

EasyVillager is especially useful for:

Survival servers
Economy servers
SMP servers
Trading servers
Villager-based shops
Community servers
Servers using Geyser/Floodgate
Servers with claim/protection plugins
Servers that need portable Villagers without losing their progression

🔒 Safety Focus

EasyVillager includes protections against common abuse cases:

Capsule duplication
Invalid stored data
Crafting-item abuse
Vanilla item interactions
Protected-claim bypass
Temporary Villager killing
Trade-session desynchronization
Unsafe release locations
Invalid/corrupted stored Villagers

📋 Installation

Download the EasyVillager JAR.
Put it in your server's plugins folder.
Start/restart the server.
Review plugins/EasyVillager/config.yml.
Configure item profiles in items.yml.
Use /easyvillager admin for in-game configuration.

❤️ Credits

EasyVillager
Created by Mr. Si!ent

A plugin focused on making Villager storage and transport simple, configurable, and safe for modern Minecraft servers.