物品函数

LyCore 注册了 Aviator 物品函数，供离渊系列插件或其它已接入 Aviator 的配置调用。

函数执行时会从上下文读取 player。匹配物品 还会从上下文读取当前传入的 item。LyCore 初始化 Aviator 时注册以下函数：

• 匹配物品
• 统计物品
• 扣除物品
• 给予物品

函数列表

函数	返回值	上下文要求	说明
匹配物品(...)	布尔值	player、item	判断当前物品是否满足全部条件
统计物品(...)	数字	player	统计玩家拥有的指定物品数量
扣除物品(...)	布尔值	player	按条件扣除玩家拥有的指定物品
给予物品(...)	布尔值	player	已注册函数，但当前实现未正确取得物品库 ID，不建议在业务配置中使用

函数参数使用字符串形式的 键=值 传入。参数中出现多个条件时，所有条件都必须满足。

颜色符号可以使用 &，函数会将其转换为 § 后再匹配物品名称、lore 或 NBT 字符串值。

匹配条件

以下条件可用于 匹配物品、统计物品 和 扣除物品：

条件	写法	说明
MythicMobs 物品	mm=物品ID	与 MythicMobs 物品库生成的物品比较
NeigeItems 物品	ni=物品ID	与 NeigeItems 物品库生成的物品比较
SXItem 物品	si=物品ID	与 SXItem 物品库生成的物品比较
AzureFlow 物品	af=物品ID	与 AzureFlow 物品库生成的物品比较
精确名称	name=物品名	物品显示名完全一致
精确 lore	lore=文本	任意一行 lore 完全一致
精确 NBT	nbt=值	任意字符串 NBT 值完全一致
包含名称	name_contains=文本	物品显示名包含指定文本
包含 lore	lore_contains=文本	任意一行 lore 包含指定文本
包含 NBT	nbt_contains=文本	任意字符串 NBT 值包含指定文本
物品 ID	id=类型 或 id=类型:耐久	类型可写 Bukkit 材质名或数字 ID

多个条件会同时参与判断。例如，以下表达式要求物品名称包含“强化石”，并且 lore 中包含“可用于装备强化”：

匹配物品("name_contains=强化石", "lore_contains=可用于装备强化")

匹配物品

函数签名

匹配物品(条件1, 条件2, ...)

匹配物品 从 Aviator 上下文读取 item。当 item 不存在、为空或物品类型为空气时，函数返回 false。

所有传入条件都匹配成功时返回 true；任意条件不满足时返回 false。

示例

判断物品名称是否包含指定文本：

匹配物品("name_contains=强化石")

同时判断名称和 lore：

匹配物品("name_contains=强化石", "lore_contains=可用于装备强化")

判断物品类型：

匹配物品("id=DIAMOND")

兼容旧版本数字 ID 和耐久值：

匹配物品("id=351:1")

判断物品库中的物品：

匹配物品("mm=强化石")

统计物品

函数签名

统计物品(条件1, 条件2, ...)

统计物品 返回数字结果，统计范围包括玩家主背包的前 36 个槽位。匹配成功时累加物品堆叠数量，而不是只计算物品格数量。

当对应插件已安装并启用时，函数还会尝试统计以下存储中的物品：

• 清守灵魂空间，插件标识为 YeeCore
• 离渊传统仓库，插件标识为 LyWarehouse
• 离渊战利品仓库，插件标识为 LyLootsWareHouse

某个存储插件未安装时，会跳过对应存储。对应插件接口发生错误时，LyCore 会记录错误并继续处理其它存储。

示例

统计玩家拥有的名称包含“强化石”的物品数量：

统计物品("name_contains=强化石")

统计 MythicMobs 物品库中的指定物品：

统计物品("mm=强化石")

统计多个条件同时满足的物品：

统计物品("id=DIAMOND", "name_contains=强化石")

扣除物品

函数签名

扣除物品(条件1, 条件2, ..., "amount=数量")

扣除物品 的默认扣除数量为 1。传入 amount 可以指定扣除数量：

参数	写法	默认值	说明
扣除数量	amount=数量	1	要扣除的物品总数量
物品条件	见匹配条件	无	用于筛选可扣除的物品

扣除顺序如下：

1. 玩家主背包前 36 个槽位
2. 清守灵魂空间
3. 离渊传统仓库
4. 离渊战利品仓库

某个插件未安装时会跳过对应存储。扣除过程中发生错误时，LyCore 会记录错误并继续处理后续存储。

当 amount 小于或等于 0 时，函数直接返回 true，不会扣除物品。

只有成功扣除全部指定数量时，函数才返回 true；可匹配物品数量不足时返回 false。

示例

扣除 5 个名称包含“强化石”的物品：

扣除物品("name_contains=强化石", "amount=5")

扣除一个 MythicMobs 物品：

扣除物品("mm=强化石", "amount=1")

按多个条件扣除物品：

扣除物品("id=DIAMOND", "name_contains=强化石", "amount=2")

给予物品

函数签名

给予物品(参数1, 参数2, ...)

给予物品 已注册到 Aviator，但当前实现存在以下限制：

• 函数内部的物品库类型默认为 mm。
• 物品库 ID 初始值为 null，当前实现未从传入参数设置有效的物品库 ID。
• 函数会在获取物品前判断物品库 ID；当前状态下会报告指定的物品库 ID 不存在并返回 false。

因此，当前版本不建议直接在业务配置中使用 给予物品。正式配置应优先使用业务插件自身提供的奖励发放方式。

物品发放处理

在实现能够取得有效物品后，发放逻辑会尝试将物品加入玩家背包。背包空间不足时，剩余物品按以下顺序处理：

1. 离渊传统仓库
2. 离渊战利品仓库
3. 清守灵魂空间
4. 如果以上存储均无法接收，则掉落在玩家当前位置附近

该处理只适用于 给予物品 内部的发放逻辑，不改变其它函数的统计或扣除范围。

注意事项

• 这些函数依赖 Aviator 表达式环境中的 player 上下文。
• 匹配物品 需要额外提供当前物品 item，单独执行且未提供 item 时会返回 false。
• 条件参数必须使用 键=值 格式；无法拆分为键和值的参数会被忽略。
• 统计物品 和 扣除物品 会检查玩家背包前 36 个槽位，不包含其它未实现的背包区域。
• 传统仓库、战利品仓库和清守灵魂空间属于可选联动功能，只有对应插件已安装并启用时才会尝试调用。