❤️ AdventureFriend

一、简介

AdventureFriend 是服务器内置社交核心，将好友、个人主页、私聊、礼物、留言墙、跨服传送、在线通知、动态流和组队系统整合在统一 GUI 与数据层中。

插件支持 SQLite 单服测试和 MySQL 多服共享；跨服环境通过服务器心跳、跨服消息队列及 AdventureServer 实现在线状态和好友传送。

👥

好友关系

请求、接受、拒绝、备注、标签、信任、屏蔽和黑名单。

🪪

个人主页

资料、状态、隐私、9 格展示柜、访问量、点赞和留言墙。

💌

聊天与礼物

TrChat/内置私聊、离线信箱、礼物收件箱和过期退回。

🌐

跨服社交

在线状态、跨服消息、好友 TP、上线通知和组队召集。

二、系统要求

项目	要求
服务端	Paper 1.21.4+
Java	21+
数据库	SQLite 或 MySQL 5.7+
推荐	MySQL 多服共享、AdventureServer 跨服、PlaceholderAPI

ℹ️ 功能状态

源码已包含好友、主页、展示柜、留言、聊天、礼物、跨服消息、通知、动态流和组队实现。玩家自主赠送主手物品由 gift.player-send 控制，默认关闭。

下一篇安装与存储 →

📥 安装与存储

安装步骤

将 AdventureFriend-1.2.9.jar 放入 Paper 的 plugins/。
单服测试可直接使用 SQLite；生产多服建议先创建 MySQL 数据库。
多服部署时所有子服使用同一数据库，并为每个服设置不同 server.id。
按需安装 AdventureServer、TrChat、PlaceholderAPI 等软依赖。
启动后执行 /f debug schema 或查看启动 schema 自检报告。

存储模式

storage:
  type: mysql
  table-prefix: af_
  mysql:
    host: localhost
    port: 3306
    database: adventure
    username: root
    password: ""
    pool-size: 10
server:
  id: lobby
  display-name: "主城"

数据表覆盖档案、展示柜、好友、请求、屏蔽、消息、礼物、留言、点赞、访问、通知、动态、在线状态、跨服消息和队伍。

⚠️ 多服部署

server.id 必须在每个子服唯一，否则在线状态和跨服消息的投递来源会混淆。

上一篇← 概览

下一篇好友系统 →

👥 好友系统

关系流程

使用 /f add <玩家> [附言] 发出请求。
接收方通过请求 GUI 或命令接受/拒绝。
建立关系后可设置独立备注、标签和信任等级。
好友关系采用规范化双人键，双方备注和标签分别保存。

默认限制

设置	默认值
好友上限	100
待处理请求上限	20
请求有效期	4320 分钟
拒绝后重发冷却	1440 分钟
连续拒绝自动拉黑	第 6 次
请求附言长度	64
备注长度	32

GUI

/f 打开主菜单；好友列表提供分页、状态显示和好友动作面板，请求列表支持查看详情后接受或拒绝。

上一篇← 安装与存储

下一篇主页与展示柜 →

🪪 主页与展示柜

档案字段

QQ、性别、自定义称谓、生日和纪念日
简介、性格、自定义状态、心情
主页隐私、免打扰、好友/消息接收策略
最后上线时间、世界、服务器
主页访问量、点赞数、主题和头像

9 格展示柜

展示柜支持物品、文本、标题和清空操作。槽位范围为 1–9。

命令	说明
`/f showcase gui`	编辑自己的展示柜
`/f showcase open [玩家]`	浏览展示柜
`/f showcase item <1-9>`	保存主手物品快照
`/f showcase text <1-9> <文字>`	设置文本
`/f showcase title <1-9> <标题>`	设置标题
`/f showcase clear <1-9>`	清空槽位

主页限制

简介上限 256、状态上限 64、留言上限 512。同一访问者 30 分钟内重复访问不重复计数。

上一篇← 好友系统

下一篇私聊系统 →

💬 私聊系统

提供者模式

模式	行为
`auto`	检测到 TrChat 时交给 TrChat，否则使用内置实现
`trchat`	强制使用 TrChat；未安装时禁用私聊
`fallback`	始终使用内置私聊

