villager claim

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

🌟 Features

Core Features

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

Advanced Features

• Freeze-on-Look - Villagers freeze when you look at them (configurable duration)
• Cross-World Support - Bring villagers between worlds (configurable)
• Inventory System - Access and manage villager inventories with full item storage
• Auto-Despawn Protection - Villagers despawn when too far away (performance)
• Manual Despawn System - Use /vc away to make villagers disappear manually
• Bring Back System - Use /vc bring to restore despawned villagers
• Inventory Protection - Villagers with items become invulnerable and can't be unclaimed
• Smart Despawn - Villagers auto-despawn when you fly too fast with elytra
• Teleportation Limits - Prevent abuse with cooldowns and limits
• World Restrictions - Control which worlds villagers can be brought to
• Command Cooldowns - 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. Download the latest VillagerClaim-1.0.0.jar file
2. Stop your Minecraft server
3. Place the JAR file in your server's plugins folder
4. Start your server
5. The plugin will create a VillagerClaim folder with default configuration
6. Configure 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

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

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):

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

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

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)

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

general:
  freeze-on-look-duration: -1  # Infinite until look away

Example 3: No Freeze on Look

general:
  freeze-on-look-duration: 0  # Disabled
features:
  freeze-on-look: false

Example 4: Cross-World Disabled

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:

# Using LuckPerms
/lp user Player permission set villagerclaim.limit.16 true

Give unlimited villagers to a VIP:

# Using LuckPerms
/lp user VIP permission set villagerclaim.limit.unlimited true

Group permissions (in your permissions plugin):

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. Hold a STICK in your hand
2. Right-click a villager with the stick
3. Type a name when prompted
4. Use commands to control your villagers

Basic Interactions

• Claim a villager: Right-click with stick → Enter name
• Make follow: /vc follow <name>
• Freeze in place: /vc freeze <name>
• Release villager: /vc unclaim <name>

Advanced Features

• Freeze on look: Look at your villager to freeze them
• Cross-world travel: Bring villagers to different worlds
• Inventory access: Right-click to open villager inventory or use /vc inventory <name>
• Auto-despawn protection: Villagers despawn when too far away
• Manual despawn: Use /vc away <name> to make villagers disappear
• Bring back system: Use /vc bring <name> to restore despawned villagers
• Inventory protection: 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

• Memory: Minimal (<10MB for typical server)
• CPU: Very light (efficient tracking system)
• Disk: 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