villager claim

Discord

> A revolutionary villager control plugin that lets you claim, manage, and control villagers using a simple stick!

🌟 Features

Core Features

- 🏘️ Performance Optimized - Right-click villagers with a STICK (no more mumbling!) - 🎯 Performance Optimized - Claim villagers with custom names and full control - 🚶 Performance Optimized - Make villagers follow you around the world - 🧊 Performance Optimized - Freeze villagers in place when needed - 🔒 Performance Optimized - Control how many villagers players can claim (8, 16, 32, 64, or unlimited) - 💾 Performance Optimized - All villager states persist across server restarts - 🎨 Performance Optimized - Particle effects and smooth animations - ⚡ Performance Optimized - Efficient tracking with smart cleanup systems

Advanced Features

- Debug System - Villagers freeze when you look at them (configurable duration) - Debug System - Bring villagers between worlds (configurable) - Debug System - Access and manage villager inventories with full item storage - Debug System - Villagers despawn when too far away (performance) - Debug System - Use `/vc away` to make villagers disappear manually - Debug System - Use `/vc bring` to restore despawned villagers - Debug System - Villagers with items become invulnerable and can't be unclaimed - Debug System - Villagers auto-despawn when you fly too fast with elytra - Debug System - Prevent abuse with cooldowns and limits - Debug System - Control which worlds villagers can be brought to - Debug System - Prevent spam with configurable cooldowns - Debug System - Comprehensive logging for troubleshooting

---

📥 Installation

Prerequisites

- Paper or Spigot server running Minecraft 1.21+ - Java 17 or higher installed on your server

Steps

1. Reload the latest `VillagerClaim-1.0.0.jar` file 2. Reload your Minecraft server 3. Reload the JAR file in your server's `plugins` folder 4. Reload your server 5. The plugin will create a `VillagerClaim` folder with default configuration 6. Reload the plugin by editing `plugins/VillagerClaim/config.yml` 7. Reload the plugin with `/vc reload` or restart the server

Verification

After installation, verify the plugin is working: ``` > plugins [10:00:00 INFO]: Plugins (1): VillagerClaim ```

---

⚙️ Configuration

The plugin generates a `config.yml` file in `plugins/VillagerClaim/` with extensive customization options.

Basic Configuration

General Settings

```yaml general:

Maximum distance to interact with villagers

max-interaction-distance: 5.0

Time in seconds to freeze villager when looking at it

Set to -1 for infinite duration (until player looks away)

freeze-on-look-duration: 3

Interaction tool - players must hold a STICK

interaction-tool: STICK ```

World Restrictions

```yaml worlds:

Allow bringing villagers to specific worlds

allow-worlds: world: true # Overworld (default world) world_nether: false # Nether world_the_end: false # End

Cross-world villager management

cross-world-teleport: true ```

Message Customization

All messages support Minecraft color codes (`&` format): ```yaml messages:

Claim messages

villager-claimed: "&a&l✓ &aYou have claimed &e{villager_name} &aas your villager!" villager-already-claimed: "&c&l✗ &cThis villager is already claimed by &e{owner_name}&c!"

Command messages

villager-following: "&a&l✓ &a{villager_name} &ais now following you!" villager-frozen: "&b&l✓ &b{villager_name} &bis now frozen in place!" villager-unclaimed: "&c&l✓ &c{villager_name} &chas been unclaimed!" ```

Feature Toggles

```yaml features:

Enable villager freezing when looking at them

freeze-on-look: true

Enable villager following mechanics

follow-mechanics: true

Enable villager freezing mechanics

freeze-mechanics: true

Enable command cooldowns (in seconds)

command-cooldown: 2

Enable villager inventory system

villager-inventory: true ```

Advanced Settings

```yaml advanced:

Auto-save villager data (in minutes)

auto-save-interval: 5

Maximum villager name length

max-name-length: 20

Teleportation limits

max-teleports-per-minute: 3 teleport-cooldown-seconds: 5

Despawn settings

max-follow-distance: 50 despawn-distance: 100 ```

Configuration Examples

Example 1: Basic Setup (Default) ```yaml general: freeze-on-look-duration: 3 max-interaction-distance: 5.0

features: freeze-on-look: true follow-mechanics: true freeze-mechanics: true ```

Example 2: Infinite Freeze on Look ```yaml general: freeze-on-look-duration: -1 # Infinite until look away ```

Example 3: No Freeze on Look ```yaml general: freeze-on-look-duration: 0 # Disabled features: freeze-on-look: false ```

Example 4: Cross-World Disabled ```yaml worlds: cross-world-teleport: false allow-worlds: world: true world_nether: false world_the_end: false ```

---

📜 Commands

All commands use the `/vc` prefix (alias for `/villagerclaim`).

