🧭 FindBuddy - Minecraft Player Tracking Plugin

🎯 Track your friends with enchanted compasses!
⚡ Real-time location updates with action bar!
🔒 Secure permission-based tracking system!

🌟 Features

🧭 Smart Compass - Enchanted compass that points to tracked players or custom waypoints
📍 Real-time Tracking - Live distance and direction updates in action bar
🔐 Permission System - Optional request-based tracking (like TPA)
🌍 Cross-World Support - Works across different worlds and dimensions
⚙️ Highly Configurable - Customize distances, cooldowns, and notifications
🛡️ Admin Tools - Cleanup commands for server management
🔄 Auto Cleanup - Automatic compass removal to prevent issues
🗺️ Waypoints - Set, remove, and locate custom waypoints with a compass

📥 Installation

Download the latest JAR file
Place in your server's plugins/ folder
Restart your server
Configure using the generated config.yml

Requirements

Minecraft: 1.21+ (Paper/Spigot/Bukkit)
Java: 17 or higher

📋 Commands

Player Commands

Command	Description
`/findbuddy locate <player>`	Start tracking a player
`/findbuddy cancel`	Cancel current tracking
`/findbuddy accept`	Accept a tracking request
`/findbuddy decline`	Decline a tracking request
`/waypoint set <name> <x> <y> <z> [world]`	Set a custom waypoint
`/waypoint remove <name>`	Remove a custom waypoint
`/waypoint locate <name>`	Get a compass to a waypoint (disappears when close)

Admin Commands

Command	Description
`/findbuddy cleanup <player>`	Remove all tracking compasses from a player

Aliases: /fb, /find

🗺️ Waypoints

Waypoints let you save and revisit custom locations easily:

Set a waypoint: /waypoint set home 100 64 200
Remove a waypoint: /waypoint remove home
Locate a waypoint: /waypoint locate home
- Gives you a glowing enchanted compass pointing to your waypoint
- The compass disappears when you are within a configurable distance (default: stop_distance in config)
- Tab completion for /waypoint set auto-suggests coordinates of the block you are looking at (like /tp)

Waypoints are saved per-player in the Finddata folder as JSON files.

⚙️ Configuration

# FindBuddy Configuration
tracking:
  stop_distance: 25          # Distance when tracking stops
  notify_target: true        # Notify target when tracked
  require_requests: true     # Require permission requests
  request_timeout: 90        # Request timeout in seconds

compass:
  refresh_cooldown: 20       # Compass refresh cooldown in seconds

🔧 Permissions

# Basic permissions
findbuddy.find:
  default: true
  description: "Allows using basic FindBuddy commands"

# Admin permissions
findbuddy.cleanup:
  default: op
  description: "Allows using cleanup commands"

# All permissions
findbuddy.*:
  default: op
  children:
    findbuddy.find: true
    findbuddy.cleanup: true
    findbuddy.waypoint: true

findbuddy.waypoint:
  default: true
  description: "Allows using waypoint commands"

🎮 How It Works

Player A uses /findbuddy locate PlayerB
System checks if requests are required
If direct tracking: Player A gets a compass and starts tracking
If requests required: Player B gets a request to accept/decline
Action bar shows real-time distance and direction
Compass points to Player B's location

Compass Features

Right-click to refresh location (with cooldown)
Cannot be dropped or moved to external inventories
Auto-removed when tracking stops
Glows with enchantment effect

🛠️ Troubleshooting

Issue	Solution
Compass not removed	Use `/findbuddy cleanup <player>`
Permission denied	Check `findbuddy.find` permission
Players can't track	Verify `require_requests` setting
Compass not working	Check if players are in same world

👨‍💻 For Developers

Quick Start

# Clone and build
git clone https://github.com/hellofaizan/FindBuddy.git
cd FindBuddy
./gradlew build

# Run with test server
./gradlew runServer

Project Structure

src/main/kotlin/in/mohammadfaizan/minecraft/
├── FindBuddy.kt                    # Main plugin class
├── commands/FindBuddyCommand.kt    # Command executor
├── listeners/                      # Event handling
├── managers/                       # Business logic
├── models/                         # Data models
├── utils/                          # Utilities
└── ui/                            # UI components

Key Components

TrackingManager - Core tracking logic and task management
CompassManager - Compass item creation and management
ConfigManager - Type-safe configuration access
MessageUtils - Consistent UI message formatting

Contributing

Fork the repository
Create feature branch
Make changes following Kotlin conventions
Add tests for new functionality
Submit pull request

📄 License

This project is licensed under the MIT License.

⭐ Star this repository if you find it useful!
🐛 Report issues on GitHub
💡 Suggest features and improvements

Made with ❤️ by Mohammad Faizan

FindBuddy