背包 LyInventory

MySQL 前置要求

启用 MySQL 存储时，必须安装 LyMySQLCore，并确认它已成功连接数据库。否则本插件的 MySQL 数据读取、保存、同步及相关记录不会生效。

LyInventory 是一款自定义背包与装备槽插件。服主可以创建多个独立背包，为每个背包设置界面标题、行数、打开权限和打开条件，并为不同槽位配置放入、解锁、属性加载、取出、点击指令等规则。

插件可用于制作饰品栏、时装栏、神器栏、材料背包、会员背包、职业装备栏等玩法。玩家可以通过普通背包界面管理装备，也可以将槽位映射到 DragonCore 或萌芽界面。背包中的物品能够按条件向属性插件提供 Lore 属性，并支持 DragonArmourers 时装展示。

插件信息

项目	内容
插件名	LyInventory
插件版本	2.1.5
作者	Liyuan
主命令	/li
Java 版本	Java 8
Bukkit API	api-version: 1.13
开发目标	Paper 1.16.5
数据存储	本地 YAML、MySQL

支持版本说明

项目使用 Bukkit API 1.13 声明，并以 Paper 1.16.5 API 作为开发依赖。现有项目文件无法确认更低版本或更高版本服务端的完整兼容范围。

玩法与机制

每个背包由一个独立 YAML 文件定义，并通过唯一背包 ID 调用。背包内分为预设物品和功能槽位：

• 预设物品：用于制作边框、按钮、玩家信息等固定界面内容，可以显示 PlaceholderAPI 变量、执行控制台指令并在点击后刷新界面。
• 功能槽位：用于存放玩家装备或特殊物品，槽位 ID 在全部背包中必须保持唯一。
• 装备操作：支持放入、替换和取出物品，并可分别执行 replace-command、take-out-command 和 click-command。
• 快捷操作：支持使用 Shift + 左键 自动寻找符合条件的空槽位，也支持从插件背包快速取回玩家背包。
• 堆叠限制：数量大于 1 的物品不能直接作为装备放入功能槽位。
• 槽位解锁：可以使用权限、PlaceholderAPI 表达式、玩家物品、Vault 金币或 PlayerPoints 点券作为解锁条件。
• 物品限制：可以按物品名称、Lore、权限、变量表达式、唯一数量、DragonArmourers 时装类型及 NBT 数据限制可放入物品。
• 属性加载：槽位中的物品 Lore 可以加载到指定属性插件，并可按槽位条件决定属性是否生效。
• 属性倍率：启用后可以通过槽位的 attribute-rate 调整指定 Lore 属性关键词中的数值。
• 原版槽位属性：使用 AttributePlus 时，可以让玩家原版背包的指定槽位参与属性读取，并为每个槽位设置物品条件。
• 装备后绑定：物品成功放入槽位时，可以按 lore-replace 将完全匹配的 Lore 替换为新内容，新内容支持 PlaceholderAPI 变量。
• 取出限制：装备放入后仍可通过权限或变量条件限制取出。
• 打开时复检：可在玩家打开背包时重新检查已装备物品的放入条件，不再符合条件的物品会尝试退回玩家背包。
• 自动保存：玩家数据发生变化后会按配置间隔自动保存，关闭背包、退出服务器、被踢出或插件关闭时也会触发保存。

依赖与联动

plugin.yml 将以下插件声明为软依赖。未安装对应插件时，与该插件有关的功能不可使用。

插件	用途
PlaceholderAPI	解析界面文本、指令和条件中的变量，并注册 LyInventory 变量
AttributePlus	加载插件背包属性，并支持读取原版背包指定槽位的属性
SX-Attribute	提供 SX-Attribute2、SX-Attribute3 属性加载模式
AttributeSystem	作为可选属性加载目标；项目代码中存在对应接口
ItemLoreOrigin	将背包装备 Lore 汇总为属性物品并定时更新
Vault	为 eco 槽位解锁条件提供经济余额和扣款功能
PlayerPoints	为 point 槽位解锁条件提供点券查询和扣除功能
DragonCore	将插件背包槽位映射到龙核界面槽位，并同步客户端物品
DragonArmourers	检测时装类型，并将指定背包中的时装应用到玩家外观
LyCore	为 hasNbt、nbtCheck 等 NBT 条件提供支持
LyMySQLCore	MySQL 模式下协调玩家数据安全加载与保存
DZ-Status	已在插件描述中声明软依赖，现有证据未确认具体配置项
ProtoclLib	已按 plugin.yml 中的名称声明软依赖

项目代码还包含萌芽界面槽位映射，以及通过 LyLootsWareHouse 查询和扣除解锁物品的兼容逻辑。这两个插件未出现在当前 plugin.yml 的软依赖列表中，使用前应确认服务器环境已正确安装对应插件。

属性插件模式

attribute-plugin 可以配置为以下已实现模式：

配置值	对应插件
AttributePlus	AttributePlus
SX-Attribute2	SX-Attribute 2
SX-Attribute3	SX-Attribute 3
AttributeSystem	AttributeSystem
ItemLoreOrigin	ItemLoreOrigin

修改属性插件模式后需要重启服务器。

核心功能

