原创 闭源 聊天 whFriend —— 服主级好友系统插件 2.9.0

# whFriend —— 服主级好友系统插件 [原创 · WH]
> **一句话介绍**：把「加好友」这件事做到极致——GUI 好友列表、私聊频道、传送、送礼、亲密度、每日任务、邮箱留言、动态圈子、群聊红包……**一个插件全搞定**，还自带**跨服同步**与**多语言**。


---
## 写在前面
服务器里玩家互相不认识？加了好友也不知道能干嘛？
**whFriend** 就是为此而生 —— 它不是一个「只能发好友请求」的简陋插件，而是一整套**社交玩法系统**：加了好友能聊天、能传送到一起玩、能送礼、能一起做任务刷亲密度、能互相发红包、能建群一起唠嗑。
**全部界面手工美化，全部文案可自定义，全部数值可配置。**
---
## 核心亮点
| | 功能 | 说明 |
| --- | --------------- | --------------------------------------------------------------------- |
| | **全套 GUI 界面** | 好友列表 / 好友详情 / 请求 / 设置 / 邮箱 / 留言簿 / 任务 / 动态 / 群聊，**共 19 个界面**，全部手工排版美化 |
| | **好友私聊 + 好友频道** | 离线留言、快速回复 `/f r`、@ 提醒、留言撤回，还有「在线好友都看得到」的频道消息 |
| | **好友传送** | `/f tp` 一步直达好友身边；坐标分享 `/f loc` 点一下就飞过去；`/f tphere` 把好友拉到身边（需对方同意） |
| | **送礼 + 邮箱** | 手持物品直接送给好友，对方不在线就进邮箱，最多存 54 件 |
| | **亲密度系统** | 陪好友挖矿、钓鱼、聊天、送礼都能涨亲密度，升级解锁称号 + 纪念品，关系越处越深 |
| | **好友每日任务** | 10 个内置任务（并肩挖矿 / 陪伴时光 / 无话不谈…），**还能在配置里无限新增**，不用改代码 |
| | **动态圈子** | 好友升级、送礼、结为好友、发红包都会进动态流，可以点赞互动 |
| | **好友红包 + 群红包** | 二倍均值随机拆分，拼手气！只有好友/群成员能抢，过期自动退款 |
| | **群聊系统** | 全服公共频道 + 好友自建群（建群/邀请/踢人/公告/群红包），支持跨服 |
| | **跨服同步** | 多服共用一个 MySQL 就能互相加好友、聊天、传送，**代理端不用装任何插件** |
| | **多语言** | 内置简体中文 / English，玩家可 `/f lang` 自助切换，也可自己加语言文件 |
| | **原创保护** | 内置品牌校验 + 反编译工具检测，抵制改名倒卖 |
---
## 界面预览
> 全部为游戏内实机截图
** 好友列表** —— 顶栏两个入口：好友动态 + 群聊

** 好友详情** —— 一眼看清关系、亲密度、服务器、备注

** 好友请求** —— 一键接受 / 一键拒绝

** 好友设置** —— 各种隐私开关，想安静就安静

** 私聊 / 留言簿**

** 邮箱** —— 离线收到的礼物都在这

** 好友动态圈子** —— 好友的一举一动都在这里

** 好友任务** —— 和好友一起完成任务拿奖励

** 任务进度** —— 每个人的进度单独记录

** 我的群聊** —— 自建群列表

** 群聊频道** —— 群内聊天 + 群红包

** 在线玩家** —— 看看谁在线，随手加好友

