**⭐ 如果您觉得有用，请为这个仓库点赞！**
**🐛 在 GitHub 上报告问题**
**💡 建议功能和改进**
❤️ 由 [Mohammad Faizan](https://mohammadfaizan.in) 制作。
# 🧭 FindBuddy - Minecraft 玩家追踪插件
**🎯 用附魔指南针追踪你的朋友！**
**⚡ 带有动作栏的实时位置更新！**
**🔒 安全的基于权限的追踪系统！**
---
## 🌟 特性
- 🧭 **智能指南针** - 指向追踪玩家或自定义航点的附魔指南针
- 📍 **实时追踪** - 动作栏中显示实时距离和方向
- 🔐 **权限系统** - 可选的基于请求的追踪（类似于 TPA）
- 🌍 **跨世界支持** - 在不同的世界和维度中工作
- ⚙️ **高度可配置** - 自定义距离、冷却时间和通知
- 🛡️ **管理员工具** - 服务器管理清理命令
- 🔄 **自动清理** - 自动移除指南针以防止问题
- 🗺️ **航点** - 使用指南针设置、移除和定位自定义航点
---
## 📥 安装
1. **下载** 最新版的 JAR 文件
2. **放置** 在你的服务器的 `plugins/` 文件夹中
3. **重启** 你的服务器
4. **配置** 使用生成的 `config.yml` 文件
### 要求
- **Minecraft**: 1.21+ (Paper/Spigot/Bukkit)
- **Java**: 17 或更高
---
## 📋 命令
### 玩家命令
| 命令 | 描述 |
|---------|-------------|
| `/findbuddy locate ` | 开始追踪一个玩家 |
| `/findbuddy cancel` | 取消当前追踪 |
| `/findbuddy accept` | 接受追踪请求 |
| `/findbuddy decline` | 拒绝追踪请求 |
| `/waypoint set [world]` | 设置一个自定义航点 |
| `/waypoint remove ` | 移除一个自定义航点 |
| `/waypoint locate ` | 获取一个导航到航点的指南针 (靠近时消失) |
### 管理员命令
| 命令 | 描述 |
|---------|-------------|
| `/findbuddy cleanup ` | 移除玩家的所有追踪指南针 |
**别名**: `/fb`, `/find`
---
## 🗺️ 航点
航点允许你轻松保存和重访自定义位置：
- **设置一个航点:** `/waypoint set home 100 64 200`
- **移除一个航点:** `/waypoint remove home`
- **定位一个航点:** `/waypoint locate home`
- 给您一个发光的附魔指南针，指向您的航点
- 当您在可配置的距离内时（默认值：config 中的 `stop_distance`），指南针会消失
- `/waypoint set` 的 Tab 补全会自动建议您正在观看的方块的坐标（类似于 `/tp`）
航点以 JSON 文件的形式，每位玩家保存在 `Finddata` 文件夹中。
---
## ⚙️ 配置
```yaml
# FindBuddy 配置
tracking:
stop_distance: 25 # 追踪停止的距离
notify_target: true # 追踪时通知目标
require_requests: true # 要求权限请求
request_timeout: 90 # 请求超时时间（秒）
compass:
refresh_cooldown: 20 # 指南针刷新冷却时间（秒）
```
---
## 🔧 权限
```yaml
# 基本权限
findbuddy.find:
default: true
description: "允许使用基本的 FindBuddy 命令"
# 管理员权限
findbuddy.cleanup:
default: op
description: "允许使用清理命令"
# 所有权限
findbuddy.*:
default: op
children:
findbuddy.find: true
findbuddy.cleanup: true
findbuddy.waypoint: true
findbuddy.waypoint:
default: true
description: "允许使用航点命令"
```
---
## 🎮 工作原理
1. **玩家 A** 使用 `/findbuddy locate PlayerB`
2. **系统检查** 是否需要请求
3. **如果直接追踪**: 玩家 A 获取指南针并开始追踪
4. **如果需要请求**: 玩家 B 会收到接受/拒绝请求
5. **动作栏显示** 实时距离和方向
6. **指南针指向** 玩家 B 的位置
### 指南针功能
- **右键单击** 以刷新位置（带冷却）
- **无法被丢弃** 或移动到外部物品栏
- **追踪停止时自动移除**
- **发出光芒** 附魔效果
---
## 🛠️ 故障排除
| 问题 | 解决方案 |
|-------|----------|
| **指南针未移除** | 使用 `/findbuddy cleanup ` |
| **权限被拒绝** | 检查 `findbuddy.find` 权限 |
| **玩家无法追踪** | 验证 `require_requests` 设置 |
| **指南针无法工作** | 检查玩家是否在同个世界|
---
## 👨💻 供开发者使用
### 快速开始
```bash
# 克隆并构建
git clone https://github.com/hellofaizan/FindBuddy.git
cd FindBuddy
./gradlew build
# 使用测试服务器运行
./gradlew runServer
```
### 项目结构
```
src/main/kotlin/in/mohammadfaizan/minecraft/
├── FindBuddy.kt # 主插件类
├── commands/FindBuddyCommand.kt # 命令执行器
├── listeners/ # 事件处理
├── managers/ # 业务逻辑
├── models/ # 数据模型
├── utils/ # 工具类
└── ui/ # UI 组件
```
### 关键组件
- **TrackingManager** - 核心追踪逻辑和任务管理
- **CompassManager** - 指南针物品创建和管理
- **ConfigManager** - 类型安全的配置访问
- **MessageUtils** - 统一的 UI 消息格式
### 贡献
1. **Fork** 仓库
2. **创建一个** 功能分支
3. **进行更改** 遵循 Kotlin 约定
4. **添加测试** 用于新功能
5. **提交** 拉取请求
---
## 📄 许可
本项目采用 **MIT 许可证** 授权。
---