插件变量

LyInventory 接入 PlaceholderAPI 后，注册标识符为 li 的变量，用于读取玩家 LyInventory 背包槽位中的物品显示名称和槽位解锁状态。

前置要求

服务器必须安装并正常启用 PlaceholderAPI。LyInventory 只有在检测到 PlaceholderAPI 已启用时，才会注册变量扩展。

变量读取的是 PlaceholderAPI 传入玩家的 LyInventory 数据缓存，不支持通过变量参数查询其他玩家。

如果启用了 MySQL 存储，还必须安装 LyMySQLCore，并确保数据库连接成功。只有相关数据成功加载到玩家缓存后，变量才能读取对应数据。

变量列表

变量	返回内容
%li_name_背包ID:槽位ID%	指定背包槽位中物品的自定义显示名称
%li_unlock_背包ID:槽位ID%	指定背包槽位的解锁状态

变量格式为：

%li_变量类型_背包ID:槽位ID%

其中：

• 变量类型 为 name 或 unlock。
• 背包ID 对应背包配置中的 id。
• 槽位ID 对应 slot-set 下的配置节点名称。
• 槽位ID 不是槽位配置中的 slot 数字，除非节点名称本身就是数字。
• 背包 ID 与槽位 ID 之间必须使用英文冒号 : 分隔。
• 背包 ID 和槽位 ID 必须与配置内容完全一致。

例如配置如下：

id: 'test'

slot-set:
  头盔:
    slot: 22

此时：

• 背包 ID 是 test。
• 槽位 ID 是 头盔。
• 界面位置是数字 22。

对应变量应写为：

%li_name_test:头盔%
%li_unlock_test:头盔%

不能因为界面位置是 22，就直接写成 %li_name_test:22%，除非 slot-set 下的节点名称确实是 22。

物品名称

%li_name_背包ID:槽位ID%

读取指定玩家指定背包槽位中装备物品的自定义显示名称。

示例：

%li_name_test:头盔%

返回规则

情况	返回值
槽位中存在物品，且物品设置了自定义显示名称	物品的完整自定义显示名称，包括颜色格式
背包缓存不存在	null
槽位没有装备物品	null
物品没有物品元数据	null
物品没有自定义显示名称	null
PlaceholderAPI 没有提供玩家上下文	空字符串

该变量读取 Bukkit 物品元数据中的自定义显示名称，不会自动返回原版材质名称。

即使槽位中存在物品，只要物品没有设置自定义显示名称，仍会返回 null。该变量也不会返回物品 Lore、材质、数量或槽位默认图标名称。

解锁状态

%li_unlock_背包ID:槽位ID%

读取指定玩家指定背包槽位是否已经解锁。

示例：

%li_unlock_test:头盔%

返回规则

返回值	说明
true	玩家缓存中的该槽位已记录为已解锁
false	玩家缓存不存在，或该槽位未记录为已解锁
空字符串	PlaceholderAPI 没有提供玩家上下文

解锁状态与槽位中是否存在装备无关。已解锁但没有装备物品的槽位仍返回 true。

该变量只读取缓存中的解锁记录，不会执行解锁条件，也不会消耗物品、金币或点券。

如果配置启用了 unlock-empty-condition-slot，没有配置 unlock-condition 的槽位会在玩家打开对应背包时加入解锁记录。记录更新后，该变量会返回 true。

使用限制

• 必须包含完整的变量类型、背包 ID、英文冒号和槽位 ID。
• 背包ID 必须对应背包配置的 id。
• 槽位ID 必须对应 slot-set 下的配置节点名称。
• 变量只读取 PlaceholderAPI 传入玩家自己的 LyInventory 缓存。
• 不能通过变量参数指定玩家名称或 UUID。
• 物品名称变量只读取自定义显示名称，不读取原版物品名称。
• 物品名称变量不会返回 Lore、材质、数量或默认槽位图标信息。
• 解锁状态变量只返回字符串 true 或 false，不会触发解锁流程。
• 查询变量不会修改背包物品、解锁记录或玩家数据。
• 使用 MySQL 存储时，必须安装 LyMySQLCore 并成功连接数据库，否则玩家数据的加载和保存不会正常生效。

当变量格式无法匹配 name_ 或 unlock_ 时，LyInventory 返回错误提示文本：

§c错误

常见问题

物品已经放入槽位，为什么名称仍返回 null？

%li_name_背包ID:槽位ID% 只读取物品自定义显示名称。请确认该物品设置了自定义名称；仅有原版材质名称或 Lore 不会被该变量返回。

为什么变量始终不解析？

请确认：

1. PlaceholderAPI 已安装并正常启用。
2. LyInventory 启动时已经检测到 PlaceholderAPI。
3. 变量使用了正确的标识符 li。
4. 变量格式包含正确的背包 ID、英文冒号和槽位 ID。

正确格式示例：

%li_name_test:头盔%
%li_unlock_test:头盔%

为什么变量返回错误的槽位结果？

请检查使用的是 slot-set 下的节点名称，而不是槽位配置中的 slot 数字。

例如：

slot-set:
  戒指:
    slot: 10

此时应使用：

%li_name_背包ID:戒指%
%li_unlock_背包ID:戒指%

不能直接使用：

%li_name_背包ID:10%

除非槽位节点名称本身就是 10。

槽位没有解锁条件，为什么仍返回 false？

启用 unlock-empty-condition-slot 后，没有解锁条件的槽位会在玩家打开对应背包时自动加入解锁记录。

如果玩家数据已经加载，但尚未打开该背包，自动解锁记录可能还没有更新，此时变量仍可能返回 false。

变量能否读取其他玩家的数据？

不能。当前变量实现只读取 PlaceholderAPI 传入玩家自己的 LyInventory 缓存，没有提供玩家名称或 UUID 参数。

启用 MySQL 后变量没有读取到数据怎么办？

确认已经安装 LyMySQLCore，并检查数据库连接是否成功。MySQL 存储只有在 LyMySQLCore 正常工作且连接数据库成功后，玩家数据才能正常加载到 LyInventory 缓存中。

占位符没有玩家上下文时返回什么？

当 PlaceholderAPI 没有传入玩家对象时，name 和 unlock 变量都会返回空字符串。