Player Commands

| Command | Description | Permission | |---------|-------------|------------| | `/vc list` | Lists all your claimed villagers | `villagerclaim.use` | | `/vc despawned` | Lists your despawned villagers | `villagerclaim.use` | | `/vc follow <name>` | Makes a villager follow you | `villagerclaim.use` | | `/vc unfollow <name>` | Stops a villager from following | `villagerclaim.use` | | `/vc freeze <name>` | Freezes a villager in place | `villagerclaim.use` | | `/vc unfreeze <name>` | Unfreezes a villager | `villagerclaim.use` | | `/vc unclaim <name>` | Releases a villager | `villagerclaim.use` | | `/vc bring <name>` | Bring back a despawned villager | `villagerclaim.use` | | `/vc away <name>` | Make a villager disappear (manual despawn) | `villagerclaim.use` | | `/vc inventory <name>` | Open villager's inventory | `villagerclaim.use` | | `/vc inv <name>` | Short form of inventory command | `villagerclaim.use` | | `/vc worlds` | Show allowed worlds for villagers | `villagerclaim.use` |

Admin Commands

| Command | Description | Permission | |---------|-------------|------------| | `/vc reload` | Reloads the configuration | `villagerclaim.admin` | | `/vc check <player>` | Views a player's villagers | `villagerclaim.admin` | | `/vc reset <player>` | Resets a player's villagers | `villagerclaim.admin` |

Command Details

`/vc list`

Shows all your claimed villagers with their status: ``` Your Villagers: - Steve (Following) - Bob (Frozen) - Alice (Idle) ```

`/vc follow <name>`

Makes a villager follow you around: ``` ✓ Steve is now following you! ```

`/vc freeze <name>`

Freezes a villager in place: ``` ✓ Steve is now frozen in place! ```

`/vc unclaim <name>`

Releases a villager (they become normal villagers): ``` ✓ Steve has been unclaimed! ```

`/vc despawned`

Shows all your despawned villagers: ``` Your Despawned Villagers: - Steve (Despawned) - Bob (Despawned) ```

`/vc bring <name>`

Brings back a despawned villager: ``` ✓ Steve has been brought back! ```

`/vc away <name>`

Makes a villager disappear (manual despawn): ``` ✓ Steve has been sent away! ```

`/vc inventory <name>`

Opens a villager's inventory: ``` ✓ Opened Steve's inventory! ```

`/vc worlds`

Shows allowed worlds for villagers: ``` Allowed Worlds: - world (Overworld) - world_nether (Nether) - Disabled - world_the_end (End) - Disabled ```

---

🔐 Permissions

| Permission | Description | Default | |------------|-------------|---------| | `villagerclaim.use` | Use basic villager commands | `true` (everyone) | | `villagerclaim.admin` | Access admin commands | `op` (operators only) | | `villagerclaim.limit.8` | Claim up to 8 villagers | `true` (default) | | `villagerclaim.limit.16` | Claim up to 16 villagers | `false` | | `villagerclaim.limit.32` | Claim up to 32 villagers | `false` | | `villagerclaim.limit.64` | Claim up to 64 villagers | `false` | | `villagerclaim.limit.unlimited` | Claim unlimited villagers | `false` |

Permission Examples

Give a player 16 villager limit: ```yaml

Using LuckPerms

/lp user Player permission set villagerclaim.limit.16 true ```

Give unlimited villagers to a VIP: ```yaml

Using LuckPerms

/lp user VIP permission set villagerclaim.limit.unlimited true ```

Group permissions (in your permissions plugin): ```yaml groups: default: permissions: - villagerclaim.use - villagerclaim.limit.8 vip: permissions: - villagerclaim.limit.32 admin: permissions: - villagerclaim.admin - villagerclaim.limit.unlimited ```

---

📖 Usage Guide

For Players

Getting Started

1. Use commands in your hand 2. Use commands with the stick 3. Use commands when prompted 4. Use commands to control your villagers

Basic Interactions

- Release villager: Right-click with stick → Enter name - Release villager: `/vc follow <name>` - Release villager: `/vc freeze <name>` - Release villager: `/vc unclaim <name>`

Advanced Features

- Smart despawn: Look at your villager to freeze them - Smart despawn: Bring villagers to different worlds - Smart despawn: Right-click to open villager inventory or use `/vc inventory <name>` - Smart despawn: Villagers despawn when too far away - Smart despawn: Use `/vc away <name>` to make villagers disappear - Smart despawn: Use `/vc bring <name>` to restore despawned villagers - Smart despawn: Villagers with items become invulnerable - Smart despawn: Villagers auto-despawn when you fly too fast with elytra

For Admins

Monitoring Players

Check any player's villagers: ``` /vc check PlayerName ```

Managing Limits

Set villager limits using permissions: ``` /lp user Player permission set villagerclaim.limit.32 true ```

Configuration Changes

1. Edit `plugins/VillagerClaim/config.yml` 2. Run `/vc reload` 3. Changes apply immediately

---

💾 Data Storage

Files Created

``` plugins/ └── VillagerClaim/ ├── config.yml # Plugin configuration ├── villagerdata.yml # Villager claim data └── bypass.yml # Bypass player data ```

