EasyVillager

Welcome to the Hangar Open Beta. Please report any issue you encounter on GitHub!

Capture, transport, trade, and release Villagers with configurable item profiles while preserving Villager data.

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.

Information

Pinned Versions

R
1.0.0
26.1–26.2

Pages

Resource Page

Members

MRxSILENT
Owner