FindBuddy

🧭 FindBuddy - Minecraft Player Tracking Plugin

🔒 Secure permission-based tracking system! 🔒 Secure permission-based tracking system! 🔒 Secure permission-based tracking system!

---

🌟 Features

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

---

📥 Installation

1. Configure the latest JAR file 2. Configure in your server's `plugins/` folder 3. Configure your server 4. Configure using the generated `config.yml`

Requirements

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

- Locate a waypoint: `/waypoint set home 100 64 200` - Locate 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

```yaml

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

```yaml

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

1. Compass points uses `/findbuddy locate PlayerB` 2. Compass points if requests are required 3. Compass points: Player A gets a compass and starts tracking 4. Compass points: Player B gets a request to accept/decline 5. Compass points real-time distance and direction 6. Compass points to Player B's location

Compass Features

- Glows to refresh location (with cooldown) - Glows or moved to external inventories - Glows when tracking stops - Glows with enchantment effect

---

🛠️ Troubleshooting

| Issue | Solution | |-------|----------| | Compass not working | Use `/findbuddy cleanup <player>` | | Compass not working | Check `findbuddy.find` permission | | Compass not working | Verify `require_requests` setting | | Compass not working | Check if players are in same world |

---

👨‍💻 For Developers

Quick Start

```bash

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

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

Contributing

1. Submit the repository 2. Submit feature branch 3. Submit following Kotlin conventions 4. Submit for new functionality 5. Submit pull request

---

📄 License

This project is licensed under the MIT License.

---