功能	说明
多背包配置	从 inventory 目录递归加载背包 YAML，每个背包使用独立 ID
自定义界面	支持 1 至 6 行界面、颜色标题、固定物品、功能槽位和点击刷新
独立槽位规则	每个槽位可单独设置默认图标、放入条件、解锁条件、属性条件和取出条件
多条件表达式	物品放入条件支持使用 && 和 || 组合“并且”或“或者”逻辑
条件提示	放入条件可以通过 <-> 附带失败提示，提示支持 PlaceholderAPI 变量
全局穿戴检测	可以从装备 Lore 提取数值，并将数值代入 <value> 执行全局变量条件
唯一装备限制	可以限制全部背包或指定背包中同名、同 Lore 物品的最大数量
槽位解锁	支持权限、反向权限、变量表达式、物品、金币和点券条件
操作指令	支持点击、放入或替换、取出、解锁成功四类控制台指令
属性联动	支持多种属性插件、属性条件、属性倍率和手动刷新
Lore 替换	装备成功放入槽位时，可将指定整行 Lore 替换为动态内容
龙核槽位映射	使用 lyinv_背包ID_槽位ID 标识映射 DragonCore 槽位
萌芽槽位映射	可通过槽位的 mapping-slot 对接萌芽界面槽位标识
时装展示	可以选择一个背包作为 DragonArmourers 外观来源，或关闭当前展示
数据持久化	保存装备、已解锁槽位和当前时装展示背包
自动恢复	本地 YAML 存储使用安全写入与备份恢复逻辑，降低存档损坏风险
开发者接口	提供背包 ID、槽位物品读取和槽位物品修改 API
装备事件	放入或替换装备前触发可取消的 ItemStackEquipToSlotEvent

数据存储

本地 YAML

未启用 MySQL 时，玩家数据保存在插件的 data 目录中，文件名使用玩家 UUID。数据包括：

• 每个背包的槽位物品；
• 每个背包的已解锁槽位；
• DragonArmourers 当前展示的背包 ID。

插件会为本地 YAML 写入创建备份，并在主文件无法正常读取时尝试恢复。

MySQL

在 config.yml 中启用 mysql.enable 后，插件会通过连接池将玩家数据序列化保存到数据库，并使用玩家名称查询和覆盖数据。

启用 MySQL 前必须确认

MySQL 模式依赖 LyMySQLCore 提供的安全玩家加载与保存事件。必须安装 LyMySQLCore，并确认数据库连接已经成功建立。仅填写数据库地址和账号并不能保证相关功能生效。

切换 mysql.enable 后需要重启服务器。

指令

插件没有声明独立权限节点。管理指令直接检查执行者是否为服务器管理员 OP。

指令	使用条件	说明
/li	OP	显示插件指令帮助和当前版本
/li reload	OP	重载主配置和背包配置，重建在线玩家的背包界面
/li open <背包ID>	玩家	打开自己的指定背包，需要满足该背包的权限和打开条件
/li open <背包ID> <玩家>	OP	让指定在线玩家打开自己的指定背包
/li look <玩家> <背包ID>	玩家	查看指定在线玩家的背包；非管理员只能查看，管理员可以操作
/li remove <玩家> <背包ID> <槽位ID>	OP	删除指定在线玩家对应槽位中的物品
/li show <背包ID>	玩家	将指定背包切换为自己的 DragonArmourers 时装展示来源
/li show disable	玩家	关闭自己的 DragonArmourers 时装展示
/li show <背包ID> <玩家>	OP	设置指定在线玩家的 DragonArmourers 时装展示背包
/li show disable <玩家>	OP	关闭指定在线玩家的 DragonArmourers 时装展示
/li refreshattr <玩家>	OP	异步刷新指定在线玩家的插件背包属性

重载注意事项

执行 /li reload 时，插件会关闭所有正在打开的 LyInventory 界面，并重新读取配置。默认的 inventory/示例背包.yml 会在每次重载时覆盖，而且不会作为正式背包加载。请复制该文件并修改文件名后再制作实际背包。

龙核与时装联动

DragonCore 槽位

启用 dragoncore-slot-mapping-enable 后，DragonCore 界面槽位的标识格式为：

lyinv_背包ID_槽位ID

例如背包 ID 为 test、槽位 ID 为 头盔 时，槽位标识为：

lyinv_test_头盔

插件会在玩家数据加载、DragonCore 配置重载和槽位物品变化时同步物品，并在玩家进入服务器后等待 DragonCore 客户端槽位缓存就绪后再次刷新。

DragonArmourers 时装

使用 /li show <背包ID> 后，插件会收集该背包中能够被 DragonArmourers 识别的时装物品，并将其作为玩家外观列表。展示背包 ID会随玩家数据一起保存。

槽位放入条件还支持 sz-type 检测，可识别以下时装类型：

类型	说明
outfit	套装
head	帽子
chest	衣服
legs	裤子
feet	鞋子
wings	翅膀
sword	武器或副手
bow	弓

开发者支持

插件对外提供 LyInventoryAPI，可以完成以下操作：

方法	说明
getAllInventoryId()	获取当前已加载的全部背包 ID
getInventoryAllItem(player, inventoryId)	获取玩家指定背包中的全部槽位物品映射
getItemStack(player, inventoryId, slotId)	获取玩家指定背包、指定槽位中的物品
setItemStack(player, inventoryId, slotId, itemStack)	设置或清空指定槽位物品，并同步界面、龙核槽位和属性

玩家通过普通背包界面放入或替换装备时，会触发 ItemStackEquipToSlotEvent。其他插件可以取消事件，也可以替换事件中的物品后再写入槽位。

更完整的配置键、条件格式和变量说明请查看对应页面，避免直接根据示例文件猜测配置。

页面索引

页面	内容
配置说明	主配置、属性插件、存储、冷却、Lore 替换和消息文本
背包配置	背包文件、预设物品、功能槽位和操作指令
条件规则	打开、放入、解锁、属性和取出条件
插件变量	PlaceholderAPI 变量及返回值
常见问题	数据库、属性、槽位映射、重载和数据保存排查
更新日志	文档整理记录