AdventurePrefix
AdventurePrefix 提供权限组前缀、管理员覆盖前缀和付费限时自定义前缀。内置文本引擎支持传统颜色、十六进制、RGB 与多锚点渐变，并通过 PAPI 交给聊天/TAB 插件展示。
原生文本引擎
& 颜色、HEX、RGB、逐字素渐变和 MiniMessage 备用模式。
限时资格
个人/团队、季度/年度四种方案，首次设置起算。
事后审核
提交即生效，管理员 GUI 通过或输入理由驳回。
多种存储
YAML、SQLite、MySQL，原样保存 UTF-8 模板。
| 版本 | 0.2.6 |
|---|---|
| 目标服务端 | Paper 1.21.8 API |
| 运行 Java | 25 |
| 可选依赖 | PlaceholderAPI |
| 显示策略 | PAPI 为主；可选接管头顶名牌，不接管聊天/Tab |
安装与存储
- 服务器安装 Java 25，将插件放入
plugins/。 - 推荐安装 PlaceholderAPI，以便聊天和 TAB 展示。
- 首次启动生成 config、prefixes、messages 和 sounds。
- 单服使用 YAML/SQLite；群组服使用共享 MySQL。
storage:
type: yaml
sqlite:
file: data.db
mysql:
host: localhost
port: 3306
database: adventureprefix
username: root
password: ""
pool-size: 10模板以纯文本原样保存，颜色解析发生在展示层；MySQL 使用 utf8mb4 和参数化语句。
文本引擎
| 格式 | 示例 |
|---|---|
| 传统颜色 | &aHello &c&lWorld |
| 十六进制 | &#FF8800文字 或 #FF8800文字 |
| RGB | &{255,136,0}文字 |
| 双色渐变 | <gradient:#FF0000:#00FF00>ABCDE</gradient> |
| 多锚点渐变 | <gradient:#F00:#FF0:#0F0>文字</gradient> |
默认引擎为 native，渐变按 Unicode 字素簇逐字插值；可通过命令切换 minimessage 备用引擎。
组前缀
prefixes:
player:
weight: 10
permission: adventureprefix.group.player
format: ""
vip:
weight: 10
permission: adventureprefix.group.vip
format: "&aVIP"
mvp:
weight: 20
permission: adventureprefix.group.mvp
format: "&6MVP"玩家同时匹配多个定义时，权重最高者生效。管理员个人覆盖和有效的自定义前缀优先于组前缀。
多个组使用相同权重时结果取决于定义顺序；建议为每个等级设置明确递增权重。
自定义前缀
校验规则
- 可见字符默认 1—12；颜色与格式标记不计长度。
- 按 Unicode 字素簇计数，避免拆开 emoji 和组合字符。
- 可启用宽度模式，让 CJK、全角和 emoji 按 2 计。
- 过滤换行、零宽字符、首尾空格和可配置脏词。
- 默认首次设置后不允许额外修改。
/aprefix custom <内容>
/aprefix preview <内容>
/aprefix custom clear资格未使用时不计时；首次成功设置时才消耗资格并开始到期倒计时。
付费方案
| ID | 类型 | 期限 | 人数 | 默认价格 |
|---|---|---|---|---|
| 1 | 个人 | P3M（季度） | 1 | 100 |
| 2 | 个人 | P1Y（年度） | 1 | 300 |
| 3 | 团队 | P3M | 5 | 400 |
| 4 | 团队 | P1Y | 5 | 1000 |
重购规则
已消耗或到期资格重新购买用于更改时，默认应用 recustomize-discount: 0.5。通过 edits.allowed 或方案级 edits 控制可修改次数。
支付系统可调用 AdventurePrefixApi，监听 PrefixGrantEvent，或执行 aprefix grant <player> <plan> [renew]。
团队方案
团队资格由拥有者维护成员列表，默认上限由方案 size 决定。
| 命令 | 用途 |
|---|---|
/aprefix team add <玩家> | 添加成员 |
/aprefix team remove <玩家> | 移除成员 |
/aprefix team list | 查看团队 |
- 成员共享该团队方案的资格范围。
- 移除成员或资格到期后，相关自定义前缀回退到默认/组前缀。
- 团队成员数包含方案定义的可用人数限制。
审核流程
- 玩家提交自定义前缀。
- 前缀立即生效并写入待审核记录。
- 在线管理员收到通知。
- 管理员使用
/aprefix admin log打开箱子 GUI。 - 左键通过；右键进入驳回理由输入，回车确认。
- 多管理员处理状态通过存储同步，避免重复审批。
review:
scan-interval-minutes: 10
notify-admins-on-submit: true系统采用事后审核以降低玩家等待成本；脏词和字符校验仍在提交前执行。
头顶名牌
nameplate:
enabled: false
format: "&f[%adventureprefix_use%&f]&r"
refresh-interval-ticks: 100启用后插件接管玩家头顶 nametag，并定时刷新。格式支持本插件文本标记、PAPI 和 %adventureprefix_use%。
/aprefix namepreview 可让玩家仅在自己客户端预览已有生效前缀 30 秒。
其他 TAB/名牌插件也可能修改 Team 前后缀。正式启用前必须确认只有一个插件负责头顶名牌。
命令与权限
根命令 /aprefix，别名 /apre、/ap。
| 命令 | 权限 |
|---|---|
help/custom/status/team/preview/namepreview/version | adventureprefix.use（所有人） |
reload/list/engine | adventureprefix.admin（OP） |
grant <玩家> <方案> [renew] | 管理员 |
revoke <玩家> | 管理员 |
set/clear <玩家> | 管理员 |
admin log | 管理员审核 GUI |
PAPI 变量
| 变量 | 结果 |
|---|---|
%adventureprefix_prefix% | 渲染后的有效前缀 |
%adventureprefix_prefix_mini% | MiniMessage 形式 |
%adventureprefix_prefix_plain% | 纯文本 |
%adventureprefix_prefix_raw% | 原始模板 |
%adventureprefix_eligible% | 是否有资格 |
%adventureprefix_plan% | 当前方案 |
%adventureprefix_remaining_days% | 剩余天数 |
配置文件
| 文件 | 用途 |
|---|---|
config.yml | 引擎、长度、定价、方案、存储、审核和名牌 |
prefixes.yml | 权限组前缀、权重和格式 |
messages.yml | 全部玩家文本，支持颜色与 PAPI |
sounds.yml | 逐事件音效 |
长度与脏词
length:
min: 1
max: 12
width-mode: false
profanity-filter: false
profanity-words: []
edits:
allowed: 0
pricing:
recustomize-discount: 0.5故障排查
聊天或 TAB 不显示
插件默认不接管聊天/Tab；请在对应插件格式中加入 AdventurePrefix PAPI 变量。
渐变长度不正确
检查标签闭合、HEX 格式和 width-mode；颜色标记不参与可见字符计数。
自定义资格立即过期
确认方案期限使用 ISO-8601 Period，例如 P3M、P1Y，并检查服务器时区。
MySQL 中文或 emoji 损坏
数据库和连接必须使用 utf8mb4；不要将表手工改为 latin1/utf8mb3。