---
## 安装步骤
```
① 把 whFriend-2.9.0.jar 丢进服务器 plugins/ 文件夹
② 重启服务器（首次启动会自动生成全部配置文件）
③（可选）装 Vault + 经济插件，红包/送礼/购买好友位等功能才会生效
④（可选）装 PlaceholderAPI，就能用 %whfriend_xxx% 变量做计分板
⑤（可选）多服用同一个 MySQL，把 config.yml 的 cross-server.enabled 改成 true
```
**就这么简单，开箱即用。**
---
## 运行环境
| 项目 | 要求 |
| ---------- | ------------------------------------------------------------------------------------ |
| 服务端 | **Paper / Spigot / Folia**（三端全兼容） |
| 游戏版本 | **1.21.x ~ 26.x**（自动适配新版本号写法） |
| Java | **21**（必须） |
| 软依赖（可选） | `Vault` 经济、`PlaceholderAPI` 变量、`SuperVanish`/`PremiumVanish` 隐身联动、`SkinsRestorer` 皮肤 |
> **不装任何软依赖也能跑**，插件会自动跳过对应功能，绝不会报错。
---
## 指令一览
主指令：`/friend`，**别名 `/f`**
### 基础
| 指令 | 作用 |
| ----------------------------- | ----------- |
| `/f` | 打开好友菜单 |
| `/f add <玩家>` | 发送好友请求 |
| `/f accept <玩家>` | 接受请求 |
| `/f deny <玩家>` | 拒绝请求 |
| `/f acceptall` / `/f denyall` | 一键全部接受 / 拒绝 |
| `/f remove <玩家>` | 删除好友 |
### 互动
| 指令 | 作用 |
| -------------------------------- | -------------- |
| `/f msg <玩家> <内容>` | 私聊（对方离线则留言） |
| `/f r <内容>` | 快速回复上一位好友 |
| `/f tp <好友>` | 直接传送到好友身边 |
| `/f tpa <好友>` | 同上 |
| `/f tphere <好友>` | 把好友拉到身边（需同意） |
| `/f tpaccept` / `/f tpdeny <好友>` | 同意 / 拒绝被拉 |
| `/f loc <好友>` | 分享当前坐标（对方点击直达） |
| `/f gift <玩家> [留言]` | 手持物品送礼 |
| `/f mailbox` | 打开邮箱 |
| `/f messages` | 打开留言簿 |
| `/f recall <玩家>` | 撤回刚发、未被读的留言 |
### 社交
| 指令 | 作用 |
| ----------------- | ---------------- |
| `/f ch <消息>` | 发到好友频道（在线好友都看得到） |
| `/f feed` | 打开好友动态圈子 |
| `/f rp <总额> <份数>` | 发好友红包 |
| `/f grab <ID>` | 抢红包 |
### 群聊
| 指令 | 作用 |
| ------------------------------- | --------- |
| `/f gc <消息>` | 在当前频道发言 |
| `/f public <消息>` | 发到全服公共频道 |
| `/f group create <群名>` | 创建群 |
| `/f group list` | 查看我的群 |
| `/f group invite <玩家>` | 邀请好友进群 |
| `/f group accept <群号>` / `deny` | 接受 / 拒绝邀请 |
| `/f group kick <玩家>` | 踢出成员 |
| `/f group leave` | 退出群 |
| `/f group disband` | 解散群 |
| `/f group notice <内容>` | 设置群公告 |
| `/f group switch <群号>` | 切换发言频道 |
| `/f group rp <总额> <份数>` | 发群红包 |
| `/f group gui` | 打开群聊界面 |
### 管理 / 设置
| 指令 | 作用 |
| ------------------- | ------------ |
| `/f tier [好友]` | 查看亲密度等级称号 |
| `/f anniversary` | 领取结识纪念日奖励 |
| `/f cleanup` | 清理僵尸好友 |
| `/f where [好友]` | 查看好友所在服务器 |
| `/f nick <好友> <备注>` | 设置备注名 |
| `/f star <好友>` | 星标置顶 |
| `/f block <玩家>` | 屏蔽玩家 |
| `/f blocklist` | 屏蔽列表 |
| `/f settings` | 打开隐私设置 |
| `/f top` | 亲密度排行榜 |
| `/f tasks` | 每日任务 |
| `/f info <好友>` | 好友详情 |
| `/f buyslot` | 购买好友位 |
| `/f lang <语言>` | 切换个人语言 |
| `/f about` | 查看插件原创信息与作者 |
### 管理员
| 指令 | 作用 |
| ------------------------------ | --------------------- |
| `/f diag` | 查看运行环境（核心 / 版本 / 兼容性） |
| `/f setintimacy <p1> <p2> <值>` | 设置两人亲密度 |
| `/f setslots <玩家> <数量>` | 设置玩家好友位 |
| `/f spy` | 私聊监听 |
| `/f gifthistory` | 送礼记录 |
| `/f stats` | 统计数据 |
| `/f reload` | 重载配置 |
---
## 权限节点
| 权限 | 默认 | 说明 |
| ------------------- | ----- | ------------ |
| `whfriend.use` | 所有人 | 使用好友系统 |
| `whfriend.admin` | OP | 管理员指令 |
| `whfriend.color` | OP | 私聊 / 频道使用颜色符 |
| `whfriend.slots.10` | 关闭 | 额外 10 个好友位 |
| `whfriend.slots.20` | 关闭 | 额外 20 个好友位 |
| `whfriend.slots.30` | 关闭 | 额外 30 个好友位 |
> 好友位档位可以自己加，比如 `whfriend.slots.50`，配置里写好就行。
> 老版本（FriendCore 时代）的旧权限节点 `friendcore.*` **依然兼容**，无需改动现有权限组。
---
## 配置文件
配置按模块拆分，**改完执行 `/f reload` 热重载**，不用重启：
| 文件 | 内容 |
| ---------------- | -------------------------------------------- |
| `config.yml` | 语言 / 原创标识 / 存储 / 跨服 / 基础 / 指令 / 兼容 / 性能 / 保护 |
| `gui.yml` | 界面外观 / 音效 / 通知提醒 |
| `social.yml` | 亲密度 / 纪念品 / 纪念日 / 送礼 / 传送 / 功能开关 / 消息格式 |
| `tasks.yml` | 每日任务（10 个内置 + 自定义新增） |
| `welfare.yml` | 好友红包 / 好友动态圈子 |
| `chat.yml` | 群聊：全服公共频道 / 自建群 / 群红包 |
| `languages/` | 多语言文案（`zh_CN.yml` / `en_US.yml`） |
**常见可配置项举例：**
- 好友位默认 5 个，买一个 100 金币，最多再买 15 个
- 亲密度等级：点头之交 → 好友 → 挚友 → 知己 → 生死之交（可自定义名称、颜色、称号前缀、升级奖励、升级广播）
- 任务：目标次数、奖励亲密度、奖励金币，全部可改；**自定义任务不用写代码**
- 红包：最低总额、最高总额、最多几份、每份最少多少、过期秒数
- 群：每人最多建几个群、单群最多多少人、建群花费、群名长度、邀请有效期
- 隐身联动：兼容 SuperVanish / PremiumVanish / CMI / EssentialsX / VanishNoPacket
---
## PlaceholderAPI 变量
装好 PlaceholderAPI 后可用（`%whfriend_xxx%`）：
```
社交 friend_count / max_friends / friend_online / pending_requests
数据 mailbox / unread_messages / blocked / online_total
排行 top_friend / top_intimacy / top_tier / top_tier_colored
纪念 anniversary / pending_anniversary / server
标识 brand / author / plugin_id / plugin_version
```
---
## 开发者 API
插件提供完整对外 API（包 `com.whfriend.api`），其他插件可以：
- 查询 / 添加 / 删除好友
- 读写亲密度、等级称号
- 发送私聊、广播频道消息
- 传送玩家到好友身边
- 监听好友事件（结为好友、升级、送礼…）
**随包附赠《whFriend API 使用文档》**，含快速接入 3 步、方法详解、事件系统、完整示例插件。
---
## 更新日志
**v2.9.0**
- 移除部分功能，并入群聊，界面更清爽
- 修复：改语言后部分文案仍显示英文（语言文件加内容版本号，启动自动刷新并备份）
- 群聊入口挪到原签到位置，好友列表顶栏更顺手
**v2.8.0**
- 新增**群聊系统**：全服公共频道 + 好友自建群 + 群红包
- 新增**防反编译 / 防篡改保护**（品牌校验 + 反编译工具检测）
- 修复：好友动态出现重复信息
**v2.7.x**
- 配置按模块拆分为 5 个文件
- 新增多语言体系，全部文案外置可翻译
- 玩家可 `/f lang` 自助切换语言
**v2.6.x**
- 好友任务完全配置化，支持自定义任务
- 「拉到身边」改为需对方同意
**v2.5.x**
- 新增好友动态圈子、好友频道、@ 提醒、留言撤回、好友红包
- 数据库 / GUI 渲染 / 内存缓存三项性能优化
**v2.4 及以前**
- GUI 视觉整体重做，三色体系统一
- 移除好友分组与铁砧搜索
---
## 常见问题
**Q：为什么红包 / 送礼 / 购买好友位不能用？**
A：这些功能依赖经济系统，请先装 **Vault** 和任意一款经济插件（如 EssentialsX Economy）。
**Q：怎么让某个玩家多几个好友位？**
A：给他对应权限，比如 `whfriend.slots.10`，或直接 `/f setslots <玩家> <数量>`。
**Q：多服怎么同步好友？**
A：所有服连同一个 MySQL，把 `config.yml` 里 `storage.type` 改成 `mysql`、`cross-server.enabled` 改成 `true`，**代理端不需要装任何插件**。
**Q：能自己改文案吗？**
A：可以。`plugins/whFriend/languages/` 下每个 yml 就是一个语言，复制一份改名翻译即可，`/f reload` 生效。
**Q：改了配置要重启吗？**
A：绝大多数配置 `/f reload` 就行；改**存储方式**和**跨服**需要重启。
**Q：和隐身插件冲突吗？**
A：内置隐身联动，兼容 SuperVanish / PremiumVanish / CMI / EssentialsX / VanishNoPacket。好友隐身时会对外显示为「离线」，不会穿帮。
---
## 声明
- 本插件为 **WH 原创作品**，标识符 **`[WH]`** / **`WH-FRIEND`**，请认准标识使用。
- **禁止**未经许可的二次售卖、改名倒卖、去除作者标识后重新发布。
- 欢迎在服务器中正常使用与自由配置，也欢迎反馈 BUG 与建议。
- 使用中遇到问题，请在本帖下方回复，附上**服务端核心 + 版本 + 报错日志**，方便定位。
---
## 最后
后续可能对ARCmeun做适配，敬请期待。
> 原创不易，尊重原创，感谢支持。