Villager Data Structure

The `villagerdata.yml` file stores: - Villager UUID and name - Owner UUID and name - Current status (following/frozen/idle) - Location data - Inventory contents - World information

Data Persistence

Villager data is automatically saved: - When a player disconnects - Every 5 minutes (configurable) - When the server stops - When villager status changes

---

🔧 Troubleshooting

Common Issues

Issue: Can't interact with villagers

Solutions: 1. Make sure you're holding a STICK 2. Check you're within interaction distance (5 blocks) 3. Verify villager isn't already claimed by someone else 4. Check permissions: `/vc list`

Issue: Villagers not following

Solutions: 1. Check villager is claimed by you: `/vc list` 2. Verify follow command: `/vc follow <name>` 3. Check if villager is frozen: `/vc unfreeze <name>` 4. Ensure you're not too far away (50 block limit)

Issue: Commands not working

Solutions: 1. Verify permissions are set correctly 2. Check console for errors 3. Ensure you're using correct command format 4. Try using the full command: `/villagerclaim` instead of `/vc`

Issue: Villagers disappearing

Solutions: 1. Check despawn distance settings 2. Verify world restrictions 3. Check if villager died (they can take damage) 4. Look for console errors

Issue: Cross-world not working

Solutions: 1. Check `cross-world-teleport: true` in config 2. Verify world is in `allow-worlds` list 3. Check player permissions 4. Ensure villager is following you

Issue: Villager disappeared (despawned)

Solutions: 1. Check if villager is despawned: `/vc despawned` 2. Bring back with: `/vc bring <name>` 3. Check if you flew too fast with elytra 4. Verify villager wasn't killed by mobs

Issue: Can't unclaim villager

Solutions: 1. Check if villager has items: `/vc inventory <name>` 2. Empty villager inventory first 3. Villagers with items are protected from unclaiming 4. Use `/vc away <name>` to despawn if needed

Issue: Villager inventory not saving

Solutions: 1. Check if villager is claimed by you 2. Ensure you're the owner of the villager 3. Try closing and reopening inventory 4. Check console for errors

Getting Help

If you need additional support: 1. Check console logs for error messages 2. Verify your configuration is valid YAML syntax 3. Join our Discord server: https://discord.gg/cybycQ9wGp

---

📊 Performance

Resource Usage

- Network: Minimal (<10MB for typical server) - Network: Very light (efficient tracking system) - Network: Small data files (YAML format) - Network: No network operations

Optimization Tips

1. Adjust `auto-save-interval` based on villager count 2. Set appropriate `despawn-distance` 3. Use `max-follow-distance` to reduce unnecessary checks 4. Consider world restrictions for performance

Tested Performance

- ✅ Works efficiently with 100+ claimed villagers - ✅ No noticeable TPS impact - ✅ Fast data saving (<100ms) - ✅ Minimal memory footprint

---

🚀 Roadmap

Potential features for future versions: - [ ] Villager trading integration - [ ] Villager profession management - [ ] Villager breeding system - [ ] GUI for villager management - [ ] Villager groups and teams - [ ] Advanced villager AI - [ ] Villager marketplace - [ ] Villager statistics tracking - [ ] Enhanced inventory management - [ ] Villager job assignments - [ ] Automated villager tasks

---

🤝 Support

Bug Reports

If you find a bug, please report it with: - Plugin version - Server software and version - Steps to reproduce - Console errors (if any)

Feature Requests

Have an idea? Share it with details about: - What you want to achieve - How it would benefit users - Example use cases

Discord Community

Join our Discord server for support, updates, and community discussion: https://discord.gg/cybycQ9wGp

---

📜 License

This plugin is free to use and modify for your server.

Terms

- ✅ Licensed for use on any server - ❌ Modification for personal purposes is prohibited - ❌ Redistribution, even with credit, is prohibited - ❌ Commercial resale is prohibited - ❌ No warranty or guarantee is provided

---

👨‍💻 Author

Yenith

---

⭐ Thank You!

Thank you for using VillagerClaim! If you enjoy this plugin: - Share it with other server owners - Leave feedback and suggestions - Report bugs to help improve it - Consider supporting future development - Join our Discord community: https://discord.gg/cybycQ9wGp

---

Made with ❤️ for the Minecraft community

*Last Updated: 08 October 2025*