# \ud83e\udded FindBuddy – Minecraft Player Tracking Plugin<\/p>\n
**\ud83c\udfaf Track your friends with enchanted compasses!**
\n**\u26a1 Real-time location updates with action bar!**
\n**\ud83d\udd12 Secure permission-based tracking system!**<\/p>\n
—<\/p>\n
## \ud83c\udf1f Features<\/p>\n
– \ud83e\udded **Smart Compass** – Enchanted compass that points to tracked players or custom waypoints
\n– \ud83d\udccd **Real-time Tracking** – Live distance and direction updates in action bar
\n– \ud83d\udd10 **Permission System** – Optional request-based tracking (like TPA)
\n– \ud83c\udf0d **Cross-World Support** – Works across different worlds and dimensions
\n– \u2699\ufe0f **Highly Configurable** – Customize distances, cooldowns, and notifications
\n– \ud83d\udee1\ufe0f **Admin Tools** – Cleanup commands for server management
\n– \ud83d\udd04 **Auto Cleanup** – Automatic compass removal to prevent issues
\n– \ud83d\uddfa\ufe0f **Waypoints** – Set, remove, and locate custom waypoints with a compass<\/p>\n
—<\/p>\n
## \ud83d\udce5 Installation<\/p>\n
1. **Download** the latest JAR file
\n2. **Place** in your server’s `plugins\/` folder
\n3. **Restart** your server
\n4. **Configure** using the generated `config.yml`<\/p>\n
### Requirements
\n– **Minecraft**: 1.21+ (Paper\/Spigot\/Bukkit)
\n– **Java**: 17 or higher<\/p>\n
—<\/p>\n
## \ud83d\udccb Commands<\/p>\n
### Player Commands ### Admin Commands **Aliases**: `\/fb`, `\/find`<\/p>\n —<\/p>\n ## \ud83d\uddfa\ufe0f Waypoints<\/p>\n Waypoints let you save and revisit custom locations easily:<\/p>\n – **Set a waypoint:** `\/waypoint set home 100 64 200` Waypoints are saved per-player in the `Finddata` folder as JSON files.<\/p>\n —<\/p>\n ## \u2699\ufe0f Configuration<\/p>\n “`yaml compass: —<\/p>\n ## \ud83d\udd27 Permissions<\/p>\n “`yaml # Admin permissions # All permissions findbuddy.waypoint: —<\/p>\n ## \ud83c\udfae How It Works<\/p>\n 1. **Player A** uses `\/findbuddy locate PlayerB` ### Compass Features —<\/p>\n ## \ud83d\udee0\ufe0f Troubleshooting<\/p>\n | Issue | Solution | —<\/p>\n ## \ud83d\udc68\u200d\ud83d\udcbb For Developers<\/p>\n ### Quick Start # Run with test server ### Project Structure ### Key Components ### Contributing —<\/p>\n ## \ud83d\udcc4 License<\/p>\n This project is licensed under the **MIT License**.<\/p>\n —<\/p>\n **\u2b50 Star this repository if you find it useful!** Made with \u2764\ufe0f by Mohammad Faizan<\/p>\n<\/div>\n","protected":false},"excerpt":{"rendered":" Locate your Buddy in the Minecraft Server<\/p>\n","protected":false},"featured_media":70142,"template":"","meta":{"_minecraft_slug":"findbuddy","_minecraft_project_id":"zGaJrliL","_minecraft_author":"hellofaizan","_minecraft_license":"MIT","_minecraft_downloads":167,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"findbuddy.zip","_minecraft_size_bytes":1477104,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-16T13:09:47.905335Z","_minecraft_date_created":"2025-07-04T04:22:28.777966Z","_minecraft_date_modified":"2025-06-23T14:06:25.727850Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/findbuddy","_minecraft_icon_attachment_id":70142,"_minecraft_imported_at":"2026-06-03T23:47:54+00:00","_minecraft_import_hash":"c347bff89bb1c2e1e9ff8ac87339899f","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[87,127,129,92],"mod_loader":[132,134],"minecraft_version":[62,37,73,74,38,78,79],"class_list":["post-70141","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-adventure","mod_category-paper","mod_category-spigot","mod_category-utility","mod_loader-paper","mod_loader-spigot","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6"],"yoast_head":"\n
\n| Command | Description |
\n|———|————-|
\n| `\/findbuddy locate
\n| `\/findbuddy cancel` | Cancel current tracking |
\n| `\/findbuddy accept` | Accept a tracking request |
\n| `\/findbuddy decline` | Decline a tracking request |
\n| `\/waypoint set
\n| `\/waypoint remove
\n| `\/waypoint locate
\n| Command | Description |
\n|———|————-|
\n| `\/findbuddy cleanup
\n– **Remove a waypoint:** `\/waypoint remove home`
\n– **Locate a waypoint:** `\/waypoint locate home`
\n – Gives you a glowing enchanted compass pointing to your waypoint
\n – The compass disappears when you are within a configurable distance (default: `stop_distance` in config)
\n – Tab completion for `\/waypoint set` auto-suggests coordinates of the block you are looking at (like `\/tp`)<\/p>\n
\n# FindBuddy Configuration
\ntracking:
\n stop_distance: 25 # Distance when tracking stops
\n notify_target: true # Notify target when tracked
\n require_requests: true # Require permission requests
\n request_timeout: 90 # Request timeout in seconds<\/p>\n
\n refresh_cooldown: 20 # Compass refresh cooldown in seconds
\n“`<\/p>\n
\n# Basic permissions
\nfindbuddy.find:
\n default: true
\n description: “Allows using basic FindBuddy commands”<\/p>\n
\nfindbuddy.cleanup:
\n default: op
\n description: “Allows using cleanup commands”<\/p>\n
\nfindbuddy.*:
\n default: op
\n children:
\n findbuddy.find: true
\n findbuddy.cleanup: true
\n findbuddy.waypoint: true<\/p>\n
\n default: true
\n description: “Allows using waypoint commands”
\n“`<\/p>\n
\n2. **System checks** if requests are required
\n3. **If direct tracking**: Player A gets a compass and starts tracking
\n4. **If requests required**: Player B gets a request to accept\/decline
\n5. **Action bar shows** real-time distance and direction
\n6. **Compass points** to Player B’s location<\/p>\n
\n– **Right-click** to refresh location (with cooldown)
\n– **Cannot be dropped** or moved to external inventories
\n– **Auto-removed** when tracking stops
\n– **Glows** with enchantment effect<\/p>\n
\n|——-|———-|
\n| **Compass not removed** | Use `\/findbuddy cleanup
\n| **Permission denied** | Check `findbuddy.find` permission |
\n| **Players can’t track** | Verify `require_requests` setting |
\n| **Compass not working** | Check if players are in same world |<\/p>\n
\n“`bash
\n# Clone and build
\ngit clone https:\/\/github.com\/hellofaizan\/FindBuddy.git
\ncd FindBuddy
\n.\/gradlew build<\/p>\n
\n.\/gradlew runServer
\n“`<\/p>\n
\n“`
\nsrc\/main\/kotlin\/in\/mohammadfaizan\/minecraft\/
\n\u251c\u2500\u2500 FindBuddy.kt # Main plugin class
\n\u251c\u2500\u2500 commands\/FindBuddyCommand.kt # Command executor
\n\u251c\u2500\u2500 listeners\/ # Event handling
\n\u251c\u2500\u2500 managers\/ # Business logic
\n\u251c\u2500\u2500 models\/ # Data models
\n\u251c\u2500\u2500 utils\/ # Utilities
\n\u2514\u2500\u2500 ui\/ # UI components
\n“`<\/p>\n
\n– **TrackingManager** – Core tracking logic and task management
\n– **CompassManager** – Compass item creation and management
\n– **ConfigManager** – Type-safe configuration access
\n– **MessageUtils** – Consistent UI message formatting<\/p>\n
\n1. **Fork** the repository
\n2. **Create** feature branch
\n3. **Make changes** following Kotlin conventions
\n4. **Add tests** for new functionality
\n5. **Submit** pull request<\/p>\n
\n**\ud83d\udc1b Report issues on GitHub**
\n**\ud83d\udca1 Suggest features and improvements**<\/p>\n