命令

/w <玩家> <内容> — 发起私聊
/r <内容> — 回复最近私聊对象
/f msg <玩家> <内容> — 主命令入口

内置模式

默认保留 90 天私聊记录，支持离线消息箱，单条消息最大 256 字符。消息发送前会检查隐私、免打扰、屏蔽和 AdventureSafe 社交限制。

上一篇← 主页与展示柜

下一篇礼物收件箱 →

🎁 礼物收件箱

功能

系统、商店或玩家向好友投递礼物
收件箱最多保留 50 件待领取礼物
跨服存储与领取
禁止 BARRIER、命令方块、结构方块、基岩等危险物品
过期礼物可通过 AdventureMail 退回送礼人

默认行为

设置	默认
礼物有效期	30 天
跨服礼物	开启
附言长度	128
玩家自主赠送主手物品	关闭
AdventureMail 退回	开启

命令

/f gift 或 /f gift inbox 打开收件箱；/f gift <玩家> 在启用玩家赠送后打开确认 GUI。若安装 AdventureShop，会优先分派到商店礼物流程。

上一篇← 私聊系统

下一篇留言墙与动态 →

📝 留言墙与动态

留言墙

/f wall — 打开自己的留言墙
/f wall <玩家> — 浏览他人留言墙
/f wall post <内容> — 给自己留言
/f wall <玩家> post <内容> — 给指定玩家留言

每页默认 10 条，支持点赞、置顶、隐藏和管理员强制管理。

动态流

/f feed 打开个人动态流。系统可以记录好友关系、主页互动、在线状态、组队等事件；默认保留 60 天。

AdventurePass 联动

配置已内置主页点赞、好友互动和拜访好友领地的任务进度命令，并分别设置 1 秒或 5 秒防刷冷却。

上一篇← 礼物收件箱

下一篇隐私与屏蔽 →

🛡️ 隐私与屏蔽

主页隐私

值	模式
0	公开
1	仅好友
2	私密

好友/消息接收策略

值	模式
0	拒绝
1	好友的好友
2	任何人

屏蔽与黑名单

/f block <玩家> / /f unblock <玩家>
/f blacklist <玩家> / /f unblacklist <玩家>
/f dnd 切换免打扰

黑名单会参与好友请求、私聊、主页、礼物和跨服 TP 校验；比普通屏蔽更严格。

上一篇← 留言墙与动态

下一篇组队系统 →

⚔️ 组队系统

队伍数据包含队长、成员、邀请与有效期。默认最大人数为 5。

入口

/f party — 打开队伍 GUI
/partychat <内容>、/pc、/pchat — 队伍聊天

能力

创建/解散队伍
邀请、接受、拒绝与踢出成员
队长转让和成员角色
队伍频道消息
通过 AdventureServer 的 atphere 召集队友

party:
  max-size: 5
cross-server:
  tphere-command: "adventureserver:atphere"

上一篇← 隐私与屏蔽

下一篇跨服能力 →

🌐 跨服能力

好友 TP

/f tp <好友> 会先检查目标、黑名单和好友限制，再调用 AdventureServer 的命名空间命令。

cross-server:
  tp-command: "adventureserver:atp"
  tphere-command: "adventureserver:atphere"
  tp-friend-only: true

在线状态与消息

presence 表记录玩家当前服务器、世界、活动和更新时间
cross_message 表持久化跨服消息，并记录过期、投递时间和目标服
好友上线通知支持 actionbar、message 和可选 title
/f notify <玩家> 切换订阅，/f notify list 查看订阅列表

⚠️ 数据库要求

多服在线状态与跨服消息必须使用共享 MySQL；各服还必须配置唯一 server.id。

上一篇← 组队系统

下一篇配置说明 →

⚙️ 配置说明

