时装衣橱 LyArmourersWardrobe
MySQL 前置要求
启用 MySQL 存储时，必须安装 LyMySQLCore，并确认它已成功连接数据库。否则本插件的 MySQL 数据读取、保存、同步及相关记录不会生效，数据库未连接完成时玩家也无法进入服务器。
LyArmourersWardrobe 是用于管理 DragonArmourers 时装的 DragonCore 衣橱插件。它把服务器配置的时装整理到可分页浏览的界面中，玩家可以搜索、筛选、试穿、穿戴、脱下或隐藏时装，并在多个穿戴方案之间切换。
插件会管理玩家永久拥有的时装、试穿期限、试穿冷却、当前方案、各部位穿戴内容和隐藏状态。永久收藏与永久穿戴还可以接入属性插件提供属性效果。
基本信息
| 项目 | 内容 |
|---|---|
| 插件名 | LyArmourersWardrobe |
| 中文名 | 时装衣橱 |
| 作者 | 离渊 |
| 项目版本 | 1.0.1 |
| Java 版本 | Java 8 |
| 编译服务端 API | Paper 1.16.5 |
| 主指令 | /lysz |
| 界面名称 | 时装衣橱 |
| 本地数据目录 | plugins/LyArmourersWardrobe/data/ |
| 时装配置目录 | plugins/LyArmourersWardrobe/armourers/ |
版本说明
项目明确使用 Paper 1.16.5 API 编译。项目文件没有声明其他 Minecraft、DragonCore 或 DragonArmourers 版本范围，因此不能据此确认其他版本兼容性。
依赖关系
| 插件 | 类型 | 用途 |
|---|---|---|
| DragonCore | 核心功能依赖 | 提供衣橱 GUI、客户端槽位、界面发包和组件刷新。未安装时衣橱界面交互无法正常工作。 |
| DragonArmourers | 核心功能依赖 | 获取时装 ID 对应的部位类型，并把衣橱方案合并到玩家皮肤列表。未安装时无法完成时装注册与显示。 |
| PlaceholderAPI | 可选依赖 | 注册 %law_...% 系列变量。未安装时仅变量功能不可用。 |
| LyMySQLCore | MySQL 模式必需 | 提供安全的玩家数据加载与保存事件。只有启用 mysql.enable 时需要。 |
| 属性插件 | 可选依赖 | 根据 attribute-plugin 的设置处理收藏属性与穿戴属性。 |
可选属性插件名称如下：
AttributePlusSX-Attribute2SX-Attribute3AttributeSystemItemLoreOrigin
plugin.yml 将 PlaceholderAPI、DragonCore 和 DragonArmourers 声明为软依赖，但衣橱界面和时装显示本身仍依赖 DragonCore 与 DragonArmourers 提供的接口。
核心玩法
玩家通过 /lysz open 打开衣橱。界面会读取服务器在 armourers/ 目录中注册的时装，并根据玩家数据显示可穿戴或可试穿状态。
- 永久拥有的时装可以直接加入当前穿戴方案。
- 未拥有的时装可以触发限时试穿，并进入全局试穿冷却。
- 同一个时装部位在一个方案中只记录一件时装。
- 玩家可以单独隐藏某个部位，不需要从方案中脱下时装。
- 玩家可以在 5 个预设方案之间切换，每个方案分别保存穿戴与隐藏状态。
- 永久收藏属性按玩家永久拥有的时装汇总。
- 永久穿戴属性按当前方案中实际穿戴的永久时装汇总。
- 试穿时装不会提供收藏属性或穿戴属性。
主要功能
| 功能 | 说明 |
|---|---|
| 时装注册 | 递归读取 plugins/LyArmourersWardrobe/armourers/ 内的 .yml 文件。每个顶层键都是时装 ID，并且必须能被 DragonArmourers 识别。 |
| 自动识别部位 | 通过 DragonArmourers 获取时装类型，不需要在时装文件中手动填写类型。 |
| 时装信息 | 支持配置显示名称、品质、说明、收藏属性和穿戴属性。 |
| 界面物品 | 默认使用书本作为时装槽位物品；开启 show-item-armourers 后会为物品附加对应时装外观。 |
| 分页浏览 | 每页数量由 file-armourers-amount 控制，界面支持上一页和下一页。 |
| 类型筛选 | 支持武器、弓箭、套装、翅膀、帽子、上衣、裤子、鞋子以及全部类型。 |
| 品质筛选 | 按 quality 中注册的品质等级筛选，也可以显示全部品质。 |
| 拥有筛选 | 支持全部、已拥有和未拥有三种状态。 |
| 拼音搜索 | 时装名称会转换为无分隔符拼音，搜索内容同样转为拼音后进行包含匹配。 |
| 永久拥有 | 管理员可以给予或移除玩家的永久时装。永久时装会保存到玩家数据。 |
| 限时试穿 | 未拥有的时装可以获得临时使用权，试穿期间会显示在其他玩家可见的皮肤列表中。 |
| 试穿冷却 | 每次开始试穿后记录下一次可试穿时间，冷却对所有时装共用。 |
| 到期处理 | 插件每秒检查限时时装。到期后自动移除时装，并从所有预设中清除对应穿戴记录。 |
| 穿戴与脱下 | 玩家可以把时装装备到当前方案对应部位，也可以单独脱下指定部位。 |
| 显示与隐藏 | 每个方案可以分别记录各部位的隐藏状态。隐藏不会删除穿戴记录。 |
| 五套预设 | 玩家数据初始化时创建索引 0 至 4 的 5 套时装方案。 |
| 当前搭配详情 | 界面会显示当前方案已穿戴时装的品质、部位、名称以及隐藏状态。 |
| 自动发放 | auto-give-armourers 中的时装会在玩家数据加载时永久发放；对应部位为空时还会自动穿戴。 |
| 属性加成 | 永久拥有提供收藏属性，当前穿戴的永久时装提供穿戴属性。 |
| 本地 YAML 存储 | 默认按玩家 UUID 保存数据，并使用临时文件、备份文件和原子替换降低文件损坏风险。 |
| YAML 损坏恢复 | 主数据文件读取失败时会尝试读取 .bak 备份；主文件与备份均不可用时返回空数据。 |
| MySQL 存储 | 开启后以玩家名为索引，将序列化后的玩家数据保存到 LyArmourersWardrobe 数据表。 |
| MySQL 自动保存 | MySQL 模式下只保存产生过数据变化的在线玩家，检查间隔由 auto-save-interval 控制。 |
| 发包限速 | 使用 packet-interval 限制同一玩家处理 DragonCore 衣橱操作包的频率。 |
| 刷新调试 | debug-skin-update 可以输出当前方案、拥有状态、隐藏状态和皮肤合并过程。 |
支持的时装部位
| 类型 ID | 默认显示名 | 用途 |
|---|---|---|
sword | 武器 | 武器时装 |
bow | 弓箭 | 弓类时装 |
outfit | 套装 | 整体套装时装 |
wings | 翅膀 | 翅膀时装 |
head | 帽子 | 头部时装 |
chest | 上衣 | 胸部时装 |
legs | 裤子 | 腿部时装 |
feet | 鞋子 | 脚部时装 |
all | 全部 | 仅用于类型筛选，不是可穿戴部位。 |
时装类型由 DragonArmourers 返回。类型不存在或不属于上表时，该时装不会完成注册，并会在控制台输出注册失败信息。
时装拥有与试穿机制
插件使用时装 ID 对应的时间值区分永久拥有与限时试穿：
| 状态 | 内部时间值 | 行为 |
|---|---|---|
| 永久拥有 | -1 | 可以保存到玩家数据，提供收藏属性，并可在穿戴时提供穿戴属性。 |
| 限时试穿 | 未来的到期时间 | 可以在试穿期限内显示和穿戴，但不会保存为永久收藏，也不会提供属性。 |
| 未拥有 | 不存在记录 | 点击穿戴时会先检查全局试穿冷却，再创建限时使用记录。 |
试穿到期后，插件会执行以下处理：
- 移除玩家的限时时装记录。
- 从全部预设方案中移除该时装。
- 清理对应的 DragonCore 时装槽位。
- 刷新当前方案皮肤、搭配详情和属性缓存。
- 向玩家发送试穿到期消息。
穿戴方案
每名玩家固定初始化 5 个方案，索引为 0、1、2、3、4。每个方案分别保存：
- 各时装部位当前穿戴的时装 ID。
- 各时装部位是否隐藏。
切换方案时，插件会比较切换前后的穿戴映射和隐藏映射。内容发生变化时才请求 DragonArmourers 刷新皮肤，同时重新填充 DragonCore 客户端槽位和搭配详情。
玩家数据保存时，只会保存永久拥有时装的穿戴记录。历史试穿记录不会在重新进入服务器后恢复为有效穿戴，也不会重新获得属性。
属性规则
| 属性来源 | 生效条件 | 试穿时装是否生效 |
|---|---|---|
attribute 收藏属性 | 玩家永久拥有该时装 | 否 |
equip-attribute 穿戴属性 | 玩家永久拥有该时装，并在当前方案中穿戴 | 否 |
属性内容按时装文件中的字符串列表汇总，然后交给 attribute-plugin 指定的属性插件解析。插件会在玩家数据加载、时装移除和关闭背包等时机刷新属性缓存。
未配置 attribute-plugin 时，时装仍可正常收藏和穿戴，但不会向属性插件提交属性内容。
数据存储
本地 YAML
mysql.enable 为 false 时，玩家数据保存在：
text
plugins/LyArmourersWardrobe/data/玩家UUID.yml保存内容包括：
| 数据键 | 内容 |
|---|---|
next-try-on-time | 下一次允许试穿的时间。 |
now-plan | 当前使用的预设索引。 |
predefined-plan | 各预设的永久时装穿戴记录与隐藏状态。 |
owned-armourers | 玩家永久拥有的时装 ID 列表。 |
本地保存会先写入唯一 .tmp 临时文件，将旧主文件移动到 .bak，再替换主文件。读取时如果主文件损坏，会尝试通过 .bak 恢复。
MySQL
mysql.enable 为 true 时，插件创建名为 LyArmourersWardrobe 的数据表，使用玩家名查询数据，并把完整玩家配置序列化到 data 字段。
数据库连接要求
MySQL 模式依赖 LyMySQLCore 的玩家安全加载与保存事件。必须安装 LyMySQLCore，并确保 LyArmourersWardrobe 已成功建立数据库连接。连接未完成时，插件会阻止玩家登录，避免在数据尚未加载时进入服务器。
指令
| 指令 | 执行者 | 权限要求 | 说明 |
|---|---|---|---|
/lysz | 控制台或玩家 | OP | 显示插件指令帮助与当前版本。非 OP 执行时不会显示帮助内容。 |
/lysz open | 玩家 | 无独立权限节点 | 打开名为 时装衣橱 的 DragonCore 界面。玩家数据尚未载入时会提示数据不存在。 |
/lysz give [玩家] [时装ID] | 控制台或玩家 | OP | 给予在线玩家指定永久时装。玩家必须在线，时装 ID 必须已经注册。 |
/lysz remove [玩家] [时装ID] | 控制台或玩家 | OP | 移除在线玩家的指定时装，并从玩家的全部预设中清除该时装。 |
/lysz reload | 控制台或玩家 | OP | 重载主配置、品质、部位名称和全部时装文件，并重启自动保存任务。 |
插件没有注册独立权限节点。管理指令直接使用 OP 状态判断。
管理员指令支持补全：
- 第一级参数补全
reload、give、remove、open。 - 第二级参数补全在线玩家名。
give和remove的第三级参数补全已注册时装 ID。- 非 OP 不会获得管理指令补全结果。
界面功能
衣橱通过 DragonCore 自定义包标识 LyArmourersWardrobe 处理操作。已确认的界面行为如下：
| 界面操作 | 作用 |
|---|---|
| 初始化 | 创建筛选缓存、载入第一页、刷新筛选按钮、方案按钮和当前穿戴槽位。 |
| 穿戴显示时装 | 穿戴永久时装，或为未拥有时装触发试穿后穿戴。 |
| 脱下时装 | 清除当前方案指定部位的穿戴记录。 |
| 显示或隐藏时装 | 修改当前方案指定部位的隐藏状态。 |
| 切换预设 | 切换索引 0 至 4 的时装方案。 |
| 上一页 | 返回上一页，最低为第 1 页。 |
| 下一页 | 仅在剩余数据足够组成后续页面时翻页。 |
| 搜索时装 | 根据时装显示名称的拼音进行包含搜索。 |
| 选择时装类型 | 按部位类型或全部类型筛选。 |
| 选择是否拥有 | 按全部、已拥有、未拥有筛选。 |
| 选择时装品质 | 按指定品质等级或全部品质筛选。 |
界面操作会受到 packet-interval 限制。间隔内连续发送的操作包会被忽略，用于降低连点器造成的服务器压力。
兼容性注意事项
DragonCore 槽位冲突
默认配置明确说明，DragonCore 自带的 DragonArmourers 槽位功能可能与本插件冲突。如果出现穿戴时装频繁不生效或不显示，可检查 DragonCore 配置中的 DragonAmourers，并根据实际情况将其设为 false。修改前应确认服务器没有依赖 DragonCore 原槽位功能。
插件处理 DragonArmourers 的玩家皮肤刷新事件时，会把当前衣橱方案中未隐藏的永久时装和有效试穿时装加入原有皮肤列表，而不是直接清空事件原有皮肤。开启 debug-skin-update 后可以在控制台查看每个时装被加入或跳过的原因。
文档索引
| 页面 | 内容 |
|---|---|
| 配置说明 | 主配置、MySQL、试穿、品质、部位名称、消息和时装文件。 |
| 龙核资源 | DragonCore GUI、客户端槽位、界面函数和资源放置。 |
| 插件变量 | PlaceholderAPI 拥有状态、数量、当前穿戴和隐藏状态变量。 |
| 发包与变量 | 自定义包操作、参数、槽位标识和界面组件交互。 |
| 常见问题 | 时装注册、显示冲突、数据库连接、试穿和属性问题排查。 |