EasyVillager

# 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: ```yaml 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: ```yaml use-limit: -1 ``` for unlimited-use capture items. Finite examples: ```yaml use-limit: 2 ``` or: ```yaml 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: ```text /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 ```text /easyvillager admin /easyvillager give [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: ```text 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 1. Download the EasyVillager JAR. 2. Put it in your server's `plugins` folder. 3. Start/restart the server. 4. Review `plugins/EasyVillager/config.yml`. 5. Configure item profiles in `items.yml`. 6. 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.