称号插件 ShiroGomaTitles
白芝麻服专属称号（前缀）插件使用说明 —— 玩家佩戴、管理员命令、配置、称号组与 PlaceholderAPI 变量
简介
ShiroGomaTitles 是白芝麻服专属的称号（前缀）插件。玩家可以收集并佩戴称号，佩戴的称号会通过 PlaceholderAPI 变量显示在你的聊天、TAB 列表或头顶姓名等处。
- 玩家侧：打开「称号仓库」GUI，点击即可佩戴 / 取消佩戴已拥有的称号。
- 管理侧：发放全局称号、添加定制称号、配置称号组奖励、切换存储后端。
本插件为 Bukkit / Spigot / Paper 系插件（api-version 1.13+），在 Youer 这类 NeoForge + Bukkit 混合端上运行于 Bukkit 侧。需要前置 PlaceholderAPI（softdepend，缺失时变量不可用，但佩戴称号功能仍正常）。
安装
- 将
ShiroGomaTitles-1.0.jar放入服务端plugins/文件夹 - 重启服务器（或重载插件）
- 首次启动会生成
plugins/ShiroGomaTitles/config.yml与players.yml
玩家使用
| 操作 | 方式 |
|---|---|
| 打开称号仓库 | 游戏内输入 /sgtitles 或别名 /sgt |
| 佩戴称号 | 在仓库里左键点击对应称号 |
| 取消佩戴 | 再次点击当前已佩戴的称号（带 ◆ 标记） |
| 翻页 | 点击仓库右下角箭头（上一页 / 下一页） |
首次打开仓库时，若你还没有默认称号，插件会自动赠送 config.yml 中 default-title 配置的称号（默认 newbie 萌新）。每个称号会显示获取时间，定制称号带有「✦ 定制称号」标记。仓库图标由插件根据称号 ID 自动分配。
管理员命令
权限节点：sgtitles.admin（默认仅 OP 拥有）。help 子命令无需权限。
| 命令 | 说明 |
|---|---|
/sgtitles · /sgtitles titles | 打开称号仓库 GUI（仅玩家可用） |
/sgtitles give <玩家> <称号ID> | 给予玩家某个全局称号 |
/sgtitles remove <玩家> <称号ID> | 移除玩家的某个全局称号 |
/sgtitles custom add <玩家> <显示名> | 为玩家添加定制称号（显示名支持 & 颜色代码） |
/sgtitles custom remove <玩家> <定制ID> | 移除玩家的某个定制称号 |
/sgtitles custom list <玩家> | 列出玩家的全部定制称号及其 ID |
/sgtitles list | 列出所有已配置的全局称号 |
/sgtitles reload | 重载 config.yml（称号、称号组、存储配置） |
/sgtitles storage | 查看当前存储后端（yml / postgres） |
/sgtitles migrate | 把 players.yml 数据迁移到 PostgreSQL |
/sgtitles migrate-to-yml | 把 PostgreSQL 数据迁回 players.yml |
/sgtitles help | 显示帮助 |
give / remove / custom 系列命令要求目标玩家在线。称号 ID 必须是 config.yml 的 titles 下已定义的 ID，否则提示「全局称号ID不存在」。要移除某个定制称号，先 /sgtitles custom list <玩家> 查到它的定制 ID。
配置（config.yml）
称号定义
titles:
newbie:
display: "&a萌新"
lore:
- "&7初来乍到，请多关照"
# gradient: # 可选，渐变颜色（HEX），用于 %sgtitle_title% 动态渐变
# - "#05ad21"
# - "#f2be02"display：显示名，支持&颜色代码lore：仓库里的描述行（支持&）gradient（可选）：一组 HEX 颜色，开启后佩戴时%sgtitle_title%会呈现流动渐变
默认称号
default-title: newbie首次打开仓库时自动赠送的称号 ID，留空则不自动赠送。
变量输出格式
placeholder-format: "&7[{title}&7]"%sgtitle_title% 的包裹格式，{title} 替换为当前佩戴称号的显示名；未佩戴时该变量为空。
称号组（集齐奖励）
当玩家集齐组内所有称号时，自动执行一组命令（仅触发一次）：
groups:
legend:
titles:
- newbie
- vip
commands:
- "say {player} 集齐了传奇组！"
- "give {player} diamond 64"
as-player: false # false=控制台执行(默认)；true=由玩家自己执行- 占位符：
{player}= 玩家名，{uuid}= 玩家 UUID as-player: false（默认）：以控制台身份执行命令- 玩家失去其中某个称号后，该组会被标记为未完成；重新集齐时会再次触发
PlaceholderAPI 变量
需安装 PlaceholderAPI。扩展标识符为 sgtitle。
| 变量 | 输出 |
|---|---|
%sgtitle_title% | 当前佩戴称号（按 placeholder-format 包裹；若配置了 gradient 则输出随时间流动的渐变） |
%sgtitle_title_gradient% | MiniMessage 格式 <gradient:...>文本</gradient>，需调用方支持 MiniMessage；未配置 gradient 时返回纯文本 |
%sgtitle_title% 的渐变是实时流动的（相位随时间变化），因此插件禁用了 PAPI 缓存。把它放进聊天格式、TAB 列表或头顶显示插件里即可看到效果。
示例（聊天前缀）：
%sgtitle_title% %player_name%&f: %message%数据存储
- 默认
storage.type: yml，玩家数据写入plugins/ShiroGomaTitles/players.yml - 可选
postgres，连接 PostgreSQL（在storage.postgres配置 host / port / database / username / password） - 切换后端后执行
/sgtitles reload；如需迁移历史数据用/sgtitles migrate（yml→postgres）或/sgtitles migrate-to-yml
迁移只是把数据复制过去，不会自动切换后端。请迁移完成后在 config.yml 改好 storage.type 并 /sgtitles reload。
常见问题
Q：变量 %sgtitle_title% 显示为空？ 未佩戴称号时本就为空。若已佩戴仍为空，检查是否安装了 PlaceholderAPI，且调用该变量的插件能正确解析 PAPI。
Q：渐变不流动 / 不显示？
%sgtitle_title% 需放在支持颜色代码的文本里（聊天 / TAB / 头顶）。%sgtitle_title_gradient% 需要调用方支持 MiniMessage 标签。称号本身需在 config.yml 配了 gradient。
Q：改了 config.yml 不生效？
执行 /sgtitles reload（或重启）。新增的 titles / groups 会在 reload 后加载。
Q：玩家收不到 give 的称号？
目标玩家必须在线；称号 ID 必须已定义在 titles 下。