配置段	用途
`storage`	SQLite/MySQL、连接池和表前缀
`server`	当前服唯一 ID 与显示名
`cross-server`	TP/召集命令和好友限制
`friend`	好友、请求、冷却和长度限制
`profile`	主页隐私、文本和留言墙
`gift`	礼物、过期、禁止物品和邮件退回
`chat`	TrChat/内置提供者与离线消息
`notify`	上线通知冷却与显示模式
`privacy`	新玩家默认策略
`integration`	软依赖自动检测
`retention`	数据清理时间和保留天数
`adventurepass`	社交任务进度命令

文本颜色

简介、留言和状态支持传统 &c、##ff5500、&#FF5500 和 MiniMessage；可通过权限要求限制。

上一篇← 跨服能力

下一篇命令列表 →

⌨️ 命令列表

常用命令

命令	说明
`/f`	打开主菜单
`/f add/accept/deny/del <玩家>`	管理好友关系
`/f list` / `/f requests`	好友与请求 GUI
`/f profile [玩家]`	打开主页
`/f note/tag <玩家> [文字]`	设置备注或标签
`/f wall [玩家]`	打开留言墙
`/f gift [玩家]`	礼物收件箱或赠送
`/f dnd`	切换免打扰
`/f notify <玩家\|list>`	上线通知订阅
`/f tp <好友>`	跨服传送请求
`/f party` / `/pc`	队伍与队聊
`/f feed`	动态流
`/w` / `/r`	私聊与回复

管理命令

命令	说明
`/f reload`	重载配置与消息
`/f debug ...`	状态、schema 和跨服诊断

别名：/friend、/f、/af、/friends。

上一篇← 配置说明

下一篇权限节点 →

🔑 权限节点

节点	默认	说明
`adventurefriend.use`	true	使用基础命令与 GUI
`adventurefriend.admin`	OP	管理任意主页、留言和社交封禁
`adventurefriend.color`	true	在简介、留言、状态使用颜色
`adventurefriend.cross-server`	true	使用跨服 TP
`adventurefriend.bypass-cooldown`	OP	绕过请求和礼物冷却
`adventurefriend.bypass-friend-limit`	OP	绕过好友数量上限
`adventurefriend.invisible-visit`	OP	匿名访问主页不留记录

上一篇← 命令列表

下一篇PAPI 变量 →

📊 PlaceholderAPI 变量

标识符为 af，数据缓存 1 秒。

变量	说明
`%af_status%`	自定义状态
`%af_friends_count%`	好友总数
`%af_friends_online%`	在线好友数（含跨服）
`%af_server%`	当前/最后服务器
`%af_online%`	跨服在线布尔值
`%af_party_size%`	队伍人数
`%af_tab_prefix%`	队伍与好友前缀
`%af_tab_suffix%`	队伍、在线好友与状态后缀
`%af_tab_sort%`	Tab 排序键
`%af_tab_status%`	状态、组队中或好友在线摘要

上一篇← 权限节点

下一篇插件联动 →

🔗 插件联动

插件	用途
TrChat	接管私聊命令
AdventureServer	好友跨服 TP 与队长召集
AdventureMail	过期礼物退回
AdventureTop	主页生涯数据
AdventureMedal	头像与勋章展示
PlaceholderAPI	10 个 af 变量
LuckPerms / Vault	权限和经济生态
AdventureTAB	好友/队伍 Tab 前后缀
AdventureSafe	社交功能限制
Dominion	好友领地拜访事件
AdventurePass	点赞、互动、拜访任务进度

上一篇← PAPI 变量

下一篇排错与状态 →

🧰 排错与状态

好友/主页数据不同步

多服环境必须使用同一 MySQL
确认表前缀一致、server.id 唯一
检查启动时 schema 自检

跨服 TP 不可用

安装 AdventureServer 并检查 tp-command
使用完整命名空间，默认 adventureserver:atp
检查 adventurefriend.cross-server 与 AdventureServer 侧权限

私聊未使用 TrChat

将 provider 设置为 auto 或 trchat
确认 passthrough-command 为有效 TrChat 命名空间命令
留空时会回退到内置私聊

礼物无法发送

玩家自主赠送默认关闭，需要设置 gift.player-send: true；系统与商店礼物收件箱不受此开关影响。

上一篇← 插件联动