概览
Title 称号系统功能概览
Title 称号系统
模块简介
Title 是 Suite 的称号系统模块，为服务器提供完整的分组称号管理能力。玩家通过活动、任务、命令等方式获取称号，称号按分组归类、按品质分级，装备后可在聊天、Tab 列表、头顶展示。模块支持展示属性（装备生效）与收藏属性（拥有即生效）双属性体系，并对接 AttributePlus、MythicLib、CraneAttribute、Symphony 四大属性插件。
模块采用 ArcartX UI 客户端面板展示称号管理界面，玩家可在界面中浏览、筛选、装备、卸下、隐藏称号，所有交互通过 Packet 通讯完成，无需服务端菜单插件。
功能特性
| 特性 | 说明 |
|---|---|
| 分组管理 | 称号按组归类（冒险类、探索类、活动类等），每个分组有独立显示名、排序权重和访问权限，同一分组只能装备一个称号 |
| 品质系统 | 普通、传说、神话等多品质等级，每个品质有独立排序权重，用于称号分级展示 |
| 双类型称号 | text（文字称号）和 icon（图标称号），图标称号支持 ArcartX 自定义文字贴图格式 |
| 有效期 / 永久 | 通过命令或 Capability 指定时长（如 7d、30m、permanent），后台定时清理过期称号 |
| 日期区间 | 支持 yyyy-MM-dd~yyyy-MM-dd 格式指定激活和过期日期，区间外的称号不生效 |
| 套装系统 | 多个称号组成一套，达到阈值后激活额外套装属性加成，UI 内实时展示进度 |
| 头顶显示 | 称号可配置 overhead-mode（texture 贴图 / text 文本 / none 关闭），装备后自动显示在玩家头顶 |
| 聊天 / Tab 前后缀 | 每个称号可独立配置 chat-prefix、chat-suffix、tab-prefix、tab-suffix |
| 展示属性 | display-attributes 仅在装备该称号时生效的属性加成 |
| 收藏属性 | collection-attributes 只要拥有且未过期即累计的属性加成（收集图鉴式） |
| 四大属性插件 | 同时对接 AttributePlus、MythicLib（含 MMOItems 生态）、CraneAttribute、Symphony |
| 展示称号 | 玩家可从已装备称号中指定一个为「主展示称号」，用于 PAPI 总展示占位符输出 |
| UI 菜单 | ArcartX UI 驱动的称号管理界面，支持分组/品质/拥有状态筛选 |
| PAPI 全量输出 | 拥有数量、装备信息、剩余时间、属性加成等全部通过 PlaceholderAPI 输出 |
| 数据持久化 | SQLite 或 MySQL，支持共享存储模式（复用本体数据源）与自建存储模式 |
| 跨服同步 | 共享存储模式下，玩家称号数据跨服同步 |
| 数据库迁移 | 注册 DatabaseMigratable 能力，支持存储切换时数据迁移 |
| 玩家数据清理 | 注册 PlayerDataPurgeable 能力，支持按 UUID 或全量清理玩家数据 |
| 跨模块授予 | 注册 TitleGrantable 能力，供 EventPacket 等模块跨模块授予称号 |
| 配置查询 | 注册 TitleConfigQueryable 能力，供 QuestGps 等模块查询称号配置元数据 |
依赖
| 依赖类型 | 名称 | 说明 |
|---|---|---|
| 外部硬依赖 | PlaceholderAPI | 占位符扩展（external-depends 硬依赖，未安装时模块不加载） |
| 外部软依赖 | AttributePlus | 展示/收藏属性同步（可选） |
| 外部软依赖 | MythicLib | 展示/收藏属性同步（可选，含 MMOItems 生态） |
| 外部软依赖 | CraneAttribute | 展示/收藏属性同步（可选） |
| 外部软依赖 | Symphony | 展示/收藏属性同步（可选） |
| ArcartX 本体 | Suite | 模块运行基础环境 |
模块本身不硬依赖任何 ArcartX 子模块。属性插件桥接是否生效由本体
config.yml的attribute-bridges统一管理，模块侧仅配置属性源前缀。
称号机制详解
称号生命周期
称号从发放到回收经历以下状态流转：
- 授予（Grant）：通过管理员命令
/axs title give或跨模块TitleGrantable能力授予玩家称号，写入title_player_titles表 - 拥有（Owned）：玩家持有称号，收藏属性立即生效（无论是否装备）
- 装备（Equip）：玩家在 UI 或通过
/title equip装备称号到对应分组，展示属性生效 - 隐藏（Hide）：玩家可隐藏称号，隐藏后不参与头顶/聊天展示，但收藏属性仍然生效
- 卸下（Unequip）：从分组卸下称号，展示属性失效
- 过期（Expire）：限时称号到期后由后台定时任务自动清理，收藏属性失效
- 回收（Revoke）：管理员通过
/axs title revoke收回称号，移除全部相关记录
分组与装备槽
每个分组（Group）相当于一个独立的装备槽位。玩家在同一分组中只能装备一个称号，装备新称号会替换该分组原有的装备。分组通过 permission 字段控制访问权限，无权限的玩家无法装备该分组的称号，也无法在 UI 中看到该分组的称号。
展示称号
玩家可从已装备的称号中指定一个为「主展示称号」（display title）。PAPI 的 %axstitle_display% 系列占位符输出该称号的信息。若未显式指定，系统按 display-title.groups 配置的分组顺序，取第一个已装备称号作为展示称号。
属性体系
| 属性类型 | 配置字段 | 生效条件 | 说明 |
|---|---|---|---|
| 展示属性 | display-attributes / display-attribute-lines | 装备该称号时 | 仅装备生效，卸下后失效 |
| 收集属性 | collection-attributes / collection-attribute-lines | 拥有该称号时 | 拥有即生效，无需装备 |
| 套装属性 | sets.<id>.bonus-attributes | 套装激活时 | 达到套装阈值后激活 |
| 总属性 | — | — | 展示属性 + 收集属性 + 套装属性的合计值 |
属性通过 display-attributes（Map<String, Double> 键值对）和 display-attribute-lines（List<String> 文本行）两种形式配置。键值对形式用于实际属性数值计算，文本行形式用于 UI 展示和属性插件源数据写入。两者可同时使用，文本行中可解析为「属性名:数值」格式的行会与键值对合并累加。
头顶显示
称号的 overhead-mode 决定装备后的头顶显示方式：
| 模式 | 说明 | 实现方式 |
|---|---|---|
texture | 贴图模式，在玩家头顶渲染自定义文字贴图 | 通过 WorldTextureBridge 挂载贴图实体，需 ArcartX 客户端支持 |
text | 文本模式，通过 Scoreboard Team 前后缀显示 | 纯服务端实现，使用 overhead-prefix / overhead-suffix |
none | 不显示 | 无头顶效果 |
当
texture模式但 WorldTextureBridge 不可用时，自动降级为text模式。
过期清理
后台定时任务按 settings.expiration-cleanup-interval-ticks 配置的周期运行，扫描所有缓存玩家状态，清理已过期的称号记录并同步外部属性。过期称号从 title_player_titles 